Deployment configuration

Choose the process you need before writing TOML. Use one file for that process, validate the effective result, and start the same command with the same file.

Do not copy fields between these boundaries. The strict schema rejects unknown or role-incompatible values instead of ignoring them.

Value resolution

The awaken product command resolves exactly three sources, in order:

1. presentation overrides such as --port, --data-dir, and --no-browser;
2. an explicit --config <path> or the standard ~/.awaken/config.toml;
3. typed defaults.

Process environment is not a deployment, model, business, or credential configuration source. Use awaken config or awaken config --json to inspect the effective, redacted result and value origins.

flowchart LR
  C[Command and presentation overrides] --> R[Typed resolver]
  F[Explicit or standard TOML] --> R
  D[Typed defaults] --> R
  R --> V{Role and cross-field validation}
  V -->|valid| E[Redacted effective configuration]
  V -->|invalid| X[Exit before service startup]
  E --> S[Start the selected process]

Common fields

Unknown TOML fields fail parsing. Command-line role subcommands (control, coordinator, worker) override role so the invoked process cannot silently acquire a broader role from the file.

Stores and schema lifecycle

Local mode migrates embedded stores during startup. Shared server deployments must run this before application Pods:

awaken database migrate --config /etc/awaken/config.toml

Application startup in server mode verifies the existing schema without writing DDL. A Worker rejects all authority database fields. Control rejects Coordinator execution databases; Coordinator rejects Control databases and the Control seal key.

Private service boundaries and secrets

awaken config never prints token values, database URLs, or seal-key material.

Worker fields

The standalone process is awaken-worker --config <path> --server <coordinator-url>; worker_server may supply the URL in TOML. Its config uses a strict schema. The accepted fields are:

A Worker is database-free. It receives claim-fenced File, Memory, Skill, Repository-verification, credential, and commit clients during registration.

Product launcher execution, Sandbox, and wake fields

The following fields belong to the awaken product-launcher configuration. Do not copy its warm-pool, proxy, package-builder, or wake fields into a standalone awaken-worker file; the strict Worker schema rejects unknown keys.

See Configure Sandbox tiers and Use a NATS wake signal for task guidance.

Observability and content capture

The product command reads log_filter, log_format, trace_file, the otlp_* / otel_* fields, content_capture, and content_redaction from the same TOML document. log_format is text or json; content capture is off, structured, or full. Configure retention and privacy before enabling full content capture.

Minimal profiles

AllInOne local:

role = "all-in-one"
mode = "local"
data_dir = "/srv/awaken"
bind = "127.0.0.1:8080"
run_local_pool = true
no_browser = false

Database-free Worker:

role = "worker"
mode = "server"
worker_server = "http://awaken-coordinator:8080"
worker_credential_material_root = "/run/awaken/credentials"
worker_credential_trust_domain = "awaken.worker"

Validate before startup

sequenceDiagram
  participant U as You
  participant C as awaken config
  participant S as Strict file schema
  participant V as Deployment validator
  participant P as Selected process

  U->>C: Supply command, overrides, and config path
  C->>S: Parse known fields
  S->>V: Resolve defaults and role constraints
  alt configuration is valid
    V-->>U: Print redacted values and origins
    U->>P: Start with the same config path
  else parsing or validation fails
    V-->>U: Exit with the offending field or constraint
  end

Hand placement is deliberately absent from deployment TOML. A claimed Worker realizes the Session’s frozen Environment, and that Environment owns the one Hand used by Native or ACP execution. The standalone awaken-sandbox hand relay is a low-level execution primitive, not a second product placement path.