CLI reference

Everything in orch runs through one executable, orch. The same binary sets up controllers and workers, deploys applications, and opens the TUI and the web dashboard. This page lists every command the CLI accepts, grouped by task, with its flags and their defaults.

Run any command with --help to print its flags, for example orch deploy --help. orch help prints the full usage summary.

Conventions

Selecting a cluster

Commands that talk to a controller (remote commands) need to know which cluster to use. orch picks one in this order:

  1. --target NAME on the command line (also written --target=NAME).
  2. The ORCH_TARGET environment variable.
  3. The ORCH_TOKEN environment variable, an access token from orch token create.
  4. The selected target, set with orch target use or orch target add.
  5. On the controller host, when no target is selected, the local administrator socket at /var/lib/orch-controller/admin.sock. Only root can open it.

If none of these apply, the command stops with:

$ orch nodes
no target is selected; run 'orch target add NAME ssh://root@CONTROLLER' or 'orch target use NAME'

--target may appear anywhere before a -- separator and only once. Pass it explicitly in scripts and CI so a command never runs against the wrong cluster:

orch deploy --wait --target production

--context FILE names an administrator context file directly. It remains for compatibility and cannot be combined with --target. See targets and interfaces for how targets are stored and reached.

These are the remote commands: join-token, status, events, deploy, rollback, nodes, logs, exec, remove, job, secret, registry, notify, tui, web, app list|status|history|diff|watch, cron runs|logs, network configure, and every node subcommand except node install and node doctor. All other commands run locally.

Flags and output

  • Flags use Go flag syntax: --flag value, --flag=value, and the single-dash forms -flag are all accepted.
  • Most commands that take positional arguments also accept flags after them, for example orch logs hello web --tail 50. Commands that print "accepts flags only" take no positional arguments.
  • --json prints machine-readable JSON on stdout. With --json, errors are also written as JSON ({"error": "...", "problems": [...]}) on stderr.
  • Streams such as logs and job output write the workload's stdout to stdout and its stderr to stderr.

Idempotency keys

Commands that change cluster state send an idempotency key so a retry after a lost reply does not apply the change twice. orch generates a key when you omit --idempotency-key. deploy, remove, rollback, network configure, and job run|retry print the key they used, and the node update commands include it in their error message, so you can retry with the same value:

orch deploy --idempotency-key idem_4f2a9c0d7e1b3a5c6d8e0f1a2b3c4d5e --target production

Keys for deploy, remove, network configure, node, and rollback must be 16 to 128 characters: letters, digits, ., _, :, and -, starting with a letter or digit.

Exit codes

Code Meaning
0 The command succeeded
1 Operational failure, such as an unreachable controller or a failed rollout
2 Usage error or manifest validation failure

Cluster setup

orch init

orch init [--name NAME] [--advertise-address IP] [--port 9443] [--recovery-dir DIR] [--wait-timeout 2m] [--json]

Installs a controller on this host as a systemd service and waits until it answers. Run it as root on the controller host.

Flag Default Purpose
--name orch Cluster name
--advertise-address detected Address workers and clients use to reach this host
--port 9443 Controller port, 1024 to 65535
--recovery-dir none Also write a day-zero recovery set to this new directory
--wait-timeout 2m Maximum wait for controller readiness
--json false Emit machine-readable JSON

The controller listens on 0.0.0.0:PORT and advertises https://ADDRESS:PORT. A break-glass administrator context is written to /etc/orch/admin. See installation.

orch join-token

orch join-token NODE [--ttl 1h] [--target NAME] [--json]

Creates a single-use join token for a worker called NODE and prints the orch join command to run on it.

Flag Default Purpose
--ttl 1h Token lifetime, from 1m through 24h
--json false Print the token id, node name, expiry, token, and command as JSON

orch join

orch join TOKEN|- [--advertise-address IP] [--wait-timeout 5m] [--json]

Installs a worker on this host with a token from orch join-token. Run it as root on the worker. Pass - instead of the token to read it from stdin, which keeps it out of the process list.

Flag Default Purpose
--advertise-address detected IPv4 address other nodes use to reach this host
--wait-timeout 5m Maximum wait for agent readiness
--json false Emit machine-readable JSON
sudo orch join - < worker-1.token

orch cluster doctor

orch cluster doctor --server HTTPS_URL --listen ADDRESS [--json]

Checks whether this host can run a controller and prints each check with its fix. It exits with 1 when the host is not ready.

Flag Default Purpose
--server required Canonical controller HTTPS URL
--listen required Controller IP listen address
--json false Emit machine-readable JSON

orch cluster install

orch cluster install --name NAME --server HTTPS_URL --listen ADDRESS --admin-dir DIR [--recovery-dir DIR] [--dry-run] [--wait-timeout 2m] [--json]

