Last Light reads configuration from environment variables (via .env
in local dev, or secrets/.env in production). The authoritative source
is src/config.ts in the repo; this page mirrors it.
GitHub App
Required if you want to manage repos (not required for messaging-only mode).
| Variable | Required | Default | Description |
|---|
GITHUB_APP_ID | Yes | — | Numeric GitHub App ID from the app settings page. |
GITHUB_APP_PRIVATE_KEY_PATH | Yes | — | Path to the .pem file you downloaded when creating the app. |
GITHUB_APP_INSTALLATION_ID | Yes | — | Installation ID — from the URL after installing the app on a repo. |
WEBHOOK_SECRET | Yes | — | Matches the webhook secret configured in your GitHub App. Used to verify webhook signatures. |
BOT_LOGIN | No | last-light[bot] | Bot login used to filter out the harness's own events from its own event stream. |
Claude / models
| Variable | Required | Default | Description |
|---|
ANTHROPIC_API_KEY | No | — | API key. If unset, the harness relies on claude login (subscription auth). |
CLAUDE_MODEL | No | claude-sonnet-4-6 | Default model used when no per-task override matches. |
CLAUDE_MODELS | No | — | Per-task-type model overrides as JSON. Keys match phase names; use default as the catch-all. Do not override chat — Haiku tends to refuse MCP tool calls. Example: {"architect":"claude-opus-4-6","triage":"claude-haiku-4-5-20251001"} |
MAX_TURNS | No | 200 | Maximum agent turns per invocation. |
Runtime
| Variable | Required | Default | Description |
|---|
PORT / WEBHOOK_PORT | No | 8644 | Port the webhook listener binds to. |
STATE_DIR | No | ./data | Base directory for persistent state (DB, sessions, sandboxes, logs). Mount as a Docker volume in production. |
DB_PATH | No | $STATE_DIR/lastlight.db | Override the SQLite database path. |
WORKFLOW_DIR | No | ./workflows | Directory containing YAML workflow definitions. |
CLAUDE_HOME_DIR | No | $STATE_DIR/claude-home | Directory the dashboard reads sandbox session JSONLs from. Local dev points this at ./data/sandbox-claude-home. |
MCP_CONFIG_PATH | No | ./mcp-config.json | Path for the generated MCP config file. |
SANDBOX_DATA_VOLUME | No | lastlight_agent-data | Either a Docker named volume or a host path (starts with /, ./, ../, ~) bind-mounted as /data in each sandbox. |
ENABLE_DIRECT_FALLBACK | No | false (in local dev) | If true, the harness falls back to in-process agent execution when the sandbox image is unavailable. Keep this off in production. |
LASTLIGHT_LOCAL_DEV | No | — | Set to 1 to prevent git-auth.ts from writing to ~/.gitconfig. Used by scripts/dev-local.sh. |
BOOTSTRAP_LABEL | No | lastlight:bootstrap | Label applied to issues that exist solely to set up missing guardrails in a target repo. |
Approval gates
| Variable | Required | Default | Description |
|---|
APPROVAL_GATES | No | — |
Comma-separated list of gate names to enable. Gate names match
approval_gate: fields declared in workflow YAML (e.g.
post_architect, post_reviewer). A gate only
pauses the run if its name appears here, so you can ship workflows with
gates pre-declared and enable them per environment.
|
Admin dashboard
| Variable | Required | Default | Description |
|---|
ADMIN_PASSWORD | No | — | If set, the dashboard requires password login. |
ADMIN_SECRET | No | random | HMAC secret used to sign session tokens. Set this to a stable value in production so sessions survive restarts. |
Slack (optional)
Two independent feature groups — see Slack integration for setup.
| Variable | Required | Default | Description |
|---|
SLACK_BOT_TOKEN | No | — | Bot User OAuth Token (xoxb-...). Presence of this var enables the Slack connector. |
SLACK_APP_TOKEN | Yes (if bot token set) | — | App-Level Token (xapp-...) for Socket Mode. |
SLACK_ALLOWED_USERS | No | — | Comma-separated Slack user IDs allowed to interact with the bot. |
SLACK_DELIVERY_CHANNEL | No | — | Channel ID where cron health reports are posted. |
SLACK_OAUTH_CLIENT_ID | No | — | Enables "Login with Slack" on the dashboard. |
SLACK_OAUTH_CLIENT_SECRET | Yes (if client id set) | — | OAuth client secret. |
SLACK_OAUTH_REDIRECT_URI | Yes (if client id set) | — | Must exactly match a redirect URL configured on the Slack app, typically https://your-host/admin/api/oauth/slack/callback. |
SLACK_ALLOWED_WORKSPACE | No | — | Restrict OAuth login to a single Slack workspace (team ID or domain). |