Installation wslc

Installation — WSL Containers (`wslc`)

Run FICSIT Foreman on Windows 11 using WSL Containers (wslc.exe) — the Linux container runtime built into the Windows Subsystem for Linux — with no Docker Desktop.

Preview feature. wslc shipped as a public preview in WSL 2.9.3 (June 2026) and is still changing. In particular it has no Docker Compose, so the stack is started as three individual containers below. A couple of the flags this guide relies on (user-defined networks, named volumes, restart policies) are new and may differ in your build — this page tells you how to check, and gives a fallback. If you just want the smoothest path, use Installation — Docker instead.

It runs the same ghcr.io/stuartmeeks/foreman-* images and ends up at the same place: http://localhost:8725.

Prerequisites — install and verify `wslc`

Run these in PowerShell:

wsl --update                    # get a WSL version that includes wslc
wslc version                    # confirm the CLI is present
wslc run --rm hello-world       # pulls + runs a tiny image to prove it works

Then probe the capabilities this guide depends on — wslc is evolving, so confirm these before you start:

wslc --help
wslc network --help             # is there a `network create`? (needed for name-based DNS)
wslc run --help                 # confirm -d  -p  -e  -v  --name  --network

If wslc network exists and wslc run accepts --network, use the primary path below. If not, jump to Fallback: no user-defined network.

Why three separate commands (not one)

The Docker path uses docker compose up -d to start everything at once. wslc has no Compose yet, so you start each service by hand. Two of them talk to each other by container name — this is baked into the images, so the --name values below are not optional:

ff-client's web server proxies /api/ to http://ff-server:8724
ff-server reaches the MCP server at http://sf-mcp:8723/mcp

So the containers must share a network on which they can resolve each other by name, and they must be named exactly sf-mcp and ff-server.

1. Create folders for persistent data

wslc's preview doesn't confirm Docker-style named volumes, but Windows bind mounts are supported — and they keep your database and saves in a folder you control (this also avoids container file-ownership quirks). Create two folders:

mkdir C:\foreman\data           # SQLite DB, auth secret, sessions, work orders
mkdir C:\foreman\saves          # uploaded playthrough .sav files (shared by two services)

Anything under C:\foreman is fine — just use the same paths consistently below.

2. Create the shared network

wslc network create foreman-net

This gives the containers automatic name-based DNS (so ff-server can find sf-mcp, and ff-client can find ff-server).

3. Start the MCP server (`sf-mcp`)

wslc run -d --name sf-mcp --network foreman-net `
  -p 8723:8723 `
  -v C:\foreman\saves:/data/saves `
  -e SAVE_DATA_DIR=/data/saves `
  ghcr.io/stuartmeeks/foreman-sf-mcp:latest

Publishing -p 8723:8723 is optional (handy for hitting /health from Windows); the other services reach it over foreman-net, not via the published port.

4. Start the backend (`ff-server`)

