Install Bitsmith

One binary, two roles. The bitsmith installer sets up whichever role the machine needs:

• The box is the server. You install it on a Linux machine or an Apple Silicon Mac. It becomes the native service that holds your VMs, apps, and storage and serves the web interface. The installer adds the packages it relies on (Docker, Samba, ZFS) and starts the service.
• The CLI is the client. You install it on a laptop, desktop, or build box to drive a box you already run, or to hand an agent the tool surface. It runs as your normal user and never sets up a box.

The installer picks the role from how you run it. Run it as root on Linux and you get the box. Run it as an ordinary user, or on macOS or Windows, and you get the CLI. Pass --box or --cli to choose for it, for example --box to make a Mac the box.

If you only need the client on a laptop or a build box, install the CLI and skip the box sections.

Install the box

Requirements:

• A 64-bit machine running Ubuntu 22.04+ (amd64 or arm64). A Raspberry Pi works if it’s running Ubuntu for ARM, not Raspberry Pi OS.
• An amd64 or arm64 processor.
• Root access (the installer runs with sudo).
• One or more drives for storage, separate from the disk the OS runs on.

Run the installer as root:

curl -fsSL https://downloads.bitsmith.app/install.sh | sudo bash

If you prefer wget:

wget -qO- https://downloads.bitsmith.app/install.sh | sudo bash

The installer detects your distribution and processor, installs dependencies, registers the bitsmith service, and starts it.

Options

Pass flags through to the installer:

curl -fsSL https://downloads.bitsmith.app/install.sh | sudo bash -s -- --skip-deps

• --version <tag> installs a specific release, for example v2026.4.19.
• --skip-deps skips installing Docker, Samba, and ZFS. Use this if you manage them yourself.
• --skip-start installs the files but doesn’t start the service yet.
• --yes accepts package installs without extra prompts.

On a Mac

Requirements:

• A Mac with Apple Silicon (M1 or newer) running macOS 26 or later.
• The Mac connected to your network with an Ethernet cable. VMs join your network through it.

Run the installer with --box:

curl -fsSL https://downloads.bitsmith.app/install.sh | sudo bash -s -- --box

Bitsmith runs as a background service, keeps the Mac awake while it is on power, and adds a menu bar app. Your folders live in /Users/Shared/Bitsmith. Apps install as Linux VMs. Containers, Docker apps and ZFS storage need a Linux server; a Mac in a cluster with one can use them there.

To share or back up folders in your own home folder, such as Documents or Desktop, give Bitsmith access in System Settings → Privacy & Security → Full Disk Access: add /usr/local/bin/bitsmith, then stop and start Bitsmith in the menu bar app. Updates keep this access.

Open the web interface

Once the service is running, open Bitsmith in a browser at your server’s address:

https://<your-server-ip>

Bitsmith serves over HTTPS with a self-signed certificate on first run, so your browser warns you the first time. That’s expected for a fresh local server. Continue past the warning to reach the setup screen.

Tip

Not sure of your server’s address? On the server, run hostname -I and use the first address it prints.

The certificate warning

The warning appears because the certificate is self-signed (created by your server, not a public authority your browser trusts). The connection is still encrypted; the browser just can’t vouch for who issued it. To remove the warning, from simplest to most polished:

• Accept it once per browser and move on. Fine for a server only you use.
• Trust the certificate on your devices by adding Bitsmith’s certificate to the system trust store. The warning disappears on those devices.
• Use a real certificate. If you reach your server through a domain name, install a certificate from a public authority (for example via your reverse proxy or DNS provider) so every device trusts it with no extra setup.

Reaching it from outside your home

Bitsmith is built to live on your home network. To reach it while away, prefer a private network like Tailscale or a VPN rather than exposing it directly to the internet. That keeps the server private and gives you an encrypted path in, which also covers the MCP endpoint.

Next step

The setup screen walks you through your license, your admin account, the network bridge, and your first storage. Continue with First-run setup.

Install the CLI

The client runs on Linux, macOS, and Windows. It installs into your user account, with no sudo and no box setup.

On Linux or macOS:

curl -fsSL https://downloads.bitsmith.app/install.sh | bash

On Windows, in PowerShell:

irm https://downloads.bitsmith.app/install.ps1 | iex

The installer puts bitsmith on your PATH and stops. To point it at a box you already run:

bitsmith connect

bitsmith connect opens the box’s consent screen in your browser. There you choose the grant: Full, Read-only, or an exact set of scopes. The agent token is stored on that machine when you finish. Add --url to name a specific box, or --token to skip the browser if you already hold a token. To pin a release or a beta, add --version <tag> after the pipe: curl -fsSL https://downloads.bitsmith.app/install.sh | bash -s -- --version <tag>.

Tip

On a Linux machine you can make it the box instead: run sudo bitsmith install. On an Apple Silicon Mac, run the installer with sudo and --box. On Windows the box lives elsewhere, so this machine only connects to it. See the agent and MCP guide for wiring the CLI up for AI agents.