nearform 开源 Last Light：可自托管的 GitHub 仓库维护 AI 智能体

Last Light

Self-host your own software factory
lastlight.dev · Roadmap

An AI agent that maintains GitHub repositories: triaging issues, reviewing PRs, monitoring repo health, and building features through an Architect → Executor → Reviewer development cycle.

Built on agentic-pi (workflow phases) and @earendil-works/pi-ai (in-process chat) with a lightweight TypeScript harness for webhook ingestion, cron scheduling, and process management. Provider-agnostic — point LASTLIGHT_MODEL at any provider/model pi-ai supports (defaults to anthropic/claude-sonnet-5-5).

Monorepo layout

This repository is a pnpm + Turborepo workspace. The harness/server internals now live under apps/server/ (formerly the repo root). At a glance:

apps/
  server/   lastlight-core  — the harness + server (src, config, workflows,
                               skills, agent-context, deploy, dashboard, spec, …)
  www/      lastlight-www     — the Astro marketing/docs site → lastlight.dev
  evals/    lastlight-evals   — the eval harness → evals.lastlight.dev
packages/
  cli/               lastlight              — the lean, published global CLI (+ the Claude Code plugin)
  shared/            lastlight-shared      — shared utilities (e.g. the provider registry)
  workflow-engine/   lastlight-workflow-engine — the reusable workflow runner
  code-facts/        lastlight-code-facts  — deterministic PR analysis (`lastlight facts`)
  agentic-pi/        agentic-pi            — the coding-agent harness core runs in the sandbox

Seven packages publish to npm: lastlight, lastlight-core, lastlight-workflow-engine, lastlight-shared, lastlight-code-facts, lastlight-evals, and agentic-pi. The root package (lastlight-monorepo) is private (as are lastlight-www and both dashboards). Common scripts run from the root via Turborepo: pnpm build / pnpm test / pnpm typecheck (each turbo run …), and pnpm dev (= pnpm --filter lastlight-core dev). See the root CLAUDE.md for the canonical workspace map and orientation.

Production Setup (Clean Server)

The fastest way to go from a bare server to a running Last Light instance:

npx lastlight setup

The setup wizard walks you through:

1. GitHub App — enter your App ID, Installation ID, and PEM key path
2. Domain & TLS — optional Caddy config for automatic HTTPS
3. Managed repositories — the owner/repo list the bot operates on
4. Model provider + API key — pick from any of pi-ai's 15+ supported providers (Anthropic, OpenAI, Google Gemini, Mistral, Groq, Cerebras, xAI, Hugging Face, Moonshot, NVIDIA, Fireworks, Together, DeepSeek, Z.AI, Kimi for Coding, MiniMax, OpenCode Zen, OpenRouter), then enter the model id and the matching API key. See packages/shared/src/providers.ts for the full registry.
5. Webhook secret — auto-generated if you don't have one
6. Slack — optional bot token and app token for Slack integration
7. Admin dashboard — optional password protection

It scaffolds your private deployment overlay at instance/ — writing instance/config.yaml (your managed repos), instance/secrets/.env, and copying your PEM to instance/secrets/app.pem (mode 600) — then offers to build and start the Docker stack. When it's done you have a running instance ready to receive webhooks. Everything deployment-specific lives in instance/, which is mounted read-only and never baked into the image; edit it and docker compose restart agent to apply (no rebuild). See Deployment overlay for the model.

Requires: Node.js 22.12+ (the repo pins 22 in .nvmrc), Docker, and a GitHub App already created (see Create a GitHub App below).

For a Docker-free production install (systemd unit, gondolin sandbox), see Native deploy below.

Quick Start (Local Dev)

Prerequisites

