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

Ollama (AI models)

Forage uses a local Ollama server for all AI features. Configure the Chat Model (used by the Graph page AI chat and the ask MCP tool) and optionally a separate Coding Model (used by the Editor code assistant and the code_task MCP tool).

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,
  "testCommand": null,
  "agentAutonomy": null,
  "snapshots": null,
  "annotations": null
}

Using a local AI model

For a fully air-gapped, zero-data-egress setup, configure Forage to use a local model via Ollama. Set the 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/