How it works

From spec to running machine

Bootstrap SaaS turns your Linux machine setup into a repeatable, versioned workflow. Here is the full process from profile creation to tracked completion.

Overview

The platform is built around four core concepts:

Profiles

Declarative machine specs

Tokens

Single-use provisioning keys

Agent

Idempotent local runner

Runs

Real-time execution logs

Step 1

Create a profile

Define your desired machine state: apt packages, shell, dotfiles, SSH keys, and Git config. Every profile is versioned and validated against a strict schema.

terminal

$ bs profile create --name "dev-workstation" > Packages: zsh, tmux, neovim, fzf, ripgrep > Shell: zsh (default) > Dotfiles: github.com/you/dotfiles > Saved as profile dev-workstation@v1

Step 2

Mint a token

Generate a single-use, time-bound token tied to a specific profile. Tokens are cryptographically random and expire after one hour by default.

terminal

$ bs token mint --profile dev-workstation --ttl 1h > Token: bs_tok_7f8a9b2c... > Expires: 2024-01-15T14:30:00Z > Uses remaining: 1

Step 3

Run the agent

On a fresh Ubuntu or Debian install, run one command. The agent verifies the token, downloads the profile, and converges the machine to the desired state.

terminal

$ curl -sSL agent.sh | bash -s -- bs_tok_7f8a9b2c... > Verifying token... OK > Profile: dev-workstation@v1 > Converging... done in 3m 42s

Step 4

Track the run

Watch provisioning progress in real time from the dashboard. Every step is logged to an immutable audit trail for compliance and debugging.

terminal

$ bs runs list > run_01jk... dev-workstation success 3m 42s 2 min ago > run_01jl... dev-workstation success 4m 01s 1 hr ago

Frequently asked questions

What Linux distributions are supported?

Ubuntu 22.04+ and Debian 12+. The agent uses apt for packages and assumes a systemd-based init. Support for additional distros is on the roadmap.

Do I need to install anything on the target machine?

No. The only requirement is curl and a network connection. The agent is delivered via a single curl | bash command and cleans up after itself.

Can I use the same token on multiple machines?

No — tokens are single-use by design. If you need to provision multiple machines, mint one token per machine. This ensures every run is individually auditable.

What happens if provisioning is interrupted?

The agent is idempotent. If you re-run the same token (before it expires), already-completed steps are skipped and only pending steps are executed.

Is my data encrypted?

Yes. All profile data and audit logs are stored in Cloudflare D1 with encryption at rest. Tokens are never stored in plaintext — only a hashed fingerprint is kept.