Self-Hosted — homelab intelligence

Why self-host?

Self-hosting is the right fit if any of these apply to you:

Your homelab monitors air-gapped or sensitive infrastructure and you don't want metrics leaving your network.
You want unlimited history and don't want to pay per-node.
You already run a docker host and want to add one more stateless service.
You want to extend or patch the code — the server is AGPL-3.0 and the agent is MIT licensed on GitHub.

If you'd rather not run another service, the managed tiers are cheaper than any VPS and include alerting, digests, and the natural-language query interface with zero setup.

Requirements

Docker 20.10+ and docker compose v2 (or Podman with compose).
A host reachable from every machine you want to monitor (LAN, VPN, or public).
~150 MB RAM idle, ~300 MB with 20+ nodes. Disk usage grows ~50 MB per node per year.
Outbound internet not required after the initial image pull.

Zero external dependencies. The natural-language query bar and the fleet intelligence digest are rule-based — no API keys, no LLM provider, no data leaves your box. Everything runs from the single container.

Quick start

Four commands and you're running.

Open source. labwatch is available on GitHub. Clone the repo and you're up in two commands.

1Clone the repo

git clone https://github.com/labwatch-dev/labwatch.git cd labwatch

2Set your secrets

Create a .env file next to docker-compose.yml:

ADMIN_SECRET=paste-a-random-string-here SESSION_SECRET=paste-a-different-random-string-here BASE_URL=http://labwatch.lan:8097

Generate secrets with openssl rand -hex 24 and paste them as values. The admin secret is used to log in and register agents. The session secret signs user cookies (must be stable across restarts).

3Start the stack

docker compose up -d

This builds the image from source (takes ~60 seconds the first time) and starts labwatch on port 8097. By default it only listens on 127.0.0.1 — agents on other machines won't be able to reach it. Either change the port in docker-compose.yml to "8097:8097" or put a reverse proxy in front. Logs: docker compose logs -f labwatch.

4Log in

Open http://your-host:8097, click Log in, and paste the admin secret from your .env. You're in.

Before exposing to the internet: put labwatch behind a reverse proxy with HTTPS — see the Reverse proxy section. The built-in server does not terminate TLS.

Environment variables

All configuration is done through environment variables — set them in .env next to the compose file, or inline in docker-compose.yml.

Variable	Default	Purpose
ADMIN_SECRET	change-me	Admin login secret. Must be changed before first boot. Also used as the `X-Admin-Secret` header for the admin API.
BASE_URL	http://localhost:8097	Public URL of your labwatch instance. Used in signup emails and the agent installer script.
DATABASE_PATH	/app/data/labwatch.db	SQLite database location inside the container. The default is mapped to the `labwatch-data` named volume.
PORT	8097	Port the FastAPI server listens on inside the container.
RETENTION_HOURS	168	How long to keep metrics, alerts, and heartbeat data. Older rows are pruned on startup and every 24h. Bump this if you want longer history (at the cost of disk).
SESSION_SECRET	auto-generated	Secret key for signing session cookies. If not set, a random key is generated on startup — meaning sessions are invalidated on every container restart. Set this to a fixed value (`openssl rand -hex 32`) if you want sessions to survive restarts.

Reverse proxy & HTTPS

For anything beyond a single-machine LAN setup you'll want HTTPS. A minimal Caddy example:

labwatch.example.com { reverse_proxy localhost:8097 }

Caddy handles ACME automatically. For nginx or Traefik, proxy to 127.0.0.1:8097 and make sure X-Forwarded-For / X-Forwarded-Proto headers are preserved. Update BASE_URL in your .env to the public HTTPS URL and restart the container.

Backups

All state lives in a single SQLite file at /app/data/labwatch.db (mapped to the labwatch-data volume). Back it up the same way you back up anything else:

docker compose exec labwatch \ python -c "import sqlite3; sqlite3.connect('/app/data/labwatch.db').backup(sqlite3.connect('/app/data/backup.db'))" docker cp labwatch:/app/data/backup.db ./labwatch-$(date +%F).db

Or just snapshot the Docker volume directly with restic, borg, or whatever you already use.

Install agents

Once the server is running, install the agent on each machine you want to monitor. The installer pulls the latest binary from your labwatch instance — no external dependency:

curl -fsSL http://your-labwatch-host:8097/install.sh | sudo bash

The script installs the agent to /usr/local/bin/labwatch, creates a systemd unit, and drops an empty config at /etc/labwatch/config.yaml. Prefer to review scripts before running? Download it first:

curl -fsSL http://your-labwatch-host:8097/install.sh -o install.sh less install.sh sudo bash install.sh

Agent config

Edit /etc/labwatch/config.yaml on the agent host. The minimum required fields are api_endpoint, admin_secret (one-time, for registration), and a collection interval:

# /etc/labwatch/config.yaml api_endpoint: "http://your-labwatch-host:8097/api/v1" admin_secret: "your-admin-secret" # remove after first register interval: 60s docker: enabled: true socket: "/var/run/docker.sock" services: - name: "Web" type: "http" endpoint: "http://localhost:80" timeout: "5s" - name: "SSH" type: "tcp" endpoint: "localhost:22" timeout: "3s"

Register with the server, then start the service:

sudo labwatch --register sudo systemctl enable --now labwatch

After a successful register the agent prints your lab_id and token to stdout. Paste them into /etc/labwatch/config.yaml, then you can remove admin_secret from the config.

Multiple nodes? Repeat the install + register on each node. Each agent gets its own lab_id and token.

Upgrading

Pull the latest source and rebuild:

cd labwatch git pull docker compose up -d --build

Your database volume is preserved across rebuilds. Schema migrations run automatically on startup.

License FAQ

The server is AGPL-3.0 and the agent is MIT. Here's what that means in practice:

I run labwatch on my LAN for myself. Does AGPL affect me?

No. AGPL's sharing requirement only triggers when you provide the software as a network service to third parties. Running it on your own LAN for your own use has zero obligations beyond the license grant you already received.

Can I embed the agent in my own project?

Yes. The agent is MIT — no restrictions. Embed it, fork it, ship it commercially, whatever you need.

What if I modify the server and host it for my team?

If you modify the server and let others access it over a network, AGPL requires you to make your modified source available to those users. The simplest way: push your fork to a public repo and link to it from the UI.

Does the managed tier (labwatch.dev) use different code?

Same codebase. The managed tier adds hosting, backups, and support — no proprietary code on top.

Troubleshooting

Container won't start

Check logs with docker compose logs labwatch. The most common causes are a port conflict on 8097 (change the left side of the port mapping) or a volume permission issue (remove the volume with docker volume rm labwatch_labwatch-data and restart — this wipes data).

Agents register but no metrics appear

Check the agent logs: journalctl -u labwatch -f. If you see 401 Unauthorized, the token in /etc/labwatch/config.yaml is wrong — re-run labwatch --register. If you see connection refused, verify api_endpoint is reachable from the agent: curl http://your-labwatch-host:8097/health.

NLQ returns “I didn’t quite get that”

The query bar uses regex pattern matching — it recognizes ~20 query shapes (fleet overview, alerts, cpu/memory/disk pressure, containers, temperature, network, nodes needing attention). Rephrase toward one of those shapes, or try clicking a suggested chip. No API key is needed — if you got an error, check docker compose logs labwatch for a stack trace.

Still stuck? Email support@labwatch.dev with your docker compose logs labwatch output and we'll dig in with you.

Self-Hosted labwatch