Configuration

Safely inspect, change, validate, and recover Oktapod configuration.

Oktapod configuration is layered on purpose. The file establishes the local bootstrap posture; durable scoped overrides can change selected runtime choices; and explicitly supplied environment variables can override both where a setting supports them. Use the operator CLI for changes so each mutation is validated, journaled, health-checked, and recoverable.

#Find the active configuration

The usual file is ~/.oktapod/oktapod.json (or $OKTAPOD_HOME/oktapod.json). Oktapod never searches a project or its ancestors for .oktapod, so running a command from a repository cannot create or adopt repository-local runtime state. An explicit OKTAPOD_CONFIG_PATH selects a specific file instead.

Host-level doctor, readiness, evidence, and usage reports resolve the same OKTAPOD_HOME, OKTAPOD_CONFIG_PATH, and OKTAPOD_DATA_DIR environment as the command that invoked them. They do not silently fall back to another profile.

Start by inspecting what is active. Secrets are redacted in show output:

oktapod config file
oktapod config show --verbose
oktapod config validate
oktapod config get model_providers

The file must be a JSON object. Use schema version 1 when declaring a root version. config validate checks the bootstrap document; it does not prove that every remote provider account, external URL, or third-party extension is currently healthy. Follow a change with oktapod doctor or oktapod checkup.

#The mental model: how values win

For supported runtime settings, think in this order:

product defaults
  → bootstrap file (~/.oktapod/oktapod.json)
  → durable scoped runtime override (where that setting supports one)
  → explicitly supplied environment variable (where supported)

The bootstrap file's env block supplies defaults to the process environment; it does not overwrite an environment variable already set by your shell or service manager. Durable overrides are intentionally limited to selected runtime controls, such as model and ACP choices, not a generic second copy of the whole config file. An explicit process environment override is useful for a temporary deployment or secret injection, but it makes the effective value less visible in the file.

Do not assume every internal setting participates in every layer. Confirm the effective behavior with the specific feature's status command and doctor.

#Outbound observability is explicit

Metrics, traces, logs, and error reporting stay local unless the process or service environment sets OKTAPOD_OBSERVABILITY_ENABLED=true. Collector and error-tracking destinations remain inert without that flag, including inherited OTEL_* and SENTRY_DSN values.

Treat this as deployment configuration, not a durable agent preference. Keep DSNs and collector credentials in a protected environment file or secret store. See Privacy and your data for the default and for temporary support sessions.

#Supported bootstrap blocks

The top-level document is extensible, but these are the common operator-facing blocks. Prefer setup/onboard commands for provider credentials and device configuration; edit a block directly only when you understand the setting.

Other focused blocks can be written by supported setup flows (for example voice or media generation). They are feature configuration, not a promise that every future internal knob is a stable public option.

#A small, safe shape

This is an illustrative local starting point. Values and provider names must be real for your deployment; do not paste placeholder secrets into a live file.

{
  "version": 1,
  "core": {
    "core_http_host": "127.0.0.1",
    "core_http_port": 8787,
    "policy_version": "policy-matrix"
  },
  "gateway": {
    "http_host": "127.0.0.1",
    "http_port": 8788
  },
  "model_providers": {
    "version": 1,
    "task_routing": "automatic",
    "chain": ["openai:primary"],
    "providers": {
      "openai:primary": {
        "kind": "openai_responses",
        "model": "<model-id>",
        "auth": {
          "credential_ref": {
            "source": "env",
            "env_var": "OPENAI_API_KEY"
          }
        }
      }
    }
  }
}

Use task_routing: "automatic" for normal task-aware routing. Set "pinned" only when you deliberately want configured model selection to remain fixed. Use oktapod models status --verbose after changing providers or the fallback chain.

#Inspect and mutate safely

Use dotted paths with get, set, and unset:

oktapod config get gateway.http_host
oktapod config set gateway.http_host --value 127.0.0.1
oktapod config set model_providers.chain --value '["openai:primary","local:backup"]' --json-value
oktapod config unset coder.default_model
oktapod config validate
oktapod doctor

Without --json-value, set writes a string. Use --json-value for JSON arrays, objects, numbers, or booleans. Always inspect the intended path first, then validate and run a health check. Avoid a broad root replacement for a small setting change.

--help and -h are safe: they return before configuration resolution or a mutation, even when the rest of the command looks complete.

#Mutation safety, journal, and rollback

CLI mutations are not blind file edits. Oktapod writes and validates a candidate, records semantic/subprocess/health outcome in a journal, and creates a last-known-good rollback snapshot before applying a meaningful change. The runtime reload kind may be live-safe, soft reload, rolling restart, or full restart; the health gate verifies the result and restores the prior snapshot if activation fails.

Inspect the evidence before retrying anything:

oktapod config journal list --limit 10
oktapod config journal inspect <mutation_id>
oktapod config rollback status

If a rejected mutation has a valid snapshot, restore it explicitly:

oktapod config rollback restore-last-known-good
oktapod config validate
oktapod doctor

Repeatedly failing mutation fingerprints are quarantined. This prevents a bad configuration from being retried indefinitely. Inspect first, fix the root cause, then clear the specific quarantine only when ready to retry:

oktapod config journal quarantine list
oktapod config journal quarantine clear <fingerprint>
oktapod config repair

config repair explains the recommended recovery. --apply-rollback performs the available rollback; --approve-retry-latest clears the current failed fingerprint only after you resolve the cause. Neither option skips validation or makes an unsafe setting safe.

#Secrets: references over inline values

Treat ~/.oktapod/oktapod.json as sensitive configuration even when it mostly contains references. Prefer a secret reference to an inline token:

{
  "credential_ref": {
    "source": "env",
    "env_var": "OPENAI_API_KEY"
  }
}

Supported secret-reference shapes include environment variables, protected files, command-based resolution, and literals where a specific integration allows them. Use an environment variable or a permission-restricted secret file for normal operation; guided OAuth setup can place a client secret in a separate 0600 file and retain only the file reference in config.

Do not commit inline API keys, OAuth secrets, gateway tokens, channel tokens, or MCP authorization headers. Avoid putting raw values in config set, shell history, terminal captures, support tickets, or memory corrections. oktapod config show redacts recognized sensitive fields, but redaction is a diagnostic convenience, not a substitute for keeping secrets out of the file.

#Common changes

Change a model chain. Use oktapod models when possible, then confirm the effective provider state:

oktapod models status --verbose
oktapod config get model_providers.chain

Configure a proxy. Use the egress_proxy block, restart, and validate health. The proxy's enforced mode covers selected Oktapod HTTP(S) surfaces; pair it with firewall/container policy for non-bypassable egress.

oktapod config get egress_proxy
oktapod restart
oktapod doctor

Add an MCP connector. Let the connector broker create the correct mcp_servers.<id> record, then inspect it:

oktapod connector add https://mcp.example.test
oktapod config get mcp_servers.<connector_id>
oktapod restart

Adjust coding harness settings. Inspect ACP first; keep the allowed harness list narrow and leave the approval policy at its safe default unless you have a specific workflow to test.

oktapod acp status
oktapod config get acp
oktapod acp doctor

#Troubleshooting

#What not to configure by hand

Avoid copying undocumented environment variables or internal database settings from source code into production. Do not edit SQLite tables to override runtime state, and do not use the bootstrap file to grant approval authority. For provider connections, skills, integrations, channels, and devices, start with guided setup or dedicated operator commands; it keeps config, durable state, credential handling, and the recovery journal aligned.