Foreman on Windows

This page is for anyone on a Windows PC. Foreman runs on macOS and Linux. On Windows it runs inside WSL2, the Linux that Windows itself ships, and everything in the rest of this guide then applies as it does on Linux. Running Foreman straight on Windows, from PowerShell, the Command Prompt or Git Bash, is not supported yet.

Foreman’s releases are tested on macOS and Linux. WSL2 is Linux, so the same code runs there, but if something behaves differently on your PC, please open an issue and say that you are on WSL2.

If you would rather not run it on your PC at all, Foreman also runs in a container on a Linux server or in GitHub Actions: see Run in the cloud.

What you need

Name	What it is
Windows 11, or Windows 10 version 2004 or later	The versions that install WSL2 with one command.
WSL2 with Ubuntu	A real Linux running beside Windows. Foreman, Claude Code and your project all live inside it.
The tools on Install, inside Ubuntu	Claude Code, Node 22 or later, git and the GitHub CLI. The copies installed on Windows do not count: Foreman only sees what is installed in Ubuntu.

Set it up

1. Install WSL2

Open PowerShell as administrator (right-click it, Run as administrator), run this, then restart the PC:

wsl --install

It installs WSL2 and Ubuntu. After the restart, open Ubuntu from the Start menu and choose a Linux user name and password when it asks. Microsoft’s own steps, and what to do on an older Windows, are on Install WSL.

If you installed WSL some time ago, check that your Ubuntu is on version 2. In PowerShell:

wsl --list --verbose

The VERSION column must say 2. If it says 1, run wsl --set-version Ubuntu 2.

Every command from here on is typed in the Ubuntu terminal, not in PowerShell.

2. Install the tools inside Ubuntu

git and the GitHub CLI:

sudo apt update
sudo apt install -y git gh

Node 22 or later. One way is nvm: install it as its page says, open a new terminal, then:

nvm install 22

Claude Code: follow its Linux steps on Set up Claude Code, then run claude once and sign in.

Then sign the GitHub CLI in, to an account that can push to your repository:

gh auth login

3. Put your project in the Linux home folder

Clone the project inside Ubuntu, under your home folder:

cd ~
git clone https://github.com/your-name/your-project.git
cd your-project

Do not work on a copy under /mnt/c/, which is your Windows drive seen from Linux. Files there are slow to read and write and do not keep Linux file permissions, and Foreman makes a git worktree per story, so it reads and writes a lot. You can still open the Linux copy from Windows: in File Explorer it is under Linux in the side bar, and VS Code opens it with its WSL extension.

4. Install Foreman

Start Claude Code in the project, from the Ubuntu terminal:

claude

Then follow Install from its first command. /foreman:init and foreman doctor work as they do on Linux, and Your first story takes over from there.

What is different on Windows

The dashboard and the Set up page open in your Windows browser. Foreman prints their address when it starts. If the page does not open by itself, copy that address into the browser on Windows; WSL2 passes it through.

Keep an Ubuntu terminal open while a run is going. Windows stops WSL2 a short while after its last terminal closes, and the run stops with it. A background service does not prevent this. Leave one Ubuntu window open, minimised if you like, for as long as Foreman should work.

Stop the PC going to sleep. A sleeping PC builds nothing. For a long or overnight run, set Windows not to sleep while plugged in, under Settings › System › Power. Foreman’s keep-awake option is for macOS only.

The background service needs systemd. foreman service install uses systemd --user, which a new Ubuntu from wsl --install already has turned on. To check, run systemctl --user status. If it reports that systemd is not running, add these two lines to /etc/wsl.conf (with sudo nano /etc/wsl.conf):

[boot]
systemd=true

Then run wsl --shutdown in PowerShell and open Ubuntu again. Microsoft describes this on Use systemd to manage Linux services with WSL. Without the service, foreman run still works; the service only adds starting again after a crash. Either way, the terminal has to stay open.

Docker comes from Docker Desktop. If your project’s slots use Docker (env.adapter is docker), install Docker Desktop on Windows and turn on its WSL integration for Ubuntu, as on Docker Desktop WSL 2 backend. foreman doctor then finds docker compose inside Ubuntu.

Keys and sign-ins live in Ubuntu. Anything you signed in to on Windows, such as git, the GitHub CLI or Claude Code, has to be signed in again inside Ubuntu. Foreman’s own keys go in through the Set up page as usual.

When it does not work

Run foreman doctor in the project, inside Ubuntu. It checks the same things as on Linux and says what to fix. The usual causes on Windows are:

What you see	Likely cause	What to do
foreman or claude is not found	The command was typed in PowerShell, or the tool is installed on Windows only.	Use the Ubuntu terminal, and install the tool inside Ubuntu.
background service says there is no service manager	systemd is off in this Ubuntu.	Turn it on as above, or run without the service.
The run stopped by itself overnight	The last Ubuntu terminal was closed, or the PC went to sleep.	Keep a terminal open and turn sleep off, then run foreman run again. Unfinished stories go back in line.
Everything is very slow	The project is under /mnt/c/.	Clone it again under your Linux home folder.

Anything else: Getting help.