Environment variables

Thoth reads configuration from environment variables (typically loaded from .env). This page lists every variable, organized by subsystem.

The runtime validates env vars at startup via zod. If a required variable is missing or malformed, the bridge prints a clear error and refuses to start.

Required (no defaults — bridge refuses to start if missing)

SLACK_BOT_TOKEN

Bot User OAuth Token for your Slack app. Format: xoxb-.... See Slack setup for how to get one.

SLACK_BOT_TOKEN=xoxb-1234567890-1234567890-AbCdEfGhIjKlMnOpQrStUvWxYz

SLACK_APP_TOKEN

App-Level Token for Socket Mode. Format: xapp-.... Generate via Basic Information → App-Level Tokens with the connections:write scope.

SLACK_APP_TOKEN=xapp-1-A012-3456-AbCdEf...

ALLOWED_USERS

Comma-separated Slack member IDs allowed to talk to the bot. Each member ID is U<...> format (find via Slack profile → Copy member ID).

ALLOWED_USERS=U01ABC123XYZ,U02DEF456UVW

PERSONA_DIR

Absolute or relative path to the persona stack directory. Typically ./persona/thoth/.

PERSONA_DIR=./persona/thoth

SANDBOX_ROOT

Directory under which per-thread Claude sandbox cwds are created. Each thread gets its own subdirectory like <SANDBOX_ROOT>/<thread-key>/.

SANDBOX_ROOT=./sandbox

Strongly forbidden (refuses to start if any are set)

These variables would override your Claude Max subscription auth and silently bill against the API. The auth probe at boot exits with code 2 if any are present.

ANTHROPIC_API_KEY        ← MUST be unset
ANTHROPIC_AUTH_TOKEN     ← MUST be unset
CLAUDE_CODE_USE_BEDROCK  ← MUST be unset
CLAUDE_CODE_USE_VERTEX   ← MUST be unset
CLAUDE_CODE_USE_FOUNDRY  ← MUST be unset

To clear them:

bash/zsh

unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN \
      CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX CLAUDE_CODE_USE_FOUNDRY

# PowerShell
Remove-Item Env:ANTHROPIC_API_KEY, Env:ANTHROPIC_AUTH_TOKEN, `
            Env:CLAUDE_CODE_USE_BEDROCK, Env:CLAUDE_CODE_USE_VERTEX, `
            Env:CLAUDE_CODE_USE_FOUNDRY

Optional core (with defaults)

SLACK_SIGNING_SECRET

Optional in Socket Mode (events arrive over WebSocket, not signed HTTP). Set if you ever switch to HTTP Events mode.

SLACK_SIGNING_SECRET=...

CLAUDE_BIN

Default: claude

Path to the Claude CLI binary. Use absolute path if claude isn’t on your shell PATH.

# Windows
CLAUDE_BIN=C:/Users/aidan/AppData/Roaming/npm/claude.cmd

# macOS / Linux
CLAUDE_BIN=/usr/local/bin/claude

AETHER_RULES_PATH

Default: unset

Optional path to a hard-rules file appended to the persona stack under an AETHER RULES section. Used for production-critical agents with incident-driven non-negotiables. See Persona stack.

MAX_TURNS

Default: 25

Hard cap on Claude turns within a single user message. After this many tool/agent loop iterations, Claude returns whatever it has.

MAX_BUDGET_USD

Default: 5

Per-thread cost cap. Once a thread exceeds this in cumulative cost, new turns are refused with a clear message.

CONCURRENCY_CAP

Default: 3

Max simultaneous Claude subprocesses. Threads beyond this cap get a queued reply. Tune up if you have multiple founders chatting in parallel.

DB_PATH

Default: ./bridge.db

SQLite file path for sessions, episodes, skill drafts, scheduled runs, party state, daily costs. Single file with WAL mode.

LOG_LEVEL

Default: info

One of: debug, info, warn, error. Use debug to see raw stream-json events from Claude when troubleshooting.

BRIDGE_REPO_ROOT

Default: current working directory

Absolute path to the bridge repo root (where .claude/skills/ lives for skill commits). Set explicitly if running from a different cwd.

Honcho identity layer (L2 memory)

HONCHO_API_KEY

Default: unset (Honcho disabled)

If set, the bridge enables the L2 identity layer (theory-of-mind per peer). Get a free API key at app.honcho.dev.

HONCHO_WORKSPACE_ID

Default: thoth-prod

