Free · MIT-licensed

Self-host LazyDev

Run the entire stack on your own server. You bring the GitHub App and LLM provider — everything else is in the Docker Compose file.

Prerequisites

  • Linux (Ubuntu/Debian) server, or macOS/Linux for local dev
  • Node.js v20+ (local dev only; Docker image bundles Node)
  • Docker & Docker Compose
  • GitHub App credentials (App ID, Private Key, Webhook Secret)
  • An LLM API key — or a local Ollama instance (free fallback)

Setup steps

Follow these in order — each step builds on the previous one.

  1. Connect GitHub with a GitHub App

    Your server hears about your issues through a GitHub App. Create one below, then install it on your repos.

  2. Environment setup

    Self-host uses two public repos. lazydev-server is the backend — every setting (GitHub App, LLM keys, database, Docker) lives in its .env file. lazydev-client is the frontend website — it only needs to know the server's address. Do not clone lazy-issue-resolver: that is our private copy that powers the hosted service.

    # Backend (server) — holds ALL backend env
git clone https://github.com/FutureMindsDev/lazydev-server.git
cd lazydev-server
cp .env.example .env

# Frontend (client) — in a separate terminal, only API URL
git clone https://github.com/FutureMindsDev/lazydev-client.git
cd lazydev-client
cp .env.example .env

    Edit the server .env. Fill in at least the block below.

    # GitHub App (server .env) — all three values come from Step 1
GITHUB_APP_ID=
GITHUB_WEBHOOK_SECRET=
# Open the downloaded .pem file and paste its FULL text here (quoted, real newlines).
# There is no file-path mode — never mount *.pem files into Docker.
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."

# Tunnel — paste your ngrok authtoken here (Step 6).
# The Docker ngrok container needs this to come online.
NGROK_AUTHTOKEN=

# LLM provider — RECOMMENDED: set LLM_CONFIG_ENCRYPTION_KEY
# and add your key in dashboard → Settings → LLM provider (§2a).
# Headless / no dashboard? Fill §2b instead:
# OPENAI_API_KEY=
# LLM_MODEL=gpt-4o-mini

    Two ways to set your AI key. §2a (recommended): put LLM_CONFIG_ENCRYPTION_KEY in .env, start the app, then add your key in the dashboard under Settings → LLM provider (it is stored encrypted). §2b: only for headless servers with no dashboard — paste the key directly into .env instead. Everything else already has working Docker defaults (database, Redis, Qdrant, folders). Touch the [DEV] localhost lines only when running the app on your machine with npm run start:dev.

  3. Pick your models provider

    You give LazyDev the model(s) that do the thinking, plus — if you want — a free extra brain for screening. Pick an option:

  4. Run the full stack

    Run this inside the server folder from Step 2. To start ngrok together with the app (recommended), add the tunnel profile:

    # Recommended: app + ngrok tunnel together
docker compose --profile tunnel up -d --build

# Only if you run ngrok on your local machine instead (Step 6, Option 2):
# docker compose up -d --build

    Use --build the first time and whenever you edit code. If you only changed settings (.env), restart without it. Next: Step 6 shows you how to read your ngrok address and paste it into the GitHub App.

    Note: Docker socket access (handled for you)

    The sandbox needs Docker to spin up throwaway containers that test each fix — but the app container never touches the raw /var/run/docker.sock. Instead, a read-only socket-proxy sidecar (tecnativa/docker-socket-proxy) holds the host socket and only passes through the handful of Docker commands the app is allowed to run. The app talks to it over the internal network: DOCKER_HOST=tcp://socket-proxy:2375. Keeping your host machine itself backed up and secured is still sensible — anyone with full host access controls everything, Docker included.

  5. Get your public webhook URL with ngrok

    Your app listens on port 3200 on your own machine — but GitHub lives on the internet and cannot reach it. A tunnel gives you a public address that forwards to your app. Sign up for ngrok, start a tunnel, then replace the placeholder Webhook URL from Step 1 with your real https://<your-address>/webhooks/github. The tunnel is needed so the GitHub App webhook can reach your server. Pick one of these three options, do not run more than one tunnel at a time:

    First — sign up and get your authtoken (all tunnel options)

    1. Sign up at https://dashboard.ngrok.com/signup and log in.
    2. Open Your Authtoken (https://dashboard.ngrok.com/get-started/your-authtoken) and copy the authtoken shown.

    What LazyDev will NOT do

    It never merges code and never touches protected branches. Fixes run one job at a time so they cannot overlap — every change arrives as a branch + PR for you to review and approve.

Prefer not to manage infrastructure?

Let us host it for you — just install the GitHub App.

See the hosted option

For the complete guide, see the server README and the client README on GitHub.