opschain agent
packs:agents
Runs an OpsChain agent in the foreground against a server: on the first run
it registers with the --token registration token, then it holds the
agent-initiated channel open and serves the built-in five-surface minimum
spec (healthz, readyz, info, metrics, logs) through the tunnel. The server
address resolves through the global target precedence — --server <url>,
OPSCHAIN_SERVER, or the active context — the same way every other
server-facing command finds its server.
This is the production daemon-side entry point. For a one-command local
development loop (embedded server, auto-enrolment, no ceremony) use the
dev subcommand:
| Subcommand | Page |
|---|---|
agent dev | opschain docs cli/agent-dev |
Flags
| Flag | Meaning |
|---|---|
--server <url> | Server base URL (global flag; default: OPSCHAIN_SERVER or the active context). A trailing / is stripped. |
--token <token> | Agent registration token — required on the first run; afterwards the saved identity in --dir is used. |
--name <name> | Agent display name (default: hostname). |
--code <code> | Per-project-unique agent code (default: the name; a code fixed on the token wins). |
--dir <path> | Agent state directory (default: <opschain home>/agent). |
--transport auto|stream|poll | Channel transport (default auto). |
--target <url> | Base URL of a local process to forward declared capabilities to (e.g. http://127.0.0.1:9000). |
--capability name[=json] | Declare an optional capability (repeatable), e.g. chat or x-doctor. An empty config takes the capability's default. |
--release <name>@<version> | The signed agent release this instance runs (default: $OPSCHAIN_AGENT_RELEASE); verified at enrolment and bound to the instance. A start that declares a different release than the state directory enrolled with re-enrols the instance (the restart-from-release contract) and needs --token. |
--lane <lane> | The lane this instance serves: stable (default), shadow, canary or a label (default: $OPSCHAIN_AGENT_LANE). |
--restart-mode exec|exit | How a platform-instructed restart from a release is performed: exec re-executes this process from the artifact fetched and verified against the release; exit ends the process with code 75 for the process manager or container platform to restart it on the image the release names. Default: exit inside a container, exec on a host ($OPSCHAIN_AGENT_RESTART_MODE). |
--artifact-store <dir|url> | Where exec-mode restarts fetch release artifacts by their content-addressed reference — a directory, or an http(s) base URL (GET <store>/<reference>); default $OPSCHAIN_AGENT_ARTIFACT_STORE. |
--dir defaults under the opschain home, so the global --home moves it
too.
Instances and the platform-instructed restart
Every opschain agent process is one instance of the agent named by
its code: a second state directory started with the same code enrols a
second instance (the server answers already_exists only when a fresh
keypair presents the instance id of a process that is still live). The
state directory remembers the instance id, its lane and the release it
enrolled with.
A release rollover (opschain admin agent rollover) drains the instance
and sends it restart_from_release over its own channel. The runtime
acknowledges, finishes what it holds, says goodbye and restarts: in
exec mode it fetches the artifact from --artifact-store by the
release's content-addressed reference, verifies its SHA-256 against the
release's digest (a reference that is not a sha256: digest refuses,
naming exit mode as the way), and re-executes itself with
OPSCHAIN_AGENT_RELEASE set; in exit mode — a container cannot
replace its own image — it exits with code 75 and the container
platform's restart policy brings it back on the image the release names.
Either way the restarted process re-enrols the same instance (same id,
same keypair) from the new release, verified at enrolment, and dispatch
resumes. The log line is platform: restart from release <name@version> instructed (<mode> mode); draining, then restarting.
Signals
SIGTERM or SIGINT drains gracefully: the agent says goodbye to the server
and the process prints stopping: saying goodbye to the server (signal again to stop hard). A second signal stops hard.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Clean shutdown. |
| 1 | Registration or the channel loop failed. |
| 2 | Usage error (no server target, bad --transport, malformed --capability, bad --release or --restart-mode). |
| 75 | A platform-instructed restart in exit mode: restart this process on the image the release names. |
Named errors
--transport must be auto, stream or poll--capability needs a name (name or name=<json-config>)--release is named <name>@<version>--restart-mode must be exec or exit
All exit 2.
Examples
First run, registering with a minted token:
opschain agent --server https://opschain.example.com --token <registration-token> --name build-agent
Fronting a local process with the chat capability:
opschain agent --server https://opschain.example.com --target http://127.0.0.1:9000 --capability chat
See also
opschain docs cli/agent-dev— the local development loop.opschain docs cli/runner— the work-executing daemon (runners run steps; agents serve capabilities).