Configuration key index

Use this index with Sonny 0.12.7 and the configuration guide . Each disclosure identifies the file key, type, default, environment spelling, command option, precedence, trust scope and when a change takes effect. Download these records for inspection. Pinned source paths and line numbers identify provenance without directing public readers into an access-controlled source repository.

These records cover root CLI values, mesh and training-service bindings, the typed resource-reuse block, variant routing and agent-messaging rollout, plus decision policy and trusted permissions . See the analysis field reference for its separate JSON patch schema, defaults and protected-layer rules. Read analysis availability , Recipe schemas , model catalogs , MCP configuration and hooks for their separate structured files and contracts. A root file is not a model catalog or Recipe, and an environment variable cannot be inferred by replacing every dot with an underscore.

The isolation configuration reference covers its separate policy/machine documents, exported schemas, raw defaults and measured schema/runtime differences.

Displayed flag defaults and source bindings do not prove that every client or command consumes a value identically. In particular, mesh serve and mesh adopt offer have distinct control-store fallback rules. Source-defined adoption and service behavior still needs the relevant mesh qualification . The value-shape examples show individual settings, including deliberately non-routable example destinations; they do not configure a ready provider, service, credential or authority grant.

Choose a root file with --config <file> and a working directory with --workdir <directory> or -C <directory>. Installed tests did not honor SONNY_CONFIG or SONNY_WORKDIR as selectors. The root file is selected from the working directory, then home; it is not merged across every ancestor. config explain uses a different, limited projection and did not agree with the tested root-file values. See inspection limits .

Parent trace disable controls do not suppress every internal MCP child trace in the installed tests. Diagnostics explains capture and redaction limits. Resource-reuse configuration acceptance also does not prove realm file replacement or delegated reuse worked.

Variant routing and approval

The variants block stages model-variant discovery and activation. It is separate from the versioned variant documents that it may discover. Its built-in mode is off, profile approval is required, and draft variants are disallowed. These three defaults were measured through the release’s exported parser; ordinary installed startup completed with that base.

validate discovers and validates without selecting; shadow selects and compiles but serves the base; on can activate an admitted selection. Installed controlled-provider runs completed in each mode with no variant catalog. That does not qualify approved variant selection or prove a candidate activated: the base can remain in use. Profile approval and variant approval are separate gates; relaxing one does not relax the other.

Root environment lookup replaces hyphens, not dots. The exact process keys are SONNY_VARIANTS.MODE, SONNY_VARIANTS.REQUIRE_PROFILE_APPROVAL, and SONNY_VARIANTS.ALLOW_DRAFT_VARIANTS. A shell’s ordinary assignment syntax does not accept dotted names; use an env command with a quoted NAME=value argument or supply a process environment map. The underscore-expanded SONNY_VARIANTS_MODE was ignored in installed startup. Bad values in each tested dotted key were read and refused. A selected root file is usually clearer than these process keys.

The source YAML parser ignores unknown members and later documents. Use one reviewed document, and do not rely on unknown-key refusal for this block. Bad modes and malformed approval booleans are refused when the runtime parser is reached. This differs from the strict analysis patch parser .

Agent-messaging rollout

The four agent_messaging switches default to false and use the exact underscore environment names shown below. These explicit overrides also take precedence over the root lookup’s raw dotted process keys, such as SONNY_AGENT_MESSAGING.LOCAL. An explicitly empty override is still an override and is refused as a malformed boolean when read. A false environment value overrode a true file value in the installed test.

local permits local messaging setup; it grants no agent identity, relationship or wake authority. The tested host refused mesh: true because mesh routing was not configured. Federation needs local messaging and protected native A2A configuration paths. The rollout resolver accepts a clean absolute path shape before checking that a file exists; file ownership, TLS material, peer grants and transport startup are later checks. Neither these settings nor the parser tests qualify a working federation deployment.

The source idle-wake helper requires local messaging, and a wake still needs a durable relationship policy and tenant budget. Installed startup with local messaging disabled did not refuse idle_wake: true: it completed an ordinary controlled model turn. That expected-refusal assertion remains failed. This case proves no mail-triggered wake or messaging capability.

Variant and messaging blocks are operator settings. Installed untrusted working-file attempts to replace them were ignored. The source confinement restores the operator’s home subtree. An explicit --config selects operator configuration. Use the disabled host-rollout example as a value-shape reference; it enables neither routing nor messaging.

Validation coverage

config validate --json exited 0 for both a bad variant mode and a bad messaging boolean in installed tests. Its analysis report is not a validator for these rollout blocks. Ordinary startup refused the tested bad variant values, malformed messaging overrides, unsupported mesh routing and missing federation prerequisites with exit 1 and text diagnostics, before a model POST. Those refusals do not use the analysis validator’s exit-3 JSON contract.

Core

debug — boolean, default false

File key

debug in the selected root configuration.

Environment

SONNY_DEBUG

Command option

sonny --debug; displayed/zero default false.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

Viper boolean conversion is not strict validation: the tested invalid SONNY_DEBUG value became false without refusal.

Value shape

{
  "debug": false
}

Pinned source

cmd/sonny/cli/cmd_session_eval.go:804 (GetBool)
cmd/sonny/cli/config.go:89 (GetBool)
cmd/sonny/cli/root.go:145 (BindPFlag)
cmd/sonny/cli/root.go:548 (GetBool)
cmd/sonny/cli/run.go:425 (GetBool)

dir — string list, default []

File key

dir in the selected root configuration.

Environment

SONNY_DIR

Command option

sonny run --dir; displayed/zero default [].

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

Additional Recipe directories can acquire project-workspace trust labels. SONNY_DIR_JSON is a separate inherited-worker transport, not the ordinary comma-separated override.

Value shape

{
  "dir": [
    "./recipes"
  ]
}

Pinned source

cmd/sonny/cli/pack_inspect_resolve.go:166 (GetStringSlice)
cmd/sonny/cli/run.go:534 (GetStringSlice)
cmd/sonny/cli/run.go:557 (BindPFlag)

log_format — string, default "text"

File key

log_format in the selected root configuration.

Environment

SONNY_LOG_FORMAT

Command option

sonny --log-format; displayed/zero default "text".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

These rows describe requested root values; diagnostic display is separate from logger parsing.

Value shape

{
  "log_format": "text"
}

Pinned source

