Last Light

Last Light

GitHub Repository Maintenance Agent
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-4-6).

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. Provider API key — OPENAI_API_KEY, ANTHROPIC_API_KEY, and/or OPENROUTER_API_KEY, whichever your LASTLIGHT_MODEL points at
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 20+, 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 20+
• 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 (OPENAI_API_KEY for openai/…, ANTHROPIC_API_KEY for anthropic/…, OPENROUTER_API_KEY for openrouter/…)

Setup

git clone https://github.com/cliftonc/lastlight.git
cd lastlight
npm install

Copy and edit the environment file:

cp .env.example .env

Fill in the required values in .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 — pick one matching your key
LASTLIGHT_MODEL=anthropic/claude-sonnet-4-6
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# OPENROUTER_API_KEY=sk-or-...

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

Run

npm run 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:

	Touched?
~/.gitconfig (your identity, credential helper)	❌ skipped (LASTLIGHT_LOCAL_DEV=1)
./data/agent-sessions/	✅ project-local; shim envelope jsonls for the dashboard live here
./data/sandbox-data/	✅ project-local bind-mount when using LASTLIGHT_SANDBOX=docker
./data/lastlight.db, ./data/sandboxes/, ./data/logs/	✅ project-local state, gitignored

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

docker compose --profile build-only build sandbox

Then run the harness (server + dashboard, with hot reload):

npm run dev            # both server and dashboard, concurrent
npm run dev:server     # server only
npm run dev:dashboard  # dashboard only