tapes

tapes serve

Run the proxy, API, and ingest servers to capture LLM conversations. 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 ingest servers 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"

Flags for tapes serve

Flags for tapes serve proxy

Embedding flags are optional for tapes serve proxy. If omitted, semantic search is disabled. Kafka flags enable event streaming — see Kafka Streaming guide. 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 Merkle DAG and 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 stores them in the Merkle DAG. 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.

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": "[email protected]",
    "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 re-hashes to the same DAG node.

tapes records total_duration_ns on every response across all providers (Anthropic, OpenAI, Ollama), measured at the proxy or ingest boundary. This duration powers the per-provider latency aggregates exposed 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