Quickstart

Quickstart

This page gets Trove running quickly with Docker Compose. It assumes you want a server plus at least one agent.

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.

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 the first bootstrap 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.

Docker host quickstart

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=trove_xxxxxxxx \
  -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.

Proxmox quickstart

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=trove_xxxxxxxx \
  -e TROVE_PROXMOX_URL=https://YOUR-PVE-HOST:8006 \
  -e TROVE_PROXMOX_TOKEN='trove@pve!trove-agent=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -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

Set the server URL and token in the manifest or create a Secret and reference it. The agent runs in-cluster and uses Kubernetes read-only API access to report workloads.

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

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.