torusv0.24.0docs

Configuration

torus reads its settings from three layers with one precedence rule; this page is the canonical guide to all of them. It covers the unified config.json under the torus home and its registered sections, the single-value knob sections and the environment-variables table, the other files under the torus home, the project-level rules, the torus.sandbox file policy, engine-owned pi settings, and the CLI and in-session inspectors that report effective state.

The three layers and precedence

torus resolves settings from three layers:

  • User layer: ~/.torus/ holds the unified config.json and acp.json; the engine’s user dir ~/.pi/agent/ holds settings.json, models.json, mcp.json, and auto-discovered skills.
  • Project layer: files inside the working repository: .torus/config.json, the .pi/ files (settings.json, mcp.json, lsp-client.json), .agents/skills/, and the AGENTS.override.md / AGENTS.md / CLAUDE.md instruction chain. Project .pi files are trust-gated: torus reads them only for a project you have trusted.
  • Session layer: environment variables and launcher flags, attached to the process rather than written to disk.

Precedence for any one setting, highest first: launcher flag over env var over user config over project config over built-in default. A flag wins by setting the env var for one session; a layer that is unset falls through to the layer beneath it.

The unified config file

User-level torus config lives in one file: config.json under the torus home (TORUS_HOME, default ~/.torus), the single user-level source for every section below. The file is user-level by construction, so a repo checkout cannot set it for a session.

SectionConfigures
chainsModel chains per tier plus compatible-provider endpoints; built-in chain providers are credential-gated at resolution (presence-only across the provider’s env var, the engine’s auth.json, and a models.json apiKey; no credential value is ever read or logged), a credential-less provider prints one startup notice naming its env var and its chain entries filter out, chain models a delegation walk or member bootstrap judged no-work, or an ambient title call watched fail to answer, sit out 5 minutes in one shared session-scoped memo that every chain consumer resolves through (naming a model explicitly bypasses the cooldown), and walk rejections surface in the transcript as fallback notes (live in the delegate tool block and trailing the result text)
automodeAuto permission-mode rules and circuit-breaker settings
serveHTTP server bind, port, token path, and scheduled triggers (auth is runtime state)
keywordsKeyword rows injected into the system prompt
permissionModeDefault permission mode (top-level key, not an object)
rosterDelegation knobs: background execution, child session storage

A section that is not a JSON object warns, names the section, and reads as unset. A config.json that cannot be parsed reads as an empty config with one warning, so every consumer degrades to its defaults instead of failing.

Knob sections and environment variables

Single-value knobs live in their own sections (ui, sessionTitle, guards, hashline, interactive, monitor, notify, commentChecker, team, reflection, approval, roster, wake), one key each; the environment-variables table below maps each env var to its config key. Knob precedence is env over config over default, and a config value of the wrong type is ignored, so the default applies.

permissionMode is a top-level scalar rather than a section: "auto" or "default" sets the default permission mode under TORUS_PERMISSION_MODE (the --permission-mode launcher flag sets the env var for one session). A defined env value decides its tier outright, even when unrecognized; the config key counts only when exactly "auto" or "default", and "bypass" is refused with a warning (bypass is startup-only: sessions must be launched with the flag or env var, so it can never be a sticky default); anything else warns and is treated as unset.

Rows carrying a config key also read that key from the unified config (env still wins); the rest are env-only.

