Deploy and Host Orca Server on Railway

Built for an LLM agent to deploy and use. There is no setup page to open: the server starts paired-ready, prints its pairing link in the deploy log, and the contract below lists every address, variable name and one script that pairs a client and checks the connection.

Orca is an open-source (MIT) workspace for running a fleet of coding agents, such as Claude Code and Codex, with your own subscriptions. Besides the desktop app, Orca runs as a headless runtime server: a remote machine that holds the repositories, worktrees, terminals and agent sessions, while any paired client (the Orca desktop app, the web client, the phone app or the orca command line) drives it over a WebSocket. Terminals survive a server restart.

About Hosting Orca Server

This template runs one service: the official Orca Linux release (v1.4.252) in a small wrapper image, pinned by digest, started with orca serve, with a volume on /home/orca. The volume holds the runtime's database, its sealed credentials, the paired devices and everything the agents clone, so pairings and work survive redeploys. The wrapper listens on Railway's injected PORT, advertises the service's public wss:// address so paired clients connect to the right place, fixes the volume's ownership at boot and then runs Orca as an unprivileged user. The server also serves Orca's web client at the public URL.

Agent contract

Public URL: ORCA_PUBLIC_URL (https:// plus the service's RAILWAY_PUBLIC_DOMAIN). It serves the Orca web client; the WebSocket endpoint is ORCA_WS_URL (wss:// plus the same domain).
Private URL: http://orca.railway.internal:8080 (the web client and the WebSocket share this port).
Credentials: the pairing link orca://pair?code=.... It is generated by the server on first boot, stored on the volume and stable across restarts and redeploys. It is not a template variable; it is printed on the line Pairing URL: of the deploy log and also written to /home/orca/pairing-url.txt inside the container (mode 600). Anyone holding it can drive this runtime, so treat it like a password.
Auth: a client presents the pairing link once with orca environment add --name NAME --pairing-code "$PAIR"; the link carries the device token and the server's public key, and later calls use --environment NAME.
Health: GET / returns 200 without credentials.

# needs: the Railway CLI logged in and linked to the project, and the Orca CLI (`orca`, bundled with the
# Orca desktop app; the image ghcr.io/bon5co/orca ships it as `orca-ide`), and ORCA_PUBLIC_URL set
curl -s -o /dev/null -w "health: %{http_code}\n" "$ORCA_PUBLIC_URL/"
PAIR=$(railway logs --service orca --deployment --lines 200 | grep -o 'orca://pair?code=[A-Za-z0-9_%=-]*' | tail -1)
orca environment add --name railway --pairing-code "$PAIR" --json | grep '"endpoint"'
orca status --environment railway --json | grep -E '"reachable"|"connectionState"|"appVersion"'

A fresh deploy prints health: 200, the line "endpoint": "wss://YOUR-DOMAIN", and then "reachable": true, "connectionState": "connected" and the Orca version.

The pairing link grants full control of the runtime. The server logs the warning "Anything that can reach this port can attempt pairing", so keep the link out of public places. Deploys of this template each get their own volume and their own link.

Why Deploy Orca Server on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Orca Server on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - no deployer fields, a contract block and one working pairing script.
Always on - agent sessions and terminals keep running when your laptop is closed.
State survives redeploys - pairings, repositories and sessions live on a volume, and the image is pinned by digest.
Public by default - one HTTPS and WebSocket address that the desktop app, the web client and a phone can all reach.

Common Use Cases

Remote coding-agent host - run Claude Code, Codex or other CLI agents on a server and drive them from any paired client.
Shared agent runtime for a team - one runtime holds the repositories and agent sessions; each person pairs their own device.
Agent orchestration from code - an orchestrating agent pairs through the orca CLI and starts worktrees, terminals and agent sessions programmatically.

Dependencies for Orca Server Hosting

One Railway volume on /home/orca, created by the template.

Deployment Dependencies

Implementation Details

Variable	Purpose
`ORCA_PUBLIC_URL`	HTTPS address of the web client.
`ORCA_WS_URL`	WebSocket address a paired client connects to.

The image entrypoint runs as root only to chown the volume, then starts orca serve --port $PORT --bind 0.0.0.0 --pairing-address wss://$RAILWAY_PUBLIC_DOMAIN as the orca user and copies the pairing link from the server output into /home/orca/pairing-url.txt.