Self-hosting
Worker capacity tuning
Size worker concurrency and sandbox resources for self-hosted deployments.
Worker capacity controls how many coding-agent jobs and sandboxed previews can run at once. Tune it from actual host resources, repository workload, expected session concurrency, and the isolation model operators should be able to rely on.
Key controls
WORKER_PROCESS_COUNTintegerNumber of in-process worker loops that can claim jobs.
WORKER_MAX_ACTIVE_SANDBOXESintegerMaximum live sandboxes on the host. Use explicit values for mixed fleets.
SANDBOX_CPU_LIMITstringCPU limit applied to sandbox containers.
SANDBOX_MEMORY_LIMIT_MBintegerMemory limit in megabytes for each sandbox.
SANDBOX_DISK_LIMIT_GBintegerDisk cap for each sandbox workspace.
Tuning approach
Start with one worker process and one active sandbox per small host.
Measure CPU, memory, disk, and preview startup latency.
Raise process count only when workers spend time idle while capacity remains available.
Set explicit active sandbox caps on larger or heterogeneous worker hosts.
Warning signs
- Preview startup frequently times out.
- Docker disk usage grows without cleanup.
- Jobs sit claimed but make no progress.
- Host memory pressure causes sandbox crashes.
Scale horizontally when isolation and predictability matter more than squeezing one large host.