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). A fourth layer — a managed repo's own .lastlight/ — is applied per run, on top of all three; see Per-repo config. The authoritative source is apps/server/src/config/config.ts in the repo; this page mirrors it.

config/default.yaml  →  instance/config.yaml  →  env  →  <repo>/.lastlight/lastlight.yml
     (packaged)            (your overlay)        (env)          (per-repo, bounded)

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.

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.

Per-repo config

A managed repo can commit a .lastlight/ directory that overrides a bounded subset of the above — models, reasoning effort, approval gates, cron participation, prompts, skills, agent context — for runs against that repo only. It's always read from the repo's default branch, so a pull request can never reconfigure the agent reviewing it, and it's bounded by a repoConfig: block you control (ship it disabled with repoConfig.enabled: false if you'd rather keep every knob central). Out of the box it's inert: nothing changes until a repo actually commits one.

Full contract, worked example and the lastlight repo commands: Per-repo config.

GitHub App

Required if you want to manage repos (not required for messaging-only mode).

Models (agentic-pi)

The agent runtime is agentic-pi (workflow phases) plus @earendil-works/pi-ai (in-process chat). It runs on any model the pi coding agent supports — Claude, GPT, Gemini, Llama, and more, as openai/…, anthropic/… or openrouter/<vendor>/<model> strings. Set whichever provider API keys match your selected models — one OpenRouter key covers most of them if you'd rather have a single billing surface.

Runtime

Approval gates

Workflow policy — fix, dependencies, review

Three blocks have no environment variable at all: they're budgets and blast-radius dials, and those belong in a file you can review and diff rather than in a shell. They live in config/default.yaml with the values below, and you override them in your instance/config.yaml.

# instance/config.yaml

review:
  postsCheck: false            # post the `last-light/review` Check Run
  trigger: after-checks        # eager | after-checks | on-request
  requestLabel: null           # the label that asks for a review in `on-request`
  skipDraft: true              # skip draft PRs
  generatedPaths:              # a push touching only these earns no re-review
    - "*.lock"
    - package-lock.json
    - pnpm-lock.yaml
    - go.sum
    - "*.min.js"
    - "*.generated.*"
    - "**/__generated__/**"

fix:                           # every PR-fixing workflow: pr-fix, dependabot-ci-fix
  maxAttempts: 3               # attempts ACROSS runs for one PR, then a human is asked
  localIterations: 2           # gate-loop iterations WITHIN one attempt
  gateTimeoutSeconds: 900      # budget for the repo's own build/test gate
  escalateModelAfterAttempt: 1 # attempts above this use models["pr-fix-retry"]
  maxCostUsd: 5.0              # cumulative ceiling for ONE PR; null = no ceiling
  maxFlakyDeferrals: 2         # "flaky" verdicts before one is taken at face value
  retryableClasses: [reproducible, env-mismatch]

dependencies:
  autoMergeMaxImpact: medium   # none | low | medium | high — ceiling for a MAJOR bump
  requireSettledChecks: true   # no merge decision until the head SHA's checks settle
  minSettledChecks: 1          # …and there must be at least this many
  auditComment: true           # post the evidence comment when auto-merging a major

trigger: after-checks means "once the head SHA's checks settle — either colour". The review can then read and cite the CI result instead of guessing at it, and a push storm collapses to one review per settled SHA. There is deliberately no settled-and-passing mode: a PR whose CI never goes green would then never be reviewed, which is exactly the PR most worth a look.

on-request means the review runs only when somebody asks. Three ways to ask: apply the requestLabel — yours, or one the target repo named in its own .lastlight/, both of which are honoured on the pull_request.labeled webhook — comment @last-light review, or — with postsCheck on — press Re-run on the last-light/review check, which is posted as a neutral conclusion so it never blocks a merge. (GitHub's reviewer picker doesn't offer App bot users, so "request a review from the bot" is handled opportunistically but is not the mechanism to rely on.) Under after-checks with postsCheck on, the check is posted queued while CI runs, so branch protection can require it without racing.

generatedPaths is the answer to a re-review with nothing new to say. Before it, the only thing suppressing a second review was "we already reviewed this exact head SHA" — and a lock file re-derivation is a new head SHA, so a dependency bump could earn two formal reviews minutes apart. When every path changed since the review we posted matches one of these patterns, the re-review is skipped.

It is deliberately hard to trip. It never suppresses a first review, never suppresses an explicit @last-light review or the request label, and never fires when the push also touched a hand-written file — one non-generated path and the review runs. Any read it can't trust (a compare that failed, a diff GitHub truncated) dispatches. Set it to [] to turn it off. Patterns: * stops at a /, ** crosses one, and a pattern with no / matches a basename anywhere in the tree — so pnpm-lock.yaml means the lock file in every package of a workspace.

With postsCheck on, this skip is the one that still leaves a check: the new head SHA gets a completed last-light/review repeating the verdict of the review that still stands. Every other skip leaves the PR alone, but this one would otherwise strand a required check on a head nobody reviewed. Its conclusion mirrors that earlier review, so a CHANGES_REQUESTED carried forward still blocks the merge.

skipDraft matches what the review sweep has always done. A draft PR is skipped on the webhook path too. Marking it Ready for review lifts that skip, but under the packaged after-checks it does not produce a review on its own: it is a PR-attention event, and attention events are deferred in that mode. What actually runs the review is the head SHA's checks settling — or, if no settle event arrives, the 30-minute review sweep. Under trigger: eager, Ready for review is the event that un-defers it.

