Self-host an AI coding agent dashboard with Docker, Kubernetes and SSO

Your agents' prompts, file paths and tool output say a lot about your code. AgentPulse keeps all of it on infrastructure you run. This guide covers the deployment options, from a single container to a multi-user Kubernetes install behind single sign-on.

Pick a deployment

Setup	Good for	Database
Local service (Bun)	One machine, no Docker	SQLite
Docker container	One machine, or a small home server	SQLite
Remote server + relays	Several machines reporting to one dashboard	SQLite or PostgreSQL
Kubernetes	A homelab or team install behind SSO	SQLite, or PostgreSQL with the overlay

Docker, on your own machine

This starts the container bound to localhost, waits for it to be healthy and configures the agent hooks:

docker run -d -p 127.0.0.1:3000:3000 -v agentpulse-data:/app/data -e DISABLE_AUTH=true \
  --restart unless-stopped --name agentpulse ghcr.io/jstuart0/agentpulse \
  && until curl -fsSL http://localhost:3000/api/v1/health >/dev/null 2>&1; do sleep 1; done \
  && curl -sSL http://localhost:3000/setup.sh | bash

The 127.0.0.1: prefix matters. DISABLE_AUTH=true turns off login, so the port must not be reachable from your network.

A server for several machines

Run AgentPulse with authentication on (the default), then install the relay on each machine that runs agents. The relay listens on localhost, queues events on disk and forwards them to the server with an API key:

curl -sSL https://your-agentpulse-server.example.com/setup-relay.sh | bash

The relay's key needs the ingest and observe scopes. Mint one per machine in Settings, so you can revoke a single machine without touching the rest.

Kubernetes with single sign-on

The repository ships Kustomize manifests in deploy/k8s/: namespace, deployment, service, PVC, network policy, resource limits and a Traefik IngressRoute. Hook ingestion is authenticated with API keys, while the dashboard goes through your identity provider:

kubectl apply -k deploy/k8s/

AgentPulse trusts identity headers from any forwardauth provider: Authentik (the default header names), Authelia, oauth2-proxy, Pomerium and Cloudflare Access. A shared secret injected by the proxy proves the headers came from it. Provider-specific setup is in FORWARDAUTH.md.

PostgreSQL

SQLite is the default and works well for one instance. For PostgreSQL, set DATABASE_URL=postgres://..., or apply the overlay in deploy/overlays/postgres/, which also switches the deployment to rolling updates. Migrations run at boot under an advisory lock, so a rolling deploy can't run them twice. Keep to one replica for now: some rate limits and queues are held in process memory.

Teams

AgentPulse runs in solo mode by default. Team mode adds people, admins and per-session owners: each session belongs to whoever's key reported it, and deleting, archiving or renaming needs the owner or an admin. Team mode attributes work to people. It doesn't make sessions private, since every member can read every session.

Data and privacy

Event retention is off by default. Set a retention period in Settings to delete old events automatically.
Each machine can list directories in ~/.agentpulse/exclude. The relay and supervisor never send sessions from those directories, and the server never learns the list.
Anonymous usage telemetry is on by default. Turn it off with AGENTPULSE_TELEMETRY=off or DO_NOT_TRACK=1.