Basic usage

This guide creates an allocation, reads its state, and releases it. You need the HTTPS endpoint and a client credential from your Beachball deployment administrator.

Configure a client profile

Create the configuration directory and copy your issued credential into it:

install -d -m 0700 "$HOME/.config/beachball"
install -m 0600 /path/to/issued-client.token \
  "$HOME/.config/beachball/client.token"

Create $HOME/.config/beachball/config.toml with your scheduler endpoint:

default_profile = "production"

[profiles.production]
endpoint = "https://beachball.example.com"
audience = "client"
credential_file = "client.token"

Replace https://beachball.example.com with the endpoint from your administrator. Relative credential paths start from the directory that contains config.toml.

Beachball accepts cleartext HTTP only for loopback addresses. On Unix, the credential must be a regular file that you own with mode 0600 or stricter.

Create an allocation

Request an allocation and wait until it is ready:

bb allocation create \
  --class ephemeral-linux-x64-medium \
  --max-lifetime 30m \
  --wait ready

The command prints the allocation ID and its current state. The deployment defines the available workload classes, regions, and host labels.

Read the allocation

Use the allocation ID from the create response:

bb allocation get ALLOCATION_ID

To follow state changes as newline-delimited JSON, run:

bb allocation events ALLOCATION_ID --follow --output jsonl

Press Ctrl+C to stop following events. This stops the client command but does not release the allocation.

Release the allocation

Release the allocation when the workload finishes:

bb allocation release ALLOCATION_ID --wait

The --wait option keeps the command open until the scheduler records a terminal allocation state. The host returns the capacity only after its agent confirms cleanup.

Run bb --help for all resources. Run bb allocation --help or bb allocation create --help for command-specific options.