Self-Hosting

Deployment Architecture

Syntropic137 runs as a set of Docker services connected through a shared network:

Quick Start with Docker Compose

npx @syntropic137/setup init

The setup wizard handles everything: Docker validation, secret generation, API key configuration, image pulls, and starting the stack. See Getting Started for the full walkthrough.

The dashboard will be available at http://localhost:8137.

Services

Service	Port	Description
`api`	8000	FastAPI backend: REST API, SSE
`gateway`	80	nginx reverse proxy + React dashboard frontend
`event-store`	50051	gRPC event sourcing server
`event-collector`	8080	High-throughput event ingestion
`timescaledb`	5432	PostgreSQL + TimescaleDB for events and metrics
`redis`	6379	Caching, pub/sub, projection store
`minio`	9000	S3-compatible artifact storage

Workspace Isolation

Each agent execution runs in an isolated Docker workspace with a two-phase security model:

Setup Phase: Secrets are available briefly to configure credential helpers. Raw tokens are cleared before the agent starts.

Agent Phase: The agent runs with only ANTHROPIC_API_KEY in its environment. Git operations use cached credentials from the setup phase.

Environment Variables

Variable	Default	Description
`APP_ENVIRONMENT`	`development`	Environment mode (`development`, `production`)
`TIMESCALEDB_HOST`	`localhost`	TimescaleDB hostname
`TIMESCALEDB_PORT`	`5432`	TimescaleDB port
`REDIS_URL`	`redis://localhost:6379`	Redis connection URL
`MINIO_ENDPOINT`	`localhost:9000`	MinIO S3 endpoint
`MINIO_ACCESS_KEY`		MinIO access key
`MINIO_SECRET_KEY`		MinIO secret key
`GITHUB_APP_ID`		GitHub App ID for webhook triggers
`GITHUB_APP_PRIVATE_KEY`		GitHub App private key (PEM)
`ANTHROPIC_API_KEY`		API key for Claude agent execution

Scaling Options

Single Server (Self-Host)

Recommended for 10–100 concurrent agents:

4+ CPU cores, 8GB+ RAM (16GB recommended)
500GB NVMe storage
Docker with workspace pooling (10–50 containers)

Multi-Server

For 100–1,000 concurrent agents, run multiple Syntropic137 instances behind a load balancer:

Kubernetes

For 1,000+ concurrent agents with auto-scaling:

Use Kata Containers runtime for workspace isolation
HPA with 70% CPU target, 3–20 replicas
PersistentVolume for artifact storage

The nginx gateway uses HTTP Basic Auth to protect external access. During npx @syntropic137/setup init, a strong random password (~256 bits of entropy) is generated automatically and stored in ~/.syntropic137/.env.

The setup wizard never prints the password to the terminal. Retrieve it from ~/.syntropic137/.env when needed:

# View password
grep SYN_API_PASSWORD ~/.syntropic137/.env | cut -d= -f2

# Copy to clipboard (macOS)
grep SYN_API_PASSWORD ~/.syntropic137/.env | cut -d= -f2 | pbcopy

# Set env vars for the syn CLI
export SYN_API_USER=admin
export SYN_API_PASSWORD=$(grep SYN_API_PASSWORD ~/.syntropic137/.env | cut -d= -f2)

To rotate credentials (generates a new password and restarts the stack):

npx @syntropic137/setup credentials rotate

Port model

The gateway exposes two ports with different auth policies:

Port	Auth	Used by
80	None	Docker health checks, internal service traffic, local dev (`localhost:8137`)
8081	Basic Auth	Cloudflare Tunnel, any external access

If you use Cloudflare Tunnel, your tunnel config must route to http://gateway:8081 (not localhost:8137). The setup wizard enforces this: npx @syntropic137/setup tunnel will exit with an error if SYN_API_PASSWORD is not set.

See the Tunnels guide for full setup instructions.

Tunnels (Optional)

For secure external access and GitHub Actions webhook delivery, set up a tunnel. Syntropic137 includes built-in Cloudflare Tunnel support via a Docker Compose profile.

See the Tunnels guide for setup instructions.

Secrets

Infrastructure secrets (database, Redis, MinIO) are stored as chmod 600 files and mounted via Docker Compose's secrets mechanism, never baked into image layers. Application-level API keys (e.g. ANTHROPIC_API_KEY) are supplied via environment variables.

See Secrets Management for details on how secrets work and optional 1Password integration.