Installs a controller like orch init, but lets you choose the URL, listen address, and where the administrator directory is written.

Flag Default Purpose
--name required Cluster name
--server required Canonical controller HTTPS URL
--listen required Controller IP listen address
--admin-dir required New portable administrator directory
--recovery-dir none Optional new day-zero recovery directory
--dry-run false Inspect and show planned actions without modifying the host
--wait-timeout 2m Maximum wait for authenticated controller readiness
--json false Emit machine-readable JSON

Import the resulting context.json with orch target import.

orch cluster init

orch cluster init --name NAME --server HTTPS_URL --data-dir DIR [--context FILE] [--json]

Creates controller state in a directory without installing services. Use it when you run orch controller serve yourself.

Flag Default Purpose
--name required Cluster name
--server required Controller HTTPS URL
--data-dir required Controller state directory
--context none Write the administrator context to this path
--json false Emit machine-readable JSON

Without --context, orch stores the administrator credentials as a local target named after the cluster and selects it.

orch node doctor

orch node doctor --advertise-address IPV4 [--json]

Checks whether this host can run a worker, without changing it. It exits with 1 when the host is not ready. It always runs locally.

Flag Default Purpose
--advertise-address required Private or public IPv4 address of this host that other nodes can reach
--json false Emit machine-readable results

orch node install

orch node install --advertise-address IPV4 [--join-file FILE|-] [--dry-run] [--wait-timeout 5m] [--json]

Installs a worker from a join file created by orch node join create. It always runs locally.

Flag Default Purpose
--advertise-address required Private or public IPv4 address of this host that other nodes can reach
--join-file none Private join file path, or - for stdin
--dry-run false Show planned actions without modifying the host or reading join credentials
--wait-timeout 5m Maximum wait for authenticated agent readiness
--json false Emit machine-readable results

orch node join

orch node join create NODE --output FILE [--ttl 15m] [--idempotency-key KEY] [--target NAME] [--json]
orch node join list [--target NAME] [--json]
orch node join revoke JOIN_ID [--idempotency-key KEY] [--target NAME] [--json]

Manages join credentials. create writes a join file (mode 0600) for orch node install; list shows join credentials and their state; revoke invalidates one, including tokens from orch join-token.

Flag Default Purpose
--output required for create New join file path; must not exist
--ttl 15m Join lifetime, from 1m through 24h
--idempotency-key generated Stable key for safe retries
--json false Emit machine-readable JSON

If create is interrupted, a private FILE.pending stage remains. Rerun the same command with the same output path to finish it.

Targets

See targets and interfaces for a full walkthrough.

orch target add

orch target add NAME ssh://[USER@]HOST[:PORT] [--use] [--json]

Remembers a controller reached over SSH. orch connects once to confirm a controller answers and records the cluster's identity. Your SSH login is the credential; no certificate is stored.

Flag Default Purpose
--use false Select the new target. It is selected automatically when no target is selected yet
--json false Emit machine-readable JSON

The location can also be unix:///PATH for an administrator socket on this machine, and an SSH location can end in a socket path (ssh://root@HOST/path/to/admin.sock). Without a path, the target uses /var/lib/orch-controller/admin.sock.

orch target import

orch target import NAME CONTEXT [--use] [--replace] [--json]

Copies an mTLS administrator context, such as /etc/orch/admin/context.json, into a private target.

Flag Default Purpose
--use false Select the imported target
--replace false Replace the credentials of an existing target for the same cluster and keep its transport
--json false Emit machine-readable JSON

orch target list

orch target list [--json]

Lists remembered targets. The selected one is marked with *.

orch target use

orch target use NAME

Selects the target that remote commands use by default.

orch target transport

orch target transport NAME direct
orch target transport NAME wireguard --address HOST:PORT
orch target transport NAME ssh --host SSH_ALIAS [--destination HOST:PORT]

Changes how an imported (certificate) target reaches its controller.

Flag Default Purpose
--address required for wireguard WireGuard-reachable controller host:port
--host required for ssh OpenSSH host or alias
--destination controller URL host and port Controller host:port as seen from the SSH host

A target added with orch target add cannot switch to a certificate transport, and an imported target cannot switch to a socket transport. Add a new target instead.

orch target test

orch target test [NAME] [--json]

Connects to the named or selected target within 10 seconds and prints the cluster name.

$ orch target test production
Connected to production through target production (socket)

Applications and deployments

These commands read orch.pkl in the current directory unless you pass -f. See applications for the file format.

orch validate

orch validate [-f orch.pkl] [--root DIR] [--json]

Evaluates and validates the application file and prints its name, service and cron job counts, and digest. Validation problems exit with 2.