VariableConsumerPurpose
TORUS_PI_BINlauncherExplicit engine binary path (overrides node_modules/.bin/pi)
TORUS_BOOTSTRAPlaunchernetwork = bootstrap the payload’s dependencies over npm instead of extracting the binary’s bundled dependency tree (the default; binaries boot offline)
TORUS_ROOTlauncher → registryPayload root override (source layout otherwise)
TORUS_ENGINElauncher sets, ui readsEngine tag (display)
TORUS_ENGINE_BINlauncher sets, roster/engine-child readEngine binary for child spawns
TORUS_ENGINE_CHILDengine-child sets, worktrees + work readMarks delegated children; gates worktree tool registration (internal)
TORUS_MEMORY_COMMIT=1memory sets, store pre-commit hook readsMarks in-process git spawns on the memory store; agent-run commits are refused (internal)
TORUS_HOMEfsutilBase dir for torus state (default ~/.torus)
TORUS_STATE_DIRfsutilExported in every torus process (main session, delegated children, team members): this project’s state root, so skills, prompts, and bash commands use $TORUS_STATE_DIR/… instead of hand-derived dashed keys. Main sessions compute it from cwd (kept fresh); engine children treat the inherited value as authoritative (the dispatching session pins them to its root, so $TORUS_STATE_DIR paths and ledger appends land in the dispatching project even from a worktree cwd). Explicit-cwd resolution (sandbox hosts) always computes fresh, and delegation logs land in the dispatching session’s root: a child running in another cwd never grows its own state dir. Tool output abbreviates state paths to $TORUS_STATE_DIR/… ($TORUS_HOME/… for other projects’) via displayPath
TORUS_SCRATCH_DIR / TORUS_SCRATCH_RETENTION_DAYSfsutilDurable scratch root for agent work products (clones, intermediates that must survive a reboot): exported in every torus process (main session, delegated children, team members), so skills, prompts, and bash commands use $TORUS_SCRATCH_DIR/… instead of hand-derived temp paths. Defaults to $TORUS_STATE_DIR/scratch; an explicit override relocates it, and children inherit the value pinned to the dispatching project, like TORUS_STATE_DIR. Tool output abbreviates paths under it to $TORUS_SCRATCH_DIR/…. Ephemeral tooling temp is a different class: per-session scratch under /tmp (mktemp, TMPDIR) is unchanged and correct for that class. TORUS_SCRATCH_RETENTION_DAYS sets how many days a scratch entry may sit unused before the session-start sweep removes it (default 14; 0 disables sweeping); the sweep is best-effort and conservative: an entry with any file newer than the cutoff stays (config: fsutil.scratchRetentionDays)
TORUS_TMUX=0fleet/panesDisable delegation tmux panes
TORUS_DELEGATE_BACKGROUND=0rosterForce delegation tools back to blocking even when called with background: true (config: roster.delegateBackground)
TORUS_WAKE_COALESCE_MS=<ms>wake-gateIdle-side wake debounce: wake markers queued while the session is idle (monitor fires, bg exits, background delegations, member wake-ups) hold up to N ms and flush as one batch (default 10000; 0 = instant flush) (config: wake.coalesceMs)
TORUS_WAKE=0wake-gateDisable the durable wake spool: undelivered wake markers (delegation results, bg exits, monitor fires) are appended to $TORUS_STATE_DIR/wake-spool/<session>.jsonl and delivered at the next session start (config: wake.spool)
TORUS_CHILD_SESSIONS=<mode>engine-child (roster, team, ACP spawns)Where delegated engine children persist their session transcripts. separate (default) redirects them to $TORUS_STATE_DIR/child-sessions, so pi’s /resume (which lists the default per-cwd session dir) shows only interactive sessions; fleet transcripts and session search read that root too. inline keeps the historical behavior (children in the default dir, visible in /resume). ephemeral runs children with --no-session, so no transcript files exist and fleet live transcripts and session search lose them; unrecognized values fall back to separate. An explicitly exported PI_CODING_AGENT_SESSION_DIR always wins (children inherit it untouched) (config: roster.childSessions)
TORUS_NOTIFY=0osnotifyDisable desktop notifications (config: notify.enabled)
TORUS_PLATFORMplatformForce platform detection (linux/darwin/win32) for the extension load gate; invalid values warn and fall back to the host platform
TORUS_GUARDS=0 / TORUS_MAX_TOOL_OUTPUTguardsDisable guards / output truncation cap (default 16000) (config: guards.enabled / guards.maxToolOutput)
TORUS_HASHLINE=0 / TORUS_FMT_CMDhashlineDisable anchoring / post-edit formatter command (config: hashline.enabled / hashline.fmtCmd)
TORUS_INTERACTIVE=0interactiveDisable interactive_bash overlay (config: interactive.enabled)
TORUS_INTERACTIVE_DEBUG=<path>interactiveAppend raw PTY chunks, emulator query responses, and child exit to a file (interactive_bash diagnostics for stalled flows)
TORUS_MONITOR=0monitorDisable monitors (config: monitor.enabled)
TORUS_BG=0monitorDisable background tasks (config: monitor.bg)
TORUS_STATUSLINE_COST=0uiDisable the session-cost statusline chip (config: ui.statuslineCost)
TORUS_BANNER=0uiKeep pi’s built-in startup header instead of the torus banner (config: ui.banner)
TORUS_TITLE_MODEL=provider/modelsession-titleOverride the session-title generator model (default: the fast chain walked candidate-by-candidate, each try capped at 15s of stream silence with provider retries off, durable failures and quota/plan-limit errors marking the shared no-work cooldown while plain rate limits stay unmarked, then the session model; config: sessionTitle.titleModel)
TORUS_TEAM_NOTIFY=0teamDisable the per-member idle/crash wake-up markers (result markers still render) (config: team.teamNotify)
TORUS_TASK_STALE_MIN=<minutes>teamStale-task threshold for team_status: an in_progress task under an idle member with no tasklist update for more than N minutes renders a read-only stale line (default 30; invalid values fall back to 30) (config: team.taskStaleMin)
TORUS_COMMENT_CHECKER=0 / TORUS_COMMENT_CHECKER_PROMPTcomment-checkerDisable / override the challenge text (config: commentChecker.enabled; TORUS_COMMENT_CHECKER_PROMPT is env-only)
TORUS_WORKTREES_ROOTworktreesWorktree root override (default $TORUS_HOME/worktrees)
TORUS_APPROVAL=0approvalDisable the trust-on-denial dialog (unmatched hosts deny; config: approval.enabled)
TORUS_PERMISSION_MODEautomodeOpt into LLM-classified bash auto-approval (1/on/auto; unset or 0/off/default keeps the built-in gate; bypass disables every permission guard, startup-only) (config: top-level permissionMode)
TORUS_INCOGNITO=1launcher sets (--incognito), memory + monitor + registry + incognito readRun memoryless: idle reflection and dream consolidation gate off, manual /reflect refuses, and on session start and exit the project state dir loses its logs, monitors, bg, reflect-state, plans, work, goal, todo, and wake-spool dirs (child-session transcripts are kept: pi rewrites them live and the child-sessions layout already keeps them out of /resume). A run launched without the flag writes everything normally; the mode is per-session, never sticky config
TORUS_PERMISSION_MODELautomodePin the permission classifier as provider/model-id (default: first available classifier, then the fast chain’s first authed chat model, then the session model)
TORUS_SANDBOX / TORUS_SANDBOX_WRITABLE / TORUS_SANDBOX_NET_ADD / TORUS_SANDBOX_NET_ONLY / TORUS_SANDBOX_DEFAULTsandboxPer-command sandbox (off | full, default off: full/on/1 sandboxes agent bash; unset runs unsandboxed unless TORUS_SANDBOX_DEFAULT=full opts the environment into default-on; unknown values fall back to the effective default with a notice; confines writes to workspace+tmp+extras, network restricted to a curated exact-host allowlist of dev-workflow hosts, registries, GitHub incl. release assets, core toolchains, and *.amazonaws.com) / extra writable roots, colon-separated / comma-separated extra allowed hosts (exact-host; over-broad entries dropped) / comma-separated hosts replacing the curated allowlist / environment default for unset TORUS_SANDBOX (full/on/1 enables; any other value is inert)
TORUS_REFLECTION=0memoryDisable idle reflection (config: reflection.enabled)
TORUS_REFLECT_TURNS=<n>memoryReflect after N settles since the last reflect (0 = idle-only; default 12) (config: reflection.reflectTurns)
TORUS_DREAMING=0memoryDisable dream consolidation (config: reflection.dreaming)
TORUS_THEME_DEBUGpersona-themeTheme debugging
TORUS_SERVE=0serveKill switch: torus serve refuses to start (exit 1)