• Node.js 22.12+ (engines.node; the repo pins 22 in .nvmrc)
• Docker Desktop (or compatible) — only needed for LASTLIGHT_SANDBOX=docker; gondolin runs without it on macOS/Linux
• A GitHub App (see Create a GitHub App below)
• An API key for whichever provider your chosen LASTLIGHT_MODEL uses. The wizard surfaces pi-ai's 15+ providers — see packages/shared/src/providers.ts for the full registry (e.g. ANTHROPIC_API_KEY for anthropic/…, OPENAI_API_KEY for openai/…, GROQ_API_KEY for groq/…, GEMINI_API_KEY for google/…, OPENROUTER_API_KEY for the openrouter/… aggregator).

Setup

git clone https://github.com/nearform/lastlight.git
cd lastlight
pnpm install          # this is a pnpm workspace — installs every package

Copy and edit the environment file. It lives in the server package, not the repo root — scripts/dev-local.sh sources apps/server/.env:

cp apps/server/.env.example apps/server/.env

Fill in the required values in apps/server/.env:

# GitHub App (required)
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_PATH=./your-app.private-key.pem
GITHUB_APP_INSTALLATION_ID=789012

# Webhook secret (required for webhook mode)
WEBHOOK_SECRET=your-secret-here

# Model + provider — the wizard surfaces pi-ai's 15+ providers. The
# registry lives in packages/shared/src/providers.ts; pick any `provider/model` it lists.
LASTLIGHT_MODEL=anthropic/claude-sonnet-5-5
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# OPENROUTER_API_KEY=sk-or-...
# GROQ_API_KEY=gsk_...      GEMINI_API_KEY=AIza...   HF_TOKEN=hf_...
# XAI_API_KEY=...
# ZAI_API_KEY=...        MISTRAL_API_KEY=...    FIREWORKS_API_KEY=...
# OPENCODE_API_KEY=...   (OpenCode Zen: Claude, GPT, Kimi, GLM, DeepSeek, … at cost)

# Sandbox backend (default: gondolin; alternatives: docker, none)
# LASTLIGHT_SANDBOX=gondolin

Run

pnpm --filter lastlight-core dev runs the harness on your host. Sandbox mode is selected by LASTLIGHT_SANDBOX:

• gondolin (default) — agentic-pi spawns a per-phase QEMU micro-VM in-process. Uses HVF on macOS, KVM on Linux. No Docker needed.
• docker — agentic-pi runs inside a per-phase sibling Docker container (the lastlight-sandbox:latest image). Requires Docker. Useful for prod-like smoke testing.
• none — agent runs in-process on your host with no isolation. Dev only — never in production.

The dev script is explicitly safe with your personal config:

If you want the Docker sandbox mode locally, build the image once first:

cd apps/server   # the compose file lives in the server package
docker compose --profile build-only build sandbox-base   # shared base first
docker compose --profile build-only build sandbox

Then run the harness (server + dashboard, with hot reload). These scripts live in the lastlight-core package (apps/server/); run them with pnpm --filter from anywhere in the repo:

pnpm --filter lastlight-core dev            # both server and dashboard, concurrent
pnpm --filter lastlight-core dev:server     # server only
pnpm --filter lastlight-core dev:dashboard  # dashboard only

Both server scripts call apps/server/scripts/dev-local.sh, which:

• Verifies the sandbox image exists when LASTLIGHT_SANDBOX=docker
• Copies your GITHUB_APP_PRIVATE_KEY_PATH into ./data/sandbox-data/secrets/app.pem (mode 600) so the sandbox can authenticate to GitHub
• Sets LASTLIGHT_LOCAL_DEV=1, STATE_DIR=./data, LASTLIGHT_SESSIONS_DIR=./data/agent-sessions
• Starts the harness with tsx watch src/index.ts (cwd is apps/server/)

Triggering work via the CLI

The CLI talks to the running server — it does not execute agents directly. Install it globally, then start the server first and, in another terminal:

npm i -g lastlight

# Cheap, safe defaults — single agent invocation
lastlight owner/repo#42                            # triage that one issue
lastlight https://github.com/owner/repo/issues/42  # same, full URL form
lastlight https://github.com/owner/repo/pull/99    # review that one PR
lastlight triage owner/repo                        # scan repo for new issues to triage
lastlight review owner/repo                        # scan repo for PRs to review
lastlight health owner/repo                        # weekly health report

