> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relaycloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a self-managed server

> Install RelayCloud on an existing macOS or Linux device to connect it as a self-managed server.

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

## Connect the server

<Steps>
  <Step title="Install the orchestrator">
    Run the published installer:

    ```sh theme={null}
    curl -fsSL https://relaycloud.app/install.sh | sh
    ```
  </Step>

  <Step title="Run setup">
    Start the setup flow:

    ```sh theme={null}
    relaycloud setup
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Background service behavior

The background service runs the following command in the background:

```sh theme={null}
relaycloud start --workspace-root <home-directory>
```

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:

```sh theme={null}
relaycloud service install
```

### macOS

RelayCloud installs a LaunchAgent at:

```text theme={null}
~/Library/LaunchAgents/app.relaycloud.plist
```

It starts in the GUI login session and does not run before login or survive logout.

### Linux

RelayCloud installs a systemd user unit at:

```text theme={null}
${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/app.relaycloud.service
```

The Orchestrator enables lingering for your user if possible so the service keeps running after you log out.

## Check status and troubleshoot

```sh theme={null}
relaycloud status
relaycloud status --json
relaycloud service status
```

The service logs are stored under:

```text theme={null}
${XDG_STATE_HOME:-$HOME/.local/state}/relaycloud/logs/
```

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`:

```sh theme={null}
curl -fsSL https://relaycloud.app/install.sh | sh -s -- --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.