Files under the torus home

Two files under the torus home are configuration; the rest of the directory is state torus mints as it runs.

config.json is the unified config file (above). acp.json under TORUS_HOME (default ~/.torus) declares external ACP-speaking agents as delegatable children, which the acp section of the extension reference consumes. Shape {"agents": {"<name>": {"command": "…", "args": […], "env": {"KEY": "value"}}}}; args defaults to [], and env is merged over the inherited child environment. An absent file means no ACP agents and the engine delegation path is untouched. Malformed JSON, a non-object root, or a bad entry warns on stderr and skips only that entry.

Name resolution: an exact name match in acp.json wins over a roster agent of the same name. The requested name is looked up there before the roster, and a name resolving nowhere is rejected naming both the roster agents and the configured ACP agent set (torus_roster and the roster section of the system prompt list configured ACP agents too).

The remaining files are behavior side-effects, state rather than config: torus writes them as it runs, and nothing reads them back as settings.

PathHolds
~/.torus/serve/auth.jsonThe serve bearer token, minted at first start (docs/serve.md)
~/.torus/serve/triggers-state.jsonPer-trigger lastFired times and webhook secrets (docs/serve.md)
$TORUS_STATE_DIR/sandbox-hosts.jsonHosts approved “Always allow (this project)” in the sandbox trust dialog ($TORUS_STATE_DIR is the per-project state root under ~/.torus/state/)
~/.torus/teams.jsonThe global team index: team id to project key
~/.torus/memory/The git-backed memory store
~/.torus/runs/One JSON run record per run (delegations and team members), keeping runs fleet-visible across processes and sessions; running records are count-capped (oldest first), finished records are pruned by age and kept 7 days
$TORUS_STATE_DIR/child-sessions/Session transcripts of delegated engine children (default TORUS_CHILD_SESSIONS=separate); transcripts sit directly under the root, resumable with pi --session-dir <root> --session-id <id>. scripts/migrate-child-sessions.mjs relocates pre-existing child sessions out of pi’s default session dir: ids come from delegation/team logs across every state root, and its --unnamed pass also moves sessions torus never named (children carry no name; named sessions are interactive). Forks (parentSession), anything modified within the hour, and named sessions always stay; dry-run unless --apply

