Skip to main content
Use this flow to connect an existing macOS or Linux device as a self-managed server.

​
Connect the server

1

Install the orchestrator

Run the published installer:
2

Run setup

Start the setup flow:
3

Sign in and name the server

The TUI presents the login screen, then asks you to name the server. Sign in to connect the device to the RelayCloud control plane.
4

Install the background service

Choose Install background service so RelayCloud runs in the background and you do not need to start it manually. Choose Not now if you want to run it manually or configure it later.
5

Import OpenCode

If the background service is ready, choose Import OpenCode. The Orchestrator discovers same-user OpenCode instances on loopback. Select which instances you want to onboard and provide Basic Auth credentials if prompted. RelayCloud verifies the connection and creates the Assistant for you.

​
Background service behavior

The background service runs the following command in the background:
If you chose not to install the background service, run this command in your terminal any time you want to make the server available through RelayCloud. You can install the background service later at any time:

​
macOS

RelayCloud installs a LaunchAgent at:
It starts in the GUI login session and does not run before login or survive logout.

​
Linux

RelayCloud installs a systemd user unit at:
The Orchestrator enables lingering for your user if possible so the service keeps running after you log out.

​
Check status and troubleshoot

The service logs are stored under:
Use relaycloud service restart after correcting a service or configuration problem. Setup screens also provide retry and back actions for authentication, device initialization, service installation, and OpenCode import failures.

​
Advanced install options

To prevent the installer from editing a shell profile, use --no-modify-path:
The installer places the binary at ${XDG_BIN_HOME:-$HOME/.local/bin}/relaycloud. If that directory is not already on your PATH, it adds a shell-specific entry when it can or prints the line you need to add manually. Open a new terminal after changing your profile.