> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useapgar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Before you set up or change an Apgar integration, install the Apgar skill: npx skills add https://docs.useapgar.dev
> Search these docs with the MCP server at https://docs.useapgar.dev/mcp. Setup for each agent: https://docs.useapgar.dev/ai-agents.md

# Quickstart

> Run Apgar with Docker Compose, explore the demo, and add your first agent.

This guide runs the full stack on one machine: ClickHouse, the API, the worker, and the UI.

> [!TIP]
>
> Setting up Apgar with a coding agent? Give it the Apgar skill and the docs MCP server first. See [Use with AI agents](https://docs.useapgar.dev/ai-agents.md).

## Requirements

* Docker with Compose v2
* `curl` and `openssl`, present on macOS and most Linux distributions

To run Apgar on Kubernetes instead, see [Kubernetes](https://docs.useapgar.dev/self-hosting/kubernetes.md).

## Run Apgar

**1. Download the Compose file**

```bash theme={null}
mkdir apgar && cd apgar
curl -fsSLO https://github.com/oimo-ai/apgar/releases/latest/download/docker-compose.yml
```

**2. Create the environment file**

Generate the three secrets into `.env`:

```bash theme={null}
cat > .env <<EOF
APGAR_SECRET_KEY=$(openssl rand -hex 32)
APGAR_ADMIN_TOKEN=$(openssl rand -hex 16)
CLICKHOUSE_PASSWORD=$(openssl rand -hex 16)
APGAR_PUBLIC_URL=http://localhost:8080
EOF
```

`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**

```bash theme={null}
docker compose up -d --wait
```

`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](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:

```bash theme={null}
docker compose exec apgar-api apgar demo seed --purge-first
```

Demo agents are marked as demo in the UI and in webhook bodies. Remove them when you are done:

```bash theme={null}
docker compose exec apgar-api apgar demo purge
```

## 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.

```bash theme={null}
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:8080/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer apg_ing_...
OTEL_RESOURCE_ATTRIBUTES=gen_ai.agent.name=my-agent,deployment.environment.name=production,apgar.release=v1.9.0
```

`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](https://docs.useapgar.dev/send-traces/langfuse.md). To receive messages, add a [Slack](https://docs.useapgar.dev/notifications/slack.md) or [webhook](https://docs.useapgar.dev/notifications/webhooks.md) connection. If nothing shows up, see [Troubleshooting](https://docs.useapgar.dev/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.