From 5313c2f77760768d0ac857c4a3f277619f08632f Mon Sep 17 00:00:00 2001 From: CrypticSwarm Date: Fri, 25 Sep 2026 14:15:32 -0500 Subject: [PATCH] Document running Swarmforge on Windows under WSL Windows had no install path: the Makefile recipes need bash and the launcher relies on POSIX-only calls, so native shells cannot run it. The new page walks from a machine with Docker Desktop to an Ubuntu distro wired to it, then hands off to the ordinary installation steps. The host prerequisites were not written down anywhere, so installation gains a section listing them, and the README and docs index point at both pages. --- README.md | 5 ++- docs/README.md | 5 ++- docs/installation.md | 5 +++ docs/windows.md | 89 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 101 insertions(+), 3 deletions(-) create mode 100644 docs/windows.md diff --git a/README.md b/README.md index 8ccb349..d3586e7 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ It emphasizes robustness, constraint-driven design, and interoperability over ad ## Installation +Check the [prerequisites](docs/installation.md#prerequisites) first. +On Windows, set up [WSL](docs/windows.md) and run everything below inside it. + 1. Add the shell helper alias and link the `swarmforge` command: ```bash @@ -44,7 +47,7 @@ is worth it once one build has populated that cache (`-O` keeps the parallel log [docs/](docs/README.md) is the index. The pages behind it: -- [Installation](docs/installation.md), [swarmforge CLI](docs/cli.md), and [Git repos and worktrees](docs/git-guard.md) — getting a session running, and what the read-only git mounts change about it. +- [Installation](docs/installation.md), [Windows (WSL)](docs/windows.md), [swarmforge CLI](docs/cli.md), and [Git repos and worktrees](docs/git-guard.md) — getting a session running, and what the read-only git mounts change about it. - [OpenCode](docs/harnesses/opencode.md), [Claude Code](docs/harnesses/claude-code.md), [Grok Build CLI](docs/harnesses/grok.md), [Codex CLI](docs/harnesses/codex.md) — one page per harness. - [Configuration and assets](docs/configuration.md), [Agents](docs/authoring/agents.md), [Skills](docs/authoring/skills.md), [Commands](docs/authoring/commands.md) — what every harness picks up, and how to write it once. - [Tongs](docs/tongs/README.md) — sidecar containers that hold what the agent must not, such as credentials. diff --git a/docs/README.md b/docs/README.md index 74ab81f..291cbbf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,8 @@ ## Running a session -- [Installation](installation.md) — the install script, pinning an OpenCode release, several aliases against one checkout. +- [Installation](installation.md) — prerequisites, the install script, pinning an OpenCode release, several aliases against one checkout. +- [Windows (WSL)](windows.md) — Ubuntu under WSL 2 with Docker Desktop, set up to run the installation steps. - [swarmforge CLI](cli.md) — `swarmforge clone` and `swarmforge init`, and the worktree layout they create. - [Git repos and worktrees](git-guard.md) — the read-only git mounts every session gets, what they stop, and what they do not. @@ -40,7 +41,7 @@ ## Reading paths -- **First session in a container** — [Installation](installation.md), then your harness's page, then [Git repos and worktrees](git-guard.md) for what the read-only mounts change about git. +- **First session in a container** — [Windows (WSL)](windows.md) if you are on Windows, [Installation](installation.md), then your harness's page, then [Git repos and worktrees](git-guard.md) for what the read-only mounts change about git. - **Giving an agent a credential without handing it over** — [Tongs](tongs/README.md), [Definition format](tongs/definitions.md), [Secret providers](tongs/secrets.md). - **Sharing skills, commands, and agents across repos** — [Configuration and assets](configuration.md), then [Agents](authoring/agents.md). - **Adding a harness or changing startup** — [Harness lifecycle](development/architecture.md), then [Testing](development/testing.md). diff --git a/docs/installation.md b/docs/installation.md index 6cee9f7..32a279b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,6 +3,11 @@ The three install steps are in the [repo README](../README.md); this page carries the detail behind them. Every variable below has a row in [Environment variables](reference/environment.md), and every target one in [Make targets](reference/make-targets.md). +## Prerequisites + +The host needs Docker with BuildKit, git, GNU make, bash, and Python 3.9 or newer; the launcher uses only the standard library. +On Windows these live inside WSL: see [Windows (WSL)](windows.md). + ## The install script Run it with `bash` (it uses Bash arrays) even if your login shell is Zsh. diff --git a/docs/windows.md b/docs/windows.md new file mode 100644 index 0000000..1420935 --- /dev/null +++ b/docs/windows.md @@ -0,0 +1,89 @@ +# Windows (WSL) + +Swarmforge runs inside a WSL 2 Ubuntu distro, with Docker Desktop on Windows as the daemon. +Native Windows shells are not supported: the Makefile recipes need bash, and the launcher relies on POSIX-only calls. + +This page assumes [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) is already installed. +Steps 1 and 2 happen on the Windows side; everything after runs in the Ubuntu shell. + +## 1. Install Ubuntu in WSL + +In PowerShell, as Administrator: + +```powershell +wsl --version +wsl --list --verbose +``` + +| What you see | What it means | What to do | +|---|---|---| +| `wsl` is not recognized | WSL isn't installed | `wsl --install -d Ubuntu-26.04`, then reboot | +| `wsl --version` prints help text or "invalid option" | An old built-in WSL | `wsl --update`, then `wsl --install -d Ubuntu-26.04` | +| Only `docker-desktop` (and maybe `docker-desktop-data`) listed | Docker Desktop's own distro, which is not for interactive use | `wsl --install -d Ubuntu-26.04` | +| An `Ubuntu…` distro already listed | An existing install | Run `wsl -d -- lsb_release -rs`. On 22.04 or newer, keep it. On anything older, install `Ubuntu-26.04` next to it: 20.04's Python is too old. | + +Make Ubuntu the default, so `wsl` opens it rather than Docker's distro: + +```powershell +wsl --set-default Ubuntu-26.04 +wsl --list --verbose # Ubuntu-26.04 has the * and VERSION 2 +``` + +Use the name the list shows if you kept an existing distro. +Ubuntu asks for a Linux username and password the first time it opens; they need not match your Windows account. +To reset a forgotten password on an existing distro, run `wsl -d Ubuntu -u root passwd `; `wsl -d Ubuntu whoami` prints the username. + +From here on, open Ubuntu with `wsl ~` from a regular PowerShell, or from the Start menu. +The `~` starts the shell in your Linux home; plain `wsl` starts in PowerShell's current folder, translated to a path under `/mnt/c`. + +If the install fails: + +- **`0x80370102`, or "virtualization not enabled":** turn on virtualization (Intel VT-x or AMD-V/SVM) in the BIOS/UEFI, and **Virtual Machine Platform** under *Turn Windows features on or off*. A Docker Desktop already running on its WSL 2 engine means both are on. +- **Microsoft Store blocked:** `wsl --install --web-download -d Ubuntu-26.04`. +- **`wsl --install` not supported:** Windows 10 needs version 2004 (build 19041) or later; `winver` shows yours. + +## 2. Connect Docker Desktop to Ubuntu + +Start Docker Desktop; Ubuntu reaches Docker only while it runs. Then: + +- **Settings → General**: check **Use the WSL 2 based engine**. +- **Settings → Resources → WSL integration**: turn on your Ubuntu distro and click **Apply & restart**. With **Enable integration with my default WSL distro** checked and Ubuntu as the default, it is already on. + +## 3. Check Docker from Ubuntu + +```bash +docker version +docker run --rm hello-world +``` + +The **Server** section of `docker version` names **Docker Desktop**. +If it names a plain Docker Engine, this distro has its own Docker from an earlier install; remove it (`sudo apt remove docker-ce docker.io`) so `docker` reaches Docker Desktop. + +If `docker` isn't found, or `docker version` has no Server section, run `wsl --shutdown` in PowerShell, restart Docker Desktop, and open Ubuntu again. +If `/var/run/docker.sock` then refuses with `permission denied`, run `sudo usermod -aG docker $USER` followed by another `wsl --shutdown`. + +## 4. Install the prerequisites + +```bash +sudo apt update && sudo apt install -y git make python3 +``` + +Set your git identity here: sessions mount the Linux `~/.gitconfig`, not the Windows one. + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + +## 5. Install Swarmforge + +Clone under your Linux home, and keep the projects you run sessions on there too: + +```bash +mkdir -p ~/src && cd ~/src +git clone https://github.com/CrypticSwarm/Swarmforge.git +cd Swarmforge +``` + +Then follow the [installation steps](../README.md#installation). +After `bash ./install.sh`, run `exec bash -l`: Ubuntu's `~/.profile` puts `~/.local/bin` on `PATH` only if it existed at login.