Setup

Install the binary, create one tiny map repo, then a single command wires up each machine. Re-running it is always safe.

1. Install

One line per machine. It downloads a standalone binary for your platform — no Node, no build step. Git is the only runtime dependency.

curl -fsSL https://raw.githubusercontent.com/treadiehq/boot/main/scripts/install.sh | bash

2. Create the map repo — once, ever

Create an empty private git repo to hold the map. boot clones this remote — it won't create it for you. Leave it empty; your first sync seeds it. A name like code-map works well.

Rather not host a git remote? Point boot at a folder something else already syncs — Dropbox, iCloud Drive, Google Drive — with --folder ~/Dropbox/boot-map.

3. Set up each machine

One command links the workspace, creates a secret key, installs the shell hook and background daemon, and prints a health check.

boot setup [email protected]:me/code-map.git ~/code

# folder transport instead of a git remote
boot setup --folder ~/Dropbox/boot-map ~/code

# accept every step (scriptable)
boot setup … --yes

1. Map — links the workspace if it's new, or pulls if it's already linked, so re-running is safe and idempotent

2. Secret key — keeps an existing key, offers to create one on a first machine, or prompts to import it where encrypted scopes already exist

3. Shell hook — appends the hydrate-on-cd snippet to your shell rc (zsh, bash, fish, or PowerShell) so repos hydrate as you navigate

4. Background daemon — installs the managed service: launchd on macOS, systemd on Linux, a Scheduled Task on Windows. It pulls and pushes the map every 60s

5. Health check — verify anytime with boot doctor --system

4. Sync your env vars (optional)

Secrets ride the map encrypted with AES-256-GCM, so the map is safe to host anywhere. The key never enters the map in plaintext.

boot env set API_KEY=sk-123 DB_URL=postgres://…   # workspace-global vars
boot env set TOKEN=abc --repo apps/web          # scope to one repo
boot env import .env                             # bulk-import a dotenv
boot env materialize                             # write .env files locally

To use the same secrets on a new machine, escrow the key under a passphrase — you transfer a short passphrase out-of-band, never the raw key.

boot env key share     # on a machine with the key: pick a passphrase
boot env key receive   # on the new machine: enter it → key installed

materialize adds .env to each repo's .git/info/exclude so it can never be committed by accident.

5. Cloud agents & CI

boot agent is a one-shot, idempotent, non-interactive bootstrap for the top of a CI job or a fresh cloud-agent container.

boot agent [email protected]:me/code-map.git ~/code            # placeholders
boot agent … --hydrate 'apps/*' 'libs/api'                    # only what you need
boot agent … --all --env                                     # everything + .env files
boot agent … --all --dry-run                                 # preview, write nothing

First run links the workspace; later runs just pull and re-apply structure — safe to run every time.

Key concepts

map

The map

A small, portable description of your workspace: which repos exist and where each one lives. This is the thing that travels between machines.

placeholder

Placeholder

A stand-in folder for a repo you haven't cloned yet — the shape of your workspace without the gigabytes.

hydrate

Hydrate

Swap a placeholder for the real clone — on demand, or automatically the first time you touch it.

transport

Transport

How the map moves between machines: a git remote (the default), or a folder something else already syncs, like Dropbox.

Full command reference →