Deployment

Hosted (default)

ReasonBlocks operates the capture gateway, durable storage, trace reconstruction, distillation pipeline, and relegation serving for your tenant. What ReasonBlocks runs

Hosted gateway at a tenant-specific URL (copy from app.reasonblocks.com Quickstart)
Capture storage and trace reconstruction
Distillation jobs, training reports, and relegation routing (cheaper model + frontier fallback)
Dashboard views for capture volume, golden-run counts, reports, and serving status

What you configure

Item	Where
Gateway URL	Dashboard → Quickstart → copy into `ANTHROPIC_BASE_URL`
Anthropic API key	Your agent environment (passthrough; never stored by ReasonBlocks)
Integration path	Integrating your agent: gateway only (A), or optional `rbtrace` shim (B/C)
Distillation	Dashboard → start job or schedule; opt-in, tenant-scoped
Relegation serving	Dashboard → enable after training report; cheaper model first, frontier fallback

Your agent process only needs the gateway URL via ANTHROPIC_BASE_URL, your existing API key, and optionally the client shim. No DuckDB files, no local rbtrace proxy, and no SSH access required for the default path. Anthropic Messages is the primary path for training and relegation serving. OpenAI Chat Completions, Responses API, Gemini, and other routes are supported for capture via the same gateway URL with the correct client env var. See Endpoint compatibility. See the Quickstart for the end-to-end hosted flow.

Security and privacy (hosted)

Anthropic API keys pass through the gateway to upstream and are not stored by ReasonBlocks.
Capture data and distillation artifacts stay in your tenant scope on ReasonBlocks infrastructure.
The optional agent shim (~150 lines) only stamps HTTP headers on LLM API paths; it does not replace the hosted gateway.

Integration paths

Where the gateway runs is separate from how you label runs in your agent process. See Integrating your agent for Path A (gateway only), Path B (install()), and Path C (install() + with rbtrace.client.run() per job).

Advanced: self-hosting the gateway

Use this when you must run the capture gateway and storage on your infrastructure. ReasonBlocks can still run distillation in the hosted product if you export traces; or you can run the full pipeline locally with the rbtrace CLI.

Architecture (self-hosted)

Three roles, usually split across processes on your ops hosts:

Gateway: HTTP forwarder and capture writer (python -m rbtrace.proxy)
Storage: append-only DuckDB file on a durable volume
Analysis: read-only CLI (python -m rbtrace inspect|trace|distill|loop) on a schedule or on demand

After local training completes, the same gateway can route with relegation using operator config from the distill output. See Quickstart — Advanced.

Install

pip install rbtrace   # when published to PyPI
# or install from a release artifact / wheel you build from trace-reconstructor

Do not treat git clone + pip install -e . as the default customer path. Reserve editable installs for ReasonBlocks engineers and contributors.

Docker

Use a released container image or your own build from trace-reconstructor. Example shape:

docker compose up -d

Typical defaults in upstream compose examples:

Listens on 8787
Persists to a named volume at /data/capture.duckdb
Health: GET http://<host>:8787/__rbtrace/stats

Point your agent at your host:

export ANTHROPIC_BASE_URL="http://<your-host>:8787"

For agents in Docker, use host.docker.internal on Mac/Windows or the service name on the same compose network.

Extract outputs from the volume

docker compose run --rm rbtrace inspect /data/capture.duckdb

docker compose run --rm rbtrace trace /data/capture.duckdb \
  --format rb_trace_v1 -o /data/traces.jsonl

Use profile tools if your compose file defines distill/loop services for scheduled jobs.

Bare metal

mkdir -p /var/lib/rbtrace
python -m rbtrace.proxy \
  --host 0.0.0.0 \
  --port 8787 \
  --db /var/lib/rbtrace/capture.duckdb \
  --note production

Run under systemd, Kubernetes, or supervisord with restart=always. Mount /var/lib/rbtrace on persistent disk.

Flush before backup

The writer batches inserts. Before snapshotting the DuckDB file:

curl -X POST http://<your-host>:8787/__rbtrace/flush

Long-term capture (self-hosted)

Single DuckDB file grows with traffic. Plan disk by exchange count (roughly tens of KB per exchange compressed, varies with prompt size).
No automatic retention is built in. Rotate by stopping the gateway, archiving capture.duckdb, and starting with a new --db path.
AGENTRECON_NOTE (or --note on the CLI) tags each capture run for slicing later.

Local distillation outputs

python -m rbtrace trace capture.duckdb --format rb_trace_v1 -o traces.jsonl
python -m rbtrace distill capture.duckdb --tenant acme --out distill-acme
python -m rbtrace loop capture.duckdb --tenant acme --out distill-acme --once

Filter to minable runs with provenance.supports_universal_claims: true (shown as golden in CLI summaries). Self-hosted relegation serving after training:

export RBTRACE_DISTILL_DIR=./distill-acme
# Enable relegation routing on the gateway host (see trace-reconstructor operator docs)

Monitoring (self-hosted)

curl http://<your-host>:8787/__rbtrace/stats

Watch writer.queue_depth, writer.dropped, and exchange counts. Non-zero dropped means the writer fell behind. Increase resources or raise AGENTRECON_MAX_QUEUE.

Security and privacy (self-hosted)

You operate the gateway, storage, and analysis CLI on your infrastructure.
API keys flow through the gateway to upstream. They are redacted in stored message text when RBTRACE_REDACT=1 (default).
Keep *.duckdb capture files and distill-*/ artifacts on ops hosts, not in agent images.

What not to deploy to agent containers

Artifact	Notes
`*.duckdb` capture files	Ops infrastructure only
Distillation artifacts	`distill-*/` directories on ops hosts

Agent surface (hosted or self-hosted): gateway URL + optional shim + your existing agent code.

Getting Started

Reference

Hosted (default)

Security and privacy (hosted)

Integration paths

Advanced: self-hosting the gateway

Architecture (self-hosted)

Install

Docker

Extract outputs from the volume

Bare metal

Flush before backup

Long-term capture (self-hosted)

Local distillation outputs

Monitoring (self-hosted)

Security and privacy (self-hosted)

What not to deploy to agent containers

​Hosted (default)

​Security and privacy (hosted)

​Integration paths

​Advanced: self-hosting the gateway

​Architecture (self-hosted)

​Install

​Docker

​Extract outputs from the volume

​Bare metal

​Flush before backup

​Long-term capture (self-hosted)

​Local distillation outputs

​Monitoring (self-hosted)

​Security and privacy (self-hosted)

​What not to deploy to agent containers

Hosted (default)

Security and privacy (hosted)

Integration paths

Advanced: self-hosting the gateway

Architecture (self-hosted)

Install

Docker

Extract outputs from the volume

Bare metal

Flush before backup

Long-term capture (self-hosted)

Local distillation outputs

Monitoring (self-hosted)

Security and privacy (self-hosted)

What not to deploy to agent containers