OrcaORCA
Star us5.4k

Remote Orca Servers

Run Orca on another machine and connect to it from your desktop or browser client.

Remote Orca Servers let one Orca runtime run on a dev box, GPU host, or always-on machine while another Orca client connects to it. Use this when the server machine should own projects, terminals, provider checks, and agent sessions instead of routing everything through your laptop.

Start a headless server

Install the Orca desktop app on the machine that should do the work, then register the bundled CLI from Settings → General → Orca CLI. The examples below use orca; on Linux the registered command may be orca-ide.

From the server machine, run:

orca serve --pairing-address <server-ip-or-tailscale-hostname>

orca serve starts an Orca runtime server without opening a desktop window. It runs in the foreground, prints the runtime endpoint plus a pairing URL, and stops when you press Ctrl-C. Use --pairing-address for the address clients should use to reach the server, such as a LAN IP, Tailscale hostname, SSH-forwarded host, or tunnel hostname.

If you need a fixed port, pass it explicitly:

orca serve --port 6768 --pairing-address devbox.tailnet-name.ts.net

Clients must be able to reach that host and port. For browser clients, orca serve also prints a browser URL with the pairing data embedded when the web client bundle is available. For mobile pairing, add --mobile-pairing.

Share a running desktop app as a server

If the server machine already has the headed Orca app open, use the in-app sharing flow instead:

  1. Open Settings → Remote Orca Servers.
  2. Under Advertise this app as a server, click New Link.
  3. Copy the generated access link.

This advertises the running desktop app as the server, so you do not need a separate orca serve process.

Connect from another desktop client

On the client machine:

  1. Open Settings → Remote Orca Servers.
  2. Click Add Server.
  3. Give the server a name.
  4. Paste the pairing URL printed by orca serve or the access link generated by New Link.
  5. Click Add Server, then connect to the server from the same pane.

After pairing, Orca lists the server in Remote Orca Servers with its connection state. Use Advanced → Default runtime only when you want new server-routed projects, terminals, and provider checks to default to that remote server.

Verify it worked

Switch to the remote server, then open or create a project from that server context. The server machine now owns the project's terminals, agent sessions, provider checks, and runtime state; the client is the UI you use to control it.

When to use SSH instead

Use SSH worktrees when your local desktop app should stay in charge while individual worktrees run through SSH. Use Remote Orca Servers when the other machine should host the Orca runtime itself.

Next steps