cmd/sonny/cli/root.go:147 (BindPFlag)
cmd/sonny/cli/root.go:309 (GetString)
cmd/sonny/cli/root.go:435 (GetString)

log_level — string, default "warn"

File key

log_level in the selected root configuration.

Environment

SONNY_LOG_LEVEL

Command option

sonny --log-level; displayed/zero default "warn".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

These rows describe requested root values; diagnostic display is separate from logger parsing.

Value shape

{
  "log_level": "info"
}

Pinned source

cmd/sonny/cli/config.go:93 (GetString)
cmd/sonny/cli/root.go:146 (BindPFlag)
cmd/sonny/cli/root.go:309 (GetString)
cmd/sonny/cli/root.go:435 (GetString)

model — string, default ""

File key

model in the selected root configuration.

Environment

SONNY_MODEL

Command option

sonny --model; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

Empty selects later Recipe/client choices; it is not a credential or endpoint declaration.

Value shape

{
  "model": "docs-model"
}

Pinned source

cmd/sonny/cli/config.go:88 (GetString)
cmd/sonny/cli/eval_runner.go:1559 (GetString)
cmd/sonny/cli/root.go:144 (BindPFlag)
cmd/sonny/cli/root.go:543 (GetString)
cmd/sonny/cli/run.go:423 (GetString)

pack — string, default ""

File key

pack in the selected root configuration.

Environment

SONNY_RECIPE SONNY_PACK

Command option

sonny run --recipe; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

Root recipe/pack aliases are normalized before lookup; conflicting alias values refuse startup. The stored key is pack; the public spelling recipe is accepted by the compatibility normalizer.

Value shape

{
  "pack": "pilot-brief-eval"
}

Pinned source

cmd/sonny/cli/run.go:431 (GetString)
cmd/sonny/cli/run.go:578 (BindPFlag)

prompt — string, default ""

File key

prompt in the selected root configuration.

Environment

SONNY_PROMPT

Command option

sonny run --prompt; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

A nonempty prompt selects one headless turn; it can initiate provider calls when run, not during this reference generation.

Value shape

{
  "prompt": "Summarize the supplied synthetic notes."
}

Pinned source

cmd/sonny/cli/child_startup.go:41 (GetString)
cmd/sonny/cli/run.go:432 (GetString)
cmd/sonny/cli/run.go:503 (GetString)
cmd/sonny/cli/run.go:506 (GetString)
cmd/sonny/cli/run.go:580 (BindPFlag)

provider — string, default ""

File key

provider in the selected root configuration.

Environment

SONNY_PROVIDER

Command option

sonny --provider; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

Empty selects later Recipe/client choices; it is not a credential or endpoint declaration.

Value shape

{
  "provider": "docs-provider"
}

Pinned source

cmd/sonny/cli/config.go:87 (GetString)
cmd/sonny/cli/eval_runner.go:1558 (GetString)
cmd/sonny/cli/pack.go:908 (GetString)
cmd/sonny/cli/root.go:143 (BindPFlag)
cmd/sonny/cli/root.go:538 (GetString)
cmd/sonny/cli/run.go:422 (GetString)

Mesh

mesh.advertise_address — string, default explicit address, then resolved mesh endpoint for mesh adopt offer

File key

mesh.advertise_address in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh adopt offer --address; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.advertise_address": "mesh.example.invalid:50052"
}

Pinned source

cmd/sonny/cli/mesh_adopt.go:143 (GetString)

mesh.agents — string map, default {}

File key

mesh.agents in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.agents": {
    "example": "https://example.invalid:18443"
  }
}

Pinned source

cmd/sonny/cli/mesh_exec.go:41 (GetStringMapString)

mesh.client_ca — string, default ""

File key

mesh.client_ca in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh --client-ca; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.client_ca": "./private/client.pem"
}

Pinned source

cmd/sonny/cli/mesh.go:181 (BindPFlag)
cmd/sonny/cli/meshcfg.go:95 (GetString)

mesh.client_cert — string, default ""

File key

mesh.client_cert in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh --client-cert; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.client_cert": "./private/client.pem"
}

Pinned source

cmd/sonny/cli/mesh.go:179 (BindPFlag)
cmd/sonny/cli/meshcfg.go:93 (GetString)

mesh.client_key — string, default ""

File key

mesh.client_key in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh --client-key; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.client_key": "./private/client.pem"
}

Pinned source

cmd/sonny/cli/mesh.go:180 (BindPFlag)
cmd/sonny/cli/meshcfg.go:94 (GetString)

mesh.client_key_pin — string, default ""

File key

mesh.client_key_pin in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh --client-key-pin; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.client_key_pin": "./private/client.pem"
}

Pinned source

cmd/sonny/cli/mesh.go:182 (BindPFlag)
cmd/sonny/cli/meshcfg.go:115 (GetString)

mesh.control_db — string, default <data-dir>/control.db

File key

mesh.control_db in the selected root configuration.

Environment

SONNY_CONTROL_DB

Command option

sonny mesh serve --control-db; displayed/zero default <data>/control.db.
sonny mesh adopt offer --control-db; displayed/zero default "".

Precedence

mesh serve: --control-db > SONNY_CONTROL_DB > mesh.control_db > data-dir default. mesh adopt offer: explicit flag > mesh.control_db > data-dir default; its helper does not read SONNY_CONTROL_DB.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.control_db": "./private/control.db"
}

Pinned source

cmd/sonny/cli/mesh.go:462 (GetString)
cmd/sonny/cli/mesh_adopt.go:309 (GetString)

mesh.dev_insecure_transport — boolean, default false

File key

mesh.dev_insecure_transport in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh --dev-insecure-transport; displayed/zero default false.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.dev_insecure_transport": false
}

Pinned source

cmd/sonny/cli/mesh.go:188 (BindPFlag)
cmd/sonny/cli/mesh.go:579 (GetBool)
cmd/sonny/cli/meshcfg.go:117 (GetBool)

mesh.endpoint — string, default ""

File key

mesh.endpoint in the selected root configuration.

Environment

SONNY_MESH_ADDR

Command option

sonny mesh --endpoint; displayed/zero default "".
sonny run --mesh-addr; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

CLI connectivity uses a legacy SONNY_MESH_ADDR fallback below the resolved key; SONNY_MESH_ENDPOINT is not a usable automatic nested mapping. An empty client endpoint can fall back to localhost:50052; run/TUI has separate panel behavior.