# Expensive, opt-in — full Architect → Executor → Reviewer → PR cycle
lastlight build owner/repo#42
lastlight build https://github.com/owner/repo/issues/42

From a source checkout, swap lastlight for pnpm --filter lastlight exec tsx src/cli.ts.

The default for a single-issue/PR shorthand is the cheap action (triage or review). Build cycles require the explicit build subcommand to opt in.

Beyond triggering work, the CLI is also how you operate and debug an instance over its admin API — no SSH:

lastlight login                   # authenticate against a server; lastlight status / whoami
lastlight workflow                # list / inspect / trigger workflow runs
lastlight session                 # tail an agent session transcript
lastlight logs                    # search the structured server logs
lastlight approvals               # list and resolve pending approval gates
lastlight cron                    # list crons, trigger one by hand
lastlight stats / activity        # spend, token counts, the activity feed
lastlight repo config validate    # check a repo's .lastlight/ config offline
lastlight facts all --repo . --base main   # deterministic diff analysis (lastlight-code-facts)
lastlight fork / pr / chat        # fork an overlay asset, PR helpers, chat
lastlight server …                # host-local lifecycle: setup/build/start/update/db

The full command catalogue lives in packages/cli/CLAUDE.md; lastlight --help lists the same set.

Authentication

pi-ai picks credentials from the provider env vars the harness forwards (the full listed set lives in packages/shared/src/providers.ts — Anthropic / OpenAI / OpenRouter / Google / Mistral / Groq / Cerebras / xAI / HuggingFace / Moonshot / NVIDIA / Fireworks / Together / DeepSeek / Z.AI / Kimi / MiniMax / OpenCode Zen). The harness forwards them into each sandbox container (or VM) so workflow runs can reach the API.

Subscription logins (OAuth) — Codex, Claude Pro, Copilot

Instead of an API key you can authenticate with a paid subscription. pi-ai supports three OAuth providers; log in once on the host and Last Light stores and refreshes the token for you:

lastlight oauth login openai-codex   # ChatGPT Plus/Pro (Codex)
lastlight oauth login anthropic      # Claude Pro/Max
lastlight oauth login github-copilot # GitHub Copilot
lastlight oauth list                 # providers + who's logged in
lastlight oauth status               # store path + token expiry
lastlight oauth test openai-codex    # verify a stored login refreshes
lastlight oauth logout [provider]    # remove one (or all)

From a source checkout, swap lastlight for pnpm --filter lastlight exec tsx src/cli.ts.

Then point the model at that provider and restart the agent:

LASTLIGHT_MODEL=openai-codex/gpt-5.5   # Codex ids: gpt-5.5 / gpt-5.4 / gpt-5.4-mini / gpt-5.3-codex-spark

The login writes auth.json under $STATE_DIR (same JSON shape pi-ai's own npx @earendil-works/pi-ai login writes; override with LASTLIGHT_AUTH_FILE). It's host-local — the browser OAuth flow runs where you type the command, so run it on the machine that runs the agent, then restart (pnpm --filter lastlight-core dev:server from source, or lastlight server restart agent for the installed deploy) to pick it up. Note tsx watch does not reload on .env changes — restart after switching LASTLIGHT_MODEL.

Reach differs by execution path. The in-process chat path passes the token as a per-call key, so all three providers work there. The sandbox (agentic-pi workflow phases) resolves credentials from env only — ANTHROPIC_OAUTH_TOKEN / COPILOT_GITHUB_TOKEN cover Anthropic and Copilot, but Codex has no env-token route and therefore can't run sandbox workflows (it's chat-only). Use an API-key provider for build/triage/review workflows if you only have a Codex subscription.

Docker Deployment

The docker-compose stack is useful when you want a single docker compose up -d deploy. For gondolin (and a smaller deployment surface area), prefer the native systemd deploy instead.

Every docker compose command in this section runs from apps/server/ — that's where docker-compose.yml lives. A production install laid out by lastlight server setup puts instance/ next to it.

