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)
    // },
    // Host directories loop/audit/post-action sessions may read despite worktree isolation
    // (e.g. an Obsidian vault). Use absolute host paths; governs Read/Glob/Grep (external_directory).
    // "allowExternalDirectories": ["/abs/host/path/to/vault"]
    //
    // Per-tool deny overrides for loop, audit, and post-action sessions, layered between the
    // external-directory allow rules and Forge's structural denies. Entries are a tool name
    // (pattern "*"), or an object to scope the pattern. Only "deny" entries are supported;
    // an "allow" array is ignored with a warning. Forge-managed permissions ("*",
    // "external_directory", and every structural deny) are rejected, as are blanket denies of
    // Forge-required permissions ("review-read", "plan-read", "section-read", "plan-adjust",
    // "bash", "read") — scope those with a pattern instead of denying them outright.
    // "permissions": {
    //   "deny": ["browser_navigate", { "permission": "bash", "pattern": "git push *" }]
    // }
    //
    // Shared scratch/temp directory available to loops in BOTH modes. It is added to the
    // external_directory allowlist and, for sandboxed loops, bind-mounted read-write at the
    // identical container path so absolute temp paths match host<->container. Created on startup
    // if missing. Defaults to "/tmp/oc-forge".
    // "tmpDir": "/tmp/oc-forge"
    //
    // 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 }
    //   }
    // }
  },

  // Max loops from one group running concurrently. Also bounds concurrent planning passes. Default 3.
  "groupLaunch": {
    "maxConcurrentLoops": 3
  },

  // Sandbox configuration. Sandbox is optional: loops always run in an isolated git worktree, and
  // when the sbx CLI and daemon are available a sandbox is provisioned automatically. Set
  // "enabled": false to force worktree-only mode even when the sbx daemon is running.
  "sandbox": {
    "enabled": true,
    "mode": "sbx",
    "image": "oc-forge-sandbox:latest",
    "imageFeatures": {
      "browserControl": false
    }
    // Mount the source project directory read-only at its identical host path. Defaults to true.
    // "mountProjectReadonly": true,
    // Network access configuration. The sbx proxy is deny-by-default: host loopback is
    // unreachable, and outbound access is allowed only for hosts listed in "allow".
    // "network": {
    //   // Hosts the sandbox may reach. Defaults to none (deny-by-default).
    //   "allow": ["registry.npmjs.org"],
    //   // Host environment variable names passed into each sandbox exec via the env file.
    //   "env": ["MY_VAR"]
    // },
    // 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 }
    // ]
  },

  // 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 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

  // Remote opencode servers available as loop launch targets.
  // Each entry requires "name" (display name in the TUI picker) and "url" (base URL of the server).
  // Optional fields: username (default "opencode"), gitRemote (default "origin"), sandbox (default true).
  // Omit "password" when the remote runs without auth.
  // "sandbox" must mirror the remote server's actual sandbox capability. See docs/configuration.md#remotes.
  // "remotes": [
  //   {
  //     "name": "my-server",
  //     "url": "http://192.168.1.20:4096",
  //     "password": "",
  //     "username": "opencode",
  //     "gitRemote": "origin",
  //     "sandbox": true
  //   }
  // ]

  // 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 }
  // }
}