Value shape

{
  "mesh.endpoint": "127.0.0.1:50052"
}

Pinned source

cmd/sonny/cli/mesh.go:165 (BindPFlag)
cmd/sonny/cli/meshcfg.go:63 (GetString)
cmd/sonny/cli/run.go:715 (BindPFlag)

mesh.peers — string list, default []

File key

mesh.peers in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny run --mesh-peer; displayed/zero default [].

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.peers": [
    "127.0.0.1:50052"
  ]
}

Pinned source

cmd/sonny/cli/meshcfg.go:67 (GetStringSlice)
cmd/sonny/cli/run.go:716 (BindPFlag)

mesh.self — boolean, default false

File key

mesh.self in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny run --mesh-self; displayed/zero default false.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.self": false
}

Pinned source

cmd/sonny/cli/run.go:488 (GetBool)
cmd/sonny/cli/run.go:728 (BindPFlag)

mesh.self_grpc — string, default ":50052"

File key

mesh.self_grpc in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny run --mesh-self-grpc; displayed/zero default ":50052".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.self_grpc": ":50052"
}

Pinned source

cmd/sonny/cli/run.go:489 (GetString)
cmd/sonny/cli/run.go:729 (BindPFlag)

mesh.self_synapse — string, default ":50053"

File key

mesh.self_synapse in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny run --mesh-self-synapse; displayed/zero default ":50053".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.self_synapse": ":50053"
}

Pinned source

cmd/sonny/cli/run.go:490 (GetString)
cmd/sonny/cli/run.go:730 (BindPFlag)

mesh.server_name — string, default ""

File key

mesh.server_name in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh --server-name; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.server_name": "mesh.example.invalid"
}

Pinned source

cmd/sonny/cli/mesh.go:183 (BindPFlag)
cmd/sonny/cli/meshcfg.go:116 (GetString)

mesh.tls_cert — string, default <config-dir>/mesh/node.crt for mesh adopt offer

File key

mesh.tls_cert in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny mesh adopt offer --cert; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "mesh.tls_cert": "./private/node.crt"
}

Pinned source

cmd/sonny/cli/mesh_adopt.go:320 (GetString)

Trace

trace — boolean, default true

File key

trace in the selected root configuration.

Environment

SONNY_TRACE

Command option

sonny run --no-trace; displayed/zero default false.

Precedence

--no-trace=true forces parent tracing off; otherwise SONNY_TRACE > selected root trace value > true.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Limits

This controls the parent trace. Installed no-trace tests still observed internal MCP child traces; see diagnostics.

Value shape

{
  "trace": false
}

Pinned source

cmd/sonny/cli/run.go:448 (GetBool)
cmd/sonny/cli/run.go:627 (SetDefault)
cmd/sonny/cli/run.go:628 (BindEnv)

trace.export.force — boolean, default false

File key

trace.export.force in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --force; displayed/zero default false.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.force": false
}

Pinned source

cmd/sonny/cli/trace_export.go:147 (BindPFlag)
cmd/sonny/cli/trace_export.go:166 (GetBool)

trace.export.format — string, default "openai_chat"

File key

trace.export.format in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --format; displayed/zero default "openai_chat".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.format": "openai_chat"
}

Pinned source

cmd/sonny/cli/trace_export.go:144 (BindPFlag)
cmd/sonny/cli/trace_export.go:163 (GetString)

trace.export.include_tools — boolean, default false

File key

trace.export.include_tools in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --include-tools; displayed/zero default false.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.include_tools": false
}

Pinned source

cmd/sonny/cli/trace_export.go:145 (BindPFlag)
cmd/sonny/cli/trace_export.go:164 (GetBool)

trace.export.keep_errors — boolean, default false

File key

trace.export.keep_errors in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --keep-errors; displayed/zero default false.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.keep_errors": false
}

Pinned source

cmd/sonny/cli/trace_export.go:148 (BindPFlag)
cmd/sonny/cli/trace_export.go:167 (GetBool)

trace.export.out — string, default ""

File key

trace.export.out in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --out; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.out": "./private/output.jsonl"
}

Pinned source

cmd/sonny/cli/trace_export.go:143 (BindPFlag)
cmd/sonny/cli/trace_export.go:162 (GetString)

trace.export.since — string, default ""

File key

trace.export.since in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --since; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.since": "2026-10-25T00:00:00Z"
}

Pinned source

cmd/sonny/cli/trace_export.go:146 (BindPFlag)
cmd/sonny/cli/trace_export.go:165 (GetString)

trace.export.trace_dir — string, default "<owned-temp>/XDG_DATA_HOME/sonny/traces"

File key

trace.export.trace_dir in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training export --trace-dir; displayed/zero default "<owned-temp>/XDG_DATA_HOME/sonny/traces".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Selected root configuration; runtime admission and credential authority remain separate.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.export.trace_dir": "./private/traces"
}

Pinned source

cmd/sonny/cli/trace_export.go:142 (BindPFlag)
cmd/sonny/cli/trace_export.go:161 (GetString)

trace.server.ca — string, default ""

File key

trace.server.ca in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training server --ca; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.server.ca": "./private/material.pem"
}

Pinned source

cmd/sonny/cli/trace_server.go:84 (BindPFlag)
cmd/sonny/cli/trace_server.go:112 (GetString)

trace.server.cert — string, default ""

File key

trace.server.cert in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training server --cert; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.server.cert": "./private/material.pem"
}

Pinned source

cmd/sonny/cli/trace_server.go:82 (BindPFlag)
cmd/sonny/cli/trace_server.go:110 (GetString)

trace.server.key — string, default ""

File key

trace.server.key in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training server --key; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.server.key": "./private/material.pem"
}

Pinned source

cmd/sonny/cli/trace_server.go:83 (BindPFlag)
cmd/sonny/cli/trace_server.go:111 (GetString)

trace.server.listen — string, default "127.0.0.1:50051"

File key

trace.server.listen in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training server --listen; displayed/zero default "127.0.0.1:50051".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.server.listen": "127.0.0.1:50051"
}

Pinned source

cmd/sonny/cli/trace_server.go:80 (BindPFlag)
cmd/sonny/cli/trace_server.go:102 (GetString)

trace.server.storage_dir — string, default ""

File key

trace.server.storage_dir in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training server --storage-dir; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.server.storage_dir": "./private/traces"
}

