Configuration

Config files

Forage uses two config files:

• Global config — ~/.forage/config.json — applies to all workspaces. Created automatically on first run.
• Workspace config — {workspace}/.forage/config.json — per-project overrides. Most fields are null by default, meaning they inherit the global value.

The easiest way to edit these is through the Forage web UI at http://localhost:9988 → Settings. Forage automatically generates its API key on first run — do not edit the apiKey field manually.

Global config template with all available options:

{
  "port": 9988,
  "mcpPort": 9989,
  "listenOnAllInterfaces": false,
  "corsOrigins": "",
  "apiKey": "<auto-generated>",
  "ollama": {
    "url": "http://localhost:11434",
    "apiKey": "",
    "model": "llama3",
    "reasoningEffort": "medium",
    "codingModel": "",
    "codingUrl": "",
    "codingApiKey": "",
    "codingReasoningEffort": "medium",
    "modelParams": {},
    "codingModelParams": {}
  },
  "chat": {
    "autoCompactAt": 75,
    "keepFirstMessages": 2,
    "keepLastMessages": 6
  },
  "snapshots": {
    "heartbeatIntervalMinutes": 30
  },
  "annotations": {
    "heartbeatIntervalMinutes": 0,
    "batchSize": 5
  },
  "agentAutonomy": "supervised",
  "workspacesDir": "",
  "services": {
    "watchFiles": true,
    "mcpServer": true,
    "startOnBoot": false
  },
  "proxy": {
    "enabled": false,
    "protocol": "http",
    "host": "",
    "port": 0,
    "username": "",
    "password": ""
  },
  "google": {
    "clientId": "",
    "clientSecret": ""
  }
}

Options reference

Servers

AI providers

Forage talks to four kinds of model backends: a local Ollama server, or the hosted OpenAI, Anthropic (Claude), and Google Gemini APIs. chatProvider and codingProvider each independently select which one serves the Chat Model (Graph page AI chat, the ask MCP tool) and the Coding Model (Editor code assistant, the code_task MCP tool) — you can mix them, e.g. Claude for chat and a local Ollama model for coding.

Ollama

OpenAI / Anthropic / Gemini

These three are API-key-only providers (no OAuth/login flow) and share the same shape: apiKey and model for the Chat Model, plus optional codingModel / codingApiKey overrides for the Coding Model — same fallback behavior as the Ollama block above.

{
  "chatProvider": "anthropic",
  "codingProvider": "ollama",
  "anthropic": {
    "apiKey": "sk-ant-...",
    "model": "claude-sonnet-5"
  },
  "ollama": {
    "url": "http://localhost:11434",
    "codingModel": "gpt-oss:32b"
  }
}

Chat

Snapshots & Annotations

Agent & Services

Proxy

Google (optional)

Required only if you want to export documentation to Google Docs. Obtain credentials from the Google Cloud Console.

Workspace config

Each workspace can override a subset of the global config. A null value means "inherit from global".

{
  "name": "my-project",
  "ollama": null,
  "chatProvider": null,
  "codingProvider": null,
  "openai": null,
  "anthropic": null,
  "gemini": null,
  "testCommand": null,
  "agentAutonomy": null,
  "snapshots": null,
  "annotations": null
}

Using a local AI model

Ollama remains the default provider and the only fully local, zero-data-egress option — Forage also supports hosted OpenAI, Anthropic, and Gemini models (see AI providers above) for teams that prefer them, but those send code context to that provider's API. For a fully air-gapped setup, leave chatProvider/codingProvider at "ollama", set ollama.url to your Ollama server, and choose a model:

{
  "ollama": {
    "url": "http://localhost:11434",
    "model": "gpt-oss:120b",
    "codingModel": "gpt-oss:32b"
  }
}

.forageIgnore

You can also create a .forageIgnore file in your project root (same syntax as .gitignore) to exclude paths from indexing without editing the config file:

# Vendor code
vendor/
third_party/

# Generated files
*.pb.go
*.generated.ts

# Large data files
fixtures/
testdata/large/