Pull (or build) the images

The stack needs the harness image and the sandbox images — the latter is what the harness spawns per phase when LASTLIGHT_SANDBOX=docker.

Prebuilt — the default. Every GitHub Release publishes ghcr.io/nearform/lastlight-{agent,sandbox-base,sandbox,sandbox-qa} as public packages, so docker pull needs no registry login. lastlight server update pulls the tag your overlay's deploy.version pins (else :latest), re-tags them to the local names the compose stack expects, restarts, and prunes superseded versions:

lastlight server update             # pull prebuilt images, restart
lastlight server update --local     # build from source instead
lastlight server update --no-build  # just up + restart, don't touch images

From source. The sandbox services sit under the build-only profile, so they are never started — only built:

cd apps/server
docker compose build agent
docker compose --profile build-only build sandbox-base   # shared base first
docker compose --profile build-only build sandbox
docker compose up -d agent

Set LASTLIGHT_SANDBOX=docker in your instance/secrets/.env. (Inside the harness container, gondolin's QEMU path isn't available unless you do the nested-virt setup yourself — the docker-sandbox path is the practical default for Docker deployments.)

Deployment overlay

Everything specific to your deployment — managed repos, model/route/approval overrides, agent-context, secrets — lives in a single instance/ folder next to docker-compose.yml. It's mounted read-only at /app/instance (LASTLIGHT_OVERLAY_DIR=/app/instance) and is never committed to the public repo or baked into the image, so it's the natural home for a private config repo.