Pinned source

cmd/sonny/cli/trace_server.go:81 (BindPFlag)
cmd/sonny/cli/trace_server.go:103 (GetString)

trace.upload.batch_size — integer, default 50

File key

trace.upload.batch_size in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training upload --batch-size; displayed/zero default 50.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.upload.batch_size": 50
}

Pinned source

cmd/sonny/cli/trace_upload.go:120 (BindPFlag)
cmd/sonny/cli/trace_upload.go:136 (GetInt)

trace.upload.ca — string, default ""

File key

trace.upload.ca in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training upload --ca; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.upload.ca": "./private/material.pem"
}

Pinned source

cmd/sonny/cli/trace_upload.go:119 (BindPFlag)
cmd/sonny/cli/trace_upload.go:144 (GetString)

trace.upload.cert — string, default ""

File key

trace.upload.cert in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training upload --cert; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.upload.cert": "./private/material.pem"
}

Pinned source

cmd/sonny/cli/trace_upload.go:117 (BindPFlag)
cmd/sonny/cli/trace_upload.go:142 (GetString)

trace.upload.key — string, default ""

File key

trace.upload.key in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training upload --key; displayed/zero default "".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.upload.key": "./private/material.pem"
}

Pinned source

cmd/sonny/cli/trace_upload.go:118 (BindPFlag)
cmd/sonny/cli/trace_upload.go:143 (GetString)

trace.upload.server — string, default "localhost:50051"

File key

trace.upload.server in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training upload --server; displayed/zero default "localhost:50051".

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.upload.server": "localhost:50051"
}

Pinned source

cmd/sonny/cli/trace_upload.go:116 (BindPFlag)
cmd/sonny/cli/trace_upload.go:135 (GetString)

trace.upload.workers — integer, default 3

File key

trace.upload.workers in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

sonny training upload --workers; displayed/zero default 3.

Precedence

Explicit bound flag > exact environment binding, if any > selected root file > declared default. Binding metadata alone does not qualify every command consumer.

Trust scope

Operator-owned --config/home file, or trusted workspace; untrusted working-file values are confined.

When changes apply

Read during command startup. Start a new invocation/session after changing this file; this entry grants no hot reload of a running service.

Value shape

{
  "trace.upload.workers": 3
}

Pinned source

cmd/sonny/cli/trace_upload.go:121 (BindPFlag)
cmd/sonny/cli/trace_upload.go:137 (GetInt)

Resource Reuse

resource_reuse.enabled — boolean, default true

File key

resource_reuse.enabled in the selected root configuration.

Environment

SONNY_RESOURCE_REUSE_ENABLED

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

Working-file values can override the home file, including advisory write preconditions and unobserved replacement. The two safety settings are not operator-only; use their exact environment overrides when required.

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.enabled": true
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.file_versions.algorithm — string, default "sha256"

File key

resource_reuse.file_versions.algorithm in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

enum: sha256

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.file_versions.algorithm": "sha256"
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.file_versions.capture_retries — integer, default 2

File key

resource_reuse.file_versions.capture_retries in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

max: 5 min: 0

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.file_versions.capture_retries": 2
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.file_versions.max_bytes — integer, default 10485760

File key

resource_reuse.file_versions.max_bytes in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

max: 1073741824 min: 1

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.file_versions.max_bytes": 10485760
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.file_versions.unobserved_replace — string, default "refuse"

File key

resource_reuse.file_versions.unobserved_replace in the selected root configuration.

Environment

SONNY_RESOURCE_REUSE_UNOBSERVED_REPLACE

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

enum: refuse,allow

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.file_versions.unobserved_replace": "refuse"
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.file_versions.validation — string, default "digest"

File key

resource_reuse.file_versions.validation in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

enum: digest

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.file_versions.validation": "digest"
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.file_versions.write_preconditions — string, default "required"

File key

resource_reuse.file_versions.write_preconditions in the selected root configuration.

Environment

SONNY_RESOURCE_REUSE_WRITE_PRECONDITIONS

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

enum: required,advisory

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.file_versions.write_preconditions": "required"
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.read_results.max_bytes — integer, default 67108864

File key

resource_reuse.read_results.max_bytes in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

max: 4294967296 min: 0

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.read_results.max_bytes": 67108864
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.read_results.max_entries — integer, default 4096

File key

resource_reuse.read_results.max_entries in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

max: 1000000 min: 1

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.read_results.max_entries": 4096
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.read_results.max_hash_workers — integer, default 4

File key

resource_reuse.read_results.max_hash_workers in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

max: 64 min: 1

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.read_results.max_hash_workers": 4
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.read_results.persist — boolean, default false

File key

resource_reuse.read_results.persist in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.read_results.persist": false
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.read_results.representation — string, default "auto"

File key

resource_reuse.read_results.representation in the selected root configuration.

Environment

SONNY_RESOURCE_REUSE_REPRESENTATION

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

enum: auto,full,compact

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.read_results.representation": "auto"
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.telemetry.enabled — boolean, default true

File key

resource_reuse.telemetry.enabled in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.telemetry.enabled": true
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.telemetry.include_content — boolean, default false

File key

resource_reuse.telemetry.include_content in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.telemetry.include_content": false
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.tool_results.enabled — boolean, default false

File key

resource_reuse.tool_results.enabled in the selected root configuration.

Environment

SONNY_RESOURCE_REUSE_TOOL_RESULTS

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.tool_results.enabled": false
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.tool_results.policy — string, default "validated_dependencies"

File key

resource_reuse.tool_results.policy in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Typed bounds

enum: validated_dependencies

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.tool_results.policy": "validated_dependencies"
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

resource_reuse.tool_results.shadow — boolean, default true

File key

resource_reuse.tool_results.shadow in the selected root configuration.

Environment

No ordinary shell environment name is bound for this nested key.

Command option

No bound command flag.

Precedence

Exact bound environment variable, when listed > selected root resource_reuse block > typed defaults. No command flag.

Trust scope

When changes apply

Resolved once at command startup; applies to a new session/runtime. Existing observations and realm authority have separate lifetimes.

Limits

persist=true and telemetry.include_content=true are refused. Other enums/ranges come from the typed resource contract; configuration acceptance does not prove realm tool behavior.

Value shape

{
  "resource_reuse.tool_results.shadow": true
}

Pinned source