Flag Default Purpose
-f, --file orch.pkl Pkl manifest path
--root manifest directory Pkl evaluation root
--json false Emit machine-readable JSON

orch render

orch render [-f orch.pkl] [--root DIR]

Prints the canonical JSON that orch would submit for the application.

Flag Default Purpose
-f, --file orch.pkl Pkl manifest path
--root manifest directory Pkl evaluation root

orch plan

orch plan [-f orch.pkl] [--root DIR] [--against previous.pkl] [--json]

Lists the changes in the application file and summarizes how many items are added, changed, and removed. It runs locally: without --against it compares with an empty application.

Flag Default Purpose
-f, --file orch.pkl Target Pkl manifest path
--root each manifest's directory Pkl evaluation root
--against none Existing Pkl manifest to compare against; must have the same application name
--json false Emit machine-readable JSON

To compare against what is deployed, use orch app diff.

orch deploy

orch deploy [-f orch.pkl] [--root DIR] [--image [NAME=]REF]... [--preview N] [--wait] [--timeout 10m] [--idempotency-key KEY] [--target NAME] [--json]

Submits the application as desired state. Without --wait it returns as soon as the controller accepts it; the rollout continues in the background.

Flag Default Purpose
-f, --file orch.pkl Pkl manifest path
--root manifest directory Pkl evaluation root
--image none Deploy this image instead of the manifest's; repeatable
--preview none Deploy the preview of pull request N as APP-pr-N on pr-N. subdomains; see preview deployments
--wait false Wait for this revision to become ready, printing progress
--timeout 10m Rollout wait deadline
--idempotency-key generated Stable key for safe retries
--json false Emit machine-readable JSON

Submitting the same configuration again reports that the desired state is already current. With --wait, the result is READY, FAILED, TIMED_OUT, or CANCELED. Stopping the watcher does not cancel the deployment; resume watching with orch app watch.

--image NAME=REF replaces the image of the service or cron job called NAME for this deployment. A bare --image REF replaces it for every service and cron job whose image has the same repository, which is what CI usually wants after building one image. Each override must match something. History records the deployed image like any other.

Images you built yourself need no registry. When an image is in the local Docker (or Podman) engine and its registry does not have it, orch deploy uploads it to the controller and pins it by digest, and nodes pull it from the controller:

docker build -t myapp .
orch deploy
# Uploading local image myapp (84 MB)

An unchanged image is not uploaded again. An image the registry has, such as redis:7, is pulled from the registry as usual, even if Docker has a copy. If the image was built for another architecture than your nodes, for example on an arm64 laptop for amd64 servers, the deploy stops before uploading and tells you to rebuild with --platform. The controller keeps the uploaded images of each application's last 10 deployments, so rollbacks to them keep working. Uploaded images are not part of controller backups; after restoring a controller, run orch deploy again to upload them.

A service with static needs no image at all: orch deploy packs its folder into an image and uploads it the same way, so a container engine isn't needed. See static sites.

Inside GitHub Actions, the deployment also records the repository, commit, branch, actor and run link, shown by orch app history. See deploy from GitHub.

orch dev

orch dev [-f orch.pkl] [--root DIR] [--env-file FILE] [--http-port 8080] [--timeout 10m]
orch dev down [--volumes]

Runs the application on this machine: starts a one-node cluster in a container on the local Docker-compatible engine, adds it as target dev, and deploys the manifest to it with HTTP services at http://SERVICE.APP.localhost:8080. See local development.

Flag Default Purpose
-f, --file orch.pkl Pkl manifest path
--root manifest directory Pkl evaluation root
--env-file orch.dev.env next to the manifest Secret values as NAME=VALUE lines
--http-port 8080 Local port for HTTP services
--timeout 10m Rollout wait deadline
--volumes false With down, also delete the dev node's data

orch app list

orch app list [--target NAME] [--json]

Lists every application on the cluster with its desired generation, revision, and rollout status.

orch app status

orch app status APP [--target NAME] [--json]

Shows the desired, observed, and active generation of an application, its status and reason, every replica with its health and node, HTTP and TCP routes, node ports, and cron jobs with their next run.

orch app history

orch app history APP [--limit 20] [--before-generation N] [--target NAME] [--json]

Lists deployments, newest first, with revision, outcome, resolved images, and for deployments from GitHub Actions the commit and run that deployed them. The current and active deployments are marked.

Flag Default Purpose
--limit 20 Page size, 1 to 50
--before-generation none Show deployments older than this generation
--json false Emit machine-readable JSON

When more history exists, the output ends with the command for the next page.

orch app diff

orch app diff APP REVISION [--against REVISION] [--target NAME] [--json]

Compares a stored revision with the current desired state, or with another revision. Output is limited to 500 changes.

