Installation & Configuration

Architecture Overview

┌─────────────┐          ┌─────────────┐
│    Synth    │◄────────►│    Envoy    │
│  (port 9410)│          │  (port 9411)│
├─────────────┤          ├─────────────┤
│ REST API    │ dispatch │ Executor    │
│ MCP Server  │─────────►│ Health      │
│ Agent       │          │ Scanner     │
│ Debrief     │◄─────────│ Reporter    │
│ Entity DB   │  report  │ Query       │
└──────┬──────┘          └──────┬──────┘
       │                        │
  SQLite DBs             Workspace Dir
  (synth.db,             (deployment
   debrief.db)            artifacts)

Synth is the orchestration server. It stores all entities (partitions, artifacts, environments, deployments) in SQLite, runs the intelligent agent, and exposes both a REST API and an MCP server. The UI is served as static files from the Synth server.

Envoy is a lightweight agent deployed on target machines. It receives deployment instructions from Synth, executes shell commands in isolated workspaces, runs health checks and verification, and reports results back. Envoy maintains its own local state and can run LLM-powered diagnostics when deployments fail.

Communication flows one direction at dispatch time (Synth sends instructions to Envoy) and one direction at report time (Envoy posts results back to Synth). There is no persistent connection between them.

Multi-Envoy Setup

For deploying across multiple machines, install Envoy on each target and point them at your Synth server.

With Docker

# On target machine: run Envoy pointed at your Synth server
docker run -d \
  --name synth-envoy \
  -p 9411:9411 \
  -v envoy-workspace:/workspace \
  -e SYNTH_SERVER_URL=http://server-host:9410 \
  -e ENVOY_PORT=9411 \
  synth-deploy/envoy

With install.sh

# On target machine: install Envoy only
./install.sh --component envoy --server-url http://server-host:9410

Registering Envoys with Synth

After starting an Envoy, configure Synth to dispatch to it by updating the Envoy endpoint in settings:

curl -X PUT http://localhost:9410/api/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"envoy": {"url": "http://envoy-host:9411", "timeoutMs": 10000}}'

Each Envoy identifies itself to Synth using a generated ID based on its host and port (e.g., envoy-0.0.0.0:9411). Envoys report deployment results and debrief entries back to Synth automatically when SYNTH_SERVER_URL is set.

Troubleshooting

Synth server fails to start: "EACCES: permission denied"

The data directory is not writable. Ensure the SYNTH_DATA_DIR path exists and is owned by the user running the Synth server. In Docker, the synth user (UID 1000) must own the mounted volume.

Envoy cannot reach Synth

Verify SYNTH_SERVER_URL is set and reachable from the Envoy host. In Docker Compose, use the service name (http://synth-server:9410). For remote setups, ensure firewalls allow traffic on port 9410.

# From the Envoy host
curl -f http://server-host:9410/health

CORS errors in the browser

Set SYNTH_CORS_ORIGIN to your UI's origin. For development:

SYNTH_CORS_ORIGIN=http://localhost:5173

For production with multiple origins:

SYNTH_CORS_ORIGIN=https://deploy.example.com,https://admin.example.com

Authentication: "401 Unauthorized"

When SYNTH_API_KEY is set, all requests except GET /health require an Authorization: Bearer <key> header. Verify the key matches exactly.

Demo data keeps appearing

The Synth server seeds demo data on first startup if the database is empty. To disable:

SYNTH_SEED_DEMO=false

Agent features not working (intent resolution, diagnostics)

LLM-powered features require SYNTH_LLM_API_KEY to be set. Without it, the agent degrades gracefully: deployments still work, but natural-language intent resolution and diagnostic investigation are disabled. Check the health endpoint for LLM connectivity status:

curl http://localhost:9410/health | jq .checks.llm

High memory usage

Both containers default to 512 MB memory limits. If deployments involve large artifacts or many concurrent operations, increase mem_limit in the compose file. For bare-metal installs, monitor with:

# systemd
systemctl status synth-server
journalctl -u synth-server --since "1 hour ago" | grep -i memory

Envoy workspace filling up disk

Envoy automatically cleans up old deployment workspaces every 10 minutes, keeping the most recent 50 workspaces or those less than 30 days old. If disk usage is still a concern, reduce the workspace retention or mount a larger volume.