Quickstart

Choose your operator and compute machines#

Use Node.js 22.12 or newer and the repository's pinned pnpm 12.14.0. The root workspace provisions Rust 1.96.0 through pnpm's Cargo integration. Python is not a runtime dependency.

Compute workspaces currently require a prepared Linux Incus/KVM host. A macOS or Windows operator can manage a separate Linux node; installing the controller does not contribute that laptop's CPU or GPU to the fleet. Check platform support before provisioning.

Build the source#

git clone https://github.com/coop-collective/enginebox.git
cd enginebox
pnpm install --frozen-lockfile
pnpm build
target/release/ebox --help

The native binaries are in target/release; the dashboard is built from packages/dashboard. Both Cargo.lock and pnpm-lock.yaml are part of the reproducible workspace.

Release installers are version-pinned. Use an archive only when that exact version and platform have published, qualified assets; the source version alone does not establish availability. See installation details.

Inspect before provisioning#

target/release/ebox init --output enginebox.toml
# Edit the generated host, storage and network configuration.
target/release/ebox doctor --config enginebox.toml
target/release/ebox plan --config enginebox.toml
# Review the plan before applying it.
target/release/ebox apply --config enginebox.toml

Configure the intended Linux host and owned Incus resources. Bootstrap prepares a credential-free base and reports its snapshot. Existing storage pools, unrelated profiles and firewall rules are not permission to overwrite them. Follow the bootstrap guide for host prerequisites and preparation evidence.

Start your controller#

Create a private fleet.toml from the fleet example. Replace the sample host, project, pool and prepared snapshot with your inspected values. Then create an API token and start the controller:

umask 077
mkdir -p "$HOME/.local/state/enginebox"
(set -C; openssl rand -hex 32 > "$HOME/.local/state/enginebox/api.token")
export ENGINEBOX_API_TOKEN_FILE="$HOME/.local/state/enginebox/api.token"
target/release/enginebox-controller --config fleet.toml

The token command refuses to overwrite an existing file. The API listens on 127.0.0.1:8765. Keep the token, controller state and host inventory outside Git. Use an SSH tunnel or your own authenticated HTTPS gateway for remote access.

For a persistent service with the dashboard, follow controller installation; it includes the owner password, stable session secret and supervisor configuration.

Connect an agent and allocate a workspace#

1. Register a template and wait for its revision to be installed on your node.
2. Connect the owner account in the dashboard's Agents panel.
3. Allocate a workspace using Minimum, Recommended or custom resources.
4. Wait for readiness, then use its native terminal or fleet MCP.

A ready VM proves the expected tools and networking are present. A successful provider prompt is a separate check of authentication, subscription eligibility and remaining allowance.