Using wbsp on Windows
There are two ways to use wbsp on a Windows machine. Both are supported; pick
one.
- Directly on Windows —
wbspruns in PowerShell, Command Prompt or Windows Terminal, like any other Windows program. Simplest if you work in Windows folders and Windows editors. See Directly on Windows. - Inside WSL — Windows Subsystem for Linux runs a real Linux inside Windows,
and
wbspruns there exactly as it does on Linux. Best if you already work in WSL, or your projects' own tools expect Linux. See Inside WSL.
The two are separate installations: each has its own sign-in and its own list of platforms. Signing in on one does not sign you in on the other.
You do not need AWS credentials either way. wbsp signs you in to the platform
and the platform does the rest.
Directly on Windows
What you need
- Windows 10 (version 2004 or later) or Windows 11, on an x64 or ARM64 machine.
- Docker Desktop for Windows, running —
wbsp deploybuilds your application's image on your machine, and Docker does the building. - Git for Windows (https://git-scm.com/download/win) — for
git pushand forwbspto read your project's repository.
1. Install wbsp
Open PowerShell (an ordinary window — not as Administrator) and run:
irm https://get.wbsp.ai/install.ps1 | iexIt downloads wbsp for your machine, checks it against the published checksum,
installs it into %LOCALAPPDATA%\Programs\wbsp, and adds that folder to your
Path. Open a new terminal window (windows that were already open do not
see the new Path) and check it:
wbsp --version2. Sign in
wbsp loginYour browser opens; sign in there, and the terminal says who you are signed in
as. If no browser opens, copy the address wbsp printed into your browser.
Signing in also sets up git and docker to use your wbsp sign-in, so
git push and docker push to the platform need no separate passwords.
For a platform other than wbsp.ai, add it once and sign in to it:
wbsp platform add <name> --base-domain <its domain>
wbsp login --platform <name>3. Work on your projects
Projects can live anywhere in your Windows folders, including folders whose names contain spaces:
cd "$HOME\My Projects"
git clone https://git.wbsp.ai/<owner>/<repo>.git
cd <repo>
wbsp deploy --destination <destination>Every command in the other guides works the same way:
useful-commands.md,
application-creator-guide.md,
credential-less-deploy.md. Destinations that run on
your own machine (compose, dev, standalone) use Docker Desktop.
Press Ctrl-C to stop following a long deploy; wbsp says what state it was
left in, and the deploy itself carries on on the platform.
Where wbsp keeps its files
| What | Where |
|---|---|
| The program | %LOCALAPPDATA%\Programs\wbsp\wbsp.exe |
Docker's helper (a copy of the program, made by the installer and by wbsp login) | %LOCALAPPDATA%\Programs\wbsp\docker-credential-wbsp.exe |
| Sign-ins, platforms, deploy records | %APPDATA%\wbsp |
When something goes wrong
| What you see | What it means | What to do |
|---|---|---|
Docker is installed but not running | Docker Desktop is not started | Start Docker Desktop from the Start menu, wait until its engine is running, run the command again |
the docker command was not found | Docker Desktop is not installed | Install it, start it, open a new terminal |
wbsp is not recognised | This window opened before the install | Open a new terminal window |
The installer says wbsp.exe is in use | A wbsp command (or a docker push) is running | Let it finish or close it, then run the installer again |
wbsp login waits and nothing happens | The browser did not open | Copy the address wbsp printed into your browser |
git push asks for a password | You have not signed in on this machine yet, or signed in before installing Git | Run wbsp login again |
Updating wbsp
Run the install command again; it replaces the old version and keeps your sign-ins and platforms:
irm https://get.wbsp.ai/install.ps1 | iexTo install a particular version, set $env:WBSP_VERSION = "0.2.120" first.
Inside WSL
Once WSL is set up, everything in the other guides works exactly as written on
Linux: you type the same wbsp commands, in a Linux terminal window.
What you need
- Windows 10 (version 2004 or later) or Windows 11.
- Docker Desktop for Windows, with WSL integration turned on (step 2).
- About 15 minutes the first time.
1. Install WSL and Ubuntu
Open PowerShell as Administrator (right-click the Start button → Terminal (Admin)) and run:
wsl --install -d UbuntuRestart Windows when it asks. After the restart an Ubuntu window opens and asks you to choose a Linux user name and password — any you like; they are only for this Linux.
From now on, "the Ubuntu window" means that terminal. You can open it again from the Start menu (search for Ubuntu).
2. Let Docker Desktop work inside Ubuntu
- Install Docker Desktop for Windows if you have not, and start it.
- Docker Desktop → Settings → Resources → WSL integration → turn on Ubuntu → Apply & restart.
Check it from the Ubuntu window:
docker versionBoth a Client and a Server section should appear. If the Server part is missing, Docker Desktop is not running, or the integration switch is off.
3. Install wbsp
In the Ubuntu window:
curl -fsSL https://get.wbsp.ai/install.sh | bashThen check it:
wbsp --versionIf the shell says wbsp: command not found, close the Ubuntu window and open a
new one — the installer adds wbsp to the path for new windows.
4. Sign in
wbsp loginwbsp tries to open your Windows browser. If no browser opens, it prints an
address instead: copy it into your browser on Windows. Either way, after you
sign in the browser hands the result straight back to wbsp in the Ubuntu
window — WSL shares localhost with Windows, so nothing else is needed.
Signing in also sets up git and docker in Ubuntu to use your wbsp sign-in,
so git push and wbsp deploy need no separate passwords.
For a platform other than wbsp.ai, add it once and sign in to it:
wbsp platform add <name> --base-domain <its domain>
wbsp login --platform <name>5. Work on your projects — inside Ubuntu
Keep your project folders inside Ubuntu's own files (your Ubuntu home,
~), not on the Windows drive:
mkdir -p ~/projects && cd ~/projects
git clone https://git.wbsp.ai/<owner>/<repo>.git
cd <repo>
wbsp deploy --destination <destination>Your Windows files are reachable from Ubuntu under /mnt/c/…, but projects
there are slow to build and can confuse git about file permissions and line
endings. If a project already lives on the Windows drive, clone it again into
~/projects rather than working on it in place.
To see your Ubuntu files from Windows — in File Explorer, open \\wsl$\Ubuntu\home\<your Linux user>.
Editing with Visual Studio Code
Install the WSL extension (by Microsoft) in VS Code on Windows. Then, in the Ubuntu window, from inside a project folder:
code .VS Code opens on Windows, editing the files inside Ubuntu, and its built-in
terminal is an Ubuntu terminal — so wbsp commands run there too.
Everything else
From here, every other guide applies unchanged: useful-commands.md, application-creator-guide.md, credential-less-deploy.md. Run their commands in the Ubuntu window.
When something goes wrong
| What you see | What it means | What to do |
|---|---|---|
docker: command not found, or Cannot connect to the Docker daemon | Docker Desktop is not running, or not shared with Ubuntu | Start Docker Desktop; check Settings → Resources → WSL integration → Ubuntu is on |
wbsp: command not found right after installing | This window started before the install | Open a new Ubuntu window |
wbsp login waits and nothing happens | The browser did not open | Copy the address wbsp printed into your Windows browser |
git lists every file as changed | The project is on the Windows drive (/mnt/c/…) | Clone it again inside ~/projects |
| Builds are very slow | The project is on the Windows drive | Clone it again inside ~/projects |
Updating wbsp
Run the install command again in the Ubuntu window; it replaces the old version:
curl -fsSL https://get.wbsp.ai/install.sh | bash