Environment variables

Read by the CLI

Variable	Meaning
`GRAPHMIND_DB`	Database path (`--db` beats it; default `~/.graphmind/graphmind.db`)
`GRAPHMIND_PAUSE_ON_ERROR`	Scope the default error breakpoint: `on` (default, every node), `off`, or a node kind (`tool`, `llm`, `chain`, `retriever`, `agent`, `custom`). `--pause-on-error` beats it.
`GRAPHMIND_ABANDON_GRACE_MS`	How long a run whose app disconnected mid-flight waits to reconnect before it is marked abandoned rather than left “running” forever (default 15000).
`GRAPHMIND_ALLOWED_ORIGINS`	Extra browser origins allowed to reach the server, comma-separated; `*` disables the check. See who is allowed to connect.
`GRAPHMIND_RETENTION`	`off` disables the startup prune entirely
`GRAPHMIND_KEEP_RUNS`	Runs to keep (default 200); `--keep` beats it
`GRAPHMIND_KEEP_DAYS`	Days to keep (default 30); `--days` beats it
`GRAPHMIND_TELEMETRY`	`0` or `false` disables telemetry entirely (also auto-disabled when `CI` is set)
`GRAPHMIND_TELEMETRY_URL`	Override the telemetry endpoint (used by tests)
`GRAPHMIND_HOME`	Directory for the telemetry install id (default `~/.graphmind`)
`GRAPHMIND_DEMO_AGENT_DIR`	Where `demo --live` finds the demo agent outside a monorepo checkout
`GRAPHMIND_VIEWER_DIST`	Serve a different viewer build directory (development)

Read by the instrumented app

Variable	Meaning
`GRAPHMIND_URL`	Ingest endpoint for adapters (default `ws://127.0.0.1:4747/ingest`)
`GRAPHMIND_DISABLED`	`1` disables instrumentation — beats everything, including an explicit `enabled: true`
`GRAPHMIND`	`1` re-enables instrumentation under `NODE_ENV=production` (disabled there by default)

Kill-switch precedence

Evaluated top to bottom; the first match wins:

Condition	Result
`GRAPHMIND_DISABLED=1`	Disabled. Beats everything, including `enabled: true`.
`enabled` option passed	As given.
`NODE_ENV=production`	Disabled unless `GRAPHMIND=1`.
Otherwise	Enabled.

Python has no NODE_ENV, so it applies the same rule to the first variable that is set out of GRAPHMIND_ENV, ENVIRONMENT, APP_ENV, PYTHON_ENV, ENV, DJANGO_ENV, FLASK_ENV, NODE_ENV, counting production / prod (case-insensitive) as production. It is a boring documented list rather than a heuristic on purpose — a debugger that turns itself off for surprising reasons is worse than one you have to switch on.

A disabled session no-ops everything: no sockets, no buffering, no warnings, and the adapter’s wrapClient / wrapModel / wrapTools are identity functions. gm.run still executes your function and still hands it a working context (ids + abort signal), so your code never has to branch on whether GraphMind is on.

Non-standard ports

Two sides have to agree. If you move the server, tell the app:

# terminal 1
graphmind --port 4848

# terminal 2
GRAPHMIND_URL=ws://127.0.0.1:4848/ingest node agent.js

Or set it in code, which wins over the variable:

const gm = graphmind({ app: 'my-agent', url: 'ws://127.0.0.1:4848/ingest' });

If you also use MCP, pass the port there too so its deep links point at the right viewer:

claude mcp add graphmind -- npx graphmind-ai mcp --port 4848

Docker & remote containers

The adapter dials 127.0.0.1 inside its own network namespace. From a container, point it at the host:

# Docker Desktop (macOS / Windows)
GRAPHMIND_URL=ws://host.docker.internal:4747/ingest

# Linux, with --add-host=host.docker.internal:host-gateway
GRAPHMIND_URL=ws://host.docker.internal:4747/ingest

The server still binds loopback on the host, so nothing is exposed to your network.

Session options that shadow the environment

Options passed to graphmind({ … }) take precedence over the variables:

Option	Default	Environment equivalent
`url`	`ws://127.0.0.1:4747/ingest`	`GRAPHMIND_URL`
`enabled`	kill-switch logic	`GRAPHMIND_DISABLED` / `GRAPHMIND`
`connectTimeoutMs`	`300`	—
`handshakeTimeoutMs`	`1000`	—
`retryIntervalMs`	`10000`	—
`bufferSize`	`2000`	—
`pauseTimeoutMs`	hold forever	—