Project-level configuration

A project-level .torus/config.json in the session’s working directory is read with the same tolerance and may set exactly the knob sections ui, sessionTitle, guards, hashline, interactive, monitor, notify, commentChecker, team, and reflection, plus the automode section’s deny and ask keys. approval is a knob section but deliberately not project-readable: a checked-in repo must not be able to silence the trust dialog. Knob precedence is env over the user file over the project file over default; the automode contribution is a tightening-only union (project deny/ask entries add to the user’s rules, never replace them). Every other top-level key in the project file, and any widening automode key (allow, environment, hardDeny, softDeny, softDenyExceptions, classifyAllShell), is refused with one warning: a checked-in repo must not be able to widen its own permissions, redirect model traffic, inject prompt keywords, or opt sessions into automode. torus config status reports the project file’s readable sections and refused keys.

Instructions and skills are project-level too: torus reads the AGENTS.override.md / AGENTS.md / CLAUDE.md chain per directory (see docs/instructions.md), and project skills drop into .agents/skills/ (see docs/skills.md).

The torus.sandbox file policy

Sandbox behavior is file-configured through pi settings files, layered under the env-only TORUS_SANDBOX* knobs the sandbox section documents. The policy lives under "torus" → "sandbox" inside those files; everything else in them is ignored.

