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": "",

  // Iterative development loop settings
  "loop": {
    "enabled": true,
    "defaultMaxIterations": 15,
    "cleanupWorktree": false,
    "stallTimeoutMs": 60000,
    "maxConsecutiveStalls": 5,  // 0 = disabled; default 5
    // 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"]
    //
    // 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; when Docker is unavailable, loops run in worktree-only mode.
  // Currently only Docker is supported; additional modes may be added later.
  // Set "enabled": false to force worktree-only mode even when Docker is available.
  "sandbox": {
    "enabled": true,
    "mode": "docker",
    "image": "oc-forge-sandbox:latest"
    // Mount the source project directory as a read-only volume. Defaults to true.
    // "mountProjectReadonly": true,
    // Container path for the read-only project mount. Defaults to '/project'.
    // "projectMountPath": "/project",
    // Network access configuration (host gateway, env passthrough).
    // "network": {
    //   // Enable host.docker.internal gateway. Defaults to true.
    //   "hostGateway": true,
    //   // Environment variable names to pass through from host process into the container.
    //   "env": ["MY_VAR"]
    // },
    // Every sandbox runs Docker-in-Docker by default: a nested, isolated Docker daemon inside
    // each container so loops can build and run containers (e.g. end-to-end tests). Each loop
    // gets its own daemon and storage, and the container runs as root (required by the nested
    // daemon); privileges are confined to the Docker host VM/daemon, not the host OS.
    // Additional host directories to bind-mount into the sandbox container.
    // Each entry requires absolute host + container paths; "readonly" defaults to true (read-only).
    // Set "readonly": false to grant the container read-write access to the host directory.
    // "mounts": [
    //   { "host": "/abs/host/reference", "container": "/reference" },
    //   { "host": "/abs/host/cache", "container": "/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": ""
    }
  },

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