Skip to content

Core infra

Status: Current | Last reviewed: 2026-06-24

The non-media services every TrueServe deploy needs: a database, a cache, an object store, and (in some configs) a message broker and a graph store.

In-cluster images

The in-cluster (Vanguard, self-hosted) images and ports:

Service Image Default port Compose file
postgres supabase/postgres:15.8.1 5432 docker-compose.infra.yml
pgbouncer bitnami/pgbouncer 6432 not in dev (cluster only)
redis redis:7-alpine 6379 infra
neo4j neo4j:5.24 7687 (bolt), 7474 (HTTP) infra
rabbitmq rabbitmq:3-management-alpine 5672 (AMQP), 15672 (mgmt) not in dev (cluster only)
minio quay.io/minio/minio:RELEASE.2025-06-13 9000 (API), 9001 (console) infra
pgadmin dpage/pgadmin4 5050 infra (dev convenience)

Note: Vanguard does not run rabbitmq or pgbouncer. async-agent uses an in-process queue locally. Cluster deploys add both.

Who connects to what

Service Used by Connection env var
postgres every Python and TS service that reads agents/conversations/etc. DATABASE_URL, default postgresql://tsf_app:tsf_dev_pass@trueserve-postgres:5432/trusrv_agents
pgbouncer (AWS only) pgbouncer is in front; apps still see DATABASE_URL pointed at it apps unchanged
redis conversation-api, surface-app, studio-api, collab-gateway (DB 4 specifically) REDIS_URL for most, COLLAB_REDIS_URL for collab
neo4j knowledge-engine NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD
rabbitmq (cluster) async-agent, event-publisher RABBITMQ_URL
object storage (S3 / S3-compatible) conversation-api (recordings and archive bundles), catalog-builder (catalog artifacts), knowledge-engine (uploads) STORAGE_BUCKET_*, STORAGE_REGION, STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, optional STORAGE_ACCESS_KEY/STORAGE_SECRET_KEY — see object-storage.md

What lives where

postgres

The system of record for everything in tables.md. Replicates to nothing in Vanguard; cluster deploys may use managed read replicas (RDS / Cloud SQL) for analytics workloads. The schema is enforced by deploy/init-scripts/ — see schema overview.

The default credentials in Vanguard are intentionally weak (tsf_app:tsf_dev_pass). Cluster deploys must override via secrets.

redis

Short-lived state and pubsub:

  • Session caches (mcp:el_mapping:* for CES sessions, surface:* for browser sessions).
  • Locks (workflow run mutual exclusion).
  • Pubsub (collab:fanout channel for collab-gateway replicas).
  • DB 4 specifically belongs to collab-gateway (see collab-gateway service doc). Other DBs are app-shared.

Note: clearing a Redis DB also clears MCP session mappings. Stale entries sometimes need a manual purge: see troubleshooting voice.

neo4j

The knowledge graph. knowledge-engine writes assertions in batches; multi-hop traversal queries (/api/knowledge/graph) read from it. Postgres holds the durable assertion log; Neo4j is rebuildable from it.

In cluster, Neo4j Aura is the recommended backend. Bolt-protocol-compatible, hosted by Neo4j.

rabbitmq

The async work queue. async-agent consumes; everything that triggers a workflow publishes (conversation-api on lifecycle events, ingest Lambdas on inbound webhooks).

minio (or S3-compatible storage)

Three categories of object:

  1. Conversation recordings — conversation_recordings.storage_path points at a path in the hot bucket.
  2. Catalog artifacts — published A2UI catalogs and their source archives (catalog-builder).
  3. Knowledge uploads — raw documents before ingestion.
  4. Conversation archive bundles — conversation_archive_items.archive_uri points at manifest.json; sibling objects include conversation.json, transcript.jsonl, events.jsonl, and archived recordings.

In Vanguard, MinIO runs locally and the data lives in a Docker volume. In cluster, it is replaced by the cloud's object store (see cloud-managed-swap.md).

Every service uses the shared storage seam (AWS SDKs) against S3-compatible endpoints. Archive sinks can reference tenant integrations for destination credentials, so MinIO, AWS S3, and GCS S3 interoperability all use the same adapter shape — see object-storage.md.

How to talk to each one in Vanguard

# postgres
psql "$DATABASE_URL"
docker exec -it tsf-local-postgres psql -U postgres trusrv_agents

# redis
redis-cli -u "$REDIS_URL"
docker exec -it tsf-local-redis redis-cli

# neo4j
docker exec -it tsf-local-neo4j cypher-shell -u neo4j -p "$NEO4J_PASSWORD"

# object storage — dev points at real S3 (agent-studio-local-* buckets)
aws s3 ls s3://agent-studio-local-recordings/ --region "$STORAGE_REGION"
# the tsf-local-minio container is CI-only (conformance suite); poke it with:
aws --endpoint-url http://localhost:9000 s3 ls

Resetting

# Wipe and reinit local DB
bash .devcontainer/db-init-local.sh

# Restart redis (loses state)
docker restart tsf-local-redis

# MinIO — delete the volume, then bring back up
docker compose -f .devcontainer/docker-compose.infra.yml stop minio
docker volume rm trueserve-framework_minio-data
docker compose -f .devcontainer/docker-compose.infra.yml up -d minio

See also