Flag Default Purpose
--against current desired state Revision to compare to
--json false Emit machine-readable JSON

orch app watch

orch app watch APP [--revision REVISION] [--timeout 10m] [--target NAME] [--json]

Follows a rollout until it is ready, fails, or the deadline passes.

Flag Default Purpose
--revision current desired state Revision to watch
--timeout 10m Rollout wait deadline
--json false Emit machine-readable JSON

orch rollback

orch rollback APP REVISION [--expected-generation N] [--wait] [--timeout 10m] [--idempotency-key KEY] [--target NAME] [--json]

Creates a new deployment from a stored revision, reusing its resolved image digests. Before sending the request, orch prints the exact command to retry it safely.

Flag Default Purpose
--expected-generation current generation Generation being replaced; the rollback is refused if the application has moved on
--wait false Wait for the rollback revision to become ready
--timeout 10m Rollout wait deadline
--idempotency-key generated Stable retry key; requires --expected-generation
--json false Emit machine-readable JSON

See rollbacks.

orch remove

orch remove APP [--idempotency-key KEY] [--target NAME] [--json]

Removes an application's desired state, which stops its workloads.

Flag Default Purpose
--idempotency-key generated Stable key for safe retries
--json false Emit machine-readable JSON

orch schema

orch schema

Prints the embedded Application.pkl schema that manifests amend.

orch pkl reader and version

orch pkl reader
orch pkl version

version prints the Pkl version this CLI evaluates manifests with.

reader serves the embedded schema over Pkl's external-reader protocol on stdin and stdout, so stock Pkl tooling can resolve older orch: imports. You do not run it by hand.

Status, events, and logs

orch status

orch status [--target NAME] [--json]

Shows the cluster name and ID, controller URL, generation, workload network, creation time, and when the administrator and controller certificates expire. Certificates that expire within 30 days are flagged with the renewal command.

orch nodes

orch nodes [--target NAME] [--json]

Lists every node with its lifecycle and connection state, operating system, capacity, allocatable and assigned resources, labels, network and ingress state, drain blockers, and certificate expiry.

orch events

orch events [--after SEQUENCE] [--limit 50] [--target NAME] [--json]

Prints cluster events with their sequence number, time, kind, and JSON payload.

Flag Default Purpose
--after 0 Only events after this sequence number
--limit 50 Maximum events to return, 1 to 200
--json false Emit JSON, including next_after_sequence for the next call

orch logs

orch logs APP SERVICE [--replica 1] [--tail 100] [-f | --previous] [--target NAME]

Prints the most recent log lines of one service replica and exits. With -f it keeps printing new output until you press Ctrl-C, and carries on through restarts and short disconnects, noting them on stderr.

With --previous it prints the logs of the replica's previous instance: the one a deploy, orch restart, or a failed start replaced. Nodes keep a replaced instance's logs for 24 hours, up to 256 MiB per node with the oldest dropped first. They stay on the node that ran it, so they are not found once the replica has moved to another node.

On a terminal, logs, exec, and the job and cron log commands drop control characters and escape sequences other than colors, so a workload cannot control your terminal. Piped or redirected output is passed through unchanged.

Flag Default Purpose
--replica 1 Replica ordinal
--tail 100 Maximum lines per stream, 1 to 10000
-f, --follow false Keep printing new output
-p, --previous false Show the previous instance's logs

orch restart

orch restart APP [SERVICE] [--replica N] [--target NAME]

Restarts a service, or every service of the application, with the same spec. Replicas restart one at a time, and each must be running again before the next one stops. Each replica gets its stopGracePeriod to shut down. --replica restarts just one replica.

orch exec

orch exec APP SERVICE [--replica 1] [--timeout 30] [--target NAME] -- COMMAND [ARG...]

Runs a non-interactive command inside a running replica and streams its output. A non-zero exit status from the command makes orch exec exit with 1.

Flag Default Purpose
--replica 1 Replica ordinal
--timeout 30 Timeout in seconds, 1 to 300

The command takes 1 to 64 non-empty arguments and at most 8 KiB in total.

orch exec hello web --replica 1 -- ./bin/healthcheck --verbose

orch volume

orch volume list [APP] [--target NAME] [--json]
orch volume backups APP VOLUME [--target NAME] [--json]
orch volume backup APP VOLUME [--target NAME] [--json]
orch volume restore APP VOLUME BACKUP [--target NAME] [--json]
orch volume download APP VOLUME BACKUP [--output FILE|-] [--target NAME]
orch volume move APP VOLUME NODE [--target NAME] [--json]

list shows each local volume, its worker, its backup schedule, the newest backup, and whether the last scheduled backup failed. backups lists every backup of one volume. backup takes one now, running the volume's before command first; it is labeled -manual and never pruned.

