Skip to content

WINDOWS_WSL.md

Latest commit

 

History

History
396 lines (241 loc) · 8.05 KB

WINDOWS_WSL.md

File metadata and controls

396 lines (241 loc) · 8.05 KB
Raw

Windows Users: Run Vibe Remote with WSL from Scratch

This guide is written for Windows users who have never used WSL before.

If someone told you "use WSL" but you do not know where to install it, how to open it, or which window should run the commands, follow this guide step by step.

Short Version

If you use Vibe Remote on Windows, the recommended setup is:

  • Windows: browser, Slack, Discord, Telegram, WeChat, Lark/Feishu
  • WSL: Vibe Remote, Claude Code / Codex / OpenCode, your code repository

In plain terms:

  • You still use Windows for your browser and chat apps
  • But the commands and agent runtime run inside a Linux terminal window

That Linux terminal window is WSL.

What Is WSL

WSL stands for Windows Subsystem for Linux.

You can think of it like this:

  • Your computer is still Windows
  • But Windows gives you a Linux command-line environment
  • You can run many developer tools inside that Linux environment

For Vibe Remote, which needs Python, Node, and agent CLIs, WSL is often smoother than running everything natively on Windows.

You Will Use Two Different Windows

This is the part that confuses most first-time users.

Window 1: PowerShell

PowerShell is only needed at the beginning to install WSL itself.

Think of it as:

  • the Windows terminal used to install WSL

Window 2: Ubuntu Terminal

The Ubuntu terminal is where you will actually install and run Vibe Remote.

Think of it as:

  • the Linux terminal used for daily Vibe Remote usage

Commands like these:

curl ...
vibe
which codex

should be run in the Ubuntu terminal, not in PowerShell.

Step 1: Install WSL

1. Open PowerShell

In Windows:

  1. Open the Start menu
  2. Search for PowerShell
  3. Find Windows PowerShell or PowerShell
  4. Right-click it
  5. Choose Run as administrator

2. Run the WSL install command

In PowerShell, run:

wsl --install

This command usually does two things:

  • installs WSL
  • installs a default Linux distribution, usually Ubuntu

If Windows asks you to restart, restart your computer.

3. After restart, look for Ubuntu

When installation is done, your Start menu will usually contain:

  • Ubuntu

If you do not see it, search for:

  • Ubuntu
  • Windows Terminal

Step 2: Launch Ubuntu for the First Time

1. Open Ubuntu

Open the Start menu and launch:

  • Ubuntu

The first launch may take from a few seconds to a few minutes while it finishes Linux setup.

2. Create a Linux username and password

Ubuntu will ask you to create:

  • a Linux username
  • a Linux password

This is your WSL Linux account, not your Windows account.

It may look like this:

Enter new UNIX username:
Enter new UNIX password:

After this step, your Ubuntu terminal is ready to use.

Step 3: Confirm You Are in the WSL Terminal

When you see a prompt like this, you are usually inside Ubuntu:

yourname@DESKTOP-XXXX:~$

Typical signs are:

  • your Linux username
  • a tilde ~
  • a dollar sign $

From this point on, the remaining commands in this guide should be run in this Ubuntu terminal.

Step 4: Install Basic Tools Inside Ubuntu

In the Ubuntu terminal, run:

sudo apt update
sudo apt install -y curl git

If it asks for a password, enter the Linux password you created earlier.

Step 5: Create a Working Directory

It is better to keep your code inside WSL's Linux filesystem, not under your Windows C: drive mount.

In the Ubuntu terminal, run:

mkdir -p ~/work
cd ~/work

Recommended path:

/home/<your-linux-username>/work

Not recommended for long-term daily use:

/mnt/c/Users/...

That path usually has more performance and file-behavior edge cases.

Step 6: Install Vibe Remote

Now you are in the right place.

In the Ubuntu terminal, run:

