Remote Orca Servers

Keep Orca running on another computer and connect from your laptop.

A Remote Orca Server lets one computer do the work while another computer provides the UI. The server keeps the projects, worktrees, terminals, tabs, provider accounts, and agent sessions. Your laptop connects to that running Orca instance.

The easiest setup is the Orca desktop app on both computers, connected through Tailscale. You do not need to run orca serve for this path.

What runs where

Client computer · Orca client
  Shows the UI and sends your input
                 │
                 │ private network route
                 ▼
Server computer · Orca server
  Stores repos and worktrees
  Runs terminals and agents

Install and authenticate Codex, Claude Code, OpenCode, git, and any provider CLIs on the server computer. A login on your laptop does not automatically carry over to the server.

On a headless orca serve host, register managed Claude/Codex accounts from the server shell (the remote client disables Add account):

orca account add --agent claude
orca account add --agent codex
orca account list

Install or refresh agent skills without a Settings UI:

orca skills install --skill orca-cli --skill orchestration
orca skills update --all

Bots that run on the server reach Slack, GitHub, Linear and webhooks through the server's own sign-in to Orca Cloud, which a sign-in on your laptop does not carry over to. Sign the server in from its shell, where orca auth login prints a link and a code to approve in any browser, or from the bot's Connectors tab in the desktop app, where the button reads Sign in on and the server's name:

orca auth login
orca auth status

You need:

  • Orca installed and updated on both computers
  • Tailscale installed on both computers
  • Both computers signed in to the same tailnet
  • The server computer awake, online, and running Orca

Tailscale gives the server a private address that usually starts with 100.. Orca puts that address first in its connection-address picker.

On the computer that should keep the sessions running:

  1. Open the Orca desktop app.
  2. Open Settings → Remote Orca Servers.
  3. Under Advertise this app as a server, click New Link.
  4. For Connection address, select the Tailscale address. It usually looks like 100.x.y.z.
  5. Click Generate Access Link.
  6. Copy the link under Pair another Orca client.

If the Tailscale address is missing, confirm Tailscale is connected and click the refresh button beside Connection address.

2. Add the server on your laptop

On the computer you want to use as the client:

  1. Open Settings → Remote Orca Servers.
  2. Click Add Server.
  3. Enter a recognizable name, such as Remote Server.
  4. Paste the access link from the server.
  5. Click Add Server.
  6. If the saved server shows Disconnected, click Connect.
On the client: name the server, paste its access link, and add it. The pairing code is redacted in this example.
On the client: name the server, paste its access link, and add it. The pairing code is redacted in this example.
Share an Orca desktop runtime with another client over a private network.
Share an Orca desktop runtime with another client over a private network.

Adding a server saves it without forcing every new project onto it. Open Advanced → Default host for new projects only when you want server-routed projects, terminals, provider checks, and browser or mobile handoff to use that server by default.

Use the remote server

Once the server shows Connected, select it or one of its projects and use Orca normally. Terminals, agent processes, files, worktrees, and session state live on the server computer.

When several paired clients share that server, the sidebar filter can offer Hide other-client workspaces so this device only lists workspaces it created. See Worktrees → Sidebar layout.

That means:

  • agents keep running when the client laptop sleeps or disconnects;
  • the server needs the repository, tools, and credentials used by those agents;
  • the server must stay awake and connected to the tailnet;
  • reconnecting the client or reopening Orca returns you to the server-owned workspace, tab, and visible-pane state without duplicating paired tabs;
  • projects you delete on the server disappear from every paired client's sidebar (no permanent ghost rows).

Access and security

Orca creates a separate, revocable token for each paired client. The server lists these under Shared Server Access.

  • Click the trash button beside a grant to revoke it. Active clients using that grant are disconnected immediately.
  • Generating another link replaces the previous unused link. Clients that already paired keep their own grants until you revoke them.
  • Keep Tailscale ACLs or grants as narrow as your setup allows.
  • Do not forward the Orca port directly to the public internet. Prefer Tailscale, WireGuard, a trusted LAN, SSH forwarding, or an authenticated tunnel.
  • Do not select 127.0.0.1 for another computer. That address only works on the server itself.

Alternative: orca serve

Use orca serve when the host should run without the desktop window—for example, a headless Linux server or a service-managed VM. For a MacBook or desktop you can leave signed in, the in-app setup above is simpler.

Install Orca and its bundled CLI on the server, then run:

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

Use --bind <literal-ip> to choose the interface that accepts runtime connections. For a server reached through an SSH tunnel or reverse proxy, bind locally; use a Tailscale or LAN IP when the client should connect directly. --pairing-address still controls only the address embedded in pairing links. --mobile-pairing needs all interfaces, so use it without --bind or with --bind 0.0.0.0.

orca-ide serve --bind 127.0.0.1 --pairing-address 127.0.0.1

For example:

