Introduction

Beachball schedules disposable Firecracker microVMs. A controller requests an allocation through the public API, the scheduler reserves capacity on an eligible host, and the host agent creates and removes the microVM.

Beachball does not define what runs inside an allocation. Workload-specific controllers, such as a CI runner controller, use the allocation API and manage their own workload lifecycle.

Components

Beachball has three runtime roles:

• The TypeScript scheduler exposes the /v1 API and stores authoritative allocation and host state in SQLite-backed Durable Objects.
• bb agent runs on each Firecracker host and manages microVMs.
• bb relay provides optional stateless fallback for encrypted WireGuard packets.

The Rust bb executable also provides unprivileged client and operator commands. The guest bootstrap passes identity, private network configuration, and one-time bootstrap data into each microVM.

The architecture page explains how these roles, the Durable Objects behind the API, and the private network fit together.

To try the complete system from a checkout, run Beachball locally. To connect to an existing deployment, start with installation, then create your first allocation. When the allocation is ready, connect to it over the private network.