Documentation

Configuration

Customize how Forage indexes your project and runs its servers.

Config file

Forage reads its configuration from forage.config.json in your project root. This file is created automatically when you run forage --init.

Here is a fully annotated example with all available options:

forage.config.json
{
  "include": ["src", "lib", "app"],
  "exclude": [
    "node_modules",
    "dist",
    "build",
    ".git",
    "coverage",
    "**/*.test.*",
    "**/*.spec.*"
  ],
  "languages": ["javascript", "typescript", "python", "go"],
  "uiPort": 9988,
  "mcpPort": 9989,
  "autoUpdate": true,
  "snapshotOnStart": false,
  "maxFileSizeKb": 512,
  "ai": {
    "provider": "ollama",
    "model": "gpt-oss:120b"
  }
}

Options reference

Indexing

OptionTypeDefaultDescription
include string[] ["./"] Directories or glob patterns to index. Relative to project root.
exclude string[] See defaults Paths and patterns to skip. node_modules, .git, and dist are excluded by default.
languages string[] Auto-detect Languages to parse. Omit to auto-detect from file extensions. Supported: javascript, typescript, python, java, go, rust, cpp, csharp, ruby, php, swift, kotlin
maxFileSizeKb number 512 Files larger than this (in KB) are skipped during indexing.
autoUpdate boolean true Watch for file changes and update the graph incrementally in the background.
snapshotOnStart boolean false Automatically create a graph snapshot each time Forage starts.

Servers

OptionTypeDefaultDescription
uiPort number 9988 Port for the Forage web UI.
mcpPort number 9989 Port for the MCP server. Update your agent configs when changing this.

AI provider

Forage uses a local or remote AI model to power the AI chat interface and natural_language_query MCP tool.

OptionTypeDefaultDescription
ai.provider string "ollama" AI provider. Options: anthropic, openai, ollama, lmstudio
ai.model string Provider default Model name. For ollama use the local model name (e.g. "gpt-oss:120b").
ai.apiKey string env:OLLAMA_API_KEY API key. Prefer setting via environment variable rather than committing to the config file.
ai.baseUrl string Provider default Override the API base URL. Required for local providers like ollama and lmstudio.

Using a local AI model

For a fully air-gapped, zero-data-egress setup, configure Forage to use a local model via Ollama or LM Studio:

forage.config.json — Ollama example
{
  "ai": {
    "provider": "ollama",
    "model": "gpt-oss:120b",
    "baseUrl": "http://localhost:11434"
  }
}
With a local AI provider, and with the exception of the remote Forage licensing server, Forage operates with zero outbound network connections. See the Security page for the full data flow.

.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:

.forageIgnore
# Vendor code
vendor/
third_party/

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

# Large data files
fixtures/
testdata/large/
← API Reference Support →