Gateway

The local server that every BudgetAI surface connects to — lifecycle, host/port, and health.

The gateway is a local server that every surface — Web UI, CLI, and channels — connects to. It manages sessions, approvals, scheduling, and budgets, and drives the shared turn loop.

Lifecycle

budgetai gateway run       # run in this terminal at 127.0.0.1:18791
budgetai gateway start     # run in the background, wait until healthy
budgetai gateway restart   # apply new config
budgetai gateway stop

Open the control console at http://127.0.0.1:18791/control/.

Host and port

budgetai gateway run --listen 0.0.0.0 --port 18791

Do not bind to 0.0.0.0 with auth mode = "none". Set up token login first, then open the port in your firewall.

Health

budgetai doctor
budgetai doctor --json

/health and /healthz are liveness checks. budgetai doctor and the Web UI Health page check provider setup, memory, search, channels, sandbox posture, and routing, and suggest fixes.

Config resolution

BudgetAI reads the first config it finds:

  1. BUDGETAI_GATEWAY_CONFIG_PATH
  2. ./budgetai.toml
  3. ~/.budgetai/config.toml
  4. Built-in defaults

Secret values from environment variables always win over file values.

PreviousUse Cases & RecipesNext Configuration