LazyDev — Lazy Issue Resolver

LazyDev is an AI-native autonomous CI engineering assistant designed to monitor GitHub issues, generate validated code fixes, and push fix branches safely.

Project Setup

1. Prerequisites

• Cloud Server/VM: A host machine running Linux (Ubuntu/Debian recommended) for production, or macOS/Linux for local development.
• Node.js: (v20 or higher)
• Docker & Docker Compose: Installed on the host.
• GitHub App Credentials:
  • App ID
  • Private Key (.pem file contents)
  • Webhook Secret
• Discord Webhook URL (Optional, for notifications).
• OpenAI API Key (Primary LLM) or a running Ollama instance (free local fallback).

---

2. Environment Setup

Clone the repository and set up the .env file.

git clone https://github.com/FutureMindsDev/lazy-issue-resolver.git
cd lazy-issue-resolver

# Copy the example env file
cp .env.example .env

Edit the .env file and populate all required fields:

NODE_ENV=production
PORT=3000

# GitHub App Settings
GITHUB_APP_ID=your_app_id
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your_webhook_secret

# AI Providers
# Option A — OpenAI (primary, recommended for best results)
OPENAI_API_KEY=your_openai_key
# OPENAI_LLM_MODEL=gpt-4o-mini   # optional, defaults to gpt-4o-mini

# Option B — Ollama (free local fallback, used automatically when OPENAI_API_KEY is not set)
# OLLAMA_HOST=http://host.docker.internal:11434
# OLLAMA_LLM_MODEL=llama3

# Git Author configuration for automated commits
GIT_USER_NAME="LazyDev Bot"
GIT_USER_EMAIL="lazydev@futureminds.dev"

# Infrastructure (Leave as defaults if using docker-compose)
DB_HOST=postgres
DB_PORT=5432
REDIS_HOST=redis
REDIS_PORT=6379

# Notifications
DISCORD_WEBHOOK_URL=your_discord_webhook

# Validation Sandbox
SANDBOX_NETWORK_MODE=bridge

LLM provider selection logic

Condition	Provider used
OPENAI_API_KEY is set	OpenAI (gpt-4o-mini by default)
OPENAI_API_KEY is not set	Ollama (OLLAMA_HOST + OLLAMA_LLM_MODEL)

Ollama on Mac/Linux: Run Ollama on your host machine. The Docker container reaches it via host.docker.internal:11434 (already set in docker-compose.yml).

Note on Sandbox: SANDBOX_NETWORK_MODE controls whether the Docker validation sandbox has internet access. Set to none for total isolation (high security), but note that validation steps (e.g. npm install) may fail if they require downloading dependencies.

---

3. Production / Beta Deployment

The docker-compose.yml bundles the NestJS app alongside all infrastructure components (PostgreSQL, Redis, Qdrant, Prometheus, Grafana).

Start the full stack

docker compose up -d --build

Use --build the first time and whenever you change source code or the Dockerfile. For config-only changes (.env, docker-compose.yml) you can restart without rebuilding:

docker compose up -d

Docker socket & permissions

The app container requires access to /var/run/docker.sock so the SandboxAgent can spin up sibling containers for code validation.

Warning

Mounting /var/run/docker.sock gives the container full control over the host Docker daemon. This is strictly required for the SandboxAgent. The container runs as root (user: root in docker-compose.yml) to ensure socket access. Ensure your host machine is adequately secured.

Cross-platform sandbox (Mac, Linux, Windows)

LazyDev uses a named Docker volume (worktrees) to share workspace files between the app container and sandbox sibling containers. This works identically on all platforms:

• On Mac (Docker Desktop) — container-internal paths like /tmp can't be bind-mounted into sibling containers. Named volumes bypass this completely.
• On Linux — named volumes work the same way.

The worktrees volume is mounted at /app/worktrees inside the app container. Sibling sandbox containers access it via --volumes-from lazydev-app. No manual configuration required — docker-compose.yml handles everything.

If you need to override the worktree base path (advanced), set:

WORKTREE_BASE_PATH=/your/custom/path

---

4. Local Development Deployment

Run the infrastructure in Docker, but the app locally for hot-reload:

docker compose up -d postgres redis qdrant
npm install
npm run start:dev

---

5. Webhook Configuration

Once the app is running, GitHub needs a public URL to send webhooks to.

Option A: Quick & Easy (Using IP and Exposed Port)

• Webhook URL: http://<your-server-ip>:3000/webhooks/github (Note: plain HTTP. GitHub allows this, but payloads travel unencrypted.)

Option B: Local Testing (ngrok)

ngrok http 3000

• Webhook URL: https://<random-id>.ngrok.app/webhooks/github

Option C: Production Recommended (Reverse Proxy with SSL)

• Webhook URL: https://lazydev.your-domain.com/webhooks/github

---

6. Installing the GitHub App

1. Navigate to your app's public installation URL: https://github.com/apps/<your-app-name>
2. Click Install.
3. Select the account or organization.
4. Choose Only select repositories and pick the repos you want LazyDev to monitor.
5. Click Install. LazyDev will now receive webhooks for issues opened in those repositories.

---

Observability (Prometheus & Grafana)

Dashboard	URL	Default login
NestJS API	http://localhost:3000	—
pgAdmin	http://localhost:5050	admin@lazydev.com / admin
RedisInsight	http://localhost:8001	—
Grafana	http://localhost:3100	admin / admin
Prometheus	http://localhost:9090	—

Add Prometheus as a Data Source in Grafana (http://prometheus:9090) and import standard Node.js dashboards to visualize AI request latencies, job failures, and processing rates.

---

Development Standards

• Linting: npm run lint
• Formatting: npm run format
• Tests: npm run test
• Commits: Conventional Commits enforced via Husky.

Features Implemented

• GitHub App Authentication: JWT + Installation Token auth.
• Secure Webhooks: HMAC-SHA256 signature verification with delivery-ID deduplication.
• Asynchronous Ingestion: BullMQ + Redis queue with exponential backoff retries.
• Distributed Locking: Redis Redlock prevents concurrent execution anomalies per repo and branch.
• Multi-Agent Orchestration: LangGraph AI pipeline — IssueAnalyzer → Research → Planning → PatchGenerator → ValidationAgent → GitAgent.
• LLM Logging: Full LLM responses logged per agent for real-time pipeline observability.
• Sandbox Validation: Generated fixes validated by running npm run build inside an isolated sibling Docker container.
• Cross-Platform Sandbox: Named Docker volume for worktrees ensures the sandbox works on Mac, Linux, and Windows without manual configuration.
• Self-Healing Loop: Automatically retries patch generation with validation feedback on failure.
• Notifications: Discord integration for pipeline alerts.
• Security & Stability: Helmet, Throttler rate limiting, BullMQ retries.

License

MIT