restore stops the service that mounts the volume, replaces the volume with the backup, and starts the service again. The volume's previous contents are kept as a -before-restore backup, and the command prints how to restore it.

download copies a backup archive (.tar.gz) to this machine, by default as APP-VOLUME-BACKUP.tar.gz; --output - writes it to standard output. See volume backups.

move moves the volume to NODE, together with every other volume of the service that mounts it. The service stops, a final -manual backup of each volume is copied to NODE through the controller and restored there, and the service starts on NODE. If a step fails, the service starts on its old node again with its data untouched. NODE must be active, connected, and match the service's constraints. See moving a volume.

With a backup destination, backups also lists the copies in the bucket and where each backup is stored, and restore and download fetch a backup that only the bucket still has to the volume's node first.

orch backup

orch backup destination [--target NAME] [--json]
orch backup destination set s3://BUCKET[/PREFIX] [--endpoint URL] [--region REGION] [--new-recovery-key] [--target NAME] [--json]
orch backup destination remove [--target NAME] [--json]

set makes the cluster copy every volume and database backup, and the controller's daily backups, to an S3 bucket. It checks that the bucket is writable and claims the prefix for this cluster first. Any S3-compatible service works; leave out --endpoint for AWS. The region is detected when left out. The access key comes from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or is asked for, and is stored encrypted on the controller. The first set prints a recovery key that controller backups are encrypted to before they reach the bucket; store it in a password manager, because orch cluster restore --from needs it and the controller keeps only its public half. Volume and database backups are always encrypted, to a key the controller keeps. Setting the destination again keeps the key unless --new-recovery-key is passed. Without an argument, destination shows the bucket, whether controller backups are encrypted, and whether the last copy succeeded. remove stops copying and leaves the bucket as it is. See off-host backups.

orch db

orch db list [APP] [--target NAME] [--json]
orch db backups APP DATABASE [--target NAME] [--json]
orch db backup APP DATABASE [--target NAME] [--json]
orch db restore APP DATABASE [BACKUP] [--target NAME] [--json]
orch db move APP DATABASE NODE [--target NAME] [--json]

Works with the databases declared under databases in orch.pkl. list shows each database's engine, the secret that holds its connection URL, and its backup schedule. backups and backup list and take backups of the volume that holds the database's backups. restore uses the newest backup unless BACKUP is given; for Postgres, MySQL, MariaDB and MongoDB it also loads the restored dump into the running database. move moves the database and its volumes to NODE, like orch volume move. See Databases.

Jobs

orch job

orch job run APP SERVICE [--wait] [--revision REVISION] [--timeout 15m] [--wait-timeout 20m] [--idempotency-key KEY] [--target NAME] [--json] -- COMMAND [ARG...]
orch job list [APP] [--limit 20] [--before ID] [--target NAME] [--json]
orch job show ID [--target NAME] [--json]
orch job logs ID [--tail 100] [--target NAME]
orch job cancel ID [--target NAME] [--json]
orch job retry ID [--wait] [--idempotency-key KEY] [--target NAME] [--json]
orch job wait ID [--timeout 15m] [--target NAME] [--json]

Runs and manages one-off jobs. run starts a command with the image and settings of a service in the current application revision. The other actions list, inspect, read logs of, cancel, retry, or wait for a job.

Flag Default Purpose
--wait false Wait for the exact run to finish (run, retry, cancel)
--revision none Only run if this is the application's current revision
--timeout 15m Process timeout for run; wait deadline for wait. 10s to 24h
--wait-timeout 20m Maximum time --wait waits, 1s to 24h
--limit 20 Maximum jobs for list, 1 to 100
--before none History cursor for list; printed as Next page: --before ID
--tail 100 Log lines per stream for logs, 1 to 10000
--idempotency-key generated Stable key for run or retry, printed on stderr
--json false Machine-readable output
orch job run hello web --wait -- ./bin/migrate up

See jobs for pre-deploy hooks and retry behavior.

orch cron

orch cron run APP JOB [--wait] [--wait-timeout 20m] [--idempotency-key KEY] [--target NAME] [--json]
orch cron runs APP JOB [--limit 20] [--target NAME] [--json]
orch cron logs APP JOB RUN_ID [--tail 100] [--target NAME]

run starts the scheduled job once now, with the same image, command, secrets, and read-only volume mounts as its schedule and on the node that owns the schedule. Use it to check that a backup job works without waiting for its next run. The run is a job: follow it with orch job logs ID, and with --wait the command exits nonzero unless it succeeds. runs lists recent scheduled runs with their scheduled time, state, and reason; logs prints the logs of one.

