CLI concepts

The command reference is generated from the declared operations and lives at Command reference. This page holds what a command list cannot carry: how an instance chooses its workspace, the in-session /mission command, and the environment variables the CLI reads.

Workspace authority

One instance serves exactly one workspace, fixed at launch. There is nothing to select afterwards, and no client anywhere offers a picker.

Which directory that is depends on the shape:

Shape	The workspace is
contenox-cli beam, contenox-cli run	the directory you started it in
contenox-cli acp	whatever the editor opened — per the protocol, the client owns the cwd

A client does not propose a working directory and the runtime does not offer a menu of them. An app or an editor discovers instances and the sessions they are already holding, and attaches to one; the workspace is a property of the instance it attached to. Serving a second workspace means starting a second instance — which is also how the process list says so.

The runtime’s own control plane (~/.contenox and a workspace’s .contenox — its config, database, and policies) is never a workspace, on any shape. There is no setting that turns this off.

A mission dispatched from an instance inherits that instance’s workspace: a unit cannot be given a working directory the session that fired it could not have opened.

The /mission slash command

Missions are the dual of chat mode. In chat you prompt turn by turn and approve each gated action yourself. In mission mode you fire a one-line intent at a registered agent under an envelope — a HITL policy that bounds what it may do unattended — and keep working; the unit acts inside the envelope, and only crossing it costs your attention.

From inside a session (contenox-cli beam, or an editor over contenox-cli acp) fire a mission without leaving the conversation:

• /mission — fires nothing. Prints the grammar, the defaults in force, and every envelope on the policy search path with its character: what a call no rule matches does, the unattended tool-call ceiling, and whether an agent may answer the unit’s questions.
• /mission <intent> — fires the configured default-mission-agent under the default-mission-policy envelope.
• /mission <agent-name> <intent> — fires the named agent instead.
• /mission --policy <envelope> [agent-name] <intent> — bounds this one mission under a different envelope. --policy=<envelope> is accepted too. Flags must come before the agent and intent, so a -- inside an intent stays literal text.

Envelopes are discovered the way the runtime’s policy loader resolves them — the workspace .contenox/, then ~/.contenox/, then each of their .generated/ directories, first match wins — so an envelope transpiled from [envelopes.<name>] in agents.toml is offered beside any hitl-policy-*.json you wrote yourself, and where both exist the top-level copy is the one listed. The picker stats the filesystem on every call rather than caching a startup snapshot, so an envelope you add mid-session shows up on the next /mission. A name that resolves to no file is refused in the session, with the available names listed, instead of dispatching a unit under a fallback nobody chose.

The two agent forms are the same shape, so contenox resolves the first token against the declared-agent registry: a hit is the named form, a miss means the whole line is the intent for the default agent. The confirmation states which agent was chosen, the envelope, where that envelope came from (--policy or default-mission-policy), and the envelope’s character — so the bounds just accepted are in the transcript, not only in a config file.

Beta: naming a user-authored agent (a custom chain-agent-* chain) requires contenox-cli config set features.beta.enabled true (or CONTENOX_OPT_IN_BETA=1) and its interface may change; /mission itself and the shipped agent-planner work without it.

The dispatch runs in-process: the fired unit is a child subprocess of the calling session’s own process, no daemon is needed, and the unit’s reports stream live back into the firing session as they land. A mission with no agent or no envelope is refused. The hardened acpx profile never offers /mission.

The oracle needs no /mission equivalent: it mounts on the ACP host itself, from contenox-cli config set execution.oracle.chain, so every subagent this session fires — through /mission, /plan, or the mission_start tool — is already covered. Whether it may rule on a given subagent’s asks is the envelope’s attention bounds, not a per-command flag.

Environment variables

Variable	Description
CONTENOX_ACP_CHAIN_PATH	Override the chain file used by contenox-cli acp sessions
CONTENOX_ACPX_CHAIN_PATH	Override the chain file used by headless ACPX sessions
CONTENOX_DEFAULT_MODEL / CONTENOX_DEFAULT_PROVIDER	Process-level override of the configured default model/provider (nothing is persisted). Also the ACP env_var auth-method contract for non-interactive setup.
CONTENOX_DEFAULT_ALT_MODEL / CONTENOX_DEFAULT_ALT_PROVIDER	Same, for the alt model pair.
CONTENOX_DEFAULT_MAX_TOKENS / CONTENOX_DEFAULT_THINK	Same, for the response token cap and reasoning level.
CONTENOX_BASE_URL	Endpoint URL for account-specific providers whose URL cannot be defaulted (e.g. Vertex: project + region).
CONTENOX_OPT_IN_BETA	Per-invocation override of the opt-in-beta config key (1/true enables the beta features, any other value disables them; unset falls back to config).
CONTENOX_SANDBOX_NETWORK_WALL	Set to 1 to build the agent sandbox’s network wall with no route at all, for a fully offline foreign agent.
CONTENOX_TOKEN_KEY_FILE / CONTENOX_TOKEN_KEY	The deployment’s token signing key, read by contenox-cli gateway serve and gateway key create. The file form is preferred. Without it the gateway enforces no key ledger: every license your authority signed is accepted and none can be revoked. The pre-gateway names RELAY_TOKEN_KEY_FILE / RELAY_TOKEN_KEY are still read as a fallback.
CONTENOX_POSTGRES_URL	Move the store off the SQLite file onto a Postgres database. Requires CONTENOX_NATS_URL and CONTENOX_VALKEY_URL too — see External backends for state.
CONTENOX_NATS_URL	Move the message bus off the database onto a NATS server (nats://host:4222; comma-separate a server list).
CONTENOX_VALKEY_URL	Move the key-value cache off the database onto a Valkey server (valkey://host:6379, or a bare host:6379). Add a user, a database index and a key namespace to keep it out of the way of whatever else uses that server: valkey://appuser:secret@host:6379/3?namespace=contenox — see Isolating contenox inside a Valkey you already run.

SANDBOX_SHELL_SCRUB, SANDBOX_TERMINAL_SCRUB, SANDBOX_ENV_ALLOW, and SANDBOX_ENV_DENY configure the shell environment scrub — see Least-privilege shell environment for their modes and current status.