tapes

tapes serve

Run the proxy, API, and derive worker together to capture LLM conversations and project them into sessions, traces, and spans. Use this when you need explicit control over ports and configuration.

tapes requires PostgreSQL with the pg_duckdb and pgvector extensions. Schema migrations run automatically when the process starts. Use tapes local up to bootstrap a local Postgres + Ollama in Docker.

Usage

# Run proxy, API, and derive worker together
tapes serve --postgres "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable"

# Run just the proxy
tapes serve proxy --postgres "$DSN"

# Run just the API server
tapes serve api --postgres "$DSN"

# Run just the ingest server (sidecar mode)
tapes serve ingest --postgres "$DSN"

# Run the derive worker (raw turns -> sessions/traces/spans)
tapes serve derive-worker --postgres "$DSN"

# Run the embed worker (derived spans -> search vectors)
tapes serve embed-worker --postgres "$DSN"

Flags for tapes serve

Flags for tapes serve proxy

Embedding flags are optional for tapes serve proxy. If omitted, semantic search is disabled. All flags can also be set via TAPES_* environment variables — see environment variables.

Flags for tapes serve api

The API server exposes read endpoints over the derived sessions, traces, and spans plus the /metrics endpoint for Prometheus scraping. See the Inspect reference for the full endpoint list.

Flags for tapes serve ingest

The ingest server accepts completed LLM conversation turns via HTTP and appends them to the raw turn log (the deriver then projects them into sessions, traces, and spans). Use this when an external gateway (e.g., Envoy AI Gateway) handles upstream LLM traffic and tapes only needs to store, embed, and publish data.

Flags for tapes serve derive-worker

The derive worker is a continuous process that reads the raw turn log and projects it into the sessions, traces, and spans the API serves. Run it alongside the proxy/ingest write path so captured turns become queryable. It does not write embeddings — that is the embed worker's job.

Flags for tapes serve embed-worker

The embed worker turns derived spans into search vectors for tapes search and /v1/search/spans. In the all-in-one tapes serve it runs in-process by default (disable with --embed-spans=false); in a split deployment, run it as its own process alongside the derive worker.

Ingest Endpoints

The ingest server exposes the following HTTP endpoints:

Ingest Payload Format

Send conversation turns with a provider-specific request and a reduced, provider-agnostic response. The optional session envelope tags the turn with harness metadata so sessions group correctly across replays.

POST /v1/ingest
Content-Type: application/json

{
  "provider": "openai",
  "agent_name": "my-agent",
  "session": {
    "org_id": "acme",
    "auth_subject": "user@example.com",
    "harness_id": "claude-code",
    "harness_session_id": "8f2c…",
    "harness_version": "1.4.2",
    "cwd": "/home/me/project",
    "name": "refactor auth middleware",
    "parent_harness_session_id": null,
    "harness_metadata": { "branch": "feature/auth" }
  },
  "request": {
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  },
  "response": {
    "model": "gpt-4",
    "message": {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "Hi there!" }
      ]
    },
    "done": true,
    "stop_reason": "stop",
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 5,
      "total_tokens": 15
    }
  }
}

Supported providers: openai, anthropic, ollama. The request uses the provider's native API format; the response uses tapes' reduced, provider-agnostic format. Ingest is idempotent — replaying the same payload is content-addressed to the same raw turn, so it does not double-count.

tapes records total_duration_ns on every response across all providers (Anthropic, OpenAI, Ollama), measured at the proxy or ingest boundary. This duration feeds the duration totals reported by /v1/stats.

Response Format

The response object must use tapes' reduced format, not the raw provider response:

The message.content array contains content blocks, each with a type field. For text responses, use { "type": "text", "text": "..." }.

The reduced format normalizes the wire shape, not the values inside it — stop_reason in particular is whatever the upstream provider returned. See /swagger for the canonical schema, including optional fields like created_at and raw_response.

Metrics

The API and ingest servers expose Prometheus RED (Rate / Errors / Duration) metrics at GET /metrics. Both endpoints are intentionally unauthenticated so an in-cluster Prometheus can scrape them.

API server