Installation

Beachball publishes x86-64 .deb and .rpm packages. A package contains bb, Firecracker 1.17.0, its matching jailer, the guest binary, and separate systemd units for the host agent and the packet relay.

Verify the package

Download the package and these files from the same release:

• beachball-host-VERSION.packages.sha256
• beachball-host-VERSION.packages.sha256.sig
• beachball-host-VERSION.packages.pub.pem

Pin the public key through a separate trusted channel. Then verify the signature and checksums:

openssl pkeyutl -verify -rawin -pubin \
  -inkey beachball-host-VERSION.packages.pub.pem \
  -in beachball-host-VERSION.packages.sha256 \
  -sigfile beachball-host-VERSION.packages.sha256.sig
sha256sum -c beachball-host-VERSION.packages.sha256

Install the package

On Debian or Ubuntu:

sudo apt install ./beachball-host_VERSION_amd64.deb

On an RPM-based distribution:

sudo dnf install ./beachball-host-VERSION-1.x86_64.rpm

Installation creates the beachball service account and private host directories. It does not enroll or start a role.

Configure private networking

Choose one stable RFC 4193 ULA /48. Configure the scheduler with the connection-signing key, its verification keys, connection-grant lifetime, and optional packet relays. Start from production-manifest.example.json.

The signing secret contains a private Ed25519 JWK. The manifest contains only the matching public JWK. Store the private JWK through the manifest's secret provider.

If relay fallback is required, configure at least one healthy relay with public QUIC and WebSocket endpoints. A direct-capable deployment can leave relay fallback optional.

Enable private ingress in each reachable workload class:

{
  "allowedNetworks": ["*"],
  "privateIngress": true
}

Set up the host

Create a host-bound one-use enrollment token and deliver it through your secret system. Then run setup:

sudo bb agent --config /etc/beachball/agent.toml setup \
  --host-id host-fra1-02 \
  --scheduler-url https://scheduler.example \
  --region fra1 \
  --cpu-millis 8000 \
  --memory-mib 16384 \
  --ephemeral-disk-mib 100000 \
  --max-placements 4 \
  --image-manifest-base-url https://images.example/manifests \
  --image-trusted-public-key BASE64_ED25519_PUBLIC_KEY \
  --guest-uplink-interface eth0 \
  --deployment-ula-prefix fd12:3456:789a::/48 \
  --blocked-management-cidr 10.0.0.0/8 \
  --guest-dns-server 1.1.1.1 \
  --connectivity-listen-endpoint 0.0.0.0:51820 \
  --candidate-discovery-endpoint stun.example.net:3478 \
  --connection-verification-key connection-signing-2026-01=BASE64URL_ED25519_PUBLIC_KEY \
  --enrollment-token-file /run/secrets/host-enrollment.token

Allow inbound UDP on the connectivity port when the host has a reachable endpoint. The agent keeps its WireGuard private key under its protected state root. The scheduler receives only the public key and short-lived candidates.

Check and start the agent:

sudo bb agent --config /etc/beachball/agent.toml doctor
sudo systemctl enable --now beachball-agent.service
sudo systemctl status beachball-agent.service

Set up a packet relay

The relay needs a public TLS identity and no scheduler or host credential. Copy relay.example.toml to /etc/beachball/relay.toml, install the certificate and private key named by that file, and restrict the files to the service account. Put the base64url-encoded SHA-256 digest of the leaf certificate DER in the deployment manifest's verificationKey; clients validate both the public certificate chain and this authenticated pin for QUIC and WebSocket connections. Permit public TCP and UDP port 443. Permit the scheduler to reach the TLS health listener on port 9443, but restrict that port at the network boundary.

Allow inbound QUIC on the configured UDP port and WebSocket over TLS on the configured TCP port. Then start the service:

sudo systemctl enable --now beachball-relay.service
sudo systemctl status beachball-relay.service

Relay mode does not open /dev/kvm, create an interface, add a route, or modify nftables. It verifies short-lived signed relay tokens and forwards framed WireGuard ciphertext without durable packet or connection state.

Add the relay's public endpoints and capacity to the scheduler manifest. If policy requires relay fallback, authenticated readiness fails until a configured relay is usable.

Clients can now connect to a private VM.