instance/
  config.yaml            # overlay config — merged over the public config/default.yaml
  agent-context/*.md     # (optional) persona/rules overrides, merged by filename
  workflows/*.yaml       # (optional) add or replace workflows by logical name
  skills/<name>/SKILL.md # (optional) skill overrides
  secrets/               # host-only, gitignored: .env + GitHub App *.pem
    .env
    app.pem

Both npx lastlight setup (the config wizard) and lastlight server setup scaffold this for you and then offer to version it as a private repo — git init + an initial commit, then gh repo create … --private --push when the GitHub CLI is authenticated, or the exact git/GitHub commands to run by hand otherwise. server setup also lets you point at an existing overlay repo to clone instead. To do it fully by hand:

mkdir -p instance/secrets
cp apps/server/deploy/.env.production.example instance/secrets/.env   # then fill it in
cp your-app.private-key.pem instance/secrets/app.pem
chmod 600 instance/secrets/.env instance/secrets/app.pem
# instance/config.yaml — at minimum your managed repos:
printf 'managedRepos:\n  - your-org/repo-one\n' > instance/config.yaml

Both the agent and caddy services read instance/secrets/.env via env_file, and the entrypoint also sources it inside the container — so no repo-root .env is needed. Merge rules: maps (models, variants, routes, approval) deep-merge over the public defaults; arrays (managedRepos, disabled.*) replace; environment variables override both. Overlay files are read at startup — edit and docker compose restart agent to apply, no rebuild. The dashboard Config tab shows Default / Overlay / Merged (non-secret) config (secret-looking keys are redacted, so a stray secret in config.yaml won't leak).

Startup is fail-fast: if LASTLIGHT_OVERLAY_DIR is set but the folder is missing or empty (the common "forgot to populate instance/" case), or a cron targets a missing workflow, or a phase's prompt/skill can't resolve, the harness exits 78 with a clear message instead of booting a broken instance.

Expose Webhooks

To receive GitHub webhooks, the server needs to be publicly reachable. The included Caddy config handles HTTPS — set DOMAIN in instance/secrets/.env:

# In instance/secrets/.env:
#   DOMAIN=lastlight.example.com

# Start both agent and caddy
docker compose up -d

Or use ngrok / Cloudflare Tunnel for testing.

State & Monitoring

The state layer is written once and runs on two dialects: SQLite (via libsql) by default, and Postgres (node-postgres or Neon) when DATABASE_URL says so. Both are supported production stores — see apps/server/src/state/CLAUDE.md. With the default SQLite store, all persistent state lives in a single Docker volume (agent-data), mounted at /app/data:

data/
  lastlight.db              # SQLite (libsql): executions, workflow_runs, approvals, sessions …
  agent-sessions/           # Dashboard JSONL envelope store (written by event-shim.ts)
    projects/-app/*.jsonl                    # Chat sessions (one per Slack thread)
    projects/-home-agent-workspace/*.jsonl   # Sandbox-mode workflow sessions
  sandboxes/                # Cloned repos per task (gondolin or docker)
  sandbox-data/             # Shared volume mounted into docker-mode sandboxes
  logs/                     # Structured logs
  secrets/app.pem           # GitHub App PEM (mode 600) for sandbox access

Mount this volume or bind-mount the directory for monitoring tools to access session logs and the execution database.

On Postgres only lastlight.db moves out — the sessions, sandboxes and logs directories are still on disk. lastlight server db check reports which store is live, and lastlight server db migrate runs the one-way SQLite → Postgres copy from inside the agent container (the lastlight-state bin ships in the image, since the CLI may never gain an edge to core).

Trigger Work via CLI

With the container running:

# Health check
curl http://localhost:8644/health

# Trigger a build cycle
lastlight https://github.com/owner/repo/issues/42

# Trigger triage
lastlight triage owner/repo

Native (systemd) Deploy

For a Linux production host with KVM available (/dev/kvm), the native deploy runs the harness directly under systemd and uses gondolin for sandboxing — no Docker required.

See apps/server/deploy/native/README.md for the full runbook. The short version:

git clone https://github.com/nearform/lastlight.git /opt/lastlight
cd /opt/lastlight/apps/server
# (optional) install -m 0600 -o root /path/to/app.pem /etc/lastlight/app.pem
sudo bash deploy/native/install.sh        # scaffolds /etc/lastlight/lastlight.env
sudo $EDITOR /etc/lastlight/lastlight.env # fill in secrets
sudo bash deploy/native/install.sh        # second run: starts the service

Re-deploys: git pull && sudo bash deploy/native/install.sh (idempotent — rebuilds and restarts the service), from apps/server/.

Required: the host kernel must expose /dev/kvm (bare-metal Linux or KVM-enabled VM). Hetzner Cloud, Cloud Run, Fly Machines (without --vm-cpu-class shared), and most managed container hosts do not expose nested virt — see packages/agentic-pi/SPIKE-gondolin.md for the full constraint matrix.

If KVM isn't available, fall back to the Docker deploy above with LASTLIGHT_SANDBOX=docker.

Setup Details

1. Create a GitHub App

1. Go to https://github.com/settings/apps/new
2. Fill in:
   • Name: your bot name (appears on comments/PRs with a [bot] badge)
   • Homepage URL: your repo URL
   • Webhook URL: https://your-domain:8644/webhooks/github (or leave blank for now)
   • Webhook Secret: a random string (same as WEBHOOK_SECRET in .env)
3. Set permissions:
   • Issues: Read & Write
   • Pull Requests: Read & Write
   • Contents: Read & Write
   • Checks: Read & Write (post the last-light/review check; receive its "Re-run" requests)
   • Commit statuses: Read (classic CI statuses — CircleCI, Jenkins, other external CI. Separate from Checks; without it CI is judged on check runs alone)
   • Metadata: Read
4. Subscribe to events: Issues, Pull request, Issue comment, Check run, Check suite (the last two enable the GitHub "Re-run checks" buttons to re-trigger a review)
5. Click Create GitHub App
6. Click Generate a private key — save the .pem file into the project directory
7. Note the App ID from the app settings page
8. Click Install App → install on your repos
9. Note the Installation ID from the URL: github.com/settings/installations/{ID}

2. Environment Variables

Legacy OPENCODE_* names are still read as fallbacks for the corresponding LASTLIGHT_* names, so existing .env files from the OpenCode era keep working.

OpenTelemetry export

OpenTelemetry is disabled by default. Set LASTLIGHT_OTEL_ENABLED=true and configure standard OTEL exporter env vars such as OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, and OTEL_RESOURCE_ATTRIBUTES to export harness spans/metrics for workflow runs, phases, agent executions, PI event streams, and chat turns.

By default Last Light exports metadata only: workflow/phase names, repo, sandbox backend, model, success/stop reason, timing, tokens, and cost. Prompt text, message content, tool arguments, and tool outputs are redacted unless LASTLIGHT_OTEL_INCLUDE_CONTENT=true; that opt-in can export sensitive data and should only be used with a trusted collector.

When LASTLIGHT_OTEL_FORWARD_TO_SANDBOX=true (default), agentic-pi workflow sandboxes emit their own telemetry too. How it reaches the backend depends on the sandbox backend:

• docker (production): sandboxes export OTLP to an in-network OTEL collector (a otel-collector compose service on the sandbox-egress network, reached by a fixed internal IP). That collector re-exports to your real backend over its own outbound network leg. This means the sandbox only ever dials one fixed internal endpoint — collectors on any port or scheme (e.g. https://collector:4318) work without special egress rules, and the backend endpoint and auth headers (OTEL_EXPORTER_OTLP_HEADERS) stay host-side and are never forwarded into the untrusted sandbox. The collector cannot be redirected by sandbox traffic, so it adds no SSRF/exfil surface.
• gondolin / none: agentic-pi runs in the harness process and already inherits the harness OTEL SDK. Allowlisted OTEL_* env vars are forwarded into the sandbox shell env directly; gondolin adds collector hosts (parsed from OTEL_EXPORTER_OTLP_ENDPOINT, signal-specific endpoint env vars, and LASTLIGHT_OTEL_COLLECTOR_HOSTS) to its egress allowlist. Private/internal metadata hosts remain blocked.

Set LASTLIGHT_OTEL_FORWARD_TO_SANDBOX=false to disable sandbox telemetry entirely and keep collector endpoints/headers in the harness only.

3. Managed Repositories

The public config/default.yaml ships an empty managedRepos list — set yours in the overlay (instance/config.yaml), which replaces the list wholesale:

managedRepos:
  - your-org/repo-one
  - your-org/repo-two

Webhooks for repos not in this list are filtered at the connector level; Slack/CLI commands targeting unmanaged repos are rejected. Install the GitHub App on each.

4. Customize Behaviour

Put deployment-specific changes in your overlay (instance/) instead of editing packaged files — that keeps your config out of the public repo and applies on a restart (no rebuild). See Deployment overlay for the full model and layout.

instance/
  config.yaml                 # non-secret config overrides only
  workflows/*.yaml            # add/replace workflows by logical `name`
  workflows/prompts/*.md      # prompt overrides/fallbacks
  skills/<name>/SKILL.md      # skill overrides/fallbacks
  agent-context/*.md          # merged by filename; overlay replaces built-ins
  secrets/                    # host-only, gitignored: .env + *.pem

The dashboard Config tab shows Default / Overlay / Merged non-secret config. Overlay files are read at startup only; docker compose restart agent after changes.

Claude Code skills

Last Light ships a Claude Code plugin that teaches Claude Code how to install, configure and operate Last Light for you. Install the skills, then in a Claude Code session just ask — e.g. "set up a Last Light server", "connect my CLI to my server", "fork the build workflow into my overlay", or "scaffold a Last Light evals workspace".

Install them with the CLI (version-matched to the installed lastlight, works offline — uses the claude plugin marketplace when present, else copies the skills into ~/.claude/skills):

lastlight skills install                 # → ~/.claude/skills (user scope)
lastlight skills install --scope project # → ./.claude/skills (this repo only)
lastlight skills list                    # show bundled skills + where they're installed
lastlight skills uninstall

Or register the marketplace directly — this repo root is itself a Claude Code marketplace (from a checkout, or straight from GitHub):

claude plugin marketplace add ./                 # from a local checkout
claude plugin marketplace add nearform/lastlight # or straight from GitHub
claude plugin install lastlight@lastlight-skills

The plugin lives at the repo root — plugins/lastlight/ (manifest in .claude-plugin/). The published lastlight CLI stages a copy into its own package at build (packages/cli/scripts/copy-plugin.mjs) so lastlight skills install works offline after a global install. These are Claude Code skills — distinct from Last Light's internal sandbox skills in apps/server/skills/.

Architecture

┌─────────────────────────────────────────┐
│            Connector Layer              │
│  GitHub Webhook │ Slack Socket Mode     │
│        ↓        │         ↓             │
│     Event Normalizer (EventEnvelope)    │
└────────────────┬────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│             Core Engine                 │
│  Event Router (deterministic)           │
│        ↓                                │
│  Workflow Runner (YAML phases)          │
│  - Sandbox: `agentic-pi run` per phase  │
│    in a gondolin VM or docker container │
│  - Chat: in-process pi-ai loop          │
│    one session per messaging thread     │
│        ↓                                │
│  Sandboxes (git clone per task)         │
│  Cron Scheduler (health reports)        │
│  State DB (SQLite or Postgres)          │
└─────────────────────────────────────────┘

How Events Flow

1. GitHub webhook → connector verifies signature, filters noise (bot events, edits, labels), normalizes to EventEnvelope
2. Router maps event type to skill deterministically (no LLM in the routing loop):
   • issue.opened → issue-triage
   • pr.opened → pr-review
   • comment.created with @last-light from a maintainer → routed by intent classifier (build / explore / question / triage / review / security / verify / qa-test / demo)
3. Workflow runner loads the matching YAML, dispatches each phase to executeAgent (src/engine/agent-executor.ts, which invokes agentic-pi) or, for chat, ChatRunner (src/engine/chat/chat-runner.ts, in-process pi-ai)
4. Build workflow (workflows/build.yaml) runs a multi-phase cycle:
   • Context (phase_0) — gathers the issue/repo context the later phases read
   • Guardrails · setup — the agent works out install/typecheck/lint and names the repo's full test command, writing it to .git/lastlight-gate.sh (inside .git, so it is never committed). It does not run the suite.
   • Guardrails · gate — a deterministic bash phase that runs that script once; the exit code is the verdict, so READY can only mean the full suite exited 0
   • Architect — read-only analysis, writes plan to .lastlight/issue-N/architect-plan.md
   • Executor — TDD implementation following the plan
   • Reviewer — independent verification (no shared context with executor), with a fix loop of up to 2 cycles if it requests changes
   • Create PR

Cron

Most cron jobs run regardless of webhooks. Only issue triage is webhook-gated. The review and autonomy sweeps deliberately carry no condition: — they are the backstop for work that stranded or for an event that never arrived, which is precisely the failure webhooks cannot self-heal. Don't disable them because webhooks are on.

Project Structure

This is a pnpm + Turborepo workspace. Everything below is the effective layout; the full annotated map lives in the root CLAUDE.md.

lastlight/                      # private root package (lastlight-monorepo)
  CLAUDE.md                     # canonical workspace map + dev orientation
  .claude-plugin/               # Claude Code marketplace manifest (repo = a marketplace)
  plugins/lastlight/            # the Claude Code plugin (skills) — staged into packages/cli at build
  apps/
    server/                     # lastlight-core — the harness + server
      src/                      #   index.ts (entry), engine/, connectors/,
                                #   workflows/, sandbox/, cron/, admin/, state/ …
      config/                   #   config loader + config/default.yaml
      workflows/                #   YAML workflow definitions + prompts/
      skills/                   #   internal sandbox skills (pr-review, building, …)
      agent-context/            #   soul.md / rules.md / security.md (bot persona)
      dashboard/                #   React + Vite admin SPA
      spec/                     #   rebuild-grade architecture spec
      deploy/                   #   entrypoint.sh, native/ systemd deploy, Caddyfile
      Dockerfile                #   harness image
      sandbox*.Dockerfile       #   sandbox images for LASTLIGHT_SANDBOX=docker
      docker-compose.yml        #   compose stack + docker-bake.hcl
      CLAUDE.md                 #   server-package development guide
    www/                        # lastlight-www — Astro site → lastlight.dev
    evals/                      # lastlight-evals — eval harness → evals.lastlight.dev
      dashboard/                #   @lastlight/evals-dashboard (private)
  packages/
    cli/                        # lastlight — the lean published global CLI
      src/                      #   cli.ts (entry), cli-server.ts, oauth-cli.ts, …
      scripts/copy-plugin.mjs   #   stages the root plugins/ + .claude-plugin/ into
                                #   this package at build (so the npm tarball ships them)
    shared/                     # lastlight-shared — e.g. src/providers.ts (registry)
    workflow-engine/            # lastlight-workflow-engine — reusable phase runner
    code-facts/                 # lastlight-code-facts — deterministic PR analysis (ts-morph
                                #   + ast-grep); consumed by the CLI, so `lastlight facts`
                                #   works on the host with --sandbox none
    agentic-pi/                 # agentic-pi — the coding-agent harness run in the sandbox (published)

Core internals that used to sit at the repo root (src/, workflows/, skills/, agent-context/, deploy/, config/, Dockerfile, docker-compose.yml, Caddyfile, spec/) now live under apps/server/.

Troubleshooting

Installing the CLI

npm i -g lastlight installs the lean lastlight package (packages/cli/). It's a thin client + host-local server lifecycle and carries none of the server's native or AI dependencies (no better-sqlite3, no @google/genai), so the install is fast and free of the transitive-deprecation noise those deps used to print. The heavy runtime lives in lastlight-core (apps/server/) and is installed on the host separately (the docker stack or lastlight server build).

Server won't start

# Check .env is loaded
pnpm --filter lastlight-core dev:server
# Look for "Required environment variable not set" errors

pnpm --filter lastlight-core dev says the sandbox image is missing (docker-sandbox mode)

cd apps/server   # the compose file lives in the server package
docker compose --profile build-only build sandbox-base   # shared base first
docker compose --profile build-only build sandbox

Workflow run fails with exit 127: sh: 1: agentic-pi: not found

The sandbox image needs agentic-pi baked in. Rebuild it:

cd apps/server   # the compose file lives in the server package
docker compose --profile build-only build sandbox-base   # shared base first
docker compose --profile build-only build sandbox

If you're on an old lastlight-sandbox:latest, this picks up the install step that the current sandbox.Dockerfile performs.

Workflow hangs forever with no output (gondolin mode on a host without KVM)

Gondolin requires /dev/kvm on Linux or HVF on macOS. Inside a container with no nested virt, VM.create() succeeds but the first vm.exec() hangs. Symptoms: phase shows "running" indefinitely with no JSONL events after sandbox_status.

Either switch to LASTLIGHT_SANDBOX=docker (sibling containers via socket) or move the harness to a KVM-capable host. Full analysis: packages/agentic-pi/SPIKE-gondolin.md.

Agent run fails with a quota / billing error

The runtime surfaces upstream errors as error_api with the verbatim provider message in the executions row:

• OpenAI: "Quota exceeded. Check your plan and billing details." → top up at https://platform.openai.com/account/billing
• Anthropic: "Credit balance is too low" → top up at https://console.anthropic.com

Chat replies fail with error_error

Check the agent logs for the underlying error — common causes:

• Wrong key for the chat model. LASTLIGHT_MODELS={"chat":"anthropic/…"} but no ANTHROPIC_API_KEY set. Fix the override or add the key.
• Model id typo. Watch for [config] Model: … in startup logs to confirm what's actually loaded.

Webhooks not arriving

# Check health endpoint
curl http://localhost:8644/health

# Test with a fake POST (should return 401 — invalid signature)
curl -X POST http://localhost:8644/webhooks/github -d '{}'

# Check Docker port mapping
docker compose ps