Run it for real

Step 1 Fork the repo

Fork Last Light so you can customize skills, tweak prompts, and track your own changes. Pull upstream updates whenever you want.

# Fork on GitHub first, then clone your fork
git clone https://github.com/YOUR-USERNAME/lastlight.git
cd lastlight

# Add upstream so you can pull updates later
git remote add upstream https://github.com/nearform/lastlight.git

Your skills, deployment config, and Dockerfile are yours to modify. The skills/ directory is where all the behavior lives — edit freely.

Step 2 Configure your overlay

Everything deployment-specific — managed repos, config overrides, and secrets — lives in a single instance/ folder, gitignored and mounted read-only at /app/instance. It's never baked into the image, so it's the natural home for a private config repo. (npx lastlight setup scaffolds all of this for you.)

# Secrets (gitignored, host-only)
mkdir -p instance/secrets
cp deploy/.env.production.example instance/secrets/.env
cp ~/path-to/your-app.private-key.pem instance/secrets/app.pem
chmod 600 instance/secrets/.env instance/secrets/app.pem

# Overlay config — at minimum the repos the bot manages
printf 'managedRepos:\n  - your-org/repo-one\n' > instance/config.yaml

Edit instance/secrets/.env with your:

• Managed repositories — set managedRepos in instance/config.yaml (the public default ships empty)
• GitHub App credentials — App ID, Installation ID, and private key path (./app.pem)
• Webhook secret — must match your GitHub App's webhook settings
• Domain — your public hostname for automatic TLS (or localhost for dev)
• Model API key — OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY matching your LASTLIGHT_MODEL (Last Light runs on any model the pi coding agent supports — Claude, GPT, Gemini, Llama, and more; default anthropic/claude-sonnet-4-6; one OpenRouter key reaches most of them)
• Sandbox backend (optional) — LASTLIGHT_SANDBOX selects gondolin (default — QEMU micro-VM), docker, or none
• Model overrides (optional) — LASTLIGHT_MODELS as JSON to route architect/executor/reviewer phases to different provider/model strings
• Reasoning effort (optional) — LASTLIGHT_THINKING as the default (off / minimal / low / medium / high / xhigh), or LASTLIGHT_THINKINGS JSON for per-phase overrides
• Approval gates (optional) — APPROVAL_GATES=post_architect,post_reviewer to pause at human-in-the-loop checkpoints
• Admin dashboard (recommended) — ADMIN_PASSWORD and a stable ADMIN_SECRET for persistent login sessions
• Slack chat (optional) — SLACK_BOT_TOKEN and SLACK_APP_TOKEN for the in-process chat skill (Socket Mode)
• Slack OAuth login (optional) — SLACK_OAUTH_CLIENT_ID, SLACK_OAUTH_CLIENT_SECRET, SLACK_OAUTH_REDIRECT_URI, and optionally SLACK_ALLOWED_WORKSPACE to restrict login to one team

See the Configuration reference for every variable the harness reads, with defaults and descriptions.

Step 3 Build & run

The harness Docker image bundles agentic-pi as an npm dep; all skills and dependencies are baked in, and GitHub tooling is built into the agent (no separate MCP process to run). Secrets are injected at runtime via the mounted volume.

# DOMAIN lives in instance/secrets/.env (read by Caddy via env_file) —
# no repo-root .env needed.

# Build and start
docker compose up -d

# Watch the logs
docker compose logs -f agent

No interactive login step — pi-ai reads the OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY you put in instance/secrets/.env and forwards them into each sandbox.

What happens:

• Agent container starts, symlinks your secrets, generates a GitHub token, and starts the webhook listener on port 8644
• Caddy container provisions a Let's Encrypt certificate for your domain and reverse-proxies HTTPS to the agent
• For local dev, set DOMAIN=localhost — Caddy serves HTTP only, no TLS

Verify it's running:

# Health check
curl https://lastlight.example.com/health

# Or locally
curl http://localhost/health

# docker-compose.override.yml
services:
  agent:
    ports:
      - "127.0.0.1:8644:8644"
  caddy:
    profiles:
      - disabled

lastlight.example.com {
    reverse_proxy localhost:8644
}

server {
    listen 443 ssl;
    server_name lastlight.example.com;
    location / {
        proxy_pass http://127.0.0.1:8644;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Step 4 Point GitHub webhooks

In your GitHub App settings, set the webhook URL and subscribe to events.

• Webhook URL: https://lastlight.example.com/webhooks/github
• Secret: same value as WEBHOOK_SECRET in your instance/secrets/.env
• Events: Issues, Pull requests, Issue comments, PR review comments, PR reviews

Install the GitHub App on the repos (or org) you want Last Light to manage. Test by opening an issue — the bot should triage it within seconds.

Step 5 Running in Kubernetes optional

Which image you need depends on the sandbox backend. The default gondolin backend runs each phase in a QEMU micro-VM, so it needs QEMU in the image and /dev/kvm on the node — use the lastlight-agent-qemu variant. The base lastlight-agent image ships no QEMU: it targets the docker backend, which wants a Docker socket that containerd-based clusters don't expose.

A complete, kubectl apply -k-able example lives in apps/server/deploy/k8s/ — namespace, the KVM device plugin, Deployment, PVC, and Service. It exposes /dev/kvm to an otherwise-unprivileged pod via the squat/generic-device-plugin DaemonSet (resource devic.es/kvm), adds the one SYS_RESOURCE capability gondolin's QEMU needs (which requires the namespace to run at privileged PodSecurity), and keeps the guest-image cache on the PVC. Follow its README for the edits it needs (image tag, Secret, StorageClass, ingress, managed repos).

Until #210 Gap 2 lands, the gondolin guest image lacks gitleaks/semgrep, so security-review falls back to a manual pass.

Create the K8s Secret from your local files: kubectl create secret generic lastlight-secrets --namespace lastlight --from-file=.env=instance/secrets/.env --from-file=app.pem=instance/secrets/app.pem