Environment variables¶

ADHD Progress Hub server configuration uses the ADHD_HUB_ prefix. Use this page as a reference rather than a setup checklist.

For a normal container install:

1. put server settings in the .env file used by Compose;
2. keep ADHD_HUB_DATA_DIR=/data and mount persistent storage there;
3. set a strong ADHD_HUB_AUTH_TOKEN before non-loopback access;
4. set ADHD_HUB_PUBLIC_URL when browsers or agents use another hostname;
5. keep secrets out of compose.yml, source control, AGENTS.md, issues, and progress notes.

Developer-only smoke/probe variables are listed separately near the end.

Configuration precedence¶

The server resolves Settings configuration in this order, highest priority first:

1. process environment variables (ADHD_HUB_*);
2. the first non-empty TOML config found from an explicit --config, ./config.toml, then ~/.config/adhd-hub/config.toml;
3. ./.env;
4. built-in defaults.

Variables documented below as direct runtime/client overrides are read by their owning component and do not necessarily participate in that Settings precedence chain.

Docker Compose adds one more practical rule: values under a service's explicit environment: section override the same names loaded through env_file. The repository Compose file intentionally pins ADHD_HUB_HOST=0.0.0.0, ADHD_HUB_PORT=8787, and ADHD_HUB_DATA_DIR=/data inside the container.

Boolean values accept the normal Pydantic forms such as true / false, 1 / 0, and similar common variants. Cron fields use standard five-field cron expressions.

Core server and storage¶

Hub behaviour and limits¶

Scheduled jobs¶

Authentication, OAuth, and reverse proxies¶

Wave 6 AI scan-lines (opt-in)¶

Soft default: off. Heuristic scan-lines always work without AI.

For most users, configure this under Settings → AI helpers:

1. choose a Base URL preset or enter a custom OpenAI-compatible base URL;
2. choose a model and optional API key;
3. set the timeout;
4. use Test and load models to refresh the model list;
5. save the settings.

UI-saved values live in data/ai.json. The API key is encrypted with the Hub access token and is never returned to the browser. Environment variables are mainly useful for provisioning a fresh instance.

Uses an OpenAI-compatible /chat/completions endpoint (local Ollama or similar preferred). Only bounded, scrubbed structured thread fields are sent — never progress bodies, transcript references, or forge source_conflicts blobs. Continuity fields are capped (~80–120 chars) and ritual/agent walls are dropped; when a forge conflict exists, Hub’s side is preferred over forge text. Common credential, URL, and machine-path patterns are redacted before the request and again on the response; keep sensitive material out of continuity fields. Stub or truncated AI replies fall back to the heuristic scan-line. On failure or when unset, heuristic scan-lines are used.

On My work, the reader’s ⋯ → Rewrite scan line forces a refresh for one thread (POST /api/threads/{id}/scan-line). With a project selected, ⋯ → Rewrite all scan lines beside the project title confirms, then rewrites every open thread in that project and its nested descendants (POST /api/projects/{slug}/scan-lines) with a short delay between calls; when AI is off the request explains and no-ops. Rewrite scan lines on their own (Settings, default off) rewrites on thread/progress save and opportunistically ensures stale cards when My work loads — only when the content hash drifts. Soft ensure uses POST /api/threads/{id}/scan-line with {"mode":"ensure"} (hash skip); omit mode or use force for a manual rewrite.

For a TLS reverse proxy, a typical configuration is:

ADHD_HUB_PUBLIC_URL=https://adhd-hub.example.com
ADHD_HUB_TRUST_PROXY_HEADERS=true
# Optional hard override:
# ADHD_HUB_COOKIE_SECURE=true

See Authentication and Installation.

OpenClaw¶

These are optional. OpenClaw connection details can also be configured from Settings → Phone alerts; UI-saved configuration is intended for normal ongoing administration while environment variables are useful for initial provisioning.

See OpenClaw connection and alerts.

Forge: GitHub or Gitea¶

Forge settings can also be saved from the dashboard. Environment variables are useful for provisioning a fresh instance; do not commit PATs/tokens.

See Forge permissions and Forge issue inbox.

Local transcript indexer paths¶

These paths are primarily for the CLI/indexer running on the machine that owns the transcripts. They are usually not useful inside the server container unless you deliberately mount those transcript directories into it.

The related ADHD_HUB_MAX_SESSIONS limit is documented under Hub behaviour above. See Indexer schedule.

Docker image / package-serving internals¶

The image sets a few implementation variables itself. They are not normal Hub configuration and usually should not be overridden:

The image also defaults ADHD_HUB_HOST=0.0.0.0, ADHD_HUB_PORT=8787, and ADHD_HUB_DATA_DIR=/data; those three are normal Hub settings described above.

Client/connect-only environment variables¶

The following variables affect the client bootstrap/connect command or CLI, not the long-running Docker server. Do not add them to the server container unless you intentionally run client tooling there.

• ADHD_HUB_URL — extra CLI Hub-URL fallback; ADHD_HUB_PUBLIC_URL and ADHD_HUB_HUB_URL are preferred where applicable.
• ADHD_HUB_CREDENTIALS — override the local CLI credentials/session JSON path.
• ADHD_HUB_NO_COLOR — disable Hub CLI status colouring when non-empty. Standard NO_COLOR is also respected.
• ADHD_HUB_CONNECT_AGENTS — default comma-separated agent targets for generated install scripts.
• ADHD_HUB_CONNECT_SCOPE — project or user Cursor MCP scope.
• ADHD_HUB_CONNECT_REGISTER — opt into project registration.
• ADHD_HUB_CONNECT_OPENCLAW_SKILLS — opt into OpenClaw skill installation.
• ADHD_HUB_CONNECT_NO_SKILLS — skip Hub skill installation in the bootstrap script.
• ADHD_HUB_CONNECT_DRY_RUN — preview connect changes.
• ADHD_HUB_CONNECT_FLAGS — additional generated-script CLI flags.
• ADHD_HUB_CONNECT_WITH_I_HAVE_ADHD, ADHD_HUB_CONNECT_WITH_GRAPHIFY, ADHD_HUB_CONNECT_WITH_RTK, ADHD_HUB_CONNECT_WITH_SUPERPOWERS, ADHD_HUB_CONNECT_WITH_CONTEXT7, ADHD_HUB_CONNECT_WITH_AGENT_BROWSER, ADHD_HUB_CONNECT_WITH_SERENA — opt-in companion defaults.

See Connect a machine or project for the supported CLI/bootstrap workflow.

Developer and smoke-test-only variables¶

These are read by repository utility scripts rather than the running Hub service and normally do not belong in a Docker .env:

• ADHD_HUB_MCP_URL — MCP endpoint override for scripts/probe_mcp.py (default http://127.0.0.1:8787/mcp).
• ADHD_HUB_SCREENSHOT_DIR — output directory used by scripts/browser_smoke.py.
• ADHD_HUB_BROWSER_EXECUTABLE — optional browser executable override for scripts/browser_smoke.py.

When changes take effect¶

Environment and TOML changes require restarting the server/container. Settings saved through the dashboard are designed to apply through the Hub's persisted preferences/configuration path and generally do not require editing .env.

For Compose:

docker compose up -d

recreates the service when its environment/configuration changed. Use docker compose logs -f adhd-hub and /api/health to verify the restart.