Installation

Run the Kanshi server (core, dashboard, and TimescaleDB) with Docker Compose, then install an agent on each host you want to monitor. To try Kanshi locally without configuring anything, use the Quickstart instead; this guide is the real, persistent setup.

1. Get the stack

curl -O https://kanshi.dev/docker-compose.yml

2. Configure

Generate separate secrets and write them to a .env file next to the compose file:

cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
KANSHI_API_KEY=$(openssl rand -hex 32)
KANSHI_DASHBOARD_KEY=$(openssl rand -hex 32)
EOF

KANSHI_API_KEY is the ingest key your agents authenticate with. KANSHI_DASHBOARD_KEY is the key you log in to the dashboard with. See Configuration for every variable, including CORS origins, the alert evaluation interval, and webhook delivery.

3. Start the server

docker compose up -d

Core applies the database schema and the 30-day retention policy on startup. The dashboard is on port 3000, the REST API on 8080, and agent ingest (gRPC) on 50051. Open http://your-server:3000 and log in with KANSHI_DASHBOARD_KEY.

Caution

Agents connect to the core over gRPC on 50051, so that port must be reachable from your hosts. Keep it and the REST API behind your firewall or a private network; only the dashboard needs to be reachable by people.

4. Install an agent on each host

curl -fsSL https://kanshi.dev/install.sh | sudo sh -s -- --service

This installs the agent as a background service (systemd on Linux, launchd on macOS) and asks for:

• the core address, for example your-server:50051
• the ingest key (KANSHI_API_KEY from step 2)

The agent starts immediately and on every boot. Adjust the collection interval, host tags, and batching with the agent variables on the Configuration page. Network metrics are collected with the other host metrics. Process telemetry is disabled by default because process names can expose workload details; enable it only on hosts where that visibility is appropriate.

The Dashboard keeps your Light or Dark theme choice in the browser. Dark is the default until you select Light from the Admin menu.

To run the agent in the foreground instead of as a service, install the binary and run it directly:

curl -fsSL https://kanshi.dev/install.sh | sh
KANSHI_CORE_ADDR=your-server:50051 KANSHI_API_KEY=your-ingest-key kanshi-agent

Windows

The install script does not run on Windows. Download the Windows agent archive (kanshi-agent_<version>_windows_amd64.zip) from the agent releases, extract kanshi-agent.exe, and run it with the core address and ingest key set:

$env:KANSHI_CORE_ADDR = "your-server:50051"
$env:KANSHI_API_KEY   = "your-ingest-key"
.\kanshi-agent.exe

To keep it running across reboots, register kanshi-agent.exe as a service with NSSM or a Task Scheduler task set to run at startup.