Architecture
OnlyBoxes uses a control-plane and execution-plane split.
Control node
The control node is the console, which exposes:
- Dashboard UI
- Dashboard implementation (OpenAPI + business logic)
- MCP endpoint
It is primarily responsible for worker registration and account-related state management.
Worker nodes
Workers are responsible for the actual execution environment. A worker connects to the control node over gRPC, reports health, and receives execution requests through the control plane.
Why the split matters
- You can keep authentication and administration centralized.
- You can scale execution independently from the console.
- Different worker implementations can coexist in the same deployment model.
Supported worker styles
| Worker | Backing implementation | Execution environment | Recommended use |
|---|---|---|---|
worker-docker | runc | Docker containers | General sandboxed code execution |
worker-boxlite | KVM | boxlite | Specialized runtime backend |
worker-bridge-e2b | E2B | Remote E2B sandboxes | Managed remote sandbox execution |
worker-sys | - | Host OS processes | Real-device or direct host control |
Deployment pattern
The common pattern is:
- Put the control node behind a reverse proxy or gateway.
- Expose dashboard HTTP and worker gRPC through TLS-terminated infrastructure.
- Run workers on separate machines that can reach the control node, and ensure the machines have sufficient resources.