Skip to content
Documentation
Getting started
Configuration
Capabilities
Control
Reference

Configuration

Every setting, and the order in which the sources are resolved.

Forge reads its settings from five places. Every setting can be given in any of them, and the first source that defines one wins - so a flag beats an environment variable, and a project file beats your personal defaults.

Precedence

sourceexample
1. CLI flags
--model, --mode, --sandbox, …
2. Environment
FORGE_* then ANTHROPIC_*
3. ./forge.toml
per-project, committed
4. ~/.config/forge/config.toml
per-user, respects XDG_CONFIG_HOME
5. Defaults
built into Settings

Highest first. This ordering is what makes a checked-in forge.toml safe: it constrains everyone who runs Forge in the repository, while still letting an individual override a setting for one run with a flag.

Config files

Both files are TOML and both are optional. Keys are the environment variable name without the FORGE_ prefix, lowercased.

Per project

./forge.toml, resolved from the workspace root. Commit it - it is how you tell everyone working in the repository which model to use and how much freedom the agent gets.

forge.toml
# forge.toml  -  committed, applies to this repositorymodel = "claude-sonnet-4-5"approval_mode = "cautious"sandbox = "docker"max_iterations = 40enable_git_tools = true

Per user

~/.config/forge/config.toml, or $XDG_CONFIG_HOME/forge/config.toml if you set that. Put your own defaults here, not credentials you would mind leaking into a backup.

~/.config/forge/config.toml
# ~/.config/forge/config.toml  -  your defaults, every repositorymodel = "claude-sonnet-4-5"approval_mode = "auto"log_level = "WARNING"

Environment

Every setting has an environment variable. Forge reads the FORGE_ name first, then falls back to the ANTHROPIC_ one where a standard name already exists - so an existing Anthropic setup works with no new variables at all.

variablesets
ANTHROPIC_MODEL
Model id to use. Also FORGE_MODEL.
ANTHROPIC_BASE_URL
Base URL of the Anthropic-compatible API. Also FORGE_BASE_URL.
ANTHROPIC_AUTH_TOKEN
Bearer token, for gateways. Also FORGE_AUTH_TOKEN.
ANTHROPIC_API_KEY
API key, as an alternative. Also FORGE_API_KEY.
FORGE_APPROVAL_MODE
cautious | auto | yolo.
FORGE_SANDBOX
none | docker.
FORGE_MAX_ITERATIONS
Loop ceiling per task.
FORGE_ENABLE_GIT_TOOLS
Register the git tools. Default on.
FORGE_LOG_LEVEL
Step-log level on stderr. Default WARNING.
FORGE_LOG_JSON
Emit structured logs as JSON.

Credentials belong in the environment, not in forge.toml. A committed config file with an API key in it is a leaked API key.

Inspecting what resolved

Precedence is only useful if you can see the result. forge config prints the merged configuration with secrets redacted, and it is the authoritative answer - if this page and that command disagree, the command is right.

$ forge config

Run it before a long unattended task. It is the fastest way to catch a model you did not mean to spend money on, or a workspace pointing somewhere unexpected.