Settings & environment variables

Layered settings

Priority low → high (later wins):

Layer	Path	Purpose
user	$FORGEAX_CONFIG_DIR/settings.json or ~/.forgeax/settings.json	Global prefs
project	<cwd>/.forgeax/settings.json	Team-shared (committable)
local	<cwd>/.forgeax/settings.local.json	Machine-private (auto-gitignored on write)

Merge semantics: deep-merge objects, union+dedupe arrays, overwrite scalars.

Example

~/.forgeax/settings.json:

{
  "model": "claude-opus-4-8",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Read", "Bash(git *)"],
    "ask": ["Bash(git push*)"],
    "deny": ["Bash(rm *)", "Write(/etc/*)"]
  },
  "sandbox": {
    "enabled": false
  }
}

Directory layout

~/.forgeax/                 # or $FORGEAX_CONFIG_DIR
  settings.json
  skills/
  commands/
  mcp.json

<project>/.forgeax/
  settings.json             # committable
  settings.local.json       # local
  skills/
  commands/
  mcp.json
  sessions/                 # WAL
  memory/                   # auto-memory

Environment variables

Variable	Role
ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL	Anthropic Messages credentials & endpoint
OPENAI_API_KEY / OPENAI_BASE_URL	OpenAI-compatible family (set FORGEAX_PROVIDER_API=openai-compat)
FORGEAX_PROVIDER_API	Force provider backend id (openai-compat, anthropic-messages, gemini, …)
FORGEAX_MODEL	Default model (overridable by --model)
FORGEAX_CONFIG_DIR	Global config root (default ~/.forgeax)
FORGEAX_MEMORY_DIR	Auto-memory directory
FORGEAX_SANDBOX	Enable OS Bash sandbox
FORGEAX_SEARCH_URL	web_search backend
BRAVE_API_KEY	Optional search backend
FORGEAX_NO_TUI	Disable Ink TUI
FORGEAX_MCP_ALLOW_WRITES	Allow mutating tools in mcp-serve
FORGEAX_CORE_SOCK	Fallback sock path for --serve

Hosts (e.g. Studio) that use a proxy gateway should translate that config into these neutral variables before injecting them. The CLI itself is not tied to a specific proxy product name.

Model selection

forgeax --model claude-opus-4-8
forgeax --model gpt-4.1                 # name prefix infers openai-compat
export FORGEAX_PROVIDER_API=openai-compat   # when protocol cannot be inferred from the model name

Next

• Permissions — permissions.* rule details
• MCP — mcp.json shape
• CLI reference — full flag list