KeyShape
mode"off" or "full"
writableExtra writable roots
hostsadd, only, and deny host lists
credentialsfiles and envVars to mask inside the sandbox
exemptCommands exempt from sandboxing
envEnv vars to set inside the sandbox
sign.relayBoolean: relay ssh commit signing through the host agent

Two layers read the policy:

  • User layer: settings.json under $PI_CODING_AGENT_DIR (default ~/.pi/agent), read unconditionally.
  • Project layer: .pi/settings.json in the working directory, read only for a trusted project, and additive-only: it may contribute writable, hosts.add, hosts.deny, env, and sign.relay. mode, exempt, hosts.only, and credentials are refused with a poison notice naming the key and the file: a committed file must not be able to weaken the sandbox. Project env keys never shadow user keys.

Engine config surfaces

Engine-owned configuration torus users can ride directly; behavior follows the engine’s docs (mcp.md, models.md, and the engine changelog under node_modules/@earendil-works/pi-coding-agent/). torus’s own code touches none of it, with one exception: the ui extension reads quietStartup when it paints the startup banner.

SurfaceWhat it gives
Project MCP overridesA file-configured server (project .pi/mcp.json, read only after project trust; user-level ~/.pi/agent/mcp.json likewise) takes precedence over torus’s in-session registerMcpServer registrations: context7 and grep_app can be replaced or disabled per-project without code; /mcp lists the overridden registration and /reload picks up file changes
MCP OAuth clientRegistration: "cimd"Identifies pi by its Client ID Metadata Document on pi.dev instead of dynamic client registration, for authorization servers that allow-list clients by that URL; cannot be combined with clientId or clientName
samplingParamsByThinkingLevelmodels.json per-model map of sampling parameters keyed by pi thinking level (off, minimal, low, medium, high, xhigh, max), merged over the model’s samplingParams per key; applies only to the openai-completions, openai-responses, and azure-openai-responses APIs. The engine’s built-in GLM catalog entries set none, so a user-supplied entry has full effect
Azure provider renameThe engine renamed azure-openai-responses to azure (engine changelog 1.0.3, inside torus’s pin): rename the provider key in auth.json, models.json, and settings.json (defaultProvider, enabledModels, modelThinkingLevels); AZURE_OPENAI_* env vars are unchanged
quietStartupA ~/.pi/agent/settings.json key the ui extension honors: true silences the startup banner, and the string "header" keeps the header row while hiding the loaded-resources details (TORUS_BANNER=0 restores pi’s built-in header instead)
.pi/lsp-client.jsonCustom LSP server declarations for the pi-lsp-client section of the extension reference
models.json endpointsThe engine’s own model-endpoint declarations under ~/.pi/agent/models.json; delegated children rely on them, since they spawn without torus’s provider registrations

CLI and in-session inspectors

The launcher owns these surfaces and intercepts each before the pi passthrough: the process is the surface, never an engine session.

SurfacePurpose
torus serveAuthenticated HTTP server over the delegation core; routes and auth live in docs/serve.md
torus acp-agentACP v1 agent over stdio for editors; see the ACP agent section of docs/serve.md
torus config statusReports the unified config’s effective state (below)
torus --permission-mode auto|default|bypassSets TORUS_PERMISSION_MODE for one session; bypass disables every permission guard and is startup-only
torus --version (-v)Prints torus and engine versions

torus config status prints one line per registered section with its effective source (config.json or default), one line per config.json key the registry does not know, and the project-level file’s report: its readable sections and any refused ones.

In session, slash commands inspect the same surfaces: /doctor for extension health, /automode for the live permission mode and rules, /login for provider authentication, and /mcp for MCP server status, including file-configured overrides.

Schemas for what you can extend live next to their surfaces: agent frontmatter in docs/agents.md, skill manifests in docs/skills.md, and the pi-package manifest in docs/pi-packages.md.