opschain agent dev
packs:agentspacks:agent-governancepacks:ai-agents
One foreground command for the agent development loop, no ceremony: it starts an embedded server over a SQLite home on loopback, silently mints an identity, manifest and registration token for the developer's agent (exactly the objects production holds), enrols it into a sandbox project, supervises the agent process beside it, and serves the full agent tree on the loopback API.
opschain agent dev [-- <agent-command> [args...]]
A trailing -- <agent-command> is supervised (restarted on exit) and
fronted; alternatively --target fronts an already-running local process.
With either, the chat capability is declared by default when no
--capability is given. On start the command prints the dev server URL and
home, the generated admin token (default profile), the agent's surface URLs
(…/{healthz,readyz,info,metrics,logs,…}) and Ctrl-C stops the loop (the agent says goodbye first).
In the default profile a trust profile is also seeded: an
assets-under-management assignment plus an AUTONOMOUS grant over the sandbox
project, edited afterwards with the same opschain admin trust verbs
production uses.
Flags
| Flag | Meaning |
|---|---|
--listen <addr> | Loopback listen address for the dev server (default 127.0.0.1:7726 — fixed so the agent's saved identity stays valid across runs of the same home). |
--project <code> | Sandbox project the agent enrols into (default local). |
--name <name> | Agent display name (default dev). |
--code <code> | Agent code under /api/projects/<project>/agents/ (default dev). |
--target <url> | Front an already-running local process instead of supervising one. Mutually exclusive with a -- command. |
--transport auto|stream|poll | Channel transport (default auto). |
--type <type> | Declared agent type (vocabulary): service or ai. Local-mode dev needs no entitlement, but on a licensed server AI-type enrolment requires the packs:agent-governance + packs:ai-agents entitlements (a hard dependency of AI-type enrolment). |
--owned-by <name> | Declared owning user or group — validated against the server's identity catalog at registration; the local sandbox has no identity backend, so it stores unvalidated there. |
--purpose <text> | Declared purpose/label disclosure (any type): what this agent is for. |
--model <ref> | AI model disclosure as <provider>/<model>[@version], e.g. anthropic/claude-sonnet-4-5@20250929. Required with --type ai. |
--adapter <ref> | AI adapter/SDK disclosure as <name>[@version], e.g. opschain-claude-adapter@1.0. Required with --type ai. |
--tool-surface <tools> | Disclosed estate tools the agent wields, comma-separated — e.g. request_lane,docs,asker_reads. Required with --type ai. |
--custody <mode> | Model-credential custody disclosure: brokered, agent-host or vault-to-host. Required with --type ai. |
--capability name[=json] | Declare an optional capability (repeatable; default: chat when a target/command is given). |
--dev-home <path> | Dev server state directory (default: <opschain home>/agent-dev). |
--strict | Seed nothing: registration-token ceremony and token-gated telemetry run exactly as production enforces them. The enforcement code is identical in both profiles — they differ only in which rows exist at t=0. |
--token <token> | Agent registration token (--strict; mint with opschain admin agent-token create). |
--admin-token <token> | Admin bearer token for the dev server (--strict: required; default profile: generated and printed). |
With --strict and no --token, no agent is enrolled: the command prints
the exact opschain admin agent-token create invocation to mint one and
keeps the server running so you can.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Clean shutdown (Ctrl-C). |
| 1 | The embedded server, enrolment or the agent loop failed. |
| 2 | Usage error. |
Named errors
give either an agent command to supervise or --target, not both--transport must be auto, stream or poll--strict runs the full production ceremony: pass --admin-token--capability needs a name (name or name=<json-config>)
All exit 2.
Examples
Supervise an agent process with the default sandbox:
opschain agent dev -- python my_agent.py
Front an already-running process, declaring a capability explicitly:
opschain agent dev --target http://127.0.0.1:9000 --capability chat
Production ceremony end to end:
opschain agent dev --strict --admin-token <token> --token <registration-token>
See also
opschain docs cli/agent— the production agent daemon this loop develops against.