Config Reference
The keys actor.sh interprets, the defaults it sets per agent, and how every other key is forwarded.
actor.sh keeps a deliberately small set of config keys of its own and forwards everything else to the agent binary. This page is the compact lookup; the guides (Claude, Codex, settings.kdl) have the prose.
Interpreted by actor.sh
| Key | Type | Effect |
|---|---|---|
use-subscription | bool | When true, drops the agent's API-key env var (ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for Codex) so a subscription login is used. |
use-subscription is the one key actor.sh acts on directly rather than passing
through. It's also a first-class --use-subscription flag on actor new.
Defaults actor.sh sets
Applied automatically to every session of that agent; override like any other key.
| Agent | Default keys |
|---|---|
| Claude | permission-mode = auto |
| Codex | sandbox = danger-full-access, a = never |
System prompt
A role's prompt is delivered per agent, not as a config
key you set directly:
| Agent | Delivery |
|---|---|
| Claude | --append-system-prompt <prompt> |
| Codex | -c collaboration_mode.settings.developer_instructions=<prompt> |
Everything else is forwarded
Any other key becomes a flag on the agent binary — a multi-character key model
forwards as --model, a single-character key like Codex's m forwards as -m.
actor.sh keeps no allow-list; whatever flags your installed claude or codex
accepts, you can drive through config.
Setting keys
| Scope | Where |
|---|---|
| All sessions of an agent | defaults "<agent>" { config … } in settings.kdl |
| A class of session | a role's config { … } block |
| One session, raw | --arg <flag> --arg <value> on actor new |
Cancelling
A more specific layer removes an inherited value with the #null cancel marker
instead of setting a new one:
defaults "claude" {
config model #null
}
The full precedence order — agent baseline → defaults → role → explicit
overrides → pass-through --arg — is in
Actor Settings.