Actor Settings

actor.sh reads its configuration from settings.kdl files written in KDL. This is where roles, agent defaults, and hooks live.

Where it lives

Two files are read, in order:

1. ~/.actor/settings.kdl — your user-wide config.
2. <cwd>/.actor/settings.kdl — project config, from the directory you run in. There's no walk-up: it's the current directory's .actor/ or nothing.

A built-in baseline is layered underneath both (it provides the main role and the default git-safety on-discard hook). Later files override earlier ones.

Top-level keys

name "studio-laptop"          // the daemon's mDNS display name
repo_dir "/home/me/.actor/repos"  // base dir for repos cloned from peers

The role block

A named preset — agent, system prompt, defaults — applied by name. Full details in Roles.

role "reviewer" {
    agent "claude"
    description "Careful code reviewer"
    prompt "You are a meticulous reviewer..."
    use-subscription #true
    config permission-mode "auto"
}

The defaults block

Per-agent defaults applied to every session of that agent, before any role:

defaults "claude" {
    use-subscription #true
    config model "claude-sonnet-4-6"
}

defaults "codex" {
    config sandbox "danger-full-access"
}

The hooks block

Shell commands for lifecycle events — see Hooks:

hooks {
    on-start "echo started $ACTOR_NAME"
    on-discard "my-cleanup"
}

Cancelling with #null

Sometimes a broad layer sets a key you want off for a narrower one. The #null value is a cancel marker: it removes a value inherited from a lower layer rather than setting a new one.

defaults "claude" {
    config model #null   // opt out of a model set elsewhere
}

How config is merged

When a session is created, its final configuration is built by layering, from weakest to strongest:

1. Agent baseline — actor.sh's built-in defaults (e.g. permission-mode=auto for Claude).
2. defaults "<agent>" — your per-agent block.
3. The role — its config, use-subscription, and system prompt.
4. Explicit overrides — values you pass on the command (--agent, --use-subscription, …).
5. Pass-through args — anything you forward verbatim with --arg.

Each layer overrides the same key in the layers beneath it; #null cancels instead of setting. A role's system prompt is a separate field from the task prompt, so applying a role never competes with the --prompt you pass.

Robustness

Unknown top-level nodes are ignored rather than rejected, so a newer config file won't break an older daemon. A malformed settings.kdl is surfaced as an error rather than silently dropped — fix the syntax and the daemon picks it up on the next read.