cmd/sonny/cli/config_resource_reuse.go:72 (resolveResourceReuse)
cmd/sonny/internal/resourcereuse/config.go:33 (typed config/defaults/Validate)

Variants

variants.allow_draft_variants — boolean, default false

File key

variants.allow_draft_variants in the selected root configuration.

Environment

SONNY_VARIANTS.ALLOW_DRAFT_VARIANTS

Command option

No bound command flag.

Precedence

Raw dotted process-environment key > selected root file > variant defaults. Root AutomaticEnv replaces hyphens only, not dots; underscore-expanded variant names are ignored. Use env with a quoted NAME=value argument for dotted keys.

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file variants are dropped and operator values restored; explicit --config is operator-selected.

When changes apply

Parsed once before eager/deferred session startup; changes apply to a new runtime. Existing sessions and approved variant activation require separate qualification.

Limits

Modes: off performs no discovery; validate parses without selection; shadow selects/compiles but serves the base; on may activate an approved selection. Missing valid variants can still leave the base active. The source YAML parser ignores unknown members and later documents; config validate did not reject a bad variant mode. Approval knobs govern separate profile and variant trust axes; a relaxed profile gate does not relax variant approval.

Value shape

{
  "variants": {
    "allow_draft_variants": false
  }
}

Pinned source

cmd/sonny/variantactivate/config.go:42 (constant key, typed FromLookup and DefaultConfig)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)
cmd/sonny/variant_wire.go:59 (runtime Viper lookup)

variants.mode — string, default "off"

File key

variants.mode in the selected root configuration.

Environment

SONNY_VARIANTS.MODE

Command option

No bound command flag.

Precedence

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file variants are dropped and operator values restored; explicit --config is operator-selected.

When changes apply

Parsed once before eager/deferred session startup; changes apply to a new runtime. Existing sessions and approved variant activation require separate qualification.

Typed bounds

enum: [off validate shadow on]

Limits

Value shape

{
  "variants": {
    "mode": "off"
  }
}

Pinned source

cmd/sonny/variantactivate/config.go:40 (constant key, typed FromLookup and DefaultConfig)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)
cmd/sonny/variant_wire.go:59 (runtime Viper lookup)

variants.require_profile_approval — boolean, default true

File key

variants.require_profile_approval in the selected root configuration.

Environment

SONNY_VARIANTS.REQUIRE_PROFILE_APPROVAL

Command option

No bound command flag.

Precedence

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file variants are dropped and operator values restored; explicit --config is operator-selected.

When changes apply

Parsed once before eager/deferred session startup; changes apply to a new runtime. Existing sessions and approved variant activation require separate qualification.

Limits

Value shape

{
  "variants": {
    "require_profile_approval": true
  }
}

Pinned source

cmd/sonny/variantactivate/config.go:41 (constant key, typed FromLookup and DefaultConfig)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)
cmd/sonny/variant_wire.go:59 (runtime Viper lookup)

Agent Messaging

agent_messaging.federation — boolean, default false

File key

agent_messaging.federation in the selected root configuration.

Environment

SONNY_AGENT_MESSAGING_FEDERATION SONNY_AGENT_MESSAGING.FEDERATION

Command option

No bound command flag.

Precedence

Exact SONNY_AGENT_MESSAGING_* environment variable, including an explicitly empty value > raw dotted process-environment key > selected root file > false. Empty/invalid environment text is a boolean error when the resolver is reached.

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file agent_messaging values are dropped and operator values restored.

When changes apply

Read at host/process messaging setup. A rollout value is not a live transport grant or permission to start a model turn.

Limits

Requires local=true and at least one protected SONNY_AGENT_MESSAGING_A2A_CONFIG / SONNY_AGENT_MESSAGING_A2A_OUTBOUND_CONFIG absolute clean path. The rollout resolver checks path shape only; file ownership, TLS, peer grants and runtime admission happen later. config validate did not reject a bad messaging boolean; inspect the startup path as well.

Value shape

{
  "agent_messaging": {
    "federation": false
  }
}

Pinned source

cmd/sonny/cli/supervisor_agent_messaging.go:55 (composed key and explicit environment override)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)

agent_messaging.idle_wake — boolean, default false

File key

agent_messaging.idle_wake in the selected root configuration.

Environment

SONNY_AGENT_MESSAGING_IDLE_WAKE SONNY_AGENT_MESSAGING.IDLE_WAKE

Command option

No bound command flag.

Precedence

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file agent_messaging values are dropped and operator values restored.

When changes apply

Read at host/process messaging setup. A rollout value is not a live transport grant or permission to start a model turn.

Limits

Source idle-wake resolver requires local messaging and durable relationship/budget authority. Installed startup with local messaging disabled ignored idle_wake=true and completed a model turn: the expected refusal assertion remains failed. This does not prove any mail-triggered wake worked. config validate did not reject a bad messaging boolean; inspect the startup path as well.

Value shape

{
  "agent_messaging": {
    "idle_wake": false
  }
}

Pinned source

cmd/sonny/cli/supervisor_agent_messaging.go:83 (composed key and explicit environment override)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)

agent_messaging.local — boolean, default false

File key

agent_messaging.local in the selected root configuration.

Environment

SONNY_AGENT_MESSAGING_LOCAL SONNY_AGENT_MESSAGING.LOCAL

Command option

No bound command flag.

Precedence

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file agent_messaging values are dropped and operator values restored.

When changes apply

Read at host/process messaging setup. A rollout value is not a live transport grant or permission to start a model turn.

Limits

Permits local agent messaging setup only. It grants no agent identity, durable relationship, transport membership or model-wake authority. config validate did not reject a bad messaging boolean; inspect the startup path as well.

Value shape

{
  "agent_messaging": {
    "local": false
  }
}

Pinned source

cmd/sonny/cli/supervisor_agent_messaging.go:47 (composed key and explicit environment override)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)

agent_messaging.mesh — boolean, default false

File key

agent_messaging.mesh in the selected root configuration.

Environment

SONNY_AGENT_MESSAGING_MESH SONNY_AGENT_MESSAGING.MESH

Command option

No bound command flag.

Precedence

Trust scope

Operator-owned explicit --config/home file, or trusted workspace. Untrusted working-file agent_messaging values are dropped and operator values restored.

When changes apply

Read at host/process messaging setup. A rollout value is not a live transport grant or permission to start a model turn.

Limits