Flag Default Purpose
--wait false Wait for the run started by run to finish
--wait-timeout 20m Maximum time --wait waits, 1s to 24h
--limit 20 Maximum runs, 1 to 100
--tail 100 Maximum lines per stream, 1 to 10000
--json false Emit machine-readable JSON (runs only)

Secrets and registries

orch secret

orch secret set APP NAME --from-stdin [--idempotency-key KEY] [--target NAME] [--json]
orch secret list APP [--target NAME] [--json]
orch secret delete APP NAME [--idempotency-key KEY] [--target NAME] [--json]

Stores, lists, and deletes an application's secrets. set only reads the value from stdin, never from an argument, and accepts 1 byte to 1 MiB. list shows each name, its current version, whether the application references it, and when it was updated; it never shows values.

printf '%s' "$DATABASE_URL" | orch secret set hello database-url --from-stdin

See secrets.

orch registry

orch registry login HOST --username USER --password-stdin [--idempotency-key KEY] [--target NAME] [--json]
orch registry list [--target NAME] [--json]
orch registry logout HOST [--idempotency-key KEY] [--target NAME] [--json]

Stores, lists, and removes credentials for private image registries. The password or token is read from stdin and accepts 1 byte to 1 MiB.

Deployer and access-token credentials can only use registries on public addresses, so an image reference cannot make the controller reach hosts on its own network. A registry on a private address works for them once an administrator has logged in to it.

orch github

orch github init [--app APP] [--branch BRANCH] [--environment NAME] [--image REPOSITORY] [--domain DOMAIN]... [--previews] [-f orch.pkl] [--repo OWNER/REPO] [--force] [--target NAME] [--json]
orch github trust OWNER/REPO --app APP [--branch main] [--environment NAME] [--domain DOMAIN]... [--previews] [--target NAME] [--json]
orch github list [--target NAME] [--json]
orch github untrust OWNER/REPO --app APP [--target NAME] [--json]

Lets GitHub Actions runs of a repository deploy one application without stored credentials. Run init inside the repository's checkout: it reads the repository from the origin remote, the application from orch.pkl, and the branch from the remote's default branch, trusts the repository, and writes .github/workflows/deploy.yml. When a Dockerfile sits next to the manifest and its workloads use one image repository, the workflow builds and pushes that image before deploying; --image names the repository explicitly. trust does the same without touching the checkout and prints the workflow instead. When ORCH_CLUSTER is set and no target is given, remote commands sign in with the run's GitHub OIDC token, and ORCH_APP picks the application when the repository is trusted for several. --domain, on init and trust, limits the domains its deploys may route. --previews lets pull requests deploy and remove their own APP-pr-N, and makes init also write .github/workflows/preview.yml. See deploy from GitHub and preview deployments.

orch notify

orch notify add slack|discord|webhook [URL] [--name NAME] [--on EVENT,...] [--target NAME] [--json]
orch notify list [--target NAME] [--json]
orch notify test [NAME] [--target NAME] [--json]
orch notify remove NAME [--target NAME] [--json]

Sends cluster problems (a lost node, a full disk, a certificate close to expiry, a stale controller backup) to Slack, Discord or a webhook. add stores the URL encrypted on the controller, reading it from stdin when it is left out, and sends a test message; it exits nonzero when the test fails. --on can also name application events, which are then sent for every application. See cluster notifications.

orch token

orch token create [NAME] --app APP [--read-only] [--domain DOMAIN]... [--ttl 720h] [--target NAME] [--json]
orch token create [NAME] --admin [--ttl 720h] [--target NAME] [--json]
orch token list [--target NAME] [--json]
orch token revoke NAME [--target NAME] [--json]

Gives an agent or script access to one application, without sharing your administrator credentials. create prints a token on stdout. With it in ORCH_TOKEN, every remote command and orch mcp can deploy, roll back, and inspect APP (with --read-only, only inspect it) and nothing else. The token contains the controller address and pins the cluster CA, so no target is needed.

export ORCH_TOKEN=$(orch token create --app shop --read-only)
orch app status shop
Flag Default Purpose
--app required unless --admin The one application the token may use
--admin false Allow everything an administrator can do, for tools that manage the whole cluster; excludes --app and --read-only
--read-only false Allow status, logs, history, and diffs, but no deploys or rollbacks
--domain any Deploys may route only this domain and its subdomains, and not the public listener; repeat for more
--ttl 720h How long the token works, up to 8760h

NAME defaults to APP, or APP-read-only with --read-only, or admin with --admin. An administrator token is exchanged for a 15-minute administrator certificate, so treat it like a context file. The token is shown only once; the controller keeps only a hash of it. Each command trades it for a 15-minute certificate, so revoke takes effect within 15 minutes. list shows when each token was last used. The controller address in the token must be reachable from where the token is used.

