Runtime clusters and previews
Reference substrate
The v1 reference runtime cluster uses Kubernetes or a compatible lightweight distribution as an internal implementation detail.
Do not expose Kubernetes concepts to customers.
Node pools:
gateway nodes
runtime sandbox nodes
build sandbox nodes
data-service nodes
observability/management nodes
Runtime agent
Each cluster runs an intrnl runtime agent that:
- Establishes outbound mTLS to the control plane
- Registers cluster identity and capabilities
- Receives desired state
- Acknowledges commands
- Reconciles workloads
- Reports health and capacity
- Streams deployment/build state
- Rotates workload certificates
- Never exposes a public cluster-admin API
No inbound SSH or Kubernetes API access is needed from the central control plane.
Per-app sandbox
V1 uses one sandbox boundary per app environment.
app production
└── OS/VM sandbox
└── workerd process
app preview A
└── OS/VM sandbox
└── workerd process
A production environment may have multiple stateless replicas behind the gateway.
Do not co-locate trusted intrnl services and untrusted application code inside the same sandbox.
Activation model
Use blue/green revision activation:
Current revision A is serving
↓
Fetch revision B and verify signature
↓
Start verified revision B workload
↓
Run health check
↓
Atomically change route pointer A → B
↓
Drain A
↓
Retain A for rollback window
A failed health check leaves revision A active.
Preview environments
A preview consists of:
- Immutable source/build revision
- Temporary app route
- Separate runtime sandbox
- Separate SQLite database
- Separate KV namespace
- Synthetic seed data
- Restricted access policy
- Expiration time
Preview access defaults to:
creator
explicit reviewers
organization administrators
No production app user receives preview access implicitly.
Scale-to-zero
Preview environments may scale to zero after inactivity.
Production apps may eventually scale to zero, but the organization pilot should favor predictable availability over aggressive cost optimization.
Static routing
The gateway keeps a locally cached route table:
hostname
→ organization
→ application
→ environment
→ active artifact revision
→ access policy version
→ runtime workload
The cache is signed/versioned and reconciled with the control plane.
An unknown or stale host never falls through to an arbitrary application.