orun is a single binary with two commands: bootstrap, which provisions a remote host as an orun node over SSH, and start, which runs the pull-based reconciliation agent on the node itself. You run bootstrap from your local machine (or CI) and rarely invoke start directly — the systemd unit created during bootstrap handles that for you.
orun bootstrap
Provision a new node over SSH. Run this command from the root of your manifest repository.orun bootstrap enters interactive mode and asks for each configuration value in turn. When you finish, it writes a node manifest to nodes/<name>.yaml and immediately proceeds with provisioning.
With a path argument, it reads the manifest you point to and skips the prompts:
Interactive prompts
When you runorun bootstrap with no argument, orun asks for the following values:
| Prompt | Required | Default |
|---|---|---|
| Node name | Yes | — |
| Host (IP or hostname) | Yes | — |
| SSH user | No | root |
| SSH private key path | No | ~/.ssh/id_ed25519 |
| Manifest git repository URL | Yes | — |
| Git branch | No | main |
| Poll interval | No | 5s |
| Data directory on the node | No | /opt/orun/ |
orun writes nodes/<name>.yaml and prints the path before continuing.
Argument
Path to an existing node manifest YAML file (for example,
nodes/web-01.yaml). When omitted, orun bootstrap enters interactive mode and writes a new manifest to nodes/<name>.yaml.What bootstrap does
Once it has a manifest,orun bootstrap:
- Connects to the remote host over SSH using the configured key.
- Detects or installs Docker or Podman on the host.
- Copies the
orunbinary to the node. - Creates and enables a systemd service unit.
- Verifies the service started successfully.
Run
orun bootstrap from the root of your manifest repository so that the generated nodes/<name>.yaml file lands in the right place to be committed alongside your other manifests.orun start
Start the orun agent loop on this node.orun bootstrap creates — you do not need to run it manually under normal circumstances.
Most users never invoke
orun start directly. The systemd service created during bootstrap manages the agent lifecycle. Use systemctl status orun and journalctl -u orun -f to inspect it.Example (systemd unit invocation)
Flags
Name of this node. Must match the metadata name in your node manifest. This value is used to scope status reporting.
URL of the manifest git repository that this node tracks (for example,
git@github.com:org/manifests.git).Directory on the node where
orun stores its local state, including the cloned manifest repository.Directory on the node containing source code used for local image builds. Only relevant when deployments use a local build context.
How often the agent polls the manifest git repository for changes. Accepts Go duration strings such as
5s, 30s, or 1m.Port on which the status HTTP API listens. The API binds to
localhost only. See the status API reference for endpoint details.Path to the age private key file used to decrypt SOPS-encrypted secrets. When omitted,
orun checks the SOPS_AGE_KEY_FILE environment variable and then falls back to /opt/orun/keys/age.key. If no key is found, the agent starts without a decryptor and logs a warning.HTTP port for the embedded Caddy ingress server.
HTTPS port for the embedded Caddy ingress server.
orun local
Configure the current machine as a local orun node — without SSH.orun local uses the Docker socket available on your machine directly. Local configuration is stored in a .orun/ directory in the repository root (which orun gitignores automatically), so it does not appear in your manifest history.
This is useful for testing your manifests on your development machine before deploying to a remote node.
Run
orun local from the root of your manifest repository. The command uses the current working directory as the repository root.