Saphan StudioDocs
Reference/Commands

saphan guardrail-proxy

Runs one command behind a local proxy that records, and optionally judges, the text exchanged between an AI client and its model provider.

Runs one command behind a local proxy that records, and optionally judges, the text exchanged between an AI client and its model provider. Saphan Studio places this wrapper around the sessions it starts itself, so you rarely type it; running it by hand is useful for testing a guardrail plugin. The proxy starts before the command, stops when the command ends, listens only on loopback or a Unix socket, and the command's exit status becomes this command's exit status. Without --enabled nothing is proxied and the command runs unchanged.

saphan guardrail-proxy --enabled --listen 127.0.0.1:0 --upstream https://api.example.invalid \
  --codec claude-messages --record-only --audit /abs/run/guardrail.jsonl \
  --address-env EXAMPLE_BASE_URL -- <command> [args...]
saphan guardrail-proxy --enabled --listen <addr> --upstream <url> --codec <name> -- <command> [args...]
flagtypedefaultwhat it does
--address-argv-placeholderstringA token in the command's own arguments that is replaced with the proxy's address, for clients that read no environment variable; a token that appears nowhere is refused.
--address-envstringArrayThe name of an environment variable set to the proxy's address in the command's environment; repeatable.
--address-profile-homestringA JSON plan for clients that read their API address from a configuration file: a per-run copy of that configuration is made with the proxy's address written in, and the original files are never modified.
--auditstringAbsolute path of this run's audit file (JSON lines), normally inside the run's own work directory; required with --enabled, and appended to rather than overwritten. If it cannot be opened, nothing runs.
--codecstringThe provider's wire format: claude-messages, chat-completions, responses, droid-chat-completions, droid-openai-chat-completions, qwen-chat-completions or qwen-responses; any other name is refused.
--enabledboolfalseTurns the proxy on; without it no proxy starts, no plugin loads, and the command runs exactly as it would without this wrapper.
--enforce-actsstringAbsolute path of a file of signed owner decisions; enforce mode only takes effect for a plugin and stage that a verified decision here names, otherwise the stage runs in observe and says why.
--listenstring127.0.0.1:0Where the proxy listens: a loopback host:port (default 127.0.0.1:0, a free port) or unix:<absolute path>. Any other address is refused, because the proxy carries your provider credential and must not be reachable from another host.
--plugin-artifactstringAbsolute path of the guardrail plugin executable; its checksum must match the one in the plugin manifest or the start is refused.
--plugin-digeststringThe SHA-256 of the plugin manifest file's exact bytes, in lower-case hex; a mismatch refuses the start.
--plugin-manifeststringAbsolute path of the guardrail plugin's manifest on this host.
--record-onlyboolfalseRecords the run without judging anything: traffic is forwarded and logged, no plugin is loaded and no call is ever stopped. Cannot be combined with the plugin or mode flags.
--request-modestringobserveobserve (default) records the plugin's decision on each request; enforce stops a request the plugin blocks or fails to answer, but only when --enforce-acts authorises it.
--response-modestringobserveobserve (default) records the plugin's decision on each response; enforce withholds a response until the plugin allows it, but only when --enforce-acts authorises it.
--transcript-dirstringAbsolute path of a directory where a transcript of the model exchange is written; without it no transcript is kept.
--transcript-run-idstringThe run identifier stamped on every transcript event; defaults to the name of the transcript directory's parent.
--transcript-streamstringThe stream (unit of work) the transcript belongs to, signed into each transcript segment; without it the transcript is written unsigned.
--upstreamstringThe provider's base URL that the proxy forwards to; required with --enabled.

Global options apply to every command — see Every command.

saphan guardrail

Inspects the model-text guardrail — the plugins that judge the text passing between an agent and its model — and prepares the owner's act that switches a stage to enforcement.

saphan hand

Records that a coordinating agent is handing the owner one decision to make on a stream, with the exact command to run and the output of its rehearsal.