Skip to content
Orbit Docs

Linux Projects (WSL)

Linux project execution lets Orbit drive a project that lives inside WSL Ubuntu — files, commands, agents, dev servers, builds, and releases — while the Orbit window itself keeps running on Windows. It exists for projects that need a Linux-native toolchain: a build that assumes systemd, a package that won’t compile under Windows paths, a CLI agent that only ships a Linux binary.

The one rule that matters

Section titled “The one rule that matters”

The project must already exist inside Ubuntu — for example /home/user/projects/my-app. Orbit does not move, copy, convert, or sync a Windows project into Linux. If you point Orbit at a Windows-side path, routing rejects it outright: C:\..., /mnt/c/..., \\wsl$, and \\wsl.localhost are all invalid Linux-routed project locations. Clone or create the project from inside Ubuntu first, then connect Orbit to it.

The guided setup

Section titled “The guided setup”

Setup Checklist → Set up a Linux project (also reachable from Project Settings → Run this project in Linux as How Linux projects work) walks through six checks in order:

  1. WSL2 and a supported Ubuntu installation — detected read-only via wsl.exe --list --verbose. Orbit never starts, stops, installs, updates, or otherwise changes a distribution from this check.
  2. The Orbit helper — its setup, lifecycle, compatibility, credentials, and update state inside Ubuntu.
  3. Project location — the Linux-native path rule above, with static clone/create examples.
  4. Linux-local coding agents — install and authentication state for each CLI, reported as one of not_installed, sign_in_required, ready, or unavailable.
  5. Routing handoff — the guide opens the existing Project Settings routing picker; it does not maintain a second routing state.
  6. A persistent ready check — return to this step any time to re-verify or troubleshoot.

If Ubuntu isn’t installed yet, the guide shows the install command wsl --install -d Ubuntu-24.04 for you to copy — it is display-only, attributed as a verified Microsoft command, and Orbit never runs it for you. You’ll need to restart Windows afterward.

What’s still Windows-only

Section titled “What’s still Windows-only”

Memtrace Govern is experimental and unavailable under WSL. This does not affect ordinary Linux project work — agents, Git, files, servers, and builds all function normally; only Govern is gated.

Next

Section titled “Next”