packages/docs/cli/environment.mdx
These variables are read by the CLI wrapper (run-node.mjs) and the embedded runtime. They are not a complete list of every model or connector secret -- see Configuration and Plugin setup for provider keys.
ELIZA_* variables are aliased to their ELIZA_* equivalents at startup (e.g. ELIZA_API_PORT maps to ELIZA_API_PORT). Either form works; the ELIZA_ prefix is the canonical user-facing name.
| Variable | Purpose |
|---|---|
ELIZA_STATE_DIR | Override state directory (config, credentials, caches). Default ~/.eliza/. |
ELIZA_CONFIG_PATH | Explicit path to eliza.json. |
ELIZA_NAMESPACE | Namespace segment for default paths (eliza produces ~/.eliza/). |
ELIZA_WORKSPACE_DIR | Default agent workspace root. |
| Variable | Default | Purpose |
|---|---|---|
ELIZA_PORT / ELIZA_UI_PORT | 2138 | Server-only port (eliza start) and UI port in dev mode. |
ELIZA_API_PORT | 31337 | API port in dev mode (when API and UI run on separate ports). |
ELIZA_API_TOKEN | (none) | API authentication token. When set, all API requests require Authorization: Bearer <token>. |
ELIZA_API_BIND | 127.0.0.1 | API server bind address. Non-loopback addresses auto-generate a connection key if no token is set. |
ELIZA_GATEWAY_PORT | 18789 | Gateway port (local services). |
ELIZA_HOME_PORT | 2142 | Home app port. |
In dev mode (bun run dev), the dev orchestrator auto-shifts to the next free port when defaults are busy, and syncs env vars.
| Variable | Purpose |
|---|---|
ELIZA_SKIP_LOCAL_UPSTREAMS | Prefer npm @elizaos/* over repo-linked ./eliza packages. |
NODE_PATH | Must include the repo node_modules root for dynamic plugin imports -- set by supported launchers. |
Run eliza doctor after changing ports or state paths to catch mismatches before you start the server.
| Variable | Purpose |
|---|---|
ELIZA_DISABLE_EDGE_TTS | Set to 1 to prevent auto-loading @elizaos/plugin-edge-tts. When the agent orchestrator is loaded, Eliza adds Edge TTS by default so swarm/PTY paths have a TTS handler -- this makes outbound calls to Microsoft's cloud. Disable if you want no network TTS. |
ELIZA_DISABLE_AUTO_BOOTSTRAP | Set to 1 to skip the one-shot native optimization bootstrap at runtime boot. |
ELIZA_DISABLE_TRAJECTORY_LOGGING | Set to 1 to opt out of trajectory persistence. Also disabled when NODE_ENV=test. |
ELIZA_ENABLE_CHILD_SKILL_CALLBACK | Set to 0 to disable the child→parent USE_SKILL bridge for spawned coding agents. Default: enabled. |