Configuration

CLI flags, environment variables, defaults, and example configurations for Forge.

Precedence

CLI flag Environment variable Default

Configuration Table

Flag	Env Var	Default	Description
--max-sessions	FORGE_MAX_SESSIONS	10	Max concurrent PTY sessions
--idle-timeout	FORGE_IDLE_TIMEOUT	1800000	Session idle timeout in ms (30 min)
--buffer-size	FORGE_BUFFER_SIZE	1048576	Ring buffer size per session (1 MB)
--shell	SHELL	/bin/bash	Default shell for create_terminal
--claude-path	FORGE_CLAUDE_PATH	claude	Path to Claude CLI binary
--auth-token	FORGE_AUTH_TOKEN	unset	Require Bearer token for /mcp, /api, and /ws
--dashboard	FORGE_DASHBOARD	off	Enable web dashboard
--port	FORGE_DASHBOARD_PORT	3141	Dashboard port
--verbose	—	off	Enable debug logging to stderr

Example Configurations

Claude Code with dashboard

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--dashboard", "--port", "3141"]
    }
  }
}

Custom config with all options

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--max-sessions", "20", "--idle-timeout", "3600000", "--dashboard"]
    }
  }
}

With auth token

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--dashboard", "--auth-token", "my-secret-token"]
    }
  }
}

Daemon Mode

Start Forge as a background daemon for HTTP MCP clients:

$ npx forge-terminal-mcp start -d --port 3141
$ npx forge-terminal-mcp status
$ npx forge-terminal-mcp stop

Data Storage

Forge stores data in ~/.forge/:

sessions.json Session metadata (reloaded on restart)
history/{id}.jsonl Per-session tool call history