polygraph config

polygraph config

polygraph config opens an interactive two-pane editor for ~/.polygraph/config.json. The editor covers the most commonly configured settings: per-agent and per-repo options. The config file itself supports more than the editor exposes; see the config file reference below.

polygraph config is interactive and does not support --json.

Left pane — the editable tree, organized into two groups:

• Agent Options — one row per agent (Claude, Codex, OpenCode). The first item under each agent is the plugin item, which shows a status chip (plugin installed, plugin not installed, checking plugin..., installing plugin..., or plugin install failed). Press i on the plugin item to install or reinstall the agent's plugin. Below it are the agent's trust and sandbox fields.
• Repo Options — one row per configured repository, each exposing createUsing, trust, and sandbox. Press a to add a repo from your account.

Right pane — contextual help for the focused property. As you move the selection, the right pane updates to explain the focused field or plugin item, including its install location.

polygraph config validate

Validate the local Polygraph config file.

polygraph config validate

Schema violations are reported as warnings and don't fail the command. Invalid JSON is fatal: if the file can't be parsed, the command errors out.

Options

Flag	Type	Description
--help, -h	boolean	Show help for the current command
--version	boolean	Show the version number for the CLI

---

Config file reference

All Polygraph settings live in ~/.polygraph/config.json. The interactive editor manages the two most commonly configured keys, agentOptions and repoOptions. Everything else is edited directly in the file. The complete schema is written to ~/.polygraph/schema.json and referenced from the file's $schema key, so editors with JSON-schema support can provide completion and validation for every setting.

Key	Managed by	Description
agentOptions	polygraph config	Per-agent settings: trust, sandbox, extraArgs, env.
repoOptions	polygraph config	Per-repo settings: createUsing, trust, sandbox.
repoStrategy	hand-edited	Default materialization strategy and per-repo overrides.
setupScripts	hand-edited	Local overrides for repo setup scripts.
multiplexer	hand-edited	Terminal multiplexer used for session panes.
gitProtocol	hand-edited	Preferred clone protocol (ssh or https).
globalRoot	hand-edited	Where session folders are created.
agentType	Polygraph CLI	Default agent for new sessions.
selectedUrl	Polygraph CLI	Selected Polygraph environment URL.
$schema	Polygraph CLI	Points at the generated schema.json.

Annotated sample

{
  "agentOptions": {
    // Per-agent settings. Valid keys: "claude", "codex", "opencode".
    "claude": {
      "trust": true,      // Skips per-action permission gating for this agent.
      "sandbox": true,    // Runs the agent inside a sandbox.
      "extraArgs": ["--verbose"],  // Extra CLI args for the agent process.
      "env": {
        "HTTP_PROXY": "http://localhost:8080"  // Extra env vars injected into the agent process.
      }
    },
    "codex": {
      "trust": true,
      "sandbox": true
    },
    "opencode": {
      "trust": false
    }
  },
  "repoOptions": {
    // Per-repo settings. Keyed by full repo name (org/repo).
    "acme/api": {
      "createUsing": "worktree",  // How Polygraph materializes the working copy.
      "trust": false,             // Per-repo trust override (overrides agentOptions value).
      "sandbox": true             // Per-repo sandbox override.
    },
    "acme/frontend": {
      "createUsing": "clone"
    }
  }
}

agentOptions

Keyed by agent name. Valid keys are claude, codex, and opencode.

Field	Type	Description
trust	boolean	Whether the agent runs trusted (skips per-action permission gating) by default.
sandbox	boolean	Whether the agent runs inside a sandbox by default.
extraArgs	string[]	Extra command-line arguments passed to the agent process.
env	object (string → string)	Extra environment variables injected into the agent process.

extraArgs and env are not exposed in the interactive editor and have to be edited directly in the file.

Per-agent defaults

When an agent has no entry in agentOptions (or omits a field), its effective trust and sandbox fall back to these built-in defaults:

Agent	Default trust	Default sandbox
Claude	✓ on	✓ on
Codex	✓ on	✓ on
OpenCode	✗ off	not supported

Sandbox

Claude and Codex agents run inside an OS-level filesystem sandbox by default. The sandbox belongs to the agent harness — Claude Code uses Seatbelt on macOS or bubblewrap on Linux; Codex uses its own workspace-write sandbox. Polygraph configures the sandbox through each harness's settings.

Platform support differs by harness:

• Claude Code — macOS, Linux, and WSL2. The sandbox cannot engage on native Windows, so Polygraph disables it there.
• Codex — macOS, Linux, and Windows. Codex's sandbox works on Windows using a restricted-token boundary.

The sandbox restricts where the agent can write. Only these paths are writable:

