> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# orun CLI reference: bootstrap and start commands

> Complete reference for the orun CLI: bootstrap to provision nodes over SSH, start to run the agent loop, and local to configure a development node.

`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.

```bash theme={null}
orun bootstrap [node-manifest]
```

**Without an argument**, `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:

```bash theme={null}
orun bootstrap nodes/web-01.yaml
```

### Interactive prompts

When you run `orun 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/`        |

After answering, `orun` writes `nodes/<name>.yaml` and prints the path before continuing.

### Argument

<ParamField path="node-manifest" type="string">
  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`.
</ParamField>

### What bootstrap does

Once it has a manifest, `orun bootstrap`:

1. Connects to the remote host over SSH using the configured key.
2. Detects or installs Docker or Podman on the host.
3. Copies the `orun` binary to the node.
4. Creates and enables a systemd service unit.
5. Verifies the service started successfully.

After bootstrap completes, no ongoing SSH access is required. The node operates autonomously.

<Note>
  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.
</Note>

***

## orun start

Start the orun agent loop on this node.

```bash theme={null}
orun start [flags]
```

The agent polls the manifest git repository on the configured interval, reconciles the desired state with the running containers, and exposes a status HTTP API. This command is typically invoked by the systemd unit that `orun bootstrap` creates — you do not need to run it manually under normal circumstances.

<Note>
  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.
</Note>

### Example (systemd unit invocation)

```bash theme={null}
orun start --node-name=web-01 --repo=git@github.com:org/manifests.git
```

### Flags

<ParamField path="--node-name" type="string" required>
  Name of this node. Must match the metadata name in your node manifest. This value is used to scope status reporting.
</ParamField>

<ParamField path="--repo" type="string" required>
  URL of the manifest git repository that this node tracks (for example, `git@github.com:org/manifests.git`).
</ParamField>

<ParamField path="--data-dir" type="string" default="/opt/orun/">
  Directory on the node where `orun` stores its local state, including the cloned manifest repository.
</ParamField>

<ParamField path="--code-dir" type="string" default="/var/lib/orun/code">
  Directory on the node containing source code used for local image builds. Only relevant when deployments use a local build context.
</ParamField>

<ParamField path="--poll-interval" type="string" default="5s">
  How often the agent polls the manifest git repository for changes. Accepts Go duration strings such as `5s`, `30s`, or `1m`.
</ParamField>

<ParamField path="--status-port" type="string" default="9100">
  Port on which the status HTTP API listens. The API binds to `localhost` only. See the [status API reference](/reference/status-api) for endpoint details.
</ParamField>

<ParamField path="--age-key-path" type="string">
  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.
</ParamField>

<ParamField path="--caddy-http-port" type="number" default="80">
  HTTP port for the embedded Caddy ingress server.
</ParamField>

<ParamField path="--caddy-https-port" type="number" default="443">
  HTTPS port for the embedded Caddy ingress server.
</ParamField>

***

## orun local

Configure the current machine as a local orun node — without SSH.

```bash theme={null}
orun local
```

Run this command from the root of your manifest repository. Instead of connecting to a remote host, `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.

<Note>
  Run `orun local` from the root of your manifest repository. The command uses the current working directory as the repository root.
</Note>