---
title: "Install on Linux and Headless Servers"
description: "Install the Linux x64 or ARM64 Cloud Link archive, run the connector in the foreground, or pair once and enable the optional systemd user service."
canonical: "https://opencodecloud.link/docs/install/linux/"
lastUpdated: "2026-10-19"
---
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](https://github.com/alvarolorentedev/opencode-cloud-link-releases/releases/latest/download/opencode-cloudlink_linux_amd64.tar.gz)
- [Linux ARM64](https://github.com/alvarolorentedev/opencode-cloud-link-releases/releases/latest/download/opencode-cloudlink_linux_arm64.tar.gz)

Verify the matching `.sha256` sidecar, then extract:

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

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

```sh
./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
<kbd>Ctrl</kbd>+<kbd>C</kbd> to stop it. Pairing state and settings are saved
outside the extracted directory.

### Useful foreground options

```sh
# 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.

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

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

```sh
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](/docs/cli/) 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.

```sh
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.

```sh
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](/docs/troubleshooting/).