Nodes

orch node usage

orch node usage NODE [--target NAME] [--json]

Shows a node's CPU, memory and disk use over the last 24 hours (in 5-minute buckets) next to what its replicas reserve and what it can offer. --json prints the node and its samples, which orch mcp draws as graphs.

orch node label and unlabel

orch node label NODE KEY=VALUE... [--target NAME] [--json]
orch node unlabel NODE KEY... [--target NAME] [--json]

Adds or removes node labels used by service constraints. The orch.* prefix is reserved.

orch node cordon, uncordon, and drain

orch node cordon NODE [--target NAME] [--json]
orch node uncordon NODE [--target NAME] [--json]
orch node drain NODE [--target NAME] [--json]

cordon stops new placement on a node, drain moves its movable workloads away, and uncordon makes it active again. drain prints an orch volume move command for each service a local volume keeps on the node. See node maintenance.

orch node update

orch node update NODE...|--all [--drain-timeout 10m] [--reboot-timeout 15m] [--target NAME] [--json]

Upgrades the operating-system packages of the named nodes, or of every node with --all, one node at a time: drain, upgrade with apt-get or dnf, reboot when the upgrade needs it, wait for the agent, return the node to service. Workers go first, then ingress nodes, then the controller's host. When a drain takes longer than --drain-timeout, the update goes ahead anyway. Nodes that are not connected are skipped and reported. See operating-system updates.

orch node ingress

orch node ingress NODE --enable|--disable [--target NAME] [--json]

Turns public HTTP, HTTPS, and TCP ingress on or off for a node. Exactly one of --enable or --disable is required.

orch node remove

orch node remove NODE [--lost --confirm-fenced] [--target NAME] [--json]

Removes a node from the cluster. For a node that is unreachable, pass both --lost and --confirm-fenced to confirm it can no longer run workloads.

All node update commands also accept --idempotency-key KEY.

Network

orch network configure

orch network configure --cidr CIDR [--idempotency-key KEY] [--target NAME] [--json]

Sets the private workload network.

Flag Default Purpose
--cidr 10.88.0.0/16 RFC 1918 workload CIDR, /16 through /19
--idempotency-key generated Stable key for safe retries
--json false Emit machine-readable JSON

Once a worker reports its network as ready, the network is frozen and a different CIDR is refused. Choose it before workers join. See networking.

Upgrades

orch cluster upgrade and orch node upgrade

orch cluster upgrade [--binary FILE] [--dry-run] [--wait-timeout 5m] [--json]
orch node upgrade [--binary FILE] [--dry-run] [--wait-timeout 5m] [--json]

Replaces the installed orch binary on a controller or worker with a trusted candidate and restarts its services. Run each as root on the host it upgrades. After orch cluster upgrade, the controller upgrades every worker to its own version, one node at a time, so orch node upgrade is only needed for a worker that cannot upgrade itself.

Flag Default Purpose
--binary this orch Trusted local candidate orch executable
--dry-run false Validate and show the upgrade without changing the host
--wait-timeout 5m Maximum wait for service readiness
--json false Emit machine-readable JSON

The output reports compatibility, the candidate version and SHA-256, planned actions, and a recovery path. See upgrades.

Backup and recovery

These commands work on controller files directly and run as root on the controller host or a recovery host.

orch cluster backup

orch cluster backup --data-dir DIR --output FILE [--secret-key-output FILE] [--json]

Writes a standalone copy of the controller database.

Flag Default Purpose
--data-dir required Controller state directory, /var/lib/orch-controller for installed controllers
--output required New backup database path
--secret-key-output none New path for the secret-encryption key, when one is required
--json false Emit machine-readable JSON

orch cluster backup inspect

orch cluster backup inspect --backup FILE [--pki-dir DIR] [--secret-key FILE] [--json]

Checks a backup without restoring it and reports its cluster, schema version, counts of nodes, applications, deployments, and jobs, and any missing recovery material.

orch cluster restore

orch cluster restore --backup FILE|DIR [--pki-dir DIR] [--secret-key FILE] --data-dir NEW_DIR [--json]
orch cluster restore --from s3://BUCKET[/PREFIX] [--backup NAME] [--endpoint URL] --data-dir NEW_DIR [--json]

Restores a backup into a new controller directory, which must not exist. --backup also takes one of the controller's automatic backup directories from DATA_DIR/backups, which already holds the PKI and secret key, so the other two flags are not needed. orch cluster backup inspect accepts the same.

--from downloads the newest controller backup from the cluster's backup destination instead, or the one --backup names. It reads the access key from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or asks for it, and the recovery key of an encrypted backup from ORCH_RECOVERY_KEY, or asks for it.