The tested host refuses true with mesh routing is not configured on this host. This is distinct from a managed deployment manifest agent_messaging capability. config validate did not reject a bad messaging boolean; inspect the startup path as well.

Value shape

{
  "agent_messaging": {
    "mesh": false
  }
}

Pinned source

cmd/sonny/cli/supervisor_agent_messaging.go:51 (composed key and explicit environment override)
cmd/sonny/cli/config_operator_keys.go:45 (operator subtree confinement)

Decision policy and trusted permissions

These are two distinct configuration contracts. The 35 fields below come from six public types and the default constructors in the pinned 0.12.7 source. Download the field records . They describe admission rules, not a generated JSON Schema or proof that a policy worker, registry or dangerous execution mode works on your machine. Read privacy and permissions before changing authority.

Decision-policy files

The root file’s policy: block defaults to mode: off. Select an operator file with --config; otherwise the home block is the operator base. A trusted working-directory block replaces that block as a whole. An untrusted project block is ignored; a project registry block is ignored even when the workspace is trusted. Revoking workspace trust falls back to the operator block, and a project cannot raise the operator’s delegation ceiling.

There are no ordinary per-field environment overrides. SONNY_POLICY is ignored with a warning. SONNY_UPSTREAM_TOKEN authenticates the transport to the operator-configured registry; it does not select a URL or grant a policy. Host metadata such as project_dir and a worker_sha256 override are not accepted file fields. The worker identity belongs to the build’s pin.

In off mode, the decoder still rejects unknown members and incompatible types, but skips bounds for active settings. The installed policy show accepted disabled settings with zero fuel and a relative worker path; that is not proof those settings can run. Zero-valued fields with Go’s omitempty tag can disappear from inspection JSON. In shadow or active, choose exactly one origin (absolute source, pack: session, or an operator registry), supply the required worker/path/budget settings, and review test execution. active also requires test_command. A shape-valid path has not been loaded, and a declared tool or grant remains subject to runtime admission.

Use the disabled example to inspect the file contract without activating a worker:

sonny policy show --json --config ./policy-disabled.yaml
sonny policy status --json --config ./policy-disabled.yaml

The installed show and status return direct JSON objects on these successful off-mode calls. They are not the versioned analysis envelope. Invalid policy mode and unknown-field cases exited 3 with text on stderr, even with --json. Do not assume every failure has a JSON body.

Protected permission files

permissions.yaml is separate from .sonny.yaml. Its required version is 1; omission does not inherit that version. Built-ins allow either dangerous mode to be requested, but request neither. In order, organization, machine and user files intersect the allow_* ceilings; a later true cannot undo an earlier false. Explicit requests use the last trusted file value, then an environment request, then an invocation flag where exposed. Requests cannot restore a denied ceiling or override a trusted isolation floor.

On Linux the trusted machine paths are /etc/sonny/permissions.yaml and /usr/local/etc/sonny/permissions.yaml, followed by <config>/permissions.yaml. macOS uses /Library/Application Support/sonny/permissions.yaml for its machine layer; Windows uses %ProgramData%\sonny\permissions.yaml. Those platform path rules are source-derived; the executed cases here are Linux only. Files must be nonempty regular files, at most 64 KiB, and pass the protected-file reader. The Linux cases accepted an owned 0600 file and refused symlinks and group/other-writable files. Each YAML document is strict: unknown/duplicate members, later documents and a same-layer allow-false/request-true contradiction are refused. Omitted or null optional booleans leave that layer unspecified.

The four reserved permission keys are not permitted in an untrusted root file, even with a false value. A project’s .sonny/permissions.yaml is ignored with a warning. --config selects a root configuration; it does not relocate or authorize a trusted permission file. The deny-only example shows the protected file shape without requesting either dangerous mode; do not copy it into a project and expect it to become trusted policy.

Request environment variables accept 1/true and 0/false (case-insensitive, with surrounding whitespace trimmed). Empty means unset; malformed nonempty requests are errors. The auto-approve variable also accepts the special dangerous value, which requests direct approval of dangerous commands. The two SONNY_POLICY_FORBID_* variables deny only on 1/true; every other value, including a typo, adds no denial and never restores an existing grant. SONNY_DANGEROUSLY_BYPASS_ALL requests both modes and must satisfy both sets of restrictions. Background service surfaces have additional request refusals; these inspection tests do not qualify unattended execution.

Inspect diagnostics and application timing

sonny config show prints permission posture as text. In the installed tests it exited 0 for malformed policy, an unsafe file, a reserved project key and an invalid request variable, while printing false (policy could not be read: ...). Read that diagnostic; the exit alone does not prove that startup will accept the configuration. The corresponding sonny run startup checks returned these refusals: unknown permission field 3, unsafe file 1, reserved project key 8, malformed request variable 1. These refusal paths printed text on stderr, not a uniform JSON envelope.

The settings are read for a new process/session or inspection. Existing session bindings, promotion, revocation and a running host’s lifecycle have separate contracts; editing a file is not evidence of reload or completed activation. The controlled checks started no policy worker, registry transport or dangerous tool execution, and qualify no live provider account.

policy — 14 fields

Pinned source type: cmd/sonny/policywire/settings.go.

`mode`

File key

policy.mode in the selected root file's policy block.

Type

string.

Built-in default

"off"

Contract

off, shadow or active. Off skips active-setting bounds; unknown keys and wrong JSON types are still refused.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"off"

Individual field shape only; not a complete configuration or an authority grant.

`source`

File key

policy.source in the selected root file's policy block.

Type

string.

Built-in default

""

Contract

Absolute policy-file path. In shadow/active, select exactly one origin: source, pack or registry. Parsing a path does not load the file.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"/owned/policy.rule"

Individual field shape only; not a complete configuration or an authority grant.

`pack`

File key

policy.pack in the selected root file's policy block.

Type

string.

Built-in default

""

Contract

The only nonempty pack value is session. Uses the session Recipe decision_policy; a Recipe without one can run without a decision policy.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"session"

Individual field shape only; not a complete configuration or an authority grant.

`registry`

File key

policy.registry in the selected root file's policy block.

Type

*policywire.RegistrySettings. Pointer fields distinguish omission from an explicit value.

Built-in default

null

Contract

Optional operator-only registry object; mutually exclusive with source and pack. No registry is configured by default.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

null

Individual field shape only; not a complete configuration or an authority grant.

