# docs / 01

Getting started

This page takes you from nothing to a running system. It should take about five minutes.

#What you need

You also need an RPC endpoint for Solana. More about that below.

Optional: the xz tool. With it, large systems unpack several times faster.

#Install

Linux, macOS and WSL:

curl -fsSL https://raw.githubusercontent.com/bettercallfolio/chainboot/main/install.sh | sh

Windows, in PowerShell:

irm https://raw.githubusercontent.com/bettercallfolio/chainboot/main/install.ps1 | iex

What the installer does:

1. It looks for Node.js 22.15 or newer. If you do not have it, it downloads the official Node.js build from nodejs.org, checks its SHA-256 against a value written into the installer, and keeps it in a private folder. Your system is not changed.
2. It downloads chainboot (one program file of under 500 kB and a small web page) and checks its SHA-256.
3. It creates the chainboot command in ~/.local/bin (on Windows: in %LOCALAPPDATA%\chainboot\bin, added to your PATH).

Nothing needs administrator rights. Run the installer again to update. To remove chainboot:

# Linux and macOS (the same script you installed with)
curl -fsSL https://raw.githubusercontent.com/bettercallfolio/chainboot/main/install.sh | sh -s -- --uninstall            # keep machines and settings
curl -fsSL https://raw.githubusercontent.com/bettercallfolio/chainboot/main/install.sh | sh -s -- --uninstall --purge    # delete everything

# Windows
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/bettercallfolio/chainboot/main/install.ps1))) -Uninstall
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/bettercallfolio/chainboot/main/install.ps1))) -Uninstall -Purge

On Windows and macOS, remove the Linux environment and the machines in it first, if you want them gone: chainboot engine reset.

If the installer says ~/.local/bin is not on your PATH, add the line it prints to your shell profile and open a new terminal.

#Add an RPC endpoint

Solana is a network of computers. Programs do not talk to "the network" directly; they talk to one computer of the network that answers questions over the internet. That computer is called an RPC endpoint, and its address looks like a web address.

chainboot does not come with an endpoint. You bring your own, for two reasons: nobody can switch off "the chainboot server", because there is none, and you decide whom you ask.

Where to get one (all have a free plan):

• Helius: https://www.helius.dev
• QuickNode: https://www.quicknode.com
• Alchemy: https://www.alchemy.com
• Triton: https://triton.one
• Ankr: https://www.ankr.com

Create an account, create an endpoint for Solana devnet, copy its URL, and add it:

chainboot rpc add https://devnet.helius-rpc.com/?api-key=YOUR-KEY

chainboot checks that the endpoint answers and that it really is a devnet endpoint.

There is also a public endpoint that needs no account: https://api.devnet.solana.com. It works, but it is strictly rate-limited. Downloading Ubuntu through it alone takes minutes instead of seconds.

Add several endpoints if you can. chainboot spreads its requests over all of them, learns how fast each one may be used, moves work away from one that is slow or failing, and asks a second endpoint when the first takes too long. One endpoint is enough; three make it smooth.

chainboot rpc list        # API keys are never shown
chainboot rpc test        # which ones answer
chainboot rpc remove 2    # remove number 2 of the list

The endpoints are stored in ~/.chainboot/config.json, readable only by you. Instead of saving them you can set the environment variable CHAINBOOT_RPC to a comma-separated list.

#Run your first system

chainboot list

image             tag      arch   download  on disk  description
alpine            latest   amd64  2.89 MB   8.43 MB  Alpine Linux 3.24, minimal root file system
solinux          latest   amd64  114 MB    504 MB   Ubuntu 26.04.1 LTS server system: SSH, sudo, git, editors and the standard tools
solinux-minimal  latest   amd64  21.8 MB   90.2 MB  Ubuntu 26.04.1 LTS, minimal base system

This list is itself read from the chain. Now run one:

chainboot run solinux

What happens:

1. chainboot finds the newest solinux in the publisher's catalog on chain.
2. It downloads the system and checks every file against its SHA-256.
3. It unpacks the system once and creates a machine: the system plus a place for everything you will change.
4. It opens a shell inside the machine. On some Linux computers this step asks for your password (sudo), because mounting a file system is normally something only the administrator may do. chainboot engine shows which way your computer uses, and chainboot engine rootless sets it up to work without the password.

You are now root in a real Ubuntu. apt update, apt install, edit files, use the network. Type exit to leave. Run the same command again and you are back in the same machine, with everything you did, in a fraction of a second.

chainboot run solinux -- apt-get update     # run one command and return
chainboot run solinux --name test           # a second, separate machine from the same image
chainboot machines                           # list your machines
chainboot rm test                            # delete one

#Prefer a window?

chainboot ui

A page opens in your browser. It is served by chainboot on your own computer (127.0.0.1) and can only be reached from it. What the page does, section by section:

Opening a machine needs a terminal: the page opens one for you where it can, and otherwise shows the command to type. On Windows and macOS the page runs inside the engine, so for actions that write a file on your computer (a disk, an archive) it shows the command instead.

#Platform notes

Linux. Machines run directly on your kernel. This is the fastest and simplest case.

Windows. chainboot creates a small WSL 2 distribution named chainboot and runs your machines inside it. The first run downloads the Ubuntu base archive from Canonical (35 MB) and Node.js for Linux (about 50 MB), both checked against pinned SHA-256 values. After that, commands are passed through automatically; you keep typing chainboot ... in PowerShell or Windows Terminal.

macOS. The same idea with a container: chainboot creates one named chainboot in OrbStack, Docker Desktop or Podman, or a Lima virtual machine if you use Lima. Your machines live inside it.

Files stay on your side: chainboot export and chainboot disk make their file inside that environment and copy it to the place you named on your computer, and commands that read a file (publish, anything with --keypair) run on your computer. Settings changed on either side, by a command or by the web interface, are kept the same on both.

On Windows and macOS, chainboot engine shows where machines run, and chainboot engine reset removes that environment with all machines in it (saves on chain are not affected). On Linux, chainboot engine shows whether machines run with or without administrator rights.

#Where things are

Settings that chainboot takes from the environment:

chainboot version shows which version is installed.

Edit this page on GitHub