• ~/.npm
• ~/.polygraph/logs
• ~/.polygraph/bundles
• The system temp directory
• The current session root (~/.polygraph/sessions/<session-id>/)
• The repository working tree

The repository working tree is in the allowlist, so the agent can edit source files, run builds, run tests, and run git commands normally. But the sandbox keeps the agent's own configuration directory read-only — .claude/ for Claude, .codex/ for Codex.

This means a git rebase or git checkout can fail if it needs to update files under the agent's configuration directory (for example, .claude/skills/ checked into the repo). In practice this is rare — the agent can still commit, push, and create branches normally.

Note

Polygraph's own push-time git pull --rebase runs outside the agent sandbox, so pushing a branch still works. The limitation is only when the agent itself runs a rebase or checkout inside the session.

Configuration

Disable the sandbox globally for an agent type:

{
  "agentOptions": {
    "claude": {
      "sandbox": false
    }
  }
}

Disable it for a single repository:

{
  "repoOptions": {
    "nrwl/ocean": {
      "sandbox": false
    }
  }
}

With the sandbox on (the default), the agent is more constrained but you get maximum isolation. Polygraph's push command handles pre-push pull-rebase for you, so pushes still work even with the sandbox enabled.

Configuring the sandbox through the agent harness

The sandbox boolean above is a convenience on/off toggle. Because the sandbox belongs to the agent harness, you can also configure it in detail through each harness's own settings. Polygraph generates its own settings on every launch (Claude's --settings flag, or Codex's -c overrides and --sandbox/--add-dir flags) that enable the sandbox and set the writable roots.

Claude Code

Sandbox settings live in Claude Code's settings files: ~/.claude/settings.json (user), or the project's .claude/settings.json / .claude/settings.local.json. The relevant keys are under the sandbox object:

Key	Type	Description
sandbox.enabled	boolean	Whether the sandbox is enabled (macOS, Linux, WSL2)
sandbox.filesystem.allowWrite	string[]	Additional writable paths
sandbox.filesystem.denyWrite	string[]	Paths denied for writes
sandbox.filesystem.denyRead	string[]	Paths denied for reads

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.cache"],
      "denyWrite": ["./secrets"]
    }
  }
}

Array settings (allowWrite, denyWrite, denyRead) are merged across all settings scopes — paths you add are combined with Polygraph's generated list, not replaced. Scalar values like sandbox.enabled follow normal precedence, where Polygraph's --settings takes priority. See Claude Code's sandbox settings documentation for the full schema.

Codex

