Install initech on Windows via WSL2

Zero to a running multi-agent session in under ten minutes.

Why WSL2

initech is a Linux/macOS native binary. It depends on a Unix PTY for terminal emulation, which Windows does not provide directly. WSL2 gives you a real Linux kernel inside Windows where initech runs unchanged. No virtualization tricks, no cross-compile.

You will run two terminals during this guide:

PowerShell for steps 01-02 (installing WSL2 itself)
Ubuntu in WSL2 for steps 03-06 (installing and running initech)

Prompts in code blocks make the distinction explicit: PS> means PowerShell, $ means the Ubuntu shell inside WSL2.

Prerequisites

Windows 10 build 19041+ or Windows 11 (any edition, Home is fine)
Local administrator rights for the initial WSL2 install (steps 01-02 only)
About 4 GB of free disk space for the Ubuntu image and dependencies
An internet connection

If you already use WSL2 daily, skip to step 03 to confirm your shell is not running as root, then continue.

01 Confirm your Windows version

Press Win + R, type winver, press Enter. A dialog shows your version and build number.

You should see: Windows 10 Version 2004 (build 19041) or higher, or any Windows 11 build. Older builds cannot run WSL2.

If your build is too old, run Windows Update before continuing.

02 Install WSL2 with Ubuntu

Open PowerShell (right-click Start menu, choose "Windows Terminal (Admin)" or "PowerShell (Admin)") and run:

PS> wsl --install

This installs the WSL2 platform, sets WSL2 as the default version, downloads the Ubuntu image, and registers it. Reboot when prompted.

After reboot, Ubuntu launches automatically and asks you to create a UNIX username and password. The password does not echo as you type — that is normal. This account is separate from your Windows account.

If wsl --install reports nothing happened or the command is missing, your machine has WSL1 partially configured. Run these instead:

PS> wsl --set-default-version 2
PS> wsl --install -d Ubuntu

You should see: a new Ubuntu terminal window with a green username@hostname:~$ prompt. From this point on, every command in this guide runs inside that Ubuntu shell.

Confirm WSL2 (not WSL1) is in use by running this in PowerShell:

PS> wsl -l -v
  NAME      STATE           VERSION
* Ubuntu    Running         2

The VERSION column must say 2. If it says 1, run wsl --set-version Ubuntu 2 and wait for the conversion.

Strongly recommended: install Windows Terminal from the Microsoft Store before continuing. The plain WSL console window has limited color, no mouse support, and rough font handling. initech's TUI looks correct in Windows Terminal and broken in the legacy console. Once installed, click the dropdown next to the new-tab button and pick Ubuntu for every command from here on.

03 Confirm you are not running as root

WSL2 sometimes drops you into a root shell — usually after an upgrade, a manual import, or certain custom images. Running initech as root is not supported: many of its tests rely on POSIX permission checks that behave differently when uid 0 owns every file. Check your user before continuing:

$ whoami
your-username

You should see: a regular username (the one you created during step 02), not root. If whoami prints root, follow the recovery steps below.

Recovery if you landed as root: create a regular user, give them sudo, and tell WSL2 to use that user by default.

# Inside the Ubuntu shell, while still root:
# adduser your-username
# usermod -aG sudo your-username

Then create or edit /etc/wsl.conf so the next launch logs you in as that user instead of root:

# cat > /etc/wsl.conf << EOF
[user]
default=your-username
EOF

Apply the change. From a PowerShell window on Windows:

PS> wsl --shutdown

Reopen the Ubuntu terminal. The shell should now log in as your-username, not root.

You should see: whoami prints your-username, and the prompt is $ not #. Only continue once this is true.

04 Update Ubuntu and install build essentials

Inside the Ubuntu shell:

$ sudo apt update && sudo apt install -y curl git ca-certificates nodejs npm

Most fresh Ubuntu images already have curl and git, but running this once guarantees you have the right versions and certificates. nodejs and npm are required by Claude Code, which is distributed as an npm package — install them now so step 05 works.

You should see: curl --version reports curl 7.x or later, git --version reports git 2.x or later, and node --version prints a version (any 18+ is fine).

05 Install Claude Code

initech runs Claude Code inside each agent pane, so Claude Code must be installed and authenticated before initech is useful. Follow the Claude Code install guide, then sign in:

$ claude login

You should see: claude --version prints a version, and claude opens an interactive session you can quit with Ctrl+C.

06 Install initech

$ curl -fsSL https://initech.sh/install.sh | bash

The script downloads the Linux binary for your architecture (amd64 or arm64) and places it in ~/.local/bin.

