Install on Linux and Headless Servers

Linux uses a headless archive for x64 and ARM64. It contains the connector, OpenCode, cloudflared, licenses, and a systemd user-service template. No GUI or desktop session is required.

Requirements

• Linux with glibc 2.39 or newer (for example Ubuntu 24.04 or Debian 13).
• x64 or ARM64. armv7 is not supported.
• An active Cloud Link subscription in OpenCode Mobile.
• A project directory that OpenCode can open.

The archive is the complete package. Keep the bundled executables together; do not copy only opencode-cloudlink out of it.

Download and extract

Download the archive for your architecture:

• Linux x64
• Linux ARM64

Verify the matching .sha256 sidecar, then extract:

sha256sum opencode-cloudlink_linux_amd64.tar.gz
# compare with the matching .sha256 sidecar
tar -xzf opencode-cloudlink_linux_amd64.tar.gz
cd opencode-cloudlink_linux_amd64
./opencode-cloudlink --version

The version output confirms the binary can run on this host.

Option 1: Use the install script

The release repository publishes an installer that verifies the archive checksum before writing files:

curl -fsSL https://raw.githubusercontent.com/alvarolorentedev/opencode-cloud-link-releases/main/install.sh -o install.sh
VERSION=<release-version> sh install.sh
# Optional custom location:
# DEST=/your/bin VERSION=<release-version> sh install.sh
opencode-cloudlink --version

Without VERSION, the script resolves the current release once and downloads that exact archive and checksum. The default destination is ~/.local/bin.

Option 2: Run from the extracted archive

Pair once in the foreground before installing a service:

./opencode-cloudlink run --working-directory /your/project

The connector prints a QR code and deep link. In OpenCode Mobile, open Settings → Cloud Link, subscribe or restore if needed, scan the code, and approve the device on the machine.

After pairing, the connector keeps running in the foreground. Press Ctrl+C to stop it. Pairing state and settings are saved outside the extracted directory.

Useful foreground options

# Choose the project folder OpenCode starts in.
./opencode-cloudlink run --working-directory /srv/project

# Use a custom machine name or control plane.
./opencode-cloudlink run --name build-server --control-plane https://api.opencodecloud.link

# Forget the saved pairing and start over.
./opencode-cloudlink run --reset

# Adopt an existing, trusted loopback OpenCode server instead of starting one.
./opencode-cloudlink run --adopt-opencode

Only use --adopt-opencode for a listener you trust. Loopback and health JSON do not prove who owns the process.

Option 3: Run as a systemd user service

1. Pair interactively once. Service mode requires saved pairing state.
2. Copy the archive’s opencode-cloudlink.service template into your user unit directory.
3. Set WorkingDirectory and any executable paths for your install.
4. Reload and enable the unit.

mkdir -p ~/.config/systemd/user
cp /path/to/extracted/archive/opencode-cloudlink.service ~/.config/systemd/user/
systemctl --user edit --full opencode-cloudlink.service

# Set WorkingDirectory to your project and adjust paths if needed.
systemctl --user daemon-reload
systemctl --user enable --now opencode-cloudlink.service

The template expects the tools in ~/.local/bin. Adjust it for a custom installation directory.

Logs and control

journalctl --user -u opencode-cloudlink.service -f
systemctl --user status opencode-cloudlink.service
systemctl --user restart opencode-cloudlink.service
systemctl --user stop opencode-cloudlink.service

Service mode uses foreground execution, needs no graphical session or secret service, and disables automatic tool downloads. Systemd restarts the process after five seconds if it exits, bounded to five starts per two minutes, so a permanent failure stops instead of looping.

Keep the service running after logout

A user service normally stops when the last session ends. Enable lingering if the machine should keep the connector available after logout:

loginctl enable-linger "$USER"

Keep awake on Linux

Settings → Power → Keep awake is off by default. On Linux it needs systemd-inhibit and a logind session. A headless service without a logind session leaves the setting inactive. It prevents automatic idle sleep only; the display may still sleep, and explicit or closed-lid sleep is never overridden. The inhibitor is released on inactivity, disconnect, quit, and unexpected exit, and is not held on battery unless Keep awake on battery is enabled.

State and environment

The state directory is ~/.config/opencode-cloudlink by default. Metadata is rust-state.json; secrets use a protected rust-secrets.json file with owner-only permissions.

Supported environment variables include:

• CLOUDLINK_CONFIG_DIR
• CLOUDLINK_CONTROL_PLANE_URL
• CLOUDLINK_MACHINE_NAME
• CLOUDLINK_TUNNEL_MODE

Flags override environment values, which override saved settings, which override defaults. See CLI reference for all options.

Update

Download and extract the new release, or rerun the install script with the new version. Stop the service before replacing the binaries. Saved pairing identity and settings survive an upgrade.

systemctl --user stop opencode-cloudlink.service
# install the new archive or rerun install.sh
systemctl --user start opencode-cloudlink.service

Uninstall

1. Stop and disable the service.
2. Remove the installed binaries and unit file.
3. Optionally remove saved state and credentials.

systemctl --user disable --now opencode-cloudlink.service
rm -f ~/.config/systemd/user/opencode-cloudlink.service
systemctl --user daemon-reload

# Only if you want a clean state:
rm -rf ~/.config/opencode-cloudlink

Deleting the local state does not remove the machine from your account. Delete the machine in OpenCode Mobile to retire its tunnel and DNS record.

Troubleshooting

Symptom	Action
setup required from the service	Pair interactively first
Proxy bind failure	Stop the other connector or process using the port
Tool missing or unsupported	Use the bundled tools or point to OpenCode v2 and cloudflared 2025.4.0+
Tunnel credentials rejected	Pair again, remove the saved connection, or use --reset
Service restarts repeatedly	Read the journal; fix the reported configuration or port problem
No connection after logout	Enable lingering for the user
Mobile terminal rejected	Basic-authenticated WebSockets are required; ticket-only handshakes are unsupported

For more, see Troubleshooting.