Configuration

AutoCode reads optional JSONC configuration from global OpenCode configuration first, then from project locations. Later candidates override earlier candidates, so local worktree or directory settings can replace global defaults without copying the whole file.

Configuration locations

Configuration keys

OpenCode applies a last-matching-rule-wins model to external-directory permissions. Place broad defaults first and more specific overrides later.

See OpenCode Go documentation for supported model names.

Web session links

AutoCode resolves server URL in this order:

1. AUTOCODE_WEB_URL
2. Runtime server URL
3. Client base URL

AUTOCODE_WEB_URL independently sets origin used for browser links. When unset, browser links use resolved server origin. For example:

AUTOCODE_WEB_URL="https://app.example.com"

AUTOCODE_WEB_URL selects server URL. AUTOCODE_WEB_URL overrides only browser-link origin.

Skills

Set autocode.skills.freeze to true to strictly skip first-run extraction and every generated-root mutation. Existing stale generated skills remain until manually removed or a later unfrozen startup updates them.

Local memories are not configured as learned skills. The active store is .opencode/autocode/memories/, starts empty for this transition, and receives Markdown .md memory files only through learn; no legacy import, conversion, or seed occurs. The recoverable snapshot is .opencode/autocode/memory-archive/v1/.agents/skills/<original learned path>/SKILL.md, outside skill discovery and active-memory scans. The shared repository-root .gitignore ignores both paths.

Tiers

Tier assignment requirements:

spy agent is available only when selected tier set explicitly configures a spy tier. No default spy model exists, and balanced does not enable spy. auto agents requires an explicitly configured smart tier.

spy gives read-only safety review and guidance. Use it directly: it is visible as a primary agent and cannot receive session handoff.

Complete Configuration Example

{
  "autocode": {
    "skills": {
      "freeze": false
    },
    "tier": "openai",
    "tiers": {
      "openai": {
        "smart":    { "model": "openai/gpt-5.6-sol", "variant": "high" },
        "balanced": { "model": "openai/gpt-5.6-terra", "variant": "medium" },
        "operator": { "model": "openai/gpt-5.6-terra", "variant": "low" },
        "context":  { "model": "openai/gpt-5.6-luna", "variant": "low" },
        "fast":     { "model": "openai/gpt-5.3-codex-spark", "variant": "low" },
        "cheap":    { "model": "openai/gpt-5.6-luna", "variant": "none" },
        "spy":      { "model": "ollama/llama-3.1-8B", "variant": "none" }
      },
      "zai-coding-plan": {
        "smart":    { "model": "zai-coding-plan/glm-5.2", "variant": "high" },
        "balanced": { "model": "zai-coding-plan/glm-5.2", "variant": "high" },
        "operator": { "model": "zai-coding-plan/glm-5.2", "variant": "high" },
        "context":  { "model": "zai-coding-plan/glm-4.7", "variant": "low" },
        "fast":     { "model": "zai-coding-plan/glm-4.5-air", "variant": "low" },
        "cheap":    { "model": "zai-coding-plan/glm-4.5-air", "variant": "low" }
      }
    }
  },
  "permission": {
    "external_directory": {
      "/tmp/safe/**": "allow",
      "/tmp/safe/specific": "deny"
    }
  }
}

Database environment variables

Replace {db_key} with letters, digits, or underscores. Environment lookup is case-insensitive. Then instruct agent to use your chosen {db_key} to access your DB.

REST authentication

For REST tools that use rest_key, authentication is resolved in this order:

1. An explicit request Authorization header is used when provided.
2. Otherwise, AutoCode uses AUTOCODE_REST_<KEY>_AUTHORIZATION.
3. Otherwise, it builds HTTP Basic authentication from both AUTOCODE_REST_<KEY>_USERNAME and AUTOCODE_REST_<KEY>_PASSWORD.

Replace <KEY> with the rest_key in uppercase. For example, for rest_key: billing:

AUTOCODE_REST_BILLING_AUTHORIZATION="Bearer <token>"

Use either the raw Authorization variable or the username/password pair; do not place real credentials in project files.

SSH tool suite

Configure each SSH target with {ssh_key} environment variables:

AUTOCODE_SSH_{ssh_key}_HOST must contain only a hostname or IP address. AutoCode does not parse host:port values from HOST; set AUTOCODE_SSH_{ssh_key}_PORT when a target uses a non-default port.

Keyfile auth has precedence. A nonexistent or unreadable keyfile falls back to password. AUTOCODE_SSH_{ssh_key}_AGENT is used only when there is no readable AUTOCODE_SSH_{ssh_key}_KEYFILE and no AUTOCODE_SSH_{ssh_key}_PASSWORD. Idle SSH connections can be reused for 5 minutes. Remote glob/grep/patch/edit/write mirror local tool intent where practical, not exact parity.