`format`

File key

policy.format in the selected root file's policy block.

Type

string.

Built-in default

"source"

Contract

source or ast_json.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"source"

Individual field shape only; not a complete configuration or an authority grant.

`worker`

File key

policy.worker in the selected root file's policy block.

Type

string.

Built-in default

""

Contract

Absolute worker path in shadow/active. The executable identity is pinned by the Sonny build, not a configurable hash; parsing does not verify or start it.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"/owned/dpolicy-worker"

Individual field shape only; not a complete configuration or an authority grant.

`test_tool`

File key

policy.test_tool in the selected root file's policy block.

Type

string.

Built-in default

"exec"

Contract

Nonempty tool name. This declaration grants no tool permission.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"exec"

Individual field shape only; not a complete configuration or an authority grant.

`test_command`

File key

policy.test_command in the selected root file's policy block.

Type

string.

Built-in default

""

Contract

Required in active mode. An executable command is operator-reviewed configuration, not a generic recovery command.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"owned-test-command"

Individual field shape only; not a complete configuration or an authority grant.

`grant`

File key

policy.grant in the selected root file's policy block.

Type

[]string.

Built-in default

[
  "artifact.read",
  "artifact.review",
  "artifact.revise",
  "artifact.test"
]

Contract

Subset of artifact.read, artifact.review, artifact.revise and artifact.test; empty grants none. Runtime admission and inherited restrictions still apply.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

[
  "artifact.read"
]

Individual field shape only; not a complete configuration or an authority grant.

`verify_protect`

File key

policy.verify_protect in the selected root file's policy block.

Type

[]string.

Built-in default

[
  "*_test.go",
  "*_test.py",
  "test_*.py",
  "*.test.js",
  "*.test.ts",
  "*.spec.js",
  "*.spec.ts",
  "**/test/**",
  "**/tests/**",
  "**/testdata/**",
  "**/__tests__/**"
]

Contract

Protected verification paths; patterns are checked with path.Match after replacing ** with *. Invalid patterns are refused in shadow/active.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

[
  "*_test.go"
]

Individual field shape only; not a complete configuration or an authority grant.

`fuel`

File key

policy.fuel in the selected root file's policy block.

Type

uint32.

Built-in default

Contract

Unsigned 32-bit integer; shadow/active require 1..10000 evaluation steps.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`budget`

File key

policy.budget in the selected root file's policy block.

Type

policywire.Budget.

Built-in default

{
  "actions": 20,
  "decisions": 40,
  "model_tokens": 4000000,
  "retries": 6,
  "wall_ms": 1800000
}

Contract

Per-episode bounds, not a model-account spending guarantee.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

{
  "actions": 20,
  "decisions": 40,
  "model_tokens": 4000000,
  "retries": 6,
  "wall_ms": 1800000
}

Individual field shape only; not a complete configuration or an authority grant.

`state_dir`

File key

policy.state_dir in the selected root file's policy block.

Type

string.

Built-in default

"\u003cstate\u003e/policy (CLI-supplied; platform-dependent)"

Contract

Absolute state directory in shadow/active. The CLI supplies <state>/policy as its default; the owned path in source fixtures is an injected test base.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

"/owned-state/policy"

Individual field shape only; not a complete configuration or an authority grant.

`delegation`

File key

policy.delegation in the selected root file's policy block.

Type

runtime.ChildDelegation.

Built-in default

{
  "children": 0,
  "depth": 0
}

Contract

Both zero disable delegation; otherwise depth 1..32 and children 1..64. Delegation cannot widen inherited authority.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

{
  "children": 0,
  "depth": 0
}

Individual field shape only; not a complete configuration or an authority grant.

policy.registry — 7 fields

Pinned source type: cmd/sonny/policywire/registry.go.

`url`

File key

policy.registry.url in the selected root file's policy block.

Type

string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

HTTPS origin; plain HTTP is admitted only for a loopback host with insecure_http=true. Syntax acceptance does not qualify registry access.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

"https://registry.example.invalid"

Individual field shape only; not a complete configuration or an authority grant.

`tenant`

File key

policy.registry.tenant in the selected root file's policy block.

Type

string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Required: 1..128 bytes, no Unicode whitespace or control characters.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

"owned-tenant"

Individual field shape only; not a complete configuration or an authority grant.

`channel`

File key

policy.registry.channel in the selected root file's policy block.

Type

string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Required: ^[a-z][a-z0-9._-]{0,63}$.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

"review"

Individual field shape only; not a complete configuration or an authority grant.

`task`

File key

policy.registry.task in the selected root file's policy block.

Type

string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Empty uses the session Recipe ID as the task category.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

""

Individual field shape only; not a complete configuration or an authority grant.

`trusted_keys`

File key

policy.registry.trusted_keys in the selected root file's policy block.

Type

map[string]string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

At least one keyed Ed25519 public key is required: standard base64 raw key, PEM or OpenSSH. An empty map shown here is a value shape and is not a valid configured registry.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

{}

Individual field shape only; not a complete configuration or an authority grant.

`baseline`

File key

policy.registry.baseline in the selected root file's policy block.

Type

*policywire.BaselineSettings. Pointer fields distinguish omission from an explicit value.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Optional pinned fallback baseline. This does not make an unavailable registry or missing eligibility proof safe.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

null

Individual field shape only; not a complete configuration or an authority grant.

`insecure_http`

File key

policy.registry.insecure_http in the selected root file's policy block.

Type

bool.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Boolean opt-in for a loopback HTTP registry only; it does not permit arbitrary insecure origins.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

false

Individual field shape only; not a complete configuration or an authority grant.

policy.registry.baseline — 2 fields

Pinned source type: cmd/sonny/policywire/registry.go.

`digest`

File key

policy.registry.baseline.digest in the selected root file's policy block.

Type

string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Required when baseline is present; must pass the release digest parser. The placeholder is not a usable digest.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

"\u003capproved AST digest\u003e"

Individual field shape only; not a complete configuration or an authority grant.

`mode`

File key

policy.registry.baseline.mode in the selected root file's policy block.

Type

string.

Built-in default

The containing optional object is absent by default. Adding it requires the documented members and validation; there is no ready registry in the defaults.

Contract

Empty, shadow or active; baseline cannot run above the configured policy mode.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator configuration only; project registry blocks are ignored even in trusted workspaces.

Value shape

"shadow"