Flag Default Purpose
--backup required without --from Standalone database backup, an automatic backup directory, or with --from a backup name
--from none Bucket to download the backup from
--endpoint AWS S3 endpoint for --from
--region detected Signing region for --from
--pki-dir none Saved controller PKI directory
--secret-key none Saved secret-encryption key
--data-dir required New controller directory
--json false Emit machine-readable JSON

orch cluster certificates renew

orch cluster certificates renew --data-dir DIR --admin-dir NEW_DIR [--json]

Issues new controller and administrator certificates from the existing cluster CA. Restart the controller afterwards and import the new context with orch target import NAME CONTEXT --replace. After the restart, administrator certificates issued before the renewal are refused. See certificate renewal.

TUI and web dashboard

orch tui

orch tui [--target NAME] [--refresh 2s]

Opens the keyboard-driven terminal interface for the selected target. It needs an interactive terminal.

Flag Default Purpose
--refresh 2s Refresh interval, 1s through 1m

orch web

orch web [--target NAME] [--port N] [--no-open]

Serves the browser dashboard for the selected target on 127.0.0.1 and prints a one-time URL. Press Ctrl+C to stop it.

Flag Default Purpose
--port 0 Loopback port; 0 picks a free port
--no-open false Print the URL without opening a browser

See targets and interfaces for both interfaces.

orch mcp

orch mcp [--target NAME] [--read-only | --allow-destructive]

Serves the cluster to AI assistants over the Model Context Protocol on stdin and stdout. Clients such as Claude Code start it themselves; see AI assistants for setup and the list of tools.

Flag Default Purpose
--target selected target Cluster that remote tools use when a call names none
--read-only false Offer only tools that do not change the cluster
--allow-destructive false Also offer tools that delete or replace workloads, secrets and data, or run commands in replicas

orch mcp expose and approve

orch mcp expose [DOMAIN | --off] [--target NAME] [--json]
orch mcp approve CODE [--deploy | --allow-destructive] [--app APP] [--ttl 720h] [--target NAME] [--json]

expose serves the MCP server from the controller at https://DOMAIN/mcp, for any MCP client that connects by URL with OAuth. Point DNS for DOMAIN at the controller's server; its ingress gets the certificate. Without arguments it prints the current URL, and --off stops serving it.

approve lets the assistant waiting on the approval page with CODE connect. See remote MCP.

Flag Default Purpose
--deploy false Also allow rolling back, restarting, backing up, retrying jobs and running cron jobs
--allow-destructive false Allow everything the MCP tools can do, including deleting apps, changing secrets and running commands in replicas
--app every app Limit the connection to what an access token for this application can do
--ttl 720h How long the connection works, from 1h to 8760h

Services and internals

These commands are run by the systemd units that orch init, orch join, and the install commands create. You rarely run them yourself.

orch controller serve

orch controller serve --data-dir DIR --listen ADDRESS [--admin-socket PATH|off] [--mcp-listen ADDRESS|off] [--backups-keep 7]

Runs the controller process. It writes a backup into DATA_DIR/backups once a day; see backups.

Flag Default Purpose
--data-dir required Initialized controller state directory
--listen required TCP listen address, for example 0.0.0.0:9443
--admin-socket DATA_DIR/admin.sock Local administrator socket; off disables it
--mcp-listen 127.0.0.1:9444 Loopback address of the remote MCP gateway that the ingress on this host forwards orch mcp expose's domain to; off disables it
--backups-keep 7 Daily backups to keep, 0 to 365; 0 turns automatic backups off

orch agent init

orch agent init --join-file FILE|- --data-dir DIR [--json]

Enrolls an agent with a join file and writes its state directory.

orch agent serve

orch agent serve --data-dir DIR --containerd-socket PATH --advertise-address IPV4 [flags]

Runs the worker agent.

Flag Default Purpose
--data-dir required Agent state directory
--containerd-socket required containerd socket path
--advertise-address required Private or public IPv4 address reachable by the other nodes
--snapshotter overlayfs containerd snapshotter
--wireguard-port 51820 WireGuard UDP listen port
--system-reserved-cpu 500m CPU reserved for the host
--system-reserved-memory 512Mi Memory reserved for the host
--cni-bin-dir /opt/cni/bin Directory containing the CNI plugins
--caddy-binary /usr/bin/caddy Pinned Caddy executable
--ingress-user orch-ingress Unprivileged user that runs Caddy
--ingress-data-dir /var/lib/orch-ingress Private Caddy data directory owned by --ingress-user

Other commands

Command Purpose
orch version [--json] Print the version, or build information as JSON
orch help Print the usage summary
orch runtime-log-sink, orch runtime-secret-init Helpers that the agent starts inside workload runtimes; not for direct use
Edit this page on GitHub