How to Install Moltbot on Windows (WSL2 Required)

Let me get the bad news out of the way immediately.

Moltbot does not run on native Windows. Not in PowerShell, not in cmd.exe, not in Git Bash. You need WSL2. That's the Windows Subsystem for Linux, version 2. There's no way around this.

I know that's annoying. Plenty of people have asked for native Windows support. Maybe it'll happen someday. But right now, WSL2 is the path. And honestly? Once you have WSL2 set up, it works really well. You might even start using it for other things too.

What is WSL2?

If you've never heard of it: WSL2 lets you run a real Linux environment inside Windows. Not a VM in the traditional sense -- it's tighter than that. Microsoft built it into Windows itself. You get a Linux terminal, a Linux filesystem, Linux tools. But it shares your Windows network stack and can access your Windows files.

It's free. It's built into Windows 10 (version 2004+) and Windows 11. You just need to turn it on.

Step 1: Enable WSL2

Open PowerShell as Administrator. Right-click the Start button, find "Terminal (Admin)" or "PowerShell (Admin)." This won't work without admin privileges.

Run this:

wsl --install

That's it. One command. Microsoft made this really easy. It installs WSL2 and Ubuntu by default.

You'll need to restart your computer after this. Yes, really. Do it.

After the restart, a Ubuntu terminal window should pop up automatically asking you to create a Linux username and password. Pick whatever you want -- this is separate from your Windows login. Don't forget the password. You'll need it for sudo commands.

If the Ubuntu window doesn't pop up automatically, find "Ubuntu" in your Start menu and open it manually.

Verifying WSL2

Open PowerShell and run:

wsl --list --verbose

You should see something like:

  NAME      STATE           VERSION
* Ubuntu    Running         2

The important part is VERSION 2. If it says version 1, you need to convert it:

wsl --set-version Ubuntu 2

This takes a few minutes. Wait for it.

Step 2: Set Up Your Linux Environment

Open your Ubuntu terminal (find it in the Start menu, or just type wsl in PowerShell).

You're now in Linux. Everything from here is standard Linux stuff.

Update packages first:

sudo apt update && sudo apt upgrade -y

This takes a while the first time. Go make coffee or something.

Install Node.js 22+

Don't use the Ubuntu default Node.js -- it's usually ancient. Use nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Close and reopen your Ubuntu terminal. Then:

nvm install 22
nvm use 22
nvm alias default 22

Verify:

node --version

Should say v22.x.x or higher. If it still shows an old version, make sure you restarted your terminal after installing nvm. This gets people every single time.

Step 3: Install Moltbot

Still in your Ubuntu terminal:

npm install -g moltbot@latest

Check it worked:

moltbot --version

Should say v2026.1.24 or newer. If you get "command not found," the npm global bin directory isn't in your PATH. Fix it:

export PATH="$PATH:$(npm config get prefix)/bin"
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc

Step 4: Run the Onboarding

moltbot onboard --install-daemon

The onboarding wizard walks you through configuration -- API keys, agent settings, etc. Answer the questions. You can change everything later.

The --install-daemon flag installs the Moltbot daemon as a background service. In WSL2, this works slightly differently than on a native Linux machine since WSL2 doesn't use systemd by default in older versions. Moltbot handles this, but if you run into issues, moltbot doctor will tell you what's going on.

Step 5: Start the Dashboard

moltbot dashboard

Now here's a nice thing about WSL2: you can access http://127.0.0.1:18789/ directly in your Windows browser. Chrome, Edge, Firefox on Windows -- they can all reach WSL2's loopback address. No port forwarding needed.

Open your browser (the Windows one, not inside WSL) and go to:

http://127.0.0.1:18789/

You should see the Moltbot dashboard. Type a message. Get a reply. Done.

Step 6: Verify Everything

Run the diagnostic tool:

moltbot doctor

This checks:

• Node.js version
• Daemon status
• Config file validity
• Network connectivity
• And a bunch of other stuff

If everything passes, you're golden. If something fails, it tells you exactly what to fix. I genuinely love this tool. Saved me hours of debugging.

Working with Files Between Windows and WSL2

This is the part that confuses people. You have two filesystems now: Windows and Linux.

Your Windows files are accessible from WSL2 at /mnt/c/ (for the C: drive), /mnt/d/ (for D:), etc.