orca serve --pairing-address 100.64.1.20
# Linux
orca-ide serve --pairing-address 100.64.1.20

The command:

  • starts the Orca runtime without opening the desktop window;
  • on macOS, stays out of the Dock and the Cmd-Tab switcher until you open a desktop window from it;
  • runs in the foreground until you press Ctrl-C;
  • prints the bound endpoint and a runtime pairing URL;
  • uses --pairing-address only for the address clients should dial.

Paste the printed pairing URL into Settings → Remote Orca Servers → Add Server on the client.

orca serve accepts clients from localhost, LAN and Tailscale addresses, including addresses on one of the server's own network prefixes (for example a same-network global IPv6 address). It refuses other public internet addresses unless:

  • you pass --allow-public;
  • --pairing-address is a hostname or a public IP;
  • a paired client has already connected from a public address; or
  • clients paired before this check was added are still paired.

The startup log says which rule applies, and the first refused public address each hour is logged. Pass --refuse-public to refuse public addresses in every case, for example on a server whose older pairings would otherwise keep them accepted.

Add --port 6768 when a firewall, tunnel, or service definition requires a fixed port:

orca serve --port 6768 --pairing-address 100.64.1.20
# Linux
orca-ide serve --port 6768 --pairing-address 100.64.1.20

Use only one host mode at a time. If the Orca desktop app is already sharing that computer, do not start a second orca serve process for the same setup.

orca serve runs on Orca's own Node server (orcad) by default. If orcad can't serve on this computer, it uses the desktop app's server instead and prints one line saying why. On a packaged macOS app it uses the desktop app's server, so paired clients can still update it, unless you set ORCA_SERVE_RUNTIME=orcad (see A Mac reached only over SSH). To always use the desktop app's server, set ORCA_SERVE_RUNTIME=electron.

Install only the server on Linux

Each release also publishes the server alone for Linux x64 and arm64: orcad, the Node runtime it runs on, and the orca-ide CLI. It needs no desktop packages (GTK, X11, Xvfb), so it suits your own headless Linux servers, VMs and containers. It is about 60 MB to download, against 190 MB for the .deb. Download it, check it, and unpack it:

arch=$(uname -m | sed 's/x86_64/x64/; s/aarch64/arm64/')
base=https://github.com/stablyai/orca/releases/latest/download
curl -fsSLO "$base/orca-server-linux-$arch.tar.gz" -O "$base/orca-server-sha256sums.txt"
sha256sum --check --ignore-missing orca-server-sha256sums.txt
sudo mkdir -p /opt/orca-server
sudo tar -xzf "orca-server-linux-$arch.tar.gz" -C /opt/orca-server --strip-components=1
/opt/orca-server/bin/orca-ide serve --pairing-address <server-tailscale-ip-or-hostname>

To pin a release, replace latest/download with download/v<version>, and keep that release's checksum in your script rather than downloading it next to the archive. The server needs glibc 2.28 or newer (Ubuntu 20.04, Debian 10, RHEL 8 and later).

orca-ide serve takes the same flags as above, including --supervise under a service manager and --recipe-json. To update, stop the server, replace /opt/orca-server with a newer release, and start it again; paired clients cannot update it for you. For orca-ide serve service install, pass --command /opt/orca-server/bin/orca-ide or put /opt/orca-server/bin on PATH. A server-only install has no browser panes, dictation or paired web client, because those come with the desktop app.

Limit terminal memory on a Linux server

By default, nothing caps how much memory a terminal's processes use, so one runaway job can push the whole server into the kernel's out-of-memory killer. On Linux you can cap each terminal by setting these variables in the environment that starts orca serve (or in its service unit):

export ORCA_TERMINAL_MEMORY_MAX=16G      # memory per terminal, 256M or more
export ORCA_TERMINAL_MEMORY_SWAP_MAX=0   # swap per terminal; 0 means no swap
orca-ide serve --pairing-address 100.64.1.20
  • Each terminal already runs in its own systemd user scope. The limits become that scope's MemoryMax and MemorySwapMax.
  • When a terminal goes over its limit, the kernel kills its largest process. Typically that is the job, and the shell keeps running. The server and every other terminal keep running.
  • The limits are off by default because Orca can't know what a sensible limit is for your workloads.
  • They need systemd with cgroup v2 and a user manager that outlives logout (loginctl enable-linger <user>). If the host can't enforce a limit, Orca skips it, logs terminal-memory-limits in the terminal host log, and starts terminals without it.
  • Orca reads them only when its terminal host process starts. That process keeps running when orca serve restarts, so terminals keep their old limits until it restarts too, for example after the server reboots.
  • They have no effect on macOS or Windows.

Use the GPU on a Linux server

