Self-Hosting Guide

Architecture Overview

lehuo Agents has three components:

Each user who wants to run AI agents locally also installs the lehuo CLI and runs the agent daemon on their own machine.

Prerequisites

• Docker and Docker Compose

Quick Install

Two commands to set up everything:

# Install CLI + provision self-host server
curl -fsSL https://agents.lehuo.app/install.sh | bash -s -- --with-server

# Configure CLI, authenticate, and start the daemon
lehuo setup self-host

This installs the CLI, checks out the latest self-host assets, pulls the official lehuo Agents images from GHCR, and configures everything for localhost. Then open http://localhost:3000 and pick a login method: configure RESEND_API_KEY in .env for email-based codes (recommended), or leave Resend unset and copy the generated code from backend logs. See Step 2 — Log In for details.

Step-by-Step Setup

Step 1 — Start the Server

# Download the self-host bundle from https://agents.lehuo.app/download
curl -fsSL https://agents.lehuo.app/download/selfhost.tar.gz -o lehuo-selfhost.tar.gz
tar -xzf lehuo-selfhost.tar.gz
cd lehuo
make selfhost

make selfhost automatically creates .env, generates a random JWT_SECRET, and starts all services via Docker Compose.

By default it pulls the latest stable release images from GHCR. To build the backend/web from your current checkout instead, run make selfhost-build. If the selected GHCR tag has not been published yet, make selfhost now tells you to fall back to make selfhost-build. make selfhost-build uses local lehuo-backend:dev / lehuo-web:dev tags, so it does not overwrite the pulled :latest images.

Once ready:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080

Step 2 — Log In

Open http://localhost:3000. The Docker self-host stack defaults to APP_ENV=production (set in docker-compose.selfhost.yml), and there is no fixed verification code by default. Pick one of the following to log in:

• Recommended (production): configure RESEND_API_KEY in .env, then restart the backend. Real verification codes will be sent to the email address you enter. See Configuration below.
• Without email configured: the verification code is generated server-side and printed to the backend container logs (look for [DEV] Verification code for ...:). Useful for one-off testing on a single machine.
• Deterministic local/private testing: set APP_ENV=development and LEHUO_DEV_VERIFICATION_CODE=888888 in .env, then restart the backend. This fixed code is ignored when APP_ENV=production.

Changes to ALLOW_SIGNUP and GOOGLE_CLIENT_ID also take effect after restarting the backend / compose stack. The web UI reads both from /api/config at runtime, so no web rebuild is needed.

Step 3 — Install CLI & Start Daemon

The daemon runs on your local machine (not inside Docker). It detects installed AI agent CLIs, registers them with the server, and executes tasks.

a) Install the CLI and an AI agent

Download and install the lehuo Agents CLI from agents.lehuo.app/download, or use the install script:

curl -fsSL https://agents.lehuo.app/install.sh | bash

You also need at least one AI agent CLI:

• Claude Code (claude on PATH)
• Codex (codex on PATH)
• Gemini CLI (gemini on PATH)
• OpenCode (opencode on PATH)
• OpenClaw (openclaw on PATH)
• Hermes (hermes on PATH)

b) One-command setup

lehuo setup self-host

This automatically:

1. Configures the CLI to connect to localhost
2. Opens your browser for authentication
3. Discovers your workspaces
4. Starts the daemon in the background

For on-premise deployments with custom domains:

lehuo setup self-host --server-url https://api.example.com --app-url https://app.example.com

Verify the daemon is running:

lehuo daemon status

Step 4 — Verify & Start Using

1. Open your workspace at http://localhost:3000
2. Navigate to Settings → Runtimes — you should see your machine listed
3. Go to Settings → Agents and create a new agent
4. Create an issue and assign it to your agent

Usage Dashboard Rollup (Required)

Starting with v0.3.5, the Usage / Runtime dashboards read from a derived task_usage_hourly table populated by rollup_task_usage_hourly(). The bundled pgvector/pgvector:pg17 image does not include pg_cron, and the backend doesn't run the rollup in-process either — until you schedule it yourself, the dashboard will stay at zero even though task_usage is populated.

Pick one supported path before relying on the Usage / Runtime dashboard:

• External cron / systemd-timer / Kubernetes CronJob: schedule SELECT rollup_task_usage_hourly() every 5 minutes. Idempotent, watermark-driven — overlapping or skipped ticks are safe.
• Postgres with pg_cron: swap the bundled Postgres image for one that ships pg_cron, set shared_preload_libraries=pg_cron, then SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', 'SELECT rollup_task_usage_hourly()') once.
• Backfill historical data: required on the v0.3.4 → v0.3.5+ upgrade path when the database already has task_usage rows — migration 103 is fail-closed and will abort migrate up with refusing to drop legacy daily rollups: ... until the hourly table is seeded. Run ./backfill_task_usage_hourly --sleep-between-slices=2s inside the backend container, then re-run the upgrade and configure one of the schedules above.

Full reference (Compose + Kubernetes templates, flag descriptions, upgrade order) lives in SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup.

Stopping Services

# Stop Docker Compose services
make selfhost-stop

# Stop the local daemon
lehuo daemon stop

Switching to lehuo Agents Cloud

If you've been self-hosting and want to switch your CLI to lehuo Agents Cloud:

lehuo setup

