Skip to content
START HERE · NO WEBSITE LOGIN NEEDED

Install your own workspace.

Choose your machine, follow the steps, and verify the result. You can switch to a compact reference whenever you are ready.

Public alpha. MSO operates with its runtime user’s authority. Review the installer source and use a normal non-root account.

Native host

Linux

VPS, home server, workstation, container-like Linux hosts, and always-on production.

Before you begin

  • Use a normal non-root user with sudo when package installation is needed.
  • Keep about 2 GB free for dependencies and the production build.
  • The installer handles supported Node/Bun/build prerequisites where possible; manual Node/Bun links are included below for recovery.
  • Keep the default 127.0.0.1 bind unless you deliberately put a protected HTTPS layer in front.
  1. 1

    Open a terminal as your normal user

    Do not switch to root. MSO host actions execute with the runtime user's authority.

    Linux · step 1
    whoami
id -u
  2. 2

    Run the canonical installer

    This installs or updates the checkout, validates the CLI, builds production, creates owner auth on first install, and uses systemd only when it is actually available.

    Linux · step 2
    curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
  3. 3

    Complete onboarding

    Connect an AI provider, choose the model/preset, and optionally add managed apps or reviewed skills.

    Linux · step 3
    mso onboard
mso skills available
  4. 4

    Verify the host runtime

    Doctor should report the actual Linux capabilities instead of assuming the install worked.

    Linux · step 4
    mso --version
mso doctor
mso -h

    Expected: doctor reports host capabilities and any remaining setup issues. Investigate errors before continuing.

  5. 5

    Open the workspace

    Start or open the browser workspace. The raw app stays on loopback by default.

    Linux · step 5
    mso web

    Local browser: http://127.0.0.1:4005

  6. 6

    Add protected remote access when needed

    Prefer Tailscale Serve or a named HTTPS reverse-proxy/tunnel. Do not publish the raw shell port directly.

    Linux · step 6
    tailscale serve 4005

    Cloudflare Tunnel is also supported as an optional gateway adapter; see the official link below.

Finish browser pairing

Use the owner password created during setup. A new browser can show “pending approval”. From the owning host terminal, list devices and approve the exact ID displayed by that browser:

List pending devices
mso device pending
Approve a browser (replace the ID)
mso device approve <deviceId> "my laptop"

Replace <deviceId> first. Stay on the same browser URL, then check approval again. Pairing and access details →

Something did not work? Troubleshooting for Linux
  • Run mso doctor --fix for safe local repairs, then rerun mso doctor.
  • If node-pty fails to compile, confirm a C/C++ compiler, make, Python 3, and supported Node are available.
  • If login loops on a remote IP, use HTTPS or tunnel to localhost; MSO's session cookie is Secure.
Full troubleshooting guide →
Official resources and full platform reference
Next: configure your workspace →Already installed? Update guide