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/cliftonc/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 (the agent runtime is agentic-pi, provider-agnostic; default anthropic/claude-sonnet-4-6; one OpenRouter key gets you Claude / GPT / Gemini / Llama / etc.)
• 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

The same Docker image works in K8s. Skip Caddy — use your cluster's Ingress controller for TLS instead.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: lastlight
spec:
  replicas: 1
  selector:
    matchLabels:
      app: lastlight
  template:
    metadata:
      labels:
        app: lastlight
    spec:
      containers:
      - name: agent
        image: your-registry/lastlight:latest
        ports:
        - containerPort: 8644
        env:
        - name: LASTLIGHT_OVERLAY_DIR
          value: /app/instance
        volumeMounts:
        - name: secrets
          mountPath: /app/instance/secrets
          readOnly: true
        - name: state
          mountPath: /app/data
      volumes:
      - name: secrets
        secret:
          secretName: lastlight-secrets
      - name: state
        persistentVolumeClaim:
          claimName: lastlight-state
---
apiVersion: v1
kind: Service
metadata:
  name: lastlight
spec:
  selector:
    app: lastlight
  ports:
  - port: 8644
    targetPort: 8644

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