Quickstart

Quickstart

This page gets a Trove server and your first agent running with Docker Compose.

Before you start

You need Docker with the Compose plugin, curl, and openssl. Confirm Docker is usable by your current user:

docker ps
docker compose version

If docker ps returns permission denied, fix Docker access first and open a new shell. Do not paper over it by adding sudo to half the commands. That tends to create root-owned files and a second problem for free.

If you already know which platform you want to monitor, jump to the matching agent page after the server is running:

• Docker-Agent
• Kubernetes-Agent
• Proxmox-Agent
• Local-Agent

The mental model

You run one central trove-server.

Then you run agents wherever the data lives:

• one Docker agent per Docker host
• one Kubernetes agent per cluster
• one Proxmox agent per Proxmox cluster
• one local agent per Linux host where you want systemd units reported

Each agent needs its own Trove token. Tokens are created on the server and shown once.

Docker host: server and agent together

Use this when the dashboard will run on the Docker host you want to watch:

mkdir trove && cd trove
curl -fsSLO https://raw.githubusercontent.com/techdox/trove/main/examples/docker-compose.yml
echo "TROVE_TOKEN=trove_$(openssl rand -hex 24)" > .env
docker compose up -d

Open http://localhost:8080. The host's containers should appear within about 30 seconds.

The token in .env bootstraps this first agent. Keep that file. Generating a different token on every restart breaks the agent's authentication.

Proxmox: server and agent together

The shortest Proxmox install uses the matching Compose example. First create and verify a read-only Proxmox token as described in Proxmox-Agent, then:

mkdir trove && cd trove
curl -fsSLO https://raw.githubusercontent.com/techdox/trove/main/examples/docker-compose.proxmox.yml
{
  echo "TROVE_TOKEN=trove_$(openssl rand -hex 24)"
  echo "TROVE_PROXMOX_URL=https://YOUR-PVE-HOST:8006"
  echo "TROVE_PROXMOX_TOKEN=trove@pve!trove-agent=PROXMOX_TOKEN_SECRET"
} > .env

Edit the two Proxmox values, then start it:

docker compose -f docker-compose.proxmox.yml up -d
docker compose -f docker-compose.proxmox.yml logs -f agent

TROVE_TOKEN is Trove's agent credential. TROVE_PROXMOX_TOKEN is the read-only Proxmox API credential. They are not interchangeable.

Server-only Compose

Use the server-only Compose file when the agents will run somewhere else.

curl -fsSLO https://raw.githubusercontent.com/techdox/trove/main/examples/docker-compose.server.yml

echo "TROVE_TOKEN=trove_$(openssl rand -hex 24)" > .env

docker compose -f docker-compose.server.yml up -d

Open:

http://localhost:8080

The dashboard will be empty until an agent connects.

The Compose file seeds one token for the first agent from TROVE_BOOTSTRAP_AGENT and TROVE_BOOTSTRAP_TOKEN. Additional agents should get their own tokens with:

docker compose -f docker-compose.server.yml exec server trove-server agent create docker-nuc01

Copy the trove_... token immediately. Trove stores only the token hash.

Add another Docker host

Run this on the Docker host you want to monitor:

docker run -d --name trove-agent-docker --restart unless-stopped \
  -e TROVE_SERVER_URL=http://YOUR-SERVER:8080 \
  -e TROVE_TOKEN=AGENT_TOKEN_VALUE \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/techdox/trove-agent-docker:latest

Use the Trove server address as seen from the Docker host. Do not use localhost unless the server is on the same host.

Add Proxmox to an existing server

For Proxmox, create a read-only API token first. The important footgun is privilege separation.

pveum user add trove@pve --comment "Trove read-only catalog agent"
pveum aclmod / --users trove@pve --roles PVEAuditor
pveum user token add trove@pve trove-agent --privsep 0

--privsep 0 matters. A privilege-separated token can authenticate but return empty data, which makes the agent look connected while nothing appears in Trove.

Then run the Proxmox agent:

docker run -d --name trove-agent-proxmox --restart unless-stopped \
  -e TROVE_SERVER_URL=http://YOUR-SERVER:8080 \
  -e TROVE_TOKEN=AGENT_TOKEN_VALUE \
  -e TROVE_PROXMOX_URL=https://YOUR-PVE-HOST:8006 \
  -e TROVE_PROXMOX_TOKEN='trove@pve!trove-agent=PROXMOX_TOKEN_SECRET' \
  -e TROVE_PROXMOX_INSECURE=true \
  ghcr.io/techdox/trove-agent-proxmox:latest

Kubernetes quickstart

Use the shipped manifest as the starting point:

curl -fsSLO https://raw.githubusercontent.com/techdox/trove/main/deploy/kubernetes/trove-agent.yaml

Create the trove-agent Secret, set TROVE_SERVER_URL and TROVE_CLUSTER_NAME in the manifest, then apply it. The shipped manifest already includes the namespace, ServiceAccount, read-only RBAC, and hardened Deployment.

See Kubernetes-Agent for the full setup notes.

Verify it worked

Check the server health endpoint:

curl http://YOUR-SERVER:8080/healthz

Check the services API:

curl http://YOUR-SERVER:8080/api/v1/services

Check the agents API:

curl http://YOUR-SERVER:8080/api/v1/agents

On the dashboard, you should see:

• the agent card
• the host or cluster it reports
• services grouped by host/platform
• recent activity events after state changes

If OIDC is enabled, the read API checks need TROVE_API_TOKEN; /healthz stays unauthenticated. See Authentication#programmatic-read-api-access.

For anything you care about, replace :latest with a tested release tag after the first install. See Upgrade-Guide for pinning and backups.

Important security note

The dashboard and read APIs are open unless OIDC is configured. Keep the server bound to a trusted network, VPN, or an authenticating reverse proxy, or enable native OIDC before exposing it more broadly. See Authentication.