Install

One-click install

The one-click installer is expected to handle all scenarios automatically when the network is available. If you encounter any issues, please contact Github Issues for help.

The installer supports quick installation or trial on Linux/Mac machines. Please ensure Docker or KVM is available on the system beforehand.

curl -fsSL https://onlybox.es/install.sh | bash

What the installer does

Checks Linux/Mac, Docker, Docker Compose v2, and systemd.
Downloads a compose template and renders initial credentials.
Starts the control node with docker compose up -d.
Creates a normal worker.
Downloads the matching worker release binary based on the available runtime (Docker or boxlite) and architecture.
Generates and enables a systemd service for the worker.
Polls until the worker comes online.

Supported flags

Flag	Default	Description
`--tag`	latest published release	Optional release override, only recommended for advanced use cases
`--workdir`	`$PWD/onlyboxes`	Working directory
`--yes` / `-y`	`false`	Non-interactive mode
`--console-http-port`	`8089`	Console HTTP port on the host
`--console-grpc-port`	`50051`	Console gRPC port on the host
`--console-start`	`auto`	Console startup mode
`--worker-runtime`	`auto`	Worker runtime selection (`docker` / `boxlite` / `auto`)
`--worker-start`	`auto`	Worker startup mode

Common examples

Forward arguments to the installer with bash -s --.

Pin a specific release (the dropdown is populated live from GitHub tags):

Versionloading…

curl -fsSL https://onlybox.es/install.sh | bash -s -- --tag 0.14.0

Unattended install into a custom directory:

curl -fsSL https://onlybox.es/install.sh | bash -s -- \
  --yes \
  --workdir /opt/onlyboxes

Custom console ports:

curl -fsSL https://onlybox.es/install.sh | bash -s -- \
  --console-http-port 18089 \
  --console-grpc-port 50052

Force the boxlite runtime (hosts without Docker):

curl -fsSL https://onlybox.es/install.sh | bash -s -- --worker-runtime boxlite

Requirements

Linux/Mac
Python 3 (the installer itself is written in Python)

What's next

Quick Start — end-to-end walkthrough from the control node to Claude Code
Console Config — all environment variables for the control node

Manual install

OnlyBoxes allows you to manually deploy and control all components and nodes, but for non-experts this can be somewhat involved — especially given the additional requirements of different worker implementations.

We do not want to provide you with a low-quality LLM-generated document that has not been reviewed by a human, so we still need some time to write the relevant content.

Until this section is completed, we recommend reading the installer implementation directly, and having an LLM Agent with access to the code repository assist you with manual installation.