Docs
Configuration
Last Light layers configuration at startup: the packaged
config/default.yaml (non-secret defaults), then an optional
$LASTLIGHT_OVERLAY_DIR/config.yaml overlay, then environment
variables (via .env in local dev, or instance/secrets/.env
in production). The authoritative source is src/config.ts in the repo;
this page mirrors it.
Config files & overlay
Non-secret config — managed repos, routes, models, variants, approvals, and
disabled.* — lives in YAML. The public config/default.yaml
ships safe defaults (and an empty managedRepos list).
Your deployment overrides go in an overlay selected by
LASTLIGHT_OVERLAY_DIR — the docker-compose stack mounts an
instance/ folder there as /app/instance.
| Variable | Required | Default | Description |
|---|---|---|---|
LASTLIGHT_OVERLAY_DIR | No | — | Trusted overlay root. Layers config.yaml over the defaults and overlays assets under workflows/, workflows/prompts/, skills/, agent-context/ (overlay wins by logical name). Secrets are read from its secrets/ subdir. Read at startup — docker compose restart agent to apply. |
Merge rules: maps (models, variants, routes,
approval) deep-merge over the defaults; arrays (managedRepos,
disabled.*) replace; environment variables override both. Secrets
(GitHub App key, provider API keys, Slack tokens, admin secret) stay env-only and
never appear in the dashboard Config tab, which shows the
Default / Overlay / Merged non-secret config.
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. |
Models (agentic-pi)
The agent runtime is agentic-pi
(workflow phases) plus @earendil-works/pi-ai (in-process chat) —
both provider-agnostic. Any provider/model string pi-ai supports works
(openai/…, anthropic/…, openrouter/<vendor>/<model>, etc.).
Set whichever provider API keys match your selected models — one OpenRouter
key covers most providers if you'd rather have a single billing surface.
| Variable | Required | Default | Description |
|---|---|---|---|
OPENAI_API_KEY | If using OpenAI | — | OpenAI API key. Required if LASTLIGHT_MODEL (or any entry in LASTLIGHT_MODELS) resolves to an OpenAI model. |
ANTHROPIC_API_KEY | If using Anthropic | — | Anthropic API key. Required if any active model is anthropic/…. |
OPENROUTER_API_KEY | If using OpenRouter | — | OpenRouter API key (sk-or-…). Required if any active model is openrouter/<vendor>/<model>. One key gives you Claude, GPT, Gemini, Llama, Mistral, DeepSeek, etc. through a single endpoint; OpenRouter takes a small per-token markup over going direct. Sign up at openrouter.ai/keys. |
LASTLIGHT_MODEL | No | anthropic/claude-sonnet-4-6 | Default model used when no per-task override matches. Must be a provider/model string pi-ai recognises. |
LASTLIGHT_MODELS | No | — | Per-task-type model overrides as JSON. Keys match phase names or skill types. Do not override chat with a small model — small models tend to refuse tool calls. Example: {"chat":"openai/gpt-5.1-mini","architect":"openai/gpt-5.5"} |
LASTLIGHT_THINKING | No | — | Catch-all reasoning-effort default. pi-ai translates it to the right per-provider knob (OpenAI reasoning_effort, Anthropic thinking budget, etc.). Allowed values: off | minimal | low | medium | high | xhigh. |
LASTLIGHT_THINKINGS | No | — | Per-task thinking-level overrides as JSON, same key scheme as LASTLIGHT_MODELS. Example: {"architect":"high","reviewer":"high","triage":"minimal"}. |
LASTLIGHT_SANDBOX | No | gondolin | Workflow sandbox backend. gondolin (default) runs each phase in a QEMU micro-VM (HVF on macOS, KVM on Linux — no Docker needed). docker runs each phase in a sibling Docker container (requires the lastlight-sandbox:latest image). none runs in-process with no isolation — dev only. |
MAX_TURNS | No | 200 | Maximum agent turns per invocation. Reserved (kept for API stability). |
OPENCODE_* names from the
OpenCode era are still read as fallbacks for the matching
LASTLIGHT_* name — OPENCODE_MODEL →
LASTLIGHT_MODEL, OPENCODE_MODELS →
LASTLIGHT_MODELS, OPENCODE_VARIANT →
LASTLIGHT_THINKING, OPENCODE_VARIANTS →
LASTLIGHT_THINKINGS. Existing .env files keep
working; rename at your leisure.
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. |
LASTLIGHT_SESSIONS_DIR | No | $STATE_DIR/agent-sessions | Directory the dashboard reads sandbox + chat session JSONLs from. event-shim.ts writes Claude-SDK-style envelope jsonl under projects/<slug>/. |
SANDBOX_DATA_VOLUME | No | lastlight_agent-data | Used only when LASTLIGHT_SANDBOX=docker. Either a Docker named volume or a host path (starts with /, ./, ../, ~) bind-mounted as /data in each sandbox. |
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). |