Skip to content
Orbit Docs

Set Up a Linux Project

This walks through routing a project to Linux. It assumes you already have (or are willing to install) WSL2 with Ubuntu.

Before you start

Section titled “Before you start”

Your project must already exist inside Ubuntu — for example /home/user/projects/my-app. Orbit will not move, copy, convert, or sync a Windows-side project into Linux for you. If you haven’t created it there yet, clone or mkdir it from an Ubuntu terminal first. Windows-side paths (C:\..., /mnt/c/..., \\wsl$, \\wsl.localhost) are all rejected when you try to route.

Steps

Section titled “Steps”
  1. Open Setup Checklist → Set up a Linux project (it stays available in the checklist while unset up), or go to Project Settings → How Linux projects work for an existing project.
  2. WSL2 + Ubuntu check — if nothing is detected, Orbit shows the copy-only install command wsl --install -d Ubuntu-24.04. Run it yourself in an elevated Windows terminal, then restart Windows. Come back to the guide and click Check again.
  3. Orbit helper check — the guide surfaces whatever helper state exists (not set up, stopped, offline, update required, incompatible) and hands you to the existing update flow if needed. This is the same helper updater used elsewhere in Orbit, not a separate one.
  4. Project location check — confirm your project’s Ubuntu path passes the location rule above.
  5. Agent check — for each Linux-local coding agent CLI, the guide reports not_installed, sign_in_required, ready, or unavailable. Install or authenticate inside Ubuntu as prompted; Orbit does not do this for you.
  6. Route the project — click Run this project in Linux in Project Settings. This opens Orbit’s normal routing picker; confirm the target and Orbit validates, locks, and switches the project’s execution target.
  7. Ready check — once all six checks pass, the guide shows a single ready state you can return to any time.

If routing fails

Section titled “If routing fails”

The guide gives distinct guidance for each of these instead of a generic error — click through from the failure and it opens the matching step directly:

  • WSL unavailable, or no supported Ubuntu installation
  • Helper not set up, stopped, offline, or needs an update
  • Incompatible Ubuntu version or configuration
  • Credentials locked
  • Agent CLI missing or needs sign-in
  • Project not yet registered, or already assigned to a different node
  • Active work is blocking the routing switch
  • A prior routing attempt needs recovery
  • The path you gave is a prohibited (Windows-side) location
Section titled “Related”