Architecture

Synodes is a distributed platform with a central control plane and regional runner nodes. Understanding how these components fit together helps you build reliable, efficient AI agent infrastructure.

System Overview

The platform has three primary layers:

1. Control Plane — the central API server that handles authentication, scheduling, and resource orchestration
2. Regional Runners — Kubernetes-based clusters deployed in multiple cloud regions that host sandbox workloads
3. Providers — cloud-specific implementations that manage the lifecycle of underlying compute resources

Control Plane

The control plane is the brain of Synodes. It exposes the REST API and gRPC endpoints that the CLI, SDKs, and integrations talk to. It handles:

• Authentication & authorization — API key validation, organization membership, role-based access
• Scheduling — routing sandbox requests to the nearest healthy runner region
• Metering & billing — tracking sandbox-minutes, database usage, and network egress
• Database provisioning — auto-creating Turso databases when sandboxes request them

Runners & Regions

Runners are the workers that actually host sandbox containers. Each region is a Kubernetes cluster deployed via the synodes-region Helm chart. A region includes:

• Proxy — routes API traffic to the correct runner pod
• Runner DaemonSet — one pod per node, managing sandbox containers
• SSH Gateway — handles synodes ssh connections with automatic routing
• Snapshot Manager — creates and restores sandbox snapshots to persistent storage

Supported regions: us (United States), eu (European Union), with additional regions configurable via the Helm chart.

Sandbox Lifecycle

Every sandbox follows a predictable state machine:

1. Created — the control plane provisions a container on a runner with the requested resources and base image
2. Starting — the container boots, environment variables are injected, and any volumes are mounted
3. Running — the sandbox is ready; you can execute commands, SSH in, or run code via the SDK
4. Stopping — triggered by auto-stop timer or manual synodes stop; the container is paused
5. Stopped — the container state is preserved to disk; can be restarted with synodes start
6. Deleted — the container and all associated resources (auto-provisioned databases, temporary storage) are destroyed

Ephemeral sandboxes skip the Stopped state — they are deleted immediately when stopped.

Network Isolation

Each sandbox runs with:

• Process isolation — each sandbox is a separate container with its own PID namespace
• File system isolation — writable layers are per-sandbox; volumes provide shared persistent storage
• Network isolation — sandboxes have private network interfaces; you can configure allow-lists for outbound CIDR ranges or block all network access entirely

# Block all outbound network
synodes create --network-block-all

# Allow specific CIDR ranges
synodes create --network-allow-list "10.0.0.0/8,172.16.0.0/12"

Cloud Providers

Synodes supports multiple cloud backends through its provider interface. Each provider handles VM/container lifecycle management for its specific cloud:

This means you can deploy Synodes regions on your own infrastructure or use the hosted platform at app.synodes.io.

Integration Points

Synodes plugs into the AI ecosystem through multiple integration packages:

• n8n — automate sandbox workflows in no-code pipelines
• Google ADK — use Synodes as the execution backend for Google Agent Development Kit
• LangChain — data analysis agents that run code inside Synodes sandboxes
• OpenCode — open-source coding agent with Synodes execution
• MCP Server — expose Synodes as a tool to MCP-compatible AI clients