On a fresh Ubuntu user, ~/.local/bin is not on PATH yet. Add it now so the initech command resolves in every new shell:

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

You should see: initech version prints a version like v1.x.x, and which initech shows a path under your home directory. If initech: command not found, the PATH export above did not stick — open a new Ubuntu terminal and try again.

07 Run initech doctor and bootstrap a project

$ initech doctor

  Prerequisites
  ok  initech v1.3.0
  ok  claude (Claude Code)
  ok  git 2.44.0
  ok  Terminal: 212x56 (meets 80x24 minimum)

  All checks passed.

Doctor checks every dependency and your terminal size in one shot. Fix anything it flags before continuing.

Bootstrap your first project:

$ mkdir ~/myproject && cd ~/myproject
$ initech init
$ initech

Run these in an interactive terminal. initech init uses an arrow-key + space-bar selector to pick agents and prompts you for project metadata. It cannot be piped, redirected, or run from a non-TTY context (CI scripts, ssh -T, headless runners). If you see not a tty or the selector renders garbled, you are not in a real terminal session — open Windows Terminal directly and run the commands there.

You should see: the TUI fills your terminal with a grid of agent panes, each running Claude Code. Press Alt+q to quit when you are done exploring.

The full Getting Started guide picks up from here with sending messages, peeking, and shutting down.

Pick a good terminal

The default Ubuntu console window from wsl --install works, but it has limited font support and no tab bar. For initech, use one of these instead:

Windows Terminal (recommended, free from Microsoft Store) — handles glyphs, true color, and lets you split panes alongside PowerShell tabs
WezTerm — cross-platform, GPU-accelerated, scriptable
Alacritty with a WSL2 launcher entry

To open Windows Terminal directly into your Ubuntu shell, install it from the Microsoft Store, then click the v arrow next to the new-tab button and pick Ubuntu from the dropdown. Set Ubuntu as the default profile in Settings if you want every new tab to land in WSL2.

Gotchas

Project location. Keep your code under your Linux home directory (~/myproject), not under /mnt/c/. File access from WSL2 to the Windows drive crosses a translation boundary and is much slower. If you need to open a Windows file from WSL2, use /mnt/c/Users/<you>/....

Clipboard. WSL2 does not auto-share the clipboard between Linux and Windows. The simplest path is to copy text out of Ubuntu by piping to clip.exe (a Windows binary that WSL2 can call directly):

$ cat file.txt | clip.exe

Pasting in Windows Terminal works as expected — Ctrl+Shift+V. If you want Linux-side copy/paste behavior (xclip, wl-copy) inside the WSL2 shell, you need to install one of those tools and configure WSLg or X11 forwarding. For most course work, clip.exe + Windows Terminal selection is enough; reach for xclip only if you have a specific Linux app that calls it.

Networking. initech listens on localhost by default. WSL2 forwards localhost to Windows automatically, so any browser on Windows can reach the web companion at localhost:9100. On corporate networks behind a firewall, you may need to allow WSL2 traffic in your VPN or zero-trust agent.

Persistence. Closing the Ubuntu window does not kill running processes. Closing the WSL2 instance with wsl --shutdown does. If you start initech, close Windows Terminal, and reopen it, your initech session may still be running.

Troubleshooting

"WslRegisterDistribution failed with error: 0x80370102". Virtualization is disabled in BIOS. Reboot, enter BIOS/UEFI setup, enable Intel VT-x or AMD-V (and "SVM Mode" on AMD), save, and retry.

"The Windows Subsystem for Linux instance has terminated". Run wsl --update in PowerShell, then restart WSL with wsl --shutdown followed by reopening the Ubuntu terminal.

curl prints "command not found". The base Ubuntu image lacks curl. Run sudo apt update && sudo apt install -y curl and try again.

initech says "Terminal too small". WSL2 launched in a tiny console. Resize the window or switch to Windows Terminal. initech needs at least 80 columns by 24 rows.

Glyphs render as boxes. Your terminal font does not include the characters initech draws. Install a Nerd Font (JetBrainsMono Nerd Font works well) and set it as the Ubuntu profile font in Windows Terminal settings.

Permissions errors writing under /home. WSL2 sometimes mounts /home read-only after a corrupted update. Run wsl --shutdown from PowerShell and reopen Ubuntu. If that does not fix it, see the WSL troubleshooting docs.

What's next

You have a Windows machine running initech end to end. From here:

Getting started for the rest of the first-session walkthrough
Configuration to customize roles and permissions
Communication for agent-to-agent messaging patterns
Troubleshooting for non-Windows-specific issues

Getting started walkthrough

Last updated: April 2026