curl -fsSL https://raw.githubusercontent.com/cyhhao/vibe-remote/master/install.sh | bash

After installation finishes, still in the same Ubuntu terminal, run:

vibe

Again, this command should be run:

  • in the Ubuntu terminal
  • not in PowerShell
  • not in CMD

Step 7: Open the Web UI in Your Windows Browser

After Vibe Remote starts, the default Web UI address is:

http://127.0.0.1:5123

Open that address in your normal Windows browser:

  • Chrome
  • Edge
  • Firefox

If no browser opens automatically, open it manually and go to:

http://127.0.0.1:5123

Step 8: Install Agent CLIs Inside WSL

If you want to use Claude Code, Codex, or OpenCode, install those CLIs inside the Ubuntu terminal too.

Do not assume a Windows installation is enough.

Why:

  • Vibe Remote is running inside WSL
  • it can only directly use commands available inside WSL

After installation, check from Ubuntu:

which claude
which codex
which opencode

If you see output like this, the CLI is available inside WSL:

/home/yourname/.local/bin/codex

Step 9: Set the Default Working Directory

In the Vibe Remote Web UI, set the default working directory to a WSL path such as:

/home/yourname/work

Avoid using these as your main default path:

C:\Users\...

or:

/mnt/c/Users/...

If you must access Windows files, /mnt/c/... can still be used temporarily, but it is better not to make it your long-term default.

A Simple Daily Workflow

Here is the easiest mental model for daily usage.

1. Open Ubuntu

Start menu -> search Ubuntu -> open it

2. Go to your project

In the Ubuntu terminal:

cd ~/work/your-project

3. Start Vibe Remote

In the Ubuntu terminal:

vibe

4. Open the browser

In your Windows browser, open:

http://127.0.0.1:5123

5. Use your chat app normally

After that, continue using Slack, Discord, Telegram, WeChat, or Lark as usual.

How to Open WSL Again Later

You do not need to reinstall anything every time.

Later, whenever you want to continue:

  1. Open the Start menu
  2. Search for Ubuntu
  3. Open Ubuntu
  4. Run:
cd ~/work/your-project
vibe

Common Questions

1. Which window should run vibe?

Use the Ubuntu terminal, not PowerShell.

2. Which window should run curl ... | bash?

Use the Ubuntu terminal, not PowerShell.

3. Do I still need PowerShell later?

Usually only for the original WSL installation.

For day-to-day Vibe Remote use, you will mostly work in Ubuntu.

4. What if http://127.0.0.1:5123 does not open?

First check whether vibe is still running in the Ubuntu terminal.

If Vibe Remote already exited, the page will not open.

You can check from Ubuntu:

vibe status

5. What if agent installation from the Web UI fails?

If Vibe Remote runs in WSL and you use the Web UI from a Windows browser, some local security checks may make certain install buttons fail.

If that happens, install the CLI manually in the Ubuntu terminal, then go back to the Web UI and fill in the path or rerun detection.

6. Do I need Linux knowledge for this?

No.

For basic usage, you only need to know how to:

  • open Ubuntu
  • use cd to enter a folder
  • run vibe
  • open http://127.0.0.1:5123 in your browser

That is enough to get started.

Quick Checklist

If all of these are true, your WSL setup is working:

  • you can open Ubuntu from the Start menu
  • Ubuntu shows a prompt like yourname@DESKTOP-XXXX:~$
  • you can run vibe inside Ubuntu
  • you can open http://127.0.0.1:5123 in your Windows browser
  • which codex, which claude, and which opencode work inside Ubuntu

Official References

If you want the Microsoft documentation:

Final Recommendation

If you are a Windows user and you are not sure whether native Windows will be stable enough for every agent CLI, the safest setup is:

  • install WSL on Windows
  • open Ubuntu
  • install and run Vibe Remote inside Ubuntu
  • open http://127.0.0.1:5123 from your Windows browser

That is usually the least painful path.