# Try with Demo App

Run a full microservices demo, GenAI services included, on Kopai in minutes

Try Kopai with the [OpenTelemetry Astronomy Shop](https://github.com/open-telemetry/opentelemetry-demo), a pre-instrumented microservices demo with 10+ services generating traces, metrics, and logs.

## Prerequisites

- Docker and Docker Compose
- Node.js v22.13.0+ — Kopai stores telemetry through the built-in `node:sqlite` module, which stays behind `--experimental-sqlite` until v22.13.0
- 3–6 GB of free memory, depending on the mode you pick in Step 2

## Step 1: Start Kopai

**npm:**

```bash
npx @kopai/app start
```

**pnpm:**

```bash
pnpm dlx @kopai/app start
```

**yarn:**

```bash
yarn dlx @kopai/app start
```

:::note
On **Linux**, bind to all interfaces so Docker containers can reach Kopai:

**npm:**

```bash
HOST=0.0.0.0 npx @kopai/app start
```

**pnpm:**

```bash
HOST=0.0.0.0 pnpm dlx @kopai/app start
```

**yarn:**

```bash
HOST=0.0.0.0 yarn dlx @kopai/app start
```

:::

## Step 2: Clone & Start the Demo

In a separate terminal:

```bash
git clone https://github.com/kopai-app/opentelemetry-demo.git
cd opentelemetry-demo
make start-kopai
```

Pick the mode that fits your machine:

| Command | Services | Memory |
|---------|----------|--------|
| `make start-kopai` | Core demo + Kafka, accounting, fraud detection | ~4.1 GiB |
| `make start-kopai-minimal` | Core demo only | ~3.1 GiB |
| `make start-kopai-agentic` | Everything above, plus the [GenAI services](#genai-telemetry) | ~5.6 GiB |

All three stop with `make stop-kopai`.

## Step 3: Generate Traffic

Open [http://localhost:8080](http://localhost:8080) and browse the Astronomy Shop — add items to cart, place orders, etc. This generates telemetry across all services.

## Step 4: Query Telemetry

Use the Kopai CLI to explore what's been collected:

**npm:**

```bash
# Recent traces
npx @kopai/cli traces search --limit 5

# Logs from a specific service
npx @kopai/cli logs search --service cart --fields Timestamp,Body --sort ASC

# Discover available metrics
npx @kopai/cli metrics discover
```

**pnpm:**

```bash
# Recent traces
pnpm dlx @kopai/cli traces search --limit 5

# Logs from a specific service
pnpm dlx @kopai/cli logs search --service cart --fields Timestamp,Body --sort ASC

# Discover available metrics
pnpm dlx @kopai/cli metrics discover
```

**yarn:**

```bash
# Recent traces
yarn dlx @kopai/cli traces search --limit 5

# Logs from a specific service
yarn dlx @kopai/cli logs search --service cart --fields Timestamp,Body --sort ASC

# Discover available metrics
yarn dlx @kopai/cli metrics discover
```

## Step 5: Open the Dashboard

View your telemetry visually at [http://localhost:8000](http://localhost:8000).

## Step 6: Ask Your Coding Agent

With the [Kopai skills](/skills) installed, your agent can investigate the demo for you:

```text
Use @kopai/cli to find errors in my services
```

## Step 7: Stop the Demo

```bash
make stop-kopai
```

## GenAI Telemetry

`make start-kopai-agentic` adds the demo's agent, chatbot, and MCP services, so Kopai also receives LLM spans, token usage, and MCP tool calls. Chat with the shop at [http://localhost:8080/chatbot/](http://localhost:8080/chatbot/).

LLM calls replay from recorded cassettes by default — no API key, no cost. Cassettes exist only for the `azure/gpt-5.5` and `claude-opus-4-7` models; point `LLM_MODEL` anywhere else and there's nothing to replay.

For live traffic, set these in `.env.override` — any OpenAI-compatible endpoint works:

```bash
USE_VCR=False
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
API_KEY=<your key>
```

:::caution
`.env.override` is tracked in git. Don't commit a real key.
:::

## How It Works

```
┌────────────────────────────────────────────────┐
│  Docker Compose Network                        │
│                                                │
│  ┌─────────────────────────────┐               │
│  │   Astronomy Shop Demo       │               │
│  │   (10+ microservices)       │               │
│  │                             │               │
│  │   All services instrumented │               │
│  │   with OpenTelemetry        │               │
│  └────────────┬────────────────┘               │
│               │                                │
│               │ OTLP (traces, metrics, logs)   │
│               ▼                                │
│  ┌─────────────────────────────┐               │
│  │   OTel Collector            │               │
│  │   (in Docker)               │               │
│  └────────────┬────────────────┘               │
│               │                                │
│               │ OTLP/HTTP                      │
│               ▼                                │
│       host.docker.internal:4318                │
└───────────────┬────────────────────────────────┘
                │
                ▼
┌────────────────────────────────────┐
│   @kopai/app (on host machine)     │
│                                    │
│   OTel collector: localhost:4318   │
│   Dashboard:      localhost:8000   │
└────────────────────────────────────┘
```

The demo loads a customization file, `otelcol-config-extras.yml`, last in its collector config chain. Kopai mounts its own exporter config over that seam and skips the demo's observability layer entirely, so the only upstream file the fork touches is the `Makefile`.

## Learn More

For details on the collector config, Compose layering, and running Kopai alongside the bundled stack, see the [full README on GitHub](https://github.com/kopai-app/opentelemetry-demo/tree/main/kopai).