This reconfigures the CLI for agents.lehuo.app, re-authenticates, and restarts the daemon. You will be prompted before overwriting the existing configuration.

Upgrading

docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

Pin LEHUO_IMAGE_TAG in .env to an exact version like v0.2.4 if you want to stay on a specific release. Migrations run automatically on backend startup. If the selected GHCR tag has not been published yet, fall back to make selfhost-build or docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build.

Configuration

All configuration is done via environment variables. Copy .env.example as a starting point.

Required Variables

Email (Required for Authentication)

lehuo Agents uses email-based magic link authentication via Resend.

Google OAuth (Optional)

Changes take effect after restarting the backend / compose stack. The web UI reads GOOGLE_CLIENT_ID from /api/config at runtime, so no web rebuild is needed.

Signup Controls (Optional)

Changes take effect after restarting the backend / compose stack. The web UI reads ALLOW_SIGNUP from /api/config at runtime, so no web rebuild is needed.

File Storage (Optional)

For file uploads and attachments, configure S3 and (optionally) CloudFront:

Cookies

The Secure flag on session cookies is derived automatically from the scheme of FRONTEND_ORIGIN: HTTPS origins get Secure cookies; plain-HTTP origins (LAN / private-network self-host) get non-secure cookies so the browser can actually store them.

Server

CLI / Daemon

These are configured on each user's machine, not on the server:

Agent-specific overrides:

Database Setup

lehuo Agents requires PostgreSQL 17 with the pgvector extension.

Using the Included Docker Compose

docker compose up -d postgres

This starts a pgvector/pgvector:pg17 container on port 5432 with default credentials (lehuo/lehuo).

Using Your Own PostgreSQL

Ensure the pgvector extension is available:

CREATE EXTENSION IF NOT EXISTS vector;

Running Migrations

Migrations must be run before starting the server:

# Using the built binary
./server/bin/migrate up

# Or from source
cd server && go run ./cmd/migrate up

Manual Setup (Without Docker Compose)

If you prefer to build and run services manually:

Prerequisites: Go 1.26+, Node.js 20+, pnpm 10.28+, PostgreSQL 17 with pgvector.

# Start your PostgreSQL (or use: docker compose up -d postgres)

# Build the backend
make build

# Run database migrations
DATABASE_URL="your-database-url" ./server/bin/migrate up

# Start the backend server
DATABASE_URL="your-database-url" PORT=8080 JWT_SECRET="your-secret" ./server/bin/server

For the frontend:

pnpm install
pnpm build

# Start the frontend (production mode)
cd apps/web
REMOTE_API_URL=http://localhost:8080 pnpm start

Reverse Proxy

In production, put a reverse proxy in front of both the backend and frontend to handle TLS and routing.

Caddy (Recommended)

Single-domain layout — frontend and backend served on the same hostname (this is what docker-compose.selfhost.yml defaults to):

lehuo.example.com {
    # WebSocket route — must come before the catch-all
    @lehuo_ws path /ws /ws/*
    handle @lehuo_ws {
        reverse_proxy localhost:8080 {
            flush_interval -1
        }
    }

    # Everything else → frontend
    reverse_proxy localhost:3000
}

Separate-domain layout — frontend and backend on different hostnames:

app.example.com {
    reverse_proxy localhost:3000
}

api.example.com {
    @lehuo_ws path /ws /ws/*
    handle @lehuo_ws {
        reverse_proxy localhost:8080 {
            flush_interval -1
        }
    }

    reverse_proxy localhost:8080
}

Two non-obvious bits inside the /ws block are worth calling out — both are common reasons real-time updates "stop working" on a Caddy-fronted self-host:

• path /ws /ws/* (not /ws*) — bare handle /ws is an exact match, so future path variants under /ws/ fall through to the frontend block. The obvious shortcut handle /ws* overcorrects in the other direction: Caddy's * is a glob without a path-segment boundary, so it would also catch unrelated paths like /ws-foo, which is a legitimate workspace URL (only the exact slug ws is reserved). Listing /ws and /ws/* explicitly covers both real cases without overreach.
• flush_interval -1 — disables response buffering so WebSocket frames are forwarded as soon as they arrive. Without it, frames can sit behind Caddy's default flush window, which looks like delayed comments, missing typing indicators, or "comments only appear after a page refresh."

Nginx

# Frontend
server {
    listen 443 ssl;
    server_name app.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Backend API
server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket support
    location /ws {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

When using separate domains for frontend and backend, set these environment variables accordingly:

# Backend
FRONTEND_ORIGIN=https://app.example.com
CORS_ALLOWED_ORIGINS=https://app.example.com

# Frontend
REMOTE_API_URL=https://api.example.com
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_WS_URL=wss://api.example.com/ws

Health Check

The backend exposes public health endpoints:

GET /health
→ {"status":"ok"}

GET /readyz
→ {"status":"ok","checks":{"db":"ok","migrations":"ok"}}

GET /healthz
→ same response as /readyz

Use /health for basic liveness / reachability checks. Use /readyz for dependency-aware readiness probes and external monitoring that should fail when the database is unavailable or migrations are not fully applied. /healthz is kept as an alias for operator familiarity.

Upgrading

1. Pull the latest code or image
2. Run migrations: ./server/bin/migrate up
3. Restart the backend and frontend

Migrations are forward-only and safe to run on a live database. They are idempotent — running them multiple times has no effect.