saphan run · Saphan Studio documentation

Starts one process — an AI coding agent or any executable — under a mandate and records it as a run: the model, effort, budget, time limit, working directory and permissions are fixed up front, enforced where the backend allows, and written to the run record with the transcript and cost. Supported backends are proc (any executable), claude-code, codex, openai-compat (an OpenAI-compatible endpoint such as LiteLLM, Ollama or vLLM), agent-loop (Saphan Studio's own agent loop), qwen-code and droid. cursor is accepted as a name, but every cursor run is refused because its adapter is not built yet. By default an agent run's network is cut to its backend's baseline hosts; a proc run is not network-cut. A refused run is still recorded and exits with code 3; secret values never appear in the record — --env passes variable names only. Output is kept under .saphan/work/<stream>/runs/<run-id>/.

saphan run --stream demo --backend proc --actor alice \
  --binary /usr/local/go/bin/go --arg test --arg ./... \
  --workdir /path/to/repo --profile execute --wall-clock 10m

saphan run --stream demo --backend claude-code --actor alice \
  --binary '$HOME/.local/bin/claude' --model <model> \
  --effort low --budget-usd 1 --brief ./brief.md --laws /abs/path/rules.md \
  --workdir /path/to/worktree --profile execute --wall-clock 15m

saphan run

flag	type	default	what it does
`--actor`	string		Who the run is mandated by — a person's id, not the process user; defaults to `SAPHAN_ACTOR`, then the identity in your Saphan configuration.
`--allow-unknown-binary-provenance`	bool	`false`	On an ssh machine, proceed when the remote binary's SHA-256 cannot be established; the record then says `unknown`. It does not allow a binary that is missing.
`--arg`	stringArray		One argument for a `proc` executable. Repeatable, in order.
`--backend`	string		Which backend runs the work. Required, except with `--machine auto`, where it narrows the choice.
`--base-ref`	string		The base branch checked for freshness on a remote machine; normally filled in from the order.
`--base-url`	string		For `openai-compat`: the endpoint root, to which `/chat/completions` is appended. Required for that backend.
`--binary`	string		The executable to run, as an absolute path or `$HOME/…` (resolved on the machine that runs it); it is never looked up on `PATH`.
`--binary-sha256`	string		The expected SHA-256 of the binary; a mismatch refuses the run.
`--branch`	string		The stream branch to create the worktree on; without it, no worktree is created and `--workdir` must already exist. Normally filled in from the order.
`--brief`	string		The kickoff brief — the file that tells the agent what to do — for model backends.
`--budget-usd`	float64	`0`	For `claude-code`: the spending limit in US dollars passed to the vendor CLI.
`--cold-go-cache`	bool	`false`	Give this run its own empty Go build and module cache, removed when the run ends, instead of the host's shared cache; use it to check that a build works from nothing.
`--config`	string		A permission class, as inline JSON or, with `--file`, a path to a class file. It can only narrow what a `proc` run may execute; its `PATH` and environment entries apply to every backend.
`--confinement`	string		Ask for the container jail for this run only; `container` is the only accepted value, and anything else is refused as `confinement-flag-not-container`. Omitted, the configured confinement applies.
`--contact`	string		Who to ask about this stream, copied from the order; recorded as an unverified hint and never used to authorise anything.
`--cost-estimate-usd`	float64	`0`	An estimate of the run's cost, recorded so `saphan cost` can compare it with the actual cost.
`--dry-run-arg`	stringArray		For `proc`: an argument for the executable's dry-run form, which declares that it supports a planning pass. Repeatable.
`--effort`	string		The reasoning effort to request; enforced where the backend supports it, and its absence recorded where it does not.
`--effort-strict`	bool	`false`	Refuse the run when the backend cannot enforce `--effort`, as with `codex` or `openai-compat`.
`--egress-open`	string		Open this run's network, with your reason in your own words. A blank reason is refused, and so is combining it with `--egress-policy`; the reason and the dispatching actor are written on the run record as `open:<reason>, <actor>`.
`--egress-policy`	bool	`false`	Judge this run by your installation's own egress policy document (`<state dir>/egress/policy.json`, edited on the console's Egress page) instead of the backend's baseline. It is refused before the run starts if the document is missing or malformed, or if the machine cannot enforce it.
`--env`	stringArray		The name of an environment variable to pass to the run in addition to the backend's baseline. Repeatable; values are never recorded.
`--ephemeral`	bool	`false`	Ask the vendor CLI not to keep its session; not allowed with the `plan` profile.
`--expect-repo`	string		The repository this run was checked against when it was composed; the run is refused if it would use another. Filled in by `saphan dispatch`.
`--expect-repo-id`	string		The identity of `--expect-repo` when it was composed, so that a different repository at the same path is refused. Filled in by `saphan dispatch`.
`--file`	bool	`false`	Read `--config` as a path to a permission-class file rather than inline JSON.
`--force-dyad`	bool	`false`	Override the lock that allows one run per stream and role at a time. Anyone who runs the command can give this flag; nothing checks that the actor is the owner. The overridden refusal and the actor are written on the run record.
`--force-usage-reading`	bool	`false`	Run on a seat whose latest usage reading shows its plan window spent while another seat has capacity. Anyone who runs the command can give this flag; nothing checks that the actor is the owner. The overridden refusal and the actor are written on the run record.
`--git-user-email`	string		The git author and committer email the run commits as; give it with `--git-user-name`. Defaults to `run.git_user_email` in configuration.
`--git-user-name`	string		The git author and committer name the run commits as; give it with `--git-user-email`. Defaults to `run.git_user_name`; a remote or seated run with neither set is refused.
`--headroom-preflight`	bool	`false`	Before starting, probe candidate places for free capacity and use the result in this run's placement check; each probe costs a small billed model turn and takes time.
`--identity`	string		The seat on `--machine` to run under; omitted, it is chosen only when the machine has exactly one seat.
`--inner-budget`	duration	`0s`	For `agent-loop`: a time budget inside `--wall-clock`; zero derives it from `--wall-clock`.
`--interactive`	bool	`false`	Open a person's role session on one seat in this terminal instead of starting an agent run: with `--role master`, `advisor` or `scribe` and `--identity`, everything else is read from the record. No run is recorded.
`--lane`	string		For `agent-loop`: the configured lane to use. Its endpoint and credential name come from this host's configuration and override the remote host's; the credential's value is read on the machine that runs it.
`--laws`	string		The absolute path of the standing-rules file the agent receives. Required for model backends; it is re-read and placed in the prompt on every start and resume, its SHA-256 is recorded, and an empty or unreadable file refuses the run.
`--machine`	string		The admitted machine to run on; whether it runs locally or over ssh comes from the machine's registry entry. `auto` lets the engine choose and reserve the first available seat for the role.
`--max-iterations`	int	`0`	For `agent-loop`: the maximum number of model turns; zero uses the default of 25.
`--max-tokens`	int	`0`	For `agent-loop`: the per-request token limit; zero uses the endpoint's default, and values under 256 are refused.
`--mode`	string		The operating mode — `full`, `economy` (the default) or `standby`. It is recorded on the run but not enforced.
`--model`	string		The model to use. Required for model backends; it is never left to the vendor's default.
`--no-channel-skeleton`	bool	`false`	Do not write the role's channel files into the workdir before the run starts; for benchmarks and runs outside the fleet.
`--no-recording`	bool	`false`	Do not record this run: no recording proxy, no audit file and no model transcript, and the run record says who opted out. It has no effect on a run the guardrail judges, which is always recorded.
`--outside-write-dir`	stringArray		Request write access to a directory outside the workdir; refused unless a signed disposition grants it. Repeatable.
`--profile`	string		The capability profile: `plan` (a planning pass that `--resume` later continues) or `execute`. Required.
`--provision`	stringArray		Copy a file or directory into the workdir before the run, as `<source>=<destination in the workdir>`; each copy is recorded by digest. Repeatable.
`--require-capability`	stringArray		A capability the target machine must have, such as `loopback-listener`. Repeatable.
`--require-egress-cut`	bool	`false`	Refuse before the run starts, as `egress-unavailable`, unless the target machine has a measured way to cut network access. Without it an agent run is still cut by its egress policy (a `proc` run is not cut); this flag only moves the refusal ahead of the start.
`--resume`	string		Continue the recorded vendor session with this key — the second pass of a planning run. It never forks a session or picks "the last one".
`--review-topology`	string		For `--role review`: `direct` (the review runs in the reviewed stream's own worktree) or `courier` (it runs on its own review stream). Required with that role and refused with any other.
`--reviewed`	string		For `--role review`: the stream being reviewed, including its round suffix when the round is numbered. Required with that role and refused with any other.
`--role`	string		The role this run carries: `master`, `executor`, `review`, `design`, `scribe` or `advisor`. A seat reserved for another role refuses the run.
`--run-id`	string		The run id to record the run under, normally supplied by `saphan dispatch place`; omitted, the run creates its own. Not allowed with `--machine auto`.
`--slot`	int	`0`	The slot on `--machine` to reserve; omitted, it is taken from the seat named by `--identity`.
`--stream`	string		The stream the run belongs to. Required.
`--track`	string		The track this stream belongs to, copied from the order; never inferred from the stream name.
`--version-arg`	string		For `proc`: the argument that makes the executable print its version, so the version is recorded.
`--wall-clock`	duration	`0s`	The time limit, such as `10m`; when it expires, the whole process group is killed. Required.
`--workdir`	string		The absolute working directory. Required. For agent backends the run cannot write outside it; a `proc` executable is not confined to it.

Global options apply to every command — see Every command.