Quickstart (Self-Hosted)

Self-hosted KubeWatch gives you the complete platform running on your own servers: gateway, auth, ingestion, query, live data, and dashboard. No data ever leaves your environment.

Prerequisites

Before you begin, make sure your server meets these requirements:

The stack now includes an embedded AI log-diagnosis model (llama.cpp serving Phi-4-mini-instruct) that's on by default and reserves 1.5-3 GB of RAM on its own. If you don't need AI log diagnosis, set EMBEDDED_LLM_ENABLED=false in .env after install and the 4 GB / 8 GB numbers from before this feature still apply. See Self-Hosted Requirements for the full breakdown.

Ports 80 and 443 must be open for inbound traffic. Outbound internet access is needed once during install to pull images from ghcr.io, and (unless you disable it) huggingface.co on first start to download the embedded model.

Supported operating systems: Ubuntu 22.04+, Debian 12+, RHEL 9+, Amazon Linux 2023.

Install with one command

Run the installer as a user with Docker access (or root):

curl -fsSL https://raw.githubusercontent.com/lloyd-theophilus/kubewatch-releases/main/install.sh | bash

Prefer to review the script first? Download, inspect, then run it:

curl -fsSL -O https://raw.githubusercontent.com/lloyd-theophilus/kubewatch-releases/main/install.sh
less install.sh
chmod +x install.sh
sudo ./install.sh

The installer asks which mode to run. Choose 2) Self-Hosted, and it'll then prompt you for:

It writes everything to ~/kubewatch-erp/ (the Compose file, a generated .env, and a Caddyfile), pulls all the images, and starts the stack. Expect this to take 2-5 minutes depending on your connection. A random admin password gets generated and printed at the end, so save it somewhere. See Install with Docker Compose for the full walkthrough and prerequisites.

Verify the installation

Once the installer completes, check that all services are running:

cd ~/kubewatch-erp
docker compose ps

All services should show Up, and you should see containers for the API gateway, the backend services (auth, ingestion, query, alerting, notifications, live data), the PostgreSQL and metrics databases, the dashboard, and a Caddy reverse proxy.

Access the dashboard

Open your browser and navigate to:

• http://localhost (if you used localhost as your domain)
• https://your-domain.com (if you configured a real domain with TLS)

Log in with the admin email you entered during setup. Your initial password was printed at the end of the install script. Check your terminal output, or look for ADMIN_PASSWORD in ~/kubewatch-erp/.env.

Deploy your first agent

With your self-hosted gateway running, deploy an agent on any host you want to monitor. Point it at your own gateway instead of the hosted KubeWatch cloud.

First, get your API key from Settings → API Keys in your self-hosted dashboard.

Then deploy the agent on the host you want to monitor:

docker run -d \
  --name kubewatch-agent \
  --restart unless-stopped \
  -e KUBEWATCH_API_KEY=YOUR_API_KEY \
  -e KUBEWATCH_SERVER_URL=https://your-domain.com \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/lloyd-theophilus/kubewatch-agent:latest

Replace YOUR_API_KEY and https://your-domain.com with your actual values.

Next steps

• Self-Hosted Requirements, full hardware and software details
• Install on Kubernetes (Helm), deploy the same stack on your own cluster instead
• Configuration Reference, all environment variables
• Upgrading, how to update your installation
• Backup & Restore, protect your data