Sailwright

Test your dev machine setup before it touches a laptop.

Sailwright is one CLI to set up, test, and keep developer machines consistent on macOS, Windows, and Linux. It is built for platform and DevEx teams that support a mixed-OS fleet. Unlike chezmoi, Nix/Devbox, or devcontainers, Sailwright runs your setup automation in real, disposable VMs before you roll it out to developers.

• Plain Ansible underneath: reuse your existing roles and playbooks
• Real VM targets: macOS, Windows 11, and Ubuntu guests, depending on your host (see Support Snapshot)
• Free and open source, no telemetry

Quick Start

macOS (Homebrew):

brew install csautter/sailwright/sailwright
sailwright install && sailwright build list

Linux:

curl -fsSL https://github.com/csautter/sailwright/releases/latest/download/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sailwright install && sailwright build list

Windows (PowerShell):

irm https://github.com/csautter/sailwright/releases/latest/download/install.ps1 | iex
sailwright install; sailwright build list

Both options work on macOS and Linux: use the install script on a Mac without Homebrew, or Homebrew on Linux if you already use it. The install scripts verify the download against the release checksums and need no sudo or admin rights. See Installation for options and manual installs.

See 🚀 Getting Started below for macOS/Windows steps, cloning the repo instead, and running your first full workflow.

Why It Helps

Without a shared automation baseline, cross-platform teams usually run into the same problems:

• developers spend hours figuring out how a machine is supposed to look
• onboarding depends too much on senior team members
• setup differences become hard to debug and reproduce
• OS-specific scripts drift over time

Sailwright addresses that by keeping setup logic in versioned Ansible roles and playbooks, then using host-appropriate tooling to apply and test them. That helps teams onboard developers faster, keep machines consistent across operating systems, and replace one-off scripts and tribal knowledge with one repeatable workflow.

Sailwright handles the developer-tooling and workflow layer that classic MDM/UEM tools leave manual, team-specific, and hard to reproduce.

Support Snapshot

The project currently supports these host-to-target workflows:

Host OS	What you can automate today
macOS	Managed workflows for macOS (Tart), Ubuntu (UTM), and Windows 11 (UTM)
Windows	Managed workflows for Ubuntu (Hyper-V) and Windows 11 (Hyper-V, plus VirtualBox as unstable)
Linux	Managed workflows for Ubuntu and Windows 11 with native QEMU/KVM via libvirt/virt-manager, plus direct Ansible runs and Docker-based Linux testing

This means Sailwright can cover every currently supported guest OS family on a macOS host, and every currently supported family except macOS on a Windows host or Linux host.

Run sailwright <command> list (for example build list or provision list) to see the exact combinations available on your current machine; see Discover what your host supports.

Machine-readable listings

Every list subcommand accepts --json and prints a single-line JSON document for scripts and tools, for example sailwright build list --json. See Machine-readable listings for the contract.

Note: macOS guests are only supported on macOS hosts due to Apple platform and licensing restrictions.

Base Model

Sailwright follows a few simple ideas:

• Ansible roles and playbooks are the source of truth for machine setup
• roles stay cross-platform where possible, with OS-specific handling where needed
• runs are idempotent, so the same workflow can be applied repeatedly
• execution is pull-oriented, so machines can run their own automation locally
• --check mode matters, so changes can be previewed before they apply

That makes it practical both for daily developer use and for testing changes in VMs before applying them to real machines.

The same command surface works on your real workstation (sailwright provision local) and on managed test targets; see Run your first useful workflow.

🚀 Getting Started

1. Choose how you want to run it

You can either:

• install it with Homebrew (default on macOS, also works on Linux)
• install it with the install script (default on Linux and Windows, also works on macOS)
• download a release binary manually
• clone the repository when you want to edit playbooks, roles, or project code

The Quick Start commands cover Homebrew and the install scripts. The Homebrew tap also offers the host-side MCP gateway for agents as brew install csautter/sailwright/sailwright-gateway; the install scripts include it by default. See Installation for pinning a version, choosing another directory, skipping the gateway, and updating.

Manual install

Release assets are published on the GitHub Releases page as sailwright_<version>_<os>_<arch>.

After extraction, the executable is named sailwright on macOS/Linux and sailwright.exe on Windows.

Each release also ships the host-side MCP gateway for agents as sailwright-gateway_<version>_<os>_<arch>; see Agent Gateway.

If you prefer the shorter sail command, create it yourself as a shell alias such as alias sail=sailwright, or install a sail symlink that points to the sailwright executable.

macOS / Linux example:

TAG="$(curl -fsSL https://api.github.com/repos/csautter/sailwright/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' | head -n1)"
VERSION="${TAG#v}"
curl -fLO "https://github.com/csautter/sailwright/releases/download/${TAG}/sailwright_${VERSION}_linux_amd64.tar.gz"
tar -xzf "sailwright_${VERSION}_linux_amd64.tar.gz"
chmod +x ./sailwright
./sailwright build list

Windows example:

$Release = Invoke-RestMethod "https://api.github.com/repos/csautter/sailwright/releases/latest"
$Tag = $Release.tag_name
$Version = $Tag.TrimStart("v")
Invoke-WebRequest -OutFile "sailwright_${Version}_windows_amd64.zip" "https://github.com/csautter/sailwright/releases/download/$Tag/sailwright_${Version}_windows_amd64.zip"
Expand-Archive "sailwright_${Version}_windows_amd64.zip" -DestinationPath .
.\sailwright.exe build list

