Docs

Get Recondo running in two terminals

Build the gateway, generate a CA, point Claude Code at it. Five minutes from clone to first captured turn.

Prerequisites. Rust (stable), Docker (for the prod-like PG + MiniStack), and optionally just. The README in the repo is the canonical source.

Build & run

# One-time setup (installs cargo-nextest)
just setup

# Build (includes fmt + clippy)
just build

# Start the gateway on :8443
just run

Without just:

cd gateway && cargo build
cd gateway && cargo run -- init    # generate CA + install into trust store
cd gateway && cargo run -- serve

Route Claude Code through the gateway

# Terminal 1
just run

# Terminal 2
NODE_EXTRA_CA_CERTS=$HOME/.recondo/ca/ca.crt \
HTTPS_PROXY=http://localhost:8443 \
claude

Route Codex through the gateway

CODEX_CA_CERTIFICATE=$HOME/.recondo/ca/ca.crt \
HTTPS_PROXY=http://localhost:8443 \
codex

Verify captures

ls ~/.recondo/objects/req/    # gzipped request bodies
ls ~/.recondo/objects/resp/   # gzipped response bodies
ls ~/.recondo/captures/       # JSON metadata linking req/resp hashes

CLI reference

The recondo binary is your inspector. Paths shown here use just recondo …; equivalent cargo run -- … works the same.

just recondo sessions List all captured sessions

just recondo session <id> Turn-by-turn trace for a session

just recondo session <id> --turns Compact turn list (no response text)

just recondo turn <id> Single turn detail — tokens, hashes, tool calls, full text

just recondo search "query" Search turns by content

just recondo stats Aggregate statistics

just recondo verify <id> Re-hash captures and compare against the database

CA certificate management

just recondo init Generate CA + install into system trust store

just recondo ca show Show CA fingerprint, subject, validity

just recondo ca export cert.pem Export CA cert to file

just recondo ca revoke Remove CA from system trust store

Production-like dev stack

PostgreSQL 17 + MiniStack (S3, KMS, IAM) running locally for full prod-fidelity development. Two flows — pick one. Fullstack mode runs everything in Docker (one command, fastest on-ramp). Native mode runs the gateway, API, and dashboard as host processes (best for active development on those components).

Fullstack mode — Docker

Gateway + API + dashboard + PostgreSQL + MiniStack, all in containers via docker-compose.fullstack.yml. Dashboard at http://localhost:3000.

# Terminal 1 — bring up the whole stack
just fullstack

# Terminal 2 — copy the gateway's CA out of the container
# (run once after `just fullstack`, and again after `just fullstack-reset`)
just dev-trust

# Terminal 3 — Claude Code through the gateway
just cl

just fullstackBuild and start gateway + API + dashboard + PG + MiniStack

just dev-trustCopy the running gateway's CA into ~/.recondo/ca/ca.crt — idempotent

just fullstack-no-gwSame minus the gateway (run gateway natively for dev)

just fullstack-downStop containers, preserve volumes

just fullstack-resetStop containers and wipe all data — re-run dev-trust after

just fullstack-logsTail gateway logs from the running stack

Native mode — host processes

First-run prerequisite. Before just cl can talk to the native gateway, your local CA needs to exist and be trusted by the system. Run just dev-trust-local once — it's self-healing (no-op when valid, regenerates only when missing or out of sync). If you ever hit CERT_SIGNATURE_FAILURE, run it again.

# Terminal 0 — one-time CA setup
just dev-trust-local

# Terminal 1 — infra + migrations
just dev-setup

# Terminal 2 — gateway with PG + local objects
just dev-run-local

# Terminal 3 — TypeScript GraphQL API
just api-dev

# Terminal 4 — React dashboard on :5173 (Vite hot-reload)
just dashboard-dev

# Terminal 5 — Claude Code through the gateway
just cl

just dev-trust-localVerify the native-gateway CA, regenerate only if missing or mismatched

just dev-trust-resetForce-rotate the CA — destructive, requires gateway stopped

just dev-setupStart dev-infra + run all migrations

just dev-infraMiniStack (:4566) + PostgreSQL 17 (:5432)

just dev-infra-downStop containers (data preserved in volumes)

just dev-infra-resetStop containers and delete data volumes

just api-migrateRun all PostgreSQL migrations

just api-migrate-downRoll back the last applied migration

just dev-runGateway with PG + S3 (full prod-like)

just dev-traceSame as dev-run with live req/resp tracing

just cl / just gemini / just codexLaunch each agent through the gateway

just tf-plan / just tf-applyTerraform against MiniStack

Environment variables

Variable Default Description

RECONDO_STORE sqlite Storage backend: sqlite or postgres

RECONDO_DB_URL — PostgreSQL connection string

RECONDO_OBJECTS local Object store: local or s3

RECONDO_S3_BUCKET — S3 bucket name for object storage

RECONDO_DATA_DIR ~/.recondo Override the gateway's local data directory

RECONDO_EXTRA_CA_CERTS — Path to extra CA certs (corporate firewalls)

AWS_ENDPOINT_URL — S3-compatible endpoint override (LocalStack, MinIO)

Corporate TLS inspection

If your corporate network re-signs TLS:

# Option A — auto-discovery (recommended, do once)
cp /path/to/corporate/CA.pem ~/.recondo/ca/extra_roots.pem

# Option B — env var (per-session)
RECONDO_EXTRA_CA_CERTS=/path/to/corporate/CA.pem just run

The gateway logs Loaded extra CA certificates for upstream TLS on startup when detected.

Testing

# 1,530 tests, no Docker required
just test

# 1,574 tests including PG + S3 testcontainers
just test-all

Both recipes run fmt + clippy + lint-arch first, so they're full pre-merge gates, not bare nextest invocations. just ci and just ci-all are aliases.

Want more?

The repo's README and docs/ directory carry the full design and reference documentation. Open an issue for anything missing.

Open the repo File an issue