Your Linux files live in the WSL2 filesystem, usually under your home directory ~/.

For Moltbot, I recommend keeping your projects in the Linux filesystem. It's faster. The Windows filesystem works but it's noticeably slower for file-heavy operations because of the translation layer between NTFS and ext4.

So if you want Moltbot agents to work on your code:

# Good - fast
~/projects/my-app/

# Works but slower
/mnt/c/Users/YourName/Documents/my-app/

Accessing the Dashboard from Windows

Like I said, http://127.0.0.1:18789/ just works in your Windows browser. Microsoft made WSL2 networking share the host's loopback, which is really convenient.

If for some reason it doesn't work (some corporate VPN setups mess with WSL2 networking), try:

# In WSL2, find your IP
ip addr show eth0 | grep inet

Use that IP address instead of 127.0.0.1 in your Windows browser.

Running Moltbot on Startup

WSL2 doesn't automatically start when Windows boots. And even when it does start, your login shell doesn't run automatically. So the daemon might not be running when you expect it to be.

A few options:

Option A: Just open Ubuntu from the Start menu. The daemon should start automatically once your WSL session is active.

Option B: Add WSL to Windows startup. Create a shortcut to wsl in your Startup folder (shell:startup). This starts WSL2 when you log in.

Option C: Use Windows Task Scheduler. Create a task that runs wsl -d Ubuntu -u yourusername -- moltbot daemon start at login. A bit fiddly to set up but it works reliably.

Honestly, Option A is fine for most people. You're going to open your terminal anyway.

Building from Source on WSL2

Same as any Linux system:

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build
pnpm build

Install pnpm first if you don't have it:

npm install -g pnpm

Build times in WSL2 are decent. Not as fast as native Linux but way faster than doing anything on the Windows filesystem.

Windows Terminal

Quick sidebar: if you're still using the default Ubuntu terminal window that pops up, switch to Windows Terminal. It's Microsoft's modern terminal app. Tabs, split panes, GPU-accelerated rendering. It automatically detects your WSL2 distributions and adds them as profiles. Way nicer experience.

You can get it from the Microsoft Store for free. Or it might already be installed on Windows 11.

Common Windows/WSL2 Issues

WSL2 won't install

Make sure virtualization is enabled in your BIOS/UEFI. It's usually called "Intel VT-x" or "AMD-V." Most modern machines have it enabled by default, but some laptops ship with it off.

Also make sure you're on Windows 10 version 2004 or later, or Windows 11.

"Cannot connect to 127.0.0.1:18789" from Windows browser

Some VPN software messes with WSL2 networking. Try disconnecting your VPN temporarily to test.

If that's the issue, you can configure your VPN to exclude local/loopback addresses. Check your VPN's docs.

Daemon keeps stopping

WSL2 has an idle timeout. If you close all WSL terminals and nothing is keeping WSL alive, it might shut down after a while, taking the daemon with it.

Fix: keep a WSL terminal open, or configure WSL to stay running. In Windows 11, you can add to %USERPROFILE%/.wslconfig:

[wsl2]
networkingMode=mirrored

[boot]
command="service moltbot start"

The boot command feature requires a fairly recent Windows build. Check Microsoft's docs for availability.

File permissions are weird

WSL2 and Windows have different permission models. If you see permission errors on files in /mnt/c/, it's the translation layer being awkward. Work in the Linux filesystem (~/) instead.

Node.js version issues

If node --version shows an old version even after nvm install:

source ~/.bashrc
nvm use 22

Make sure nvm's init script is in your .bashrc. The nvm installer should have added it, but sometimes it goes to .profile instead.

Everything else

moltbot doctor

You know the drill by now.

Is WSL2 Really Necessary?

Yeah. Sorry. Moltbot relies on Unix-y things -- process management, filesystem semantics, shell scripting conventions -- that don't translate cleanly to native Windows. WSL2 gives you a real Linux kernel, which is what Moltbot needs.

The good news: WSL2 is actually good. It's fast, it's well-integrated with Windows, and Microsoft keeps improving it. Once you get over the initial setup, you barely notice you're running Linux inside Windows.

And who knows, you might end up doing more and more stuff in WSL2. A lot of developers have. It's pretty great for general development work too.

Go build something.