wslc run -d --name ff-server --network foreman-net `
  -p 8724:8724 `
  -v C:\foreman\data:/data `
  -v C:\foreman\saves:/data/saves `
  -e MCP_URL=http://sf-mcp:8723/mcp `
  -e SAVE_DATA_DIR=/data/saves `
  -e DATABASE_URL=file:/data/foreman.db `
  -e ANTHROPIC_API_KEY=sk-ant-... `
  ghcr.io/stuartmeeks/foreman-ff-server:latest

ANTHROPIC_API_KEY is optional — leave it out to have each browser client supply its own key. To run on an OpenAI-compatible provider instead, pass LLM_PROVIDER / LLM_API_KEY / LLM_MODEL / LLM_BASE_URL (see Configuration).
MCP_URL and DATABASE_URL shown here match the image defaults; they're listed so the command is self-explanatory.
On first start it runs its database migrations, then boots.

5. Start the web app (`ff-client`)

wslc run -d --name ff-client --network foreman-net `
  -p 8725:80 `
  ghcr.io/stuartmeeks/foreman-ff-client:latest

6. Open the foreman

Browse to http://localhost:8725.

Verify and manage

wslc container list                    # all three should be running
wslc container logs ff-server          # look for DB migrations + a successful MCP connect
wslc container logs sf-mcp
wslc container logs ff-client

Everyday control:

wslc container stop  ff-client ff-server sf-mcp
wslc container start sf-mcp ff-server ff-client     # start mcp first
wslc container rm    ff-client ff-server sf-mcp     # remove (your C:\foreman data stays)

Auto-start on boot: Docker Compose's restart: unless-stopped has no confirmed wslc equivalent in the preview, so the containers won't come back by themselves after a reboot. Re-run the start commands (or the script below), or wire the script into Windows Task Scheduler at logon.

To update to newer images later:

wslc container stop ff-client ff-server sf-mcp
wslc container rm   ff-client ff-server sf-mcp
wslc image pull ghcr.io/stuartmeeks/foreman-sf-mcp:latest
wslc image pull ghcr.io/stuartmeeks/foreman-ff-server:latest
wslc image pull ghcr.io/stuartmeeks/foreman-ff-client:latest
# then re-run steps 3–5. Your C:\foreman data (DB + saves) is preserved.

Optional: one-shot start script

Save as start-foreman-wslc.ps1 and run it in PowerShell (e.g. ./start-foreman-wslc.ps1 -AnthropicApiKey sk-ant-...). It's just the commands above, made idempotent.

param(
  [string]$DataRoot        = "C:\foreman",
  [string]$AnthropicApiKey = "",
  [string]$Network         = "foreman-net"
)

$ErrorActionPreference = "Stop"

New-Item -ItemType Directory -Force -Path "$DataRoot\data", "$DataRoot\saves" | Out-Null

# Create the network if it doesn't already exist (ignore the error if it does).
wslc network create $Network 2>$null

# Remove any previous containers so this is re-runnable.
wslc container rm -f ff-client ff-server sf-mcp 2>$null

wslc run -d --name sf-mcp --network $Network `
  -p 8723:8723 `
  -v "$DataRoot\saves:/data/saves" `
  -e SAVE_DATA_DIR=/data/saves `
  ghcr.io/stuartmeeks/foreman-sf-mcp:latest

$serverArgs = @(
  "run","-d","--name","ff-server","--network",$Network,
  "-p","8724:8724",
  "-v","$DataRoot\data:/data",
  "-v","$DataRoot\saves:/data/saves",
  "-e","MCP_URL=http://sf-mcp:8723/mcp",
  "-e","SAVE_DATA_DIR=/data/saves",
  "-e","DATABASE_URL=file:/data/foreman.db"
)
if ($AnthropicApiKey) { $serverArgs += @("-e","ANTHROPIC_API_KEY=$AnthropicApiKey") }
$serverArgs += "ghcr.io/stuartmeeks/foreman-ff-server:latest"
wslc @serverArgs

wslc run -d --name ff-client --network $Network `
  -p 8725:80 `
  ghcr.io/stuartmeeks/foreman-ff-client:latest

Write-Host "FICSIT Foreman is starting — open http://localhost:8725"

To stop everything: wslc container stop ff-client ff-server sf-mcp.

Fallback: no user-defined network

If your wslc build has no network create / --network, the two name-based hops (ff-server → sf-mcp, and ff-client → ff-server) can't resolve. Route them through the Windows host instead — this only works if your wslc exposes a host-gateway address reachable from inside a container (commonly host.docker.internal; confirm with wslc run --help / the release notes).

Publish both backend ports (-p 8723:8723 on sf-mcp, -p 8724:8724 on ff-server) so they're reachable on the host.
Point the backend at the MCP server via the host gateway: -e MCP_URL=http://host.docker.internal:8723/mcp (drop --network foreman-net).

The client's /api/ proxy target (ff-server:8724) is baked into its image, so override it with your own nginx config mounted over the default. Save this as C:\foreman\default.conf:

server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;
  location /api/ { proxy_pass http://host.docker.internal:8724; }
  location /    { try_files $uri $uri/ /index.html; }
}

then run the client with it mounted:

wslc run -d --name ff-client `
  -p 8725:80 `
  -v C:\foreman\default.conf:/etc/nginx/conf.d/default.conf:ro `
  ghcr.io/stuartmeeks/foreman-ff-client:latest

If neither a user-defined network nor a host gateway is available in your preview build, use Installation — Docker until wslc networking matures.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Installation wslc

Installation — WSL Containers (`wslc`)

Prerequisites — install and verify `wslc`

Why three separate commands (not one)

1. Create folders for persistent data

2. Create the shared network

3. Start the MCP server (`sf-mcp`)

4. Start the backend (`ff-server`)

5. Start the web app (`ff-client`)

6. Open the foreman

Verify and manage

Optional: one-shot start script

Fallback: no user-defined network

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Installation wslc

Installation — WSL Containers (wslc)

Prerequisites — install and verify wslc

Why three separate commands (not one)

1. Create folders for persistent data

2. Create the shared network

3. Start the MCP server (sf-mcp)

4. Start the backend (ff-server)

5. Start the web app (ff-client)

6. Open the foreman

Verify and manage

Optional: one-shot start script

Fallback: no user-defined network

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Installation — WSL Containers (`wslc`)

Prerequisites — install and verify `wslc`

3. Start the MCP server (`sf-mcp`)

4. Start the backend (`ff-server`)

5. Start the web app (`ff-client`)