Codex sandbox is configured in ~/.codex/config.toml (or the project's .codex/config.toml) and via CLI flags (--sandbox, --add-dir). The sandbox mode is set with sandbox_mode; Polygraph uses workspace-write when the sandbox is on. The available modes are read-only, workspace-write, and danger-full-access. The relevant config keys are under the [sandbox_workspace_write] table:

Key	Type	Description
sandbox_mode	string	Sandbox mode: read-only, workspace-write, or danger-full-access
sandbox_workspace_write.writable_roots	string[]	Additional writable paths
sandbox_workspace_write.network_access	boolean	Whether outbound network access is allowed

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = ["/Users/YOU/.cache"]

In workspace-write mode, .codex/ is kept read-only even when the rest of the workspace is writable. See Codex's advanced configuration documentation for the full schema.

Turning the sandbox off removes filesystem isolation

Without the sandbox, the agent can write anywhere its OS user can. Only disable it when you understand and accept the risk.

Environment inheritance

Child agents inherit the environment of the shell where you started the Polygraph session. Provider-routing variables like ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN reach child agents this way.

agentOptions.<agent>.env entries override inherited values with the same key. Use env to pin a value for a specific agent type regardless of what the shell provides.

extraArgs semantics

extraArgs are appended to the child agent's command line after Polygraph's own flags. Repeated flags resolve last-wins, so extraArgs can override Polygraph's defaults. For example, adding ["--model", "claude-opus-4-5"] to a Claude entry overrides the model Polygraph would otherwise use.

Model selection

Polygraph never forces a model on child agents. Each child resolves its model from that agent's own configuration, as if you launched the agent yourself.

Default resolution by agent:

• claude: its own settings, the ANTHROPIC_MODEL environment variable, or the CLI default.
• codex: the model setting in ~/.codex/config.toml.
• opencode: the model setting in opencode.json (provider/model format).

To pin a model for all children of a given agent type, add it to agentOptions:

• claude: "extraArgs": ["--model", "<model-id>"] (repeated flags resolve last-wins) or "env": {"ANTHROPIC_MODEL": "<model-id>"}.
• codex: "extraArgs": ["-c", "model=<model-id>"] (Codex accepts -c key=value config overrides on the command line).
• opencode: set the model in your OpenCode configuration file.

Proxy-backed environments

When Claude is routed through an Anthropic-compatible proxy, such as a GitHub Copilot-backed endpoint, set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in your shell. Child agents inherit those variables automatically. No env entry is needed for them.

If the proxy's model catalog uses different identifiers than Anthropic's, pin the model in agentOptions. A complete example combining agentOptions and repoOptions:

{
  "$schema": "~/.polygraph/schema.json",
  "agentOptions": {
    "claude": {
      "trust": true,
      "sandbox": true,
      "env": {
        "ANTHROPIC_MODEL": "<provider-model-id>"
      }
    },
    "codex": {
      "trust": true,
      "sandbox": true
    }
  },
  "repoOptions": {
    "acme/api": {
      "trust": false
    },
    "acme/frontend": {
      "createUsing": "worktree"
    }
  }
}

ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN are inherited from the shell and don't need to appear in env. You'd only add them here to override what the shell provides for a specific agent type. env and extraArgs are agent-level only. There's no per-repo override for them.

repoOptions

Keyed by repository full name (for example acme/api).

Field	Type	Description
createUsing	strategy	How Polygraph materializes the repository working copy for the session.
trust	boolean	Per-repo override of the effective trust for any agent operating in this repo.
sandbox	boolean	Per-repo override of the effective sandbox for any agent operating in this repo.

createUsing strategies

createUsing accepts one of three strategies as a bare string:

Value	Description
clone	Polygraph clones the repo into the session folder.
worktree	Polygraph creates a git worktree from an existing local clone.
superset	Polygraph uses a superset working copy shared across repos.

Most repos only need the bare string form:

{ "createUsing": "worktree" }

Each strategy also accepts an object form with a type discriminator and per-strategy options:

• worktree accepts an optional base (path to the local clone).
• superset accepts an optional include (string array of repos to group) and sectionName.

{ "createUsing": { "type": "worktree", "base": "/path/to/local/clone" } }

Resolution rules

The effective trust and sandbox for an agent working in a repo is resolved along this chain, where the most specific value wins:

built-in per-agent default  →  agentOptions[<agent>]  →  repoOptions[<repo>]

A repoOptions[<repo>] value overrides the agent-level value, which overrides the built-in default. A field that isn't set inherits from the previous layer. An explicit false does not fall through: setting trust: false at the repo or agent level turns it off. extraArgs and env are agent-only and have no per-repo override.

Some examples:

• Claude's built-in trust default is true. In a repo with "trust": false under repoOptions["acme/api"], Claude runs untrusted because the per-repo value wins.
• A repo with no trust field in repoOptions inherits the agent's value: true for Claude, and OpenCode's built-in default of false for OpenCode.
• Setting agentOptions.opencode.trust = true makes OpenCode trusted in every repo that doesn't override it, since the agent layer beats the built-in default.

repoStrategy

The default materialization strategy for repositories that don't set their own createUsing, plus per-repo overrides:

{
  "repoStrategy": {
    "default": "worktree",
    "overrides": {
      "acme/api": "clone"
    }
  }
}

Both default and each override accept the same values as createUsing. When a session materializes a repo, the strategy resolves in this order:

repoOptions[<repo>].createUsing  →  repoStrategy.overrides[<repo>]  →  repoStrategy.default

The built-in default is clone. The repo a session is started from is always used in place and ignores these settings.

setupScripts

Local overrides for the setup script that runs after a repo is materialized into a session. Keyed by repo full name; * wildcards are supported:

{
  "setupScripts": {
    "acme/api": "pnpm install",
    "acme/*": { "script": "./scripts/setup.sh", "mode": "replace" }
  }
}

A bare string is shorthand for { "script": "...", "mode": "after" }.

• after runs after the repo's server-configured setup script.
• replace replaces the server-configured setup entirely. When several replace patterns match the same repo, the most specific one wins; a literal repo name beats a wildcard.

Malformed entries are skipped with a warning.

multiplexer

Which terminal multiplexer Polygraph uses to open session panes. One of auto, none, tmux, iterm2, kitty, ghostty, cmux, or zellij. auto detects one from the environment.

gitProtocol

Preferred git clone protocol for Polygraph repositories: ssh or https. Overrides git/gh auto-detection, and is itself overridden by the POLYGRAPH_GIT_PROTOCOL environment variable.

globalRoot

The directory where Polygraph creates session folders. Defaults to ~/.polygraph/sessions. The POLYGRAPH_ROOT environment variable takes precedence.

CLI-managed keys

Polygraph writes these itself and they rarely need to be edited by hand:

• agentType is the default agent (claude, codex, or opencode) for new sessions. When unset, Polygraph detects one from the environment.
• selectedUrl is the Polygraph environment URL the CLI is signed into.
• $schema points at the generated schema.json next to the config file.