Individual field shape only; not a complete configuration or an authority grant.

policy.budget — 5 fields

Pinned source type: cmd/sonny/policywire/settings.go.

`decisions`

File key

policy.budget.decisions in the selected root file's policy block.

Type

uint64.

Built-in default

Contract

Unsigned 64-bit integer; positive in shadow/active.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`actions`

File key

policy.budget.actions in the selected root file's policy block.

Type

uint64.

Built-in default

Contract

Unsigned 64-bit integer; positive in shadow/active.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`retries`

File key

policy.budget.retries in the selected root file's policy block.

Type

uint64.

Built-in default

Contract

Unsigned 64-bit integer; zero is valid and disables retrying a failed action as that action.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`wall_ms`

File key

policy.budget.wall_ms in the selected root file's policy block.

Type

uint64.

Built-in default

Contract

Unsigned 64-bit integer; positive milliseconds in shadow/active.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`model_tokens`

File key

policy.budget.model_tokens in the selected root file's policy block.

Type

uint64.

Built-in default

Contract

Unsigned 64-bit integer; positive in shadow/active.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

policy.delegation — 2 fields

Pinned source type: internal/runtime/child_delegation.go.

`depth`

File key

policy.delegation.depth in the selected root file's policy block.

Type

uint32.

Built-in default

Contract

Unsigned 32-bit integer: both delegation members zero, or depth 1..32 with children 1..64.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`children`

File key

policy.delegation.children in the selected root file's policy block.

Type

uint32.

Built-in default

Contract

Unsigned 32-bit integer: both delegation members zero, or children 1..64 with depth 1..32.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Operator block, or a trusted workspace block replacing it as a whole. Host metadata and inherited delegation limits cannot be granted by a file.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

permissions.yaml — 5 fields

Pinned source type: cmd/sonny/permissionpolicy/config.go.

`version`

File key

version in a protected permissions.yaml.

Type

int.

Built-in default

Contract

Required literal integer 1 in each file; the built-in version is not an implicit default for a document that omits it.

Environment

No environment variable binds this field.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Organization, machine and user protected permissions.yaml only; project files cannot grant these settings.

Value shape

Individual field shape only; not a complete configuration or an authority grant.

`allow_auto_approve`

File key

allow_auto_approve in a protected permissions.yaml.

Type

*bool. Pointer fields distinguish omission from an explicit value.

Built-in default

true

Contract

Optional boolean permission ceiling, intersected across layers. False cannot be restored to true by a later layer. True permits a request but does not enable auto-approval.

Environment

SONNY_POLICY_FORBID_AUTO_APPROVE See the request/deny parsing rules above.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Organization, machine and user protected permissions.yaml only; project files cannot grant these settings.

Value shape

false

Individual field shape only; not a complete configuration or an authority grant.

`allow_isolation_bypass`

File key

allow_isolation_bypass in a protected permissions.yaml.

Type

*bool. Pointer fields distinguish omission from an explicit value.

Built-in default

true

Contract

Optional boolean ceiling, intersected across layers. It does not override a trusted isolation floor.

Environment

SONNY_POLICY_FORBID_ISOLATION_BYPASS See the request/deny parsing rules above.

Command option

No field override flag; --config selects an operator root file, not a trusted permissions file.

Trust scope

Organization, machine and user protected permissions.yaml only; project files cannot grant these settings.

Value shape

false

Individual field shape only; not a complete configuration or an authority grant.

`auto_approve`

File key

auto_approve in a protected permissions.yaml.

Type

*bool. Pointer fields distinguish omission from an explicit value.

Built-in default

false

Contract

Optional boolean request, last explicit trusted layer wins, subject to the composed permission ceiling. Cannot be true in a layer that also sets allow_auto_approve=false.

Environment

SONNY_DANGEROUSLY_AUTO_APPROVE_TOOLS SONNY_DANGEROUSLY_BYPASS_ALL See the request/deny parsing rules above.

Command option

--dangerously-auto-approve-tools --dangerously-bypass-all on commands that expose these requests; permission ceilings still apply.

Trust scope

Organization, machine and user protected permissions.yaml only; project files cannot grant these settings.

Value shape

false

Individual field shape only; not a complete configuration or an authority grant.

`bypass_isolation`

File key

bypass_isolation in a protected permissions.yaml.

Type

*bool. Pointer fields distinguish omission from an explicit value.

Built-in default

false

Contract

Optional boolean request, last explicit trusted layer wins, subject to ceilings and the isolation floor. Cannot be true beside allow_isolation_bypass=false.

Environment

SONNY_DANGEROUSLY_BYPASS_ISOLATION SONNY_DANGEROUSLY_BYPASS_ALL See the request/deny parsing rules above.

Command option

--dangerously-bypass-isolation --dangerously-bypass-all on commands that expose these requests; permission ceilings still apply.

Trust scope

Organization, machine and user protected permissions.yaml only; project files cannot grant these settings.

Value shape

false

Individual field shape only; not a complete configuration or an authority grant.

Variant routing and approval Share link

Agent-messaging rollout Share link

Validation coverage Share link

Core

Mesh

Trace

Resource Reuse

Variants

Agent Messaging

Decision policy and trusted permissions Share link

Decision-policy files Share link

Protected permission files Share link

Inspect diagnostics and application timing Share link

mode

source

pack

registry

format

worker

test_tool

test_command

grant

verify_protect

fuel

budget

state_dir

delegation

url

tenant

channel

task

trusted_keys

baseline

insecure_http

digest

mode

decisions

actions

retries

wall_ms

model_tokens

depth

children

version

allow_auto_approve

allow_isolation_bypass

auto_approve

bypass_isolation

Variant routing and approval

Agent-messaging rollout

Validation coverage

Decision policy and trusted permissions

Decision-policy files

Protected permission files

Inspect diagnostics and application timing

`mode`

`source`

`pack`

`registry`

`format`

`worker`

`test_tool`

`test_command`

`grant`

`verify_protect`

`fuel`

`budget`

`state_dir`

`delegation`

`url`

`tenant`

`channel`

`task`

`trusted_keys`

`baseline`

`insecure_http`

`digest`

`mode`

`decisions`

`actions`

`retries`

`wall_ms`

`model_tokens`

`depth`

`children`

`version`

`allow_auto_approve`

`allow_isolation_bypass`

`auto_approve`

`bypass_isolation`