Getting Started

Getting Started

From nothing to your first wip up. If you already know which mode you want, jump straight to Container Mode, Compose Native Mode, or Compose Mode.

Prerequisites

Requirement	Why
Windows x64	wip ships as a self-contained Native AOT binary — no runtime to install
WSL2	WSLC containers run in a WSL2-backed VM
Microsoft WSLC	wip shells out to wslc.exe / wslc for everything

Confirm wslc itself is reachable before installing anything:

wslc.exe version || wslc version

wip looks for the binary in this order when wslc.command is left at auto:

1. wslc.exe (on PATH)
2. wslc (on PATH)
3. /mnt/c/Windows/System32/wslc.exe

If none of those exist, see WSLC Not Found.

Installation

scoop install https://raw.githubusercontent.com/slidict/wip/main/wip.json

Or via WinGet:

winget install Slidict.Wip

Or manually: download and extract wip-<version>-win-x64.zip from Releases, then add the folder holding wip.exe to your PATH. Full details, including building from source, are in the README's Requirements & installation.

Coming from v1? Through v1, wip was a Ruby gem (gem install wslc-wip). That implementation still works but has no further updates planned — see Ruby Implementation.

From source, when you want to run an unreleased revision or hack on it:

git clone https://github.com/slidict/wip.git
cd wip
dotnet publish src/Wip.Cli/Wip.Cli.csproj -c Release -r win-x64

Check what you got:

wip version

That prints wip's own version and then asks wslc for its version — see wip version.

Generate a wip.yml

cd my-project
wip init

wip init looks for compose.yml / compose.yaml / docker-compose.yml / docker-compose.yaml next to the file it's about to write:

• found → writes mode: compose-native, pointing at that file
• not found → writes mode: container, with a dependencies: skeleton

It refuses to overwrite an existing wip.yml unless you pass --force, and --template rails|node|rust|csharp picks a stack-appropriate default sync.exclude list. Full details: wip init.

The generated file is deliberately full of comments and TODO: markers. At minimum you need to fill in:

• container mode — dependencies.app.image (and rename app / container: if you like)
• compose-native mode — compose.service, so wip knows which service is "the app"

Verify it works

wip doctor

Every check prints [OK], [WARN], or [FAIL]. Warnings alone still exit 0; a WSL2, interop, WSLC, config, or sync failure exits 1. See wip doctor for what each line means.

First boot

wip build     # only if you have a build: / interaction.build definition
wip up -d
wip shell

wip up creates the network (if network: is set), starts every sidecar, mirrors the source if you configured Source Sync, then starts the primary container. See wip up.

Then run your project's own commands through the interactions you declared:

wip rails console
wip rspec

Those come from the interaction: block — see Interactions.

Where to go next

Question	Page
Which mode should I use?	Choosing a Mode
What does every wip.yml key do?	Configuration Reference
What commands exist?	CLI Command Reference
Boot feels unbearably slow	Fixing a Slow Boot
I'm coming from dip	Migrating from dip
Something failed	Troubleshooting & FAQ