On Linux, orca serve turns off hardware acceleration by default, because most headless hosts have no GPU and a failing GPU process can stop the server from starting. Browser panes then render in software. If the host gives the Orca process a GPU (for example a render node such as /dev/dri/renderD128), set ORCA_SERVE_GPU=1 in the environment that starts orca serve (or in its service unit) to keep hardware acceleration on:

export ORCA_SERVE_GPU=1
orca-ide serve --pairing-address 100.64.1.20

This only stops Orca from turning the GPU off. Chromium may still render in software on Orca's own Xvfb, which has no GPU of its own; open chrome://gpu in a browser pane to check, and point DISPLAY at a GPU-backed X server if it reports software rendering. If you installed the server with orca serve service install, add the variable to the service unit yourself. If the server stops starting or browser panes crash with it set, unset it to go back to software rendering.

Copies of a machine image

Copies of a machine image share the server identity: the pairing key, the paired devices, and the installation id. Revoking a device on one copy leaves it working on the others, and the desktop app treats all copies as one server. Set ORCA_INSTANCE_ID per instance (for example the cloud-init instance id) in the environment that starts orca serve, or run orca serve reset-identity on each copy.

  • With ORCA_INSTANCE_ID set, Orca records the value with the server identity. If a later start sees a different value, Orca creates a new identity and removes all paired devices on that copy, so clients pair with it again.
  • The first value Orca sees on an existing server is only recorded, so setting the variable later keeps existing pairings. Use a value that stays the same across restarts of one instance; a value that changes on every boot forces a new pairing each time.
  • When ORCA_INSTANCE_ID is not set, Orca never changes the identity on its own.
  • If Orca cannot write the new identity (for example on a full or read-only disk), it keeps serving the current one unchanged, logs an error, and tries again on the next start.
  • orca serve reset-identity does the same reset on demand. Stop Orca on that machine first; the command asks for confirmation, or pass --yes.
  • Each reset moves the replaced files into a new folder under orca-identity-backups in the Orca data directory (the five most recent are kept). To undo an unwanted reset, stop Orca and copy the files from that folder back into the data directory.

Mobile from a headless server

For the Orca mobile app, request a mobile-scoped QR code and link:

orca serve --pairing-address 100.64.1.20 --mobile-pairing
# Linux
orca-ide serve --pairing-address 100.64.1.20 --mobile-pairing

Keep the phone on the same tailnet, open Orca Mobile, choose Pair, and scan the terminal QR code or paste the printed link.

Pair without restarting the server

orca pair asks the Orca already running on this machine for a new pairing, so you do not have to stop a service or restart orca serve. Run it on the server, as the user Orca runs as:

orca pair --mobile --address 100.64.1.20   # QR code and link for Orca Mobile
orca pair --address 100.64.1.20            # access link for another Orca
# Linux
orca-ide pair --mobile --address 100.64.1.20

It works the same against the desktop app, a foreground orca serve, or orca serve service install. Only the machine's own user can run it; paired clients and phones cannot create pairings.

A Mac reached only over SSH

On a packaged macOS app, orca serve uses the desktop app's server, which needs a desktop login: started from an SSH session with nobody logged in, it aborts at startup. To serve such a Mac, ask for Orca's Node server instead. It has no in-app updater, so update the app yourself (for example with brew upgrade --cask stablyai/orca/orca) and restart the server:

ORCA_SERVE_RUNTIME=orcad orca serve --pairing-address 100.64.1.20

Desktop app or orca serve?

Desktop app on the serverorca serve
Best forAn old laptop, Mac mini, or desktopA headless Linux box, VM, or managed service
SetupSettings and buttonsTerminal command and service configuration
Server windowOpenNone
Access linkNew Link → Generate Access LinkPrinted in the terminal
LifetimeWhile the desktop app is runningWhile the foreground process or service is running

Remote Orca Server or SSH?

Use SSH worktrees when Orca on your laptop should own the runtime and use another machine only to run selected worktrees and terminals.

Use a Remote Orca Server when the other machine should own the full Orca runtime and preserve shared sessions for desktop, browser, mobile, or automation clients.

See Ways to run Orca for the full comparison.

Troubleshooting

The Tailscale address is not listed

On the server, confirm Tailscale is connected, then click the refresh button beside Connection address. Both computers must be signed in to the same tailnet. A Tailscale IPv4 address usually starts with 100..

The server is disconnected

Confirm the server computer is awake, Orca is still running, and Tailscale shows both devices online. Check your tailnet ACLs or grants if one device cannot reach the other.

Update Orca on both computers if the server row reports an incompatible protocol version.

On the server, open Settings → Remote Orca Servers → Shared Server Access and revoke that grant. Generate a new link for the intended client.

The server cannot find an agent CLI

Install and authenticate that CLI on the server computer. Remote sessions use the server's PATH, home directory, and credentials—not the client's.

orca serve advertises the wrong address

Stop the command and restart it with an address the client can reach:

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

Do not use a wildcard address or 127.0.0.1 for a remote client.

Next steps