forge-config.jsonc

{
  // Data directory for plugin storage (forge.db, logs)
  // When empty, resolves to ~/.local/share/opencode/forge (or XDG_DATA_HOME equivalent)
  "dataDir": "",

  // Logging configuration
  "logging": {
    "enabled": false,
    "debug": false,
    "file": ""
  },

  // Session compaction settings
  "compaction": {
    "customPrompt": true,
    "maxContextTokens": 0
  },

  // Messages transform hook for read-only enforcement
  "messagesTransform": {
    "enabled": true,
    "debug": false
  },

  // Model override for plan execution sessions (format: "provider/model")
  "executionModel": "",

  // Model override for the auditor agent (format: "provider/model")
  "auditorModel": "",

  // Default variant (reasoning/thinking-effort) for the execution model (e.g., "high", "max")
  "executionVariant": "",

  // Default variant for the auditor model (independent; does not inherit executionVariant)
  "auditorVariant": "",

  // Ordered auditor fallback models used when the current auditor model hits a provider
  // usage/auth limit mid-loop. Tried in order. Entries are a "provider/model" string, or
  // an object to pin a variant to that fallback; auditorVariant is NOT inherited, so a
  // string entry runs with no variant. Empty/omitted means a limited auditor terminates
  // the loop as before.
  // "auditorFallbackModels": ["provider/model-b", { "model": "provider/model-c", "variant": "high" }],

  // Iterative development loop settings
  "loop": {
    "enabled": true,
    "defaultMaxIterations": 15,
    "cleanupWorktree": false,
    "stallTimeoutMs": 60000,
    "maxConsecutiveStalls": 5,  // 0 = disabled; default 5
    "busyStallTimeoutMs": 900000,  // busy with no tool activity or streamed content → abort + continue; 0 = disabled
    // Worktree loop completion logging (off by default)
    "worktreeLogging": {
      "enabled": false,
      "directory": ""
    }
    // Post-completion action (skill and/or prompt) run inside the worktree before teardown.
    // (disabled by default)
    // "postAction": {
    //   "enabled": false,
    //   "skill": "pr-review",
    //   "prompt": "Auto-defer anything needing clarification; do not use the question tool.",
    //   "model": "provider/model"  // optional: override model (defaults to auditor model chain)
    // },
    // "allowExternalDirectories": ["/abs/host/path/to/vault"]
    //
    // "permissions": {
    //   "deny": ["browser_navigate", { "permission": "bash", "pattern": "git push *" }]
    // }
    //
    // Inline opencode config written as opencode.jsonc into each loop worktree (skip-if-exists;
    // never overwrites a committed opencode.json/opencode.jsonc). Primarily for enabling per-loop
    // MCP servers. The written file is git-excluded so it never enters loop commits.
    // "worktreeOpencodeConfig": {
    //   "mcp": {
    //     "my-server": { "type": "local", "command": ["npx", "some-mcp-server"], "enabled": true }
    //   }
    // }
  },

  "sandbox": {
    "enabled": true,
    "mode": "msb",
    "image": "oc-forge-sandbox:latest"
    // Mount the source project directory read-only at its identical host path. Defaults to true.
    // "mountProjectReadonly": true,
    // Resolve permission prompts to allow or deny in sessions whose shell runs in a sandbox (e.g.
    // after turning it on in the `Host sandbox` menu), using the auto-approve policy. Defaults to true.
    // "autoApprovePermissions": true,
    // Host environment variables pass through at create time as bare names (msb resolves each name
    // from its own environment, so values never appear on forge's command line); host-held
    // secrets are bound reference-only and exposed inside the sandbox as $MSB_<env> placeholders
    // that msb substitutes only for the listed hosts.
    // "network": {
    //   // OPT-IN egress restriction: hosts the sandbox may reach. Leave empty (or omit) for
    //   // msb's default of allowing all public egress.
    //   "allow": ["registry.npmjs.org"],
    //   // Host environment variable names to inject into the sandbox at create time.
    //   // Only names set in the host process are injected, as ordinary guest environment
    //   // variables (msb resolves a bare name from its own environment, so the value never
    //   // appears on forge's command line). Host-held credentials belong in "secrets" instead,
    //   // which never enter the guest.
    //   "env": ["MY_VAR"],
    //   // Host-held credentials bound at create time. Each entry references a host env var and
    //   // the hostnames allowed to receive its real value at the network boundary; the value
    //   // never enters the guest. The named variable must be exported in the environment that
    //   // launches opencode: a bound secret with a missing variable makes every sandboxed shell
    //   // command fail, and forge logs a warning naming the variable.
    //   "secrets": [
    //     { "env": "NPM_TOKEN", "hosts": ["registry.npmjs.org"] }
    //   ],
    //   // Allow the sandbox to reach private (LAN) address ranges, which msb blocks by default
    //   // even when public egress is open. Exposes every service on your LAN to agent-run commands.
    //   // Applied at create time; the loop settings dialog and the Host sandbox menu can override
    //   // it per sandbox. Defaults to false.
    //   "allowLan": false
    // },
    // Additional host directories to bind-mount into the sandbox at their identical host path.
    // "readonly" defaults to true (read-only); set false to grant the sandbox read-write access.
    // "mounts": [
    //   { "host": "/abs/host/reference" },
    //   { "host": "/abs/host/cache", "readonly": false }
    // ]
    // Per-sandbox resources. Both disks are dedicated block devices mounted at create time and are
    // sparse, so the generous defaults cost no real host disk until used. Disk sizes are fixed at
    // creation; the Host sandbox menu can change CPUs and memory on a running host sandbox, which
    // restarts it in place.
    // "resources": {
    //   // Backs the in-VM Docker Engine data dir (/var/lib/docker).
    //   "dockerDisk": "16g",
    //   // Backs /opt/forge/cache (pnpm store, npm/uv/pip caches, uv-managed Pythons, cargo registry/git,
    //   // Go modules), keeping unbounded tool caches off the small sandbox root filesystem.
    //   "cacheDisk": "16g"
    // }
  },

  // Policy applied while auto-approve is on for a session. Requests are only ever allowed or
  // denied, never prompted. Extra deny rules use OpenCode permission action/resource wildcard
  // syntax; explicit OpenCode "ask" rules are allowed and OpenCode "deny" rules still deny.
  // "autoApprove": {
  //   "deny": [
  //     { "action": "shell", "resource": "rm -rf *" }
  //   ]
  // },

  // TUI sidebar widget configuration
  "tui": {
    "sidebar": true,
    "showVersion": true,
    // Optional keybinds for Forge palette commands. Leave a value empty to
    // register the command without a default binding (run it from the palette).
    "keybinds": {
      "executePlan": "<leader>f",
      "dashboard": ""
    }
  },

  // Dashboard HTTP server bind address (`pnpm dashboard` and the TUI "Open web dashboard" command).
  // Defaults to loopback only. Use "0.0.0.0" to listen on all interfaces so the dashboard is
  // reachable from other devices on a LAN or VPN.
  // WARNING: the dashboard has NO authentication. A non-loopback bind exposes every loop plan,
  // goal, audit result, finding, and cost to anyone who can reach the port. Restrict access with
  // a firewall or VPN.
  // Consecutive ports (port..port+9) are tried when the configured port is busy.
  "dashboard": {
    "host": "localhost",
    "port": 4747
  },

  // TTL in ms for completed/cancelled loops before cleanup. Default: 604800000 (7 days)
  "completedLoopTtlMs": 604800000

  // Per-agent overrides (temperature range: 0.0 - 2.0)
  // Keys are agent display names (e.g., "code", "architect", "auditor")
  // "agents": {
  //   "architect": { "temperature": 0.0 },
  //   "auditor": { "temperature": 0.0 },
  //   "code": { "temperature": 0.7 }
  // }
}