import { TagSelector } from '../../features/docs/TagSelector'

export const meta = {
  title: 'Install',
  description: 'One-click installation path for Linux/Mac.',
  section: 'Getting Started',
  order: 30,
  slug: 'install',
}

# 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](https://github.com/coooolfan/onlyboxes/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.

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

### What the installer does

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

### Supported flags

| Flag | Default | Description |
| --- | --- | --- |
| `--tag` | `0.6.1` | 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):

<TagSelector locale="en" />

Unattended install into a custom directory:

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

Custom console ports:

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

Force the boxlite runtime (hosts without Docker):

```bash
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](/en/docs/quick-start) — end-to-end walkthrough from the control node to Claude Code
- [Console Config](/en/docs/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](https://github.com/coooolfan/onlyboxes/blob/main/scripts/install.py) directly, and having an LLM Agent with access to the [code repository](https://github.com/coooolfan/onlyboxes) assist you with manual installation.