When you run a release binary outside a Git checkout, Sailwright extracts its embedded runtime assets into a managed app-data directory. See Managed Application Data for the default locations and override options.

Clone the repository

git clone https://github.com/csautter/sailwright.git
cd sailwright

2. Install host dependencies

macOS

sailwright install

This runs scripts/macos/sailwright-install-dependencies.sh.

Ubuntu / Debian

sailwright install

This runs scripts/linux/sailwright-install-dependencies.sh.

On macOS, Linux, and Windows, sailwright install --with-go also bootstraps the Go toolchain.

Windows

Run the command from your normal shell. Windows will prompt for elevation through UAC if needed:

sailwright.exe install
# optionally with Go and VirtualBox support:
sailwright.exe install --with-go --virtualbox

This runs scripts/windows/sailwright-self-setup.ps1.

3. Discover what your host supports

Start with the list commands before running a longer workflow:

sailwright build list
sailwright create list
sailwright provision list

Use --help when you want the supported flags for a command:

sailwright --help
sailwright build --help
sailwright provision --help

4. Run your first useful workflow

There are two common entry paths.

A. Configure the current machine directly

Use the built-in wrapper first when you want the shared command surface:

sailwright provision local --check
sailwright provision local --proto ssh --check
sailwright provision local --playbook ./playbooks/setup.yml --check
sailwright provision local

Configure ansible-role-sources.yml when you want the bare command to select your machine setup automatically. Without that config, it runs the bundled role-source smoke/example playbook. For more wrapper examples and platform-specific local behavior, use Local Provisioning. For direct localhost or remote-target ansible-playbook examples, use Running Playbooks.

B. Test the setup in a disposable VM first

Example on a supported host:

sailwright build ubuntu --type server --arch amd64
sailwright create ubuntu --type server --arch amd64
sailwright provision ubuntu --type server --arch amd64 --check
sailwright provision ubuntu --type server --arch amd64

If you are targeting Windows and remote access is not configured yet, start with Windows Ansible Access.

On Linux and macOS, an interactive sailwright build ubuntu ... offers to pull the published image instead of building locally (default: build locally). When you want to share reusable build artifacts through an OCI registry instead of rebuilding them locally, use sailwright push and sailwright pull; see the OCI build artifact registry workflow.

Trust & Privilege Model

Sailwright collects no telemetry and phones home to nothing: it makes no network calls except the ones you explicitly ask for (release/self-update downloads, OCI registry push/pull, and the Ansible/VM/network operations your playbooks define).

Elevation is scoped and temporary rather than "run everything as root/admin." On Windows, sailwright provision local creates a dedicated local admin account with a random or rotated password, enables WinRM-over-HTTPS or SSH only on the loopback address for the duration of the run, and restores the prior WinRM/SSH/firewall state during cleanup — see Windows Ansible Access for the exact mechanism. On macOS/Linux, install and provisioning scripts prompt for sudo only for the specific steps that need it.

Docs Map

The root README is the fast entry point. Use these guides when you want the next level of detail:

• Local Provisioning for the sailwright provision local wrapper, platform defaults, and Windows cleanup flags
• Running Playbooks for direct localhost, remote-host, VM, and Windows ansible-playbook examples
• Testing Workflows for OCI artifact registry push/pull and host-specific VM and Docker test flows
• Automated Quick-Start for the recorded, single-command end-to-end run of the full VM lifecycle
• Deterministic E2E Scenarios for the scripted user-cycle tests on real hosts
• Agent Gateway (experimental) for letting coding agents in a devcontainer drive Sailwright on the host through an MCP gateway with host-side approval
• Demo Recordings for how the quick-start recordings and website terminal demo are produced
• Managed Application Data for cache, runtime, and app-data locations
• Ansible Role Sources for layering local and Git-backed role roots during provisioning
• Windows Ansible Access for manual WinRM and SSH setup on Windows targets plus OpenSSH rollback notes
• Example Ansible Roles for the current sample role catalog and repository layout

📦 Example Roles

The repository already includes example roles for common developer tooling such as brew, java, jetbrains, k9s, kind, kubectl, kubelogin, openssh, python, and spotify.

Use Example Ansible Roles as the catalog and roles/ as the source of truth.

🤝 Contributing

Contributions are welcome. Good areas to improve include:

• more roles and playbooks
• broader cross-platform coverage
• better docs and troubleshooting guidance
• bug fixes and test coverage

See CONTRIBUTING.md for contribution terms and the Contributor License Agreement (CLA).

📜 License

Copyright (c) 2026 Carl-Christian Sautter.

Sailwright is free and open source under the AGPLv3: use it at no cost across your whole organization, including for commercial purposes. A separate commercial license is available only if you want to embed Sailwright in a closed-source product or service.

See LICENSE.md and the Licensing FAQ for what the AGPLv3 requires.

💡 Inspiration

This project grew out of real onboarding and support pain in mixed-OS teams. The goal is simple: make machine setup reproducible, testable, and much less dependent on memory or hand-written host-specific scripts.