The Honcho workspace ID. Workspaces isolate identity facts; you can have one per project or one shared.

HONCHO_BASE_URL

Default: https://api.honcho.dev

Override only if self-hosting Honcho.

HONCHO_DIALECTIC_TIMEOUT_MS

Default: 1500

Timeout for the per-turn Dialectic call (the pre-spawn user-model fetch). Soft-fails on timeout — your reply still happens, just without that context.

HONCHO_WRITE_TIMEOUT_MS

Default: 5000

Timeout for the post-turn ingest write. Fire-and-forget anyway, so this is just for graceful cleanup.

HONCHO_DISABLED

Default: false

Force-disable Honcho even if HONCHO_API_KEY is set. Useful for local dev without consuming API quota.

Episodic memory (L3)

EPISODIC_DISABLED

Default: false

Disable cross-thread episodic recall. The bridge skips embedding + storage. Cuts ~50–100ms latency per turn but loses cross-thread continuity.

Reflection (L5)

REFLECTION_DISABLED

Default: false

Disable session-end Reflexion. Sessions still happen but no reflection writes (no skill drafts, no MEMORY.md updates).

REFLECTION_IDLE_MIN

Default: 30

Minutes of thread inactivity before reflection auto-fires. Manual trigger via /done always works regardless.

REFLECTION_MAX_BUDGET_USD

Default: 0.5

Per-session reflection cost cap. The reflection subprocess refuses to exceed this on a single session.

REFLECTION_DAILY_CAP_USD

Default: 5.0

Daily total reflection cost cap (UTC day). After this, reflections are deferred until next UTC midnight.

Multi-agent party

PARTY_DISABLED

Default: false

Disable the multi-agent council. The /party slash command will return an error if disabled.

PARTY_DEFAULT_BUDGET_USD

Default: 1.5

Default per-party cost cap if --budget flag isn’t passed to /party.

PARTY_DAILY_CAP_USD

Default: 10.0

Daily total party cost cap (UTC day).

PARTY_PERSONA_DIR

Default: auto-resolved to <PERSONA_DIR>/../thoth/party

Absolute path to the party persona files directory. Each persona file is a separate Markdown file defining one council member.

COUNCIL_CHANNEL_ID

Default: unset

Slack channel where multi-agent council parties post. If unset, parties post in the originating thread.

Dashboard

DASHBOARD_DISABLED

Default: false

Disable the local web dashboard.

DASHBOARD_PORT

Default: 8787

Port the dashboard listens on (loopback only).

DASHBOARD_BIND

Default: 127.0.0.1

Bind address. Keep loopback in production; the dashboard exposes internal state.

Don't bind to 0.0.0.0

The dashboard has no auth. Binding to a public interface exposes your memory + sessions + skill drafts to anyone who can reach the host. Keep it on 127.0.0.1.

DASHBOARD_AUTO_OPEN

Default: true

If true, the dashboard auto-opens in your default browser on bridge startup. Set to false for headless / CI environments.

Ambient agents

AMBIENT_DISABLED

Default: false

Disable the ambient-agent triggers (morning digest, stale-skill nudges, etc.).

AMBIENT_ANNOUNCE_CHANNEL

Default: unset

Slack channel ID where ambient nudges post. If unset, nudges DM the founder directly.

AMBIENT_DAILY_CAP_USD

Default: 1.0

Daily total budget for autonomous ambient runs (UTC day). Ambient agents track spend and pause when exhausted.

Auto-skill harvester

AUTO_HARVEST_DISABLED

Default: false

Disable the 6-hour auto-harvest cycle that scans recent episodes for recurring patterns and proposes skill drafts.

Anthropic status monitor

ANTHROPIC_STATUS_DISABLED

Default: false

Disable the 60-second poller for status.claude.com. Useful in isolated networks or CI.

ANTHROPIC_STATUS_ANNOUNCE_CHANNEL

Default: unset

Slack channel where status incidents are announced. If unset, no broadcast.

Loaded from .env

Thoth uses dotenv at runtime startup. The .env file is loaded automatically; no explicit import 'dotenv/config' needed in your project.

Multi-environment workflow:

.env              ← committed defaults (no secrets)
.env.local        ← gitignored secrets (overrides)
.env.production   ← prod-specific (gitignored)

dotenv loads .env first, then .env.local overrides. Set NODE_ENV=production to also load .env.production.

What’s next

• Configuration reference — file-based config (v0.6+)
• CLI reference — every command
• Slack setup — full walkthrough