Install the node

One command as root turns a clean Ubuntu server into your node. Give it the token from your detachbox contact and the empty disk for the pool:

curl -fsSL https://api.detachbox.com/api/v1/node-host/install \
  | sudo bash -s -- <token> --disk /dev/sdb

It takes 30 to 60 minutes, most of them spent building OpenZFS and the first base image. It ends with "The node … is live", and your account's terminals open at https://my.detachbox.com.

On a server other people log in to, leave the token out: every local user can see a command line while the install runs. Without it, the command asks for the token on your terminal as detachbox enrollment token: and does not show what you type.

curl -fsSL https://api.detachbox.com/api/v1/node-host/install \
  | sudo bash -s -- --disk /dev/sdb

What the command takes

A rerun without --private-network keeps the networks the earlier run was given. Once the node has enrolled, change them with private-networks, not with the install command.

The checks come first

The command opens with a table of checks: the system, root, systemd, the root filesystem, other containers or tunnels on the server, CPU and RAM, the disk, the private networks, the clock, Secure Boot and the kernel headers when ZFS has to be built, DNS, every outbound destination, TLS and the token. Each line reads ✓ or ✗, and under each ✗ is the fix. Nothing on the server changes until every line is ✓.

To see the table before the day you install, put --check after the token:

curl -fsSL https://api.detachbox.com/api/v1/node-host/install \
  | sudo bash -s -- <token> --check --disk /dev/sdb

It runs the checks alone and ends with Nothing on this machine changed and the token is not spent: the same command without --check installs the node. The node-host it downloaded and verified stays on the server for that next run, as after every run.

The eight steps

1. Packages: the newest Incus from Zabbly's stable repository (7.6 or later) and the newest cloudflared from Cloudflare, from their own apt repositories, with their signing keys built into the installer. The install holds both (apt-mark hold): a restart of either cuts the open connections to the node for a few seconds, so they move only at a moment you pick, or on a day no terminal runs.
2. OpenZFS 2.4.4 and the ZFS cache limit. The installer builds OpenZFS from the official release, its SHA-256 pinned and its signature checked with the OpenZFS release key, into packages with a DKMS module, so every kernel with headers gets it. It swaps Ubuntu's module for the new one without a reboot.
3. The ZFS pool boxes on your disk.
4. Incus: its storage, two bridges (one for the terminals, one for the node's edge), their firewall rules, the projects, and Incus's own API on the edge's bridge only.
5. The first base image: Ubuntu with Docker, Claude Code, Codex and OpenCode, 10 to 20 minutes. The node rebuilds it every 6 hours.
6. Enrollment with api.detachbox.com: the node gets its name, its keys, its Cloudflare Tunnel and its own domain under detachbox.dev; node-host gets its config and units.
7. cloudflared and node-host start.
8. The server's bring-up: detachbox reaches node-host through the tunnel, starts the edge (the terminal gateway and the preview proxy), runs a smoke test and sets up your account's Compute. The command prints each stage as the server reaches it.

Each step prints the part it is at, such as the configure, compile and packaging of the OpenZFS build. While a long part runs, a line comes every 30 seconds.

A rerun picks up where it stopped

If anything stops the install, such as a blocked host, a dropped connection or a reboot, run the same command again. It continues from the step that stopped, and work that finished is not done twice. The node-host it downloaded and verified stays on the server, root's only, until the install puts it in place. A token downloads node-host three times, then once every 30 minutes; the command says how long to wait.

• When the remote shell you started it from drops, the install stops where it is. Started without a terminal, from a script or a tool with a time limit, it keeps running. On a shaky connection, run it inside tmux.
• Ctrl-C, or sudo kill <pid> from another session, stops a run within seconds, together with everything its step started.
• One run at a time. Start the command while a run is at work and it changes nothing: it says since when that run has been working, its process, and how to follow it.
• A rerun goes on the same disk. To start over on another disk, uninstall first.

When a step fails

The command prints what failed, why, and the command or change that fixes it, with the last 30 lines of the failing command. The failure goes to detachbox with your token, so your detachbox contact sees it too. Fix it and run the same command again. Node troubleshooting covers the usual ones.

The log

/var/lib/detachbox-node/install/install.log holds every run whole: the line that names its start and release, every line of every command it ran, and how it ended. If you lost the session, the log says how the run ended. To follow a run from another session:

sudo tail -f /var/lib/detachbox-node/install/install.log

What runs on the server

What lands where