Skip to main content
This guide runs the full stack on one machine: ClickHouse, the API, the worker, and the UI.
Setting up Apgar with a coding agent? Give it the Apgar skill and the docs MCP server first. See Use with AI agents.

​
Requirements

  • Docker with Compose v2
  • curl and openssl, present on macOS and most Linux distributions
To run Apgar on Kubernetes instead, see Kubernetes.

​
Run Apgar

1

Download the Compose file

2

Create the environment file

Generate the three secrets into .env:
APGAR_SECRET_KEY encrypts stored connection secrets. Keep .env safe: losing the key makes those secrets unreadable.Apgar sends an anonymous usage report once a day. Add APGAR_TELEMETRY=0 to .env to turn it off.
3

Start the stack

apgar-migrate creates the database and exits. The API and the worker start after it has finished, and the command returns once every service is healthy.
4

Sign in

Open http://localhost:8080 and sign in with the value of APGAR_ADMIN_TOKEN. Print it with grep APGAR_ADMIN_TOKEN .env.

​
Explore the demo

The Agents page is empty after the first sign in and offers Seed demo data. Seeding takes about two minutes. It creates two demo agents, billing-copilot and support-agent, with 14 days of scripted releases. Two releases regress on a guardrail: a tool error spike on billing-copilot and a tool loop on support-agent. Two more change without failing, with shorter answers and a model switch that show up in the informational metrics. Open a release to see its verdict, the failing metrics, and where each change is concentrated. The button is shown only while no agent exists. Later, seed from the command line instead:
Demo agents are marked as demo in the UI and in webhook bodies. Remove them when you are done:

​
Add your agent

1

Create the agent

On the Agents page, select Add agent. Enter a name, choose OTLP as the source, pick the Release attribute your traces will carry (apgar.release in this guide), and optionally an environment such as production. Apgar creates an ingest token bound to the agent and shows it once, with the exporter environment to copy.
2

Configure the exporter

Set the copied variables in the environment of your agent service, and add the release attribute to OTEL_RESOURCE_ATTRIBUTES. The copied snippet leaves it out because its value changes with every deploy.
apgar.release is the identifier of the running build: a version, a tag, or a commit hash. Set it from your deploy pipeline. Apgar reads only the attribute chosen on the agent. Turns without it are stored as untagged and never take part in a verdict.
3

Ship a release

About a minute after a trace completes, the agent page lists its release. Turn counts there update every 5 minutes. The first release of an agent has nothing to compare with and shows as First release. From the second release on, Apgar compares each release with the previous one, posts the result, and shows it on the release page.
To pull traces from Langfuse instead, see Langfuse. To receive messages, add a Slack or webhook connection. If nothing shows up, see Troubleshooting.