Docs

Prerequisites

Before you start, make sure you have the following in place.

A host machine

Last Light runs as a single Node process (locally) or a single Docker container (in production). It spawns Docker sandbox containers for every agent task, so the host needs Docker installed and the Docker socket reachable by the harness.

  • Node.js 20+ — for local development (npm run dev).
  • Docker — required in both dev and production. Agent tasks run inside sandbox containers so the bot cannot touch your host filesystem, credentials, or git identity.
  • Git — for cloning the repo you want to deploy.
Do not deploy Last Light onto core infrastructure. It's an autonomous agent with write access to your repos. Run it on an isolated host (a cheap VPS, a dedicated VM, a separate cloud project) where it cannot reach sensitive internal systems.

A GitHub App

Last Light authenticates to GitHub as its own GitHub App rather than as a personal access token. This keeps the bot's actions clearly attributed (last-light[bot]), lets you downscope permissions per workflow, and makes installation per-repo instead of per-user.

The Create a GitHub App page walks through the exact permissions and events to request. You'll end up with four values you need to paste into .env: App ID, Installation ID, webhook secret, and a .pem private key.

Anthropic credentials

Pick one of two auth modes:

  • Claude Code subscription (default for local dev) — run claude login on the host. The harness seeds the resulting credentials into the sandbox's claude-home directory on every start, so the sandbox is logged in without bind-mounting your real ~/.claude.
  • Anthropic API key — set ANTHROPIC_API_KEY in .env. Useful for production deployments where you want per-request billing and no interactive login.
In Docker, always run claude login as the lastlight user, not root: docker exec -it --user lastlight lastlight-agent-1 claude login. Logging in as root causes permission errors on .credentials.json and corrupts the MCP auth cache. See the README troubleshooting section.

Optional: a Slack workspace

Slack integration is optional but recommended — it's how you chat with the bot outside GitHub. You'll need permission to create a Slack app and install it in your workspace. See Slack integration.

Optional: a public domain

To receive GitHub webhooks in real-time (instead of relying on cron polling), the harness needs to be publicly reachable over HTTPS. In production this is handled by the bundled Caddy reverse proxy, which provisions TLS automatically — you just point a DNS record at your host. For local testing, use ngrok or Cloudflare Tunnel.

← Previous Introduction