The fix budgets bound a loop that diagnoses a CI failure before it retries it. maxAttempts and maxCostUsd both bound the current problem, not the PR's lifetime: a push from anyone but the bot is a fresh problem, so it re-arms the attempt counter and the cost window together and clears the escalation with no label to remove by hand. A diagnosis class outside retryableClasses escalates straight away rather than spending budget on a retry that can't help — its members are checked against the five diagnosis classes, so a typo narrows the set with a warning instead of silently making everything terminal. And maxCostUsd ships on: an unbounded agent loop against a genuinely broken PR is the one failure mode that costs real money.

For dependencies, impact rather than semver magnitude is what gates a major bump — a @types/* major is not a framework rewrite. Set autoMergeMaxImpact: none to keep every major in front of a human.

Know which half of that block is enforced where. requireSettledChecks and minSettledChecks are enforced in code: the merge verdict is computed from the head SHA's resolved check state before the run starts and handed to the agent as a decided answer it is told not to re-derive, and requireSettledChecks additionally makes the dispatch gate refuse a PR whose checks are still running. autoMergeMaxImpact is an instruction to the agent: the impact tier is the model's own judgement, reported in the run's completion marker, and the ceiling reaches the run as prompt text — nothing parses the tier or withholds the merge tools from a run that reported one above the ceiling. Lowering the ceiling narrows what the agent is told it may land; it is not a hard stop.

All three are repo-settable, one-way: a repo's .lastlight/ can only ever make itself more conservative than you are. See Per-repo config for the per-key clamps and the three keys a repo can't touch at all.

Build assets

The per-phase build handoff docs — architect-plan.md, status.md, executor-summary.md, reviewer-verdict.md, guardrails-report.md, and the explore-* docs — can live in one of two places, selected by buildAssets.location in YAML (or the LASTLIGHT_BUILD_ASSETS env var). With repo (the default) they're committed into the target repo under .lastlight/<issueKey>/ and ride the working branch — the historical behaviour. With server they're externalized to the Last Light host instead, never committed into the target repo: injected into each phase from outside the repo and harvested back after, PR-body links point at the dashboard's Artifacts view rather than GitHub blob URLs, and the admin API serves them read-only at /admin/api/artifacts.

Admin dashboard

Slack (optional)

Two independent feature groups — see Slack integration for setup.

OpenTelemetry (optional)

Telemetry is disabled by default. Set LASTLIGHT_OTEL_ENABLED=true and point the standard OTEL_* exporter vars at your collector. See Observability for what's exported, content redaction, and how sandbox telemetry is routed per backend.

Feedback signals (optional)

A 👍 or 👎 on something Last Light wrote becomes an eval signal against the workflow run that produced it. Slack works out of the box (it sends a real reaction_added event); the GitHub half has to be polled — GitHub delivers no webhook for reactions at all — so it ships off:

feedback:
  enabled: true              # Slack signals, live
  github: false              # opt into the GitHub reaction poller
  pollSchedule: "*/30 * * * *"
  windowDays: 14             # how long a bot comment stays pollable
  maxAnchorsPerTick: 500     # = 5 GraphQL requests per tick
  retentionDays: 90
  otel: true                 # export each signal onto the run's trace

Env overrides: LASTLIGHT_FEEDBACK_ENABLED, LASTLIGHT_FEEDBACK_GITHUB, LASTLIGHT_FEEDBACK_OTEL, LASTLIGHT_FEEDBACK_WINDOW_DAYS. Operator-only — a target repo cannot set these. See Feedback signals for the emoji vocabulary, the Slack scope you need to add, and how the polling budget stays bounded.

The "my repos" filter (optional)

By default every admin who logs into the dashboard sees every managed repo's runs and sessions. In an org with a lot of repos that is mostly noise. Turn this on and each GitHub-authenticated admin gets a header toggle that filters every list down to the repos their GitHub org teams own, plus the ones their own account owns:

teamVisibility:
  enabled: false             # operator switch — needs the App's `Members: read`
  ttlMinutes: 60             # how long a resolved answer is reused
  maxTeamsPerUser: 50        # more teams than this ⇒ show everything
  maxPagesPerTeam: 20        # 100 repos/page; a bigger grant ⇒ show everything
  maxRequestsPerResolve: 60  # ceiling for one cache miss

This is a view preference, not access control. The filter travels as an ordinary ?repos= query parameter the dashboard asks for; omit it and the server returns global data exactly as before, and a hand-crafted API call still sees everything. That is what lets every budget above fail open: when a team is too big to enumerate, or someone is in too many teams, or GitHub refuses the query, you see more than strictly necessary rather than a partial list that quietly hides work you own.

Setup. Grant the GitHub App the organization Members: read permission, subscribe it to the team, membership and organization webhook events, and re-consent the App on each installation. Until then the resolver fails open and nothing is filtered for anyone — the toggle still appears once enabled is on, and says why it has nothing to offer, so an outstanding setup step reads as an outstanding setup step rather than as a feature that silently did nothing.

Just created a team? A resolved answer is cached for ttlMinutes (60 by default) and served stale-while-revalidate, so the first load after it expires still returns the old answer and refreshes behind you — it takes a second load to see a change. The webhooks above make that instant by invalidating the cache the moment a membership or a team's repo grant changes. Without them, click the toggle while it reads my repos (none) to re-check immediately.

Nothing is crawled up front. A person's teams are resolved the first time they load the dashboard — one GraphQL query per org plus a page or two per team — and cached in SQLite, so the cost tracks their team count, not the org's repo count. The webhooks above invalidate the cache when membership or a team's repo grant changes; POST /admin/api/me/repos/resync is the manual fallback. Operator-only — a target repo cannot set these.