OpenCode Desktop: install it and connect to a remote server

Installing it

The download page and the version 2 docs offer builds for:

• macOS: a DMG for Apple silicon or Intel, or brew install --cask opencode-desktop
• Windows: an installer for x64 or ARM64
• Linux: a .deb or .rpm, x64 or ARM64; the docs also list an AppImage

There is no phone app; on a phone, OpenCode is its web interface. The app is OpenCode version 2. It connects only to version 2 servers, and it turns an older one away: “…which isn’t compatible with this app. Upgrade it to OpenCode V2 to continue.” If your terminal’s opencode --version prints a bare number such as 1.19.3, that is version 1; installing OpenCode on Linux covers moving to version 2.

Where its work runs

OpenCode 2 runs one background server for each user account. The docs describe it this way: “Every local OpenCode client connects to that server, which owns sessions, configuration, integrations, permissions, and tool execution.” The desktop app is one of those clients. On your laptop it finds that server, or starts one with its own copy of OpenCode, so a session’s commands, file edits and model calls run on the laptop. When the laptop sleeps, the work stops.

Adding another server moves the work. The app becomes a window onto OpenCode on that machine, with its projects, sessions and providers. Projects on each server are listed under that server’s name. A provider you connect while working on a server is stored there; in the app’s words, “Your OpenCode credentials will be stored on this server.”

Adding a server over SSH

The add-server button gives a choice of server types, SSH among them. Type the host as you would after ssh: me@203.0.113.7, an alias from ~/.ssh/config, or a short command such as ssh -p 2222 -i ~/.ssh/work me@host. The app runs your computer’s own OpenSSH client, so a name that works with ssh in your terminal works here, keys and jump hosts included. A password, a key’s passphrase, or the question about a new host’s fingerprint comes up inside the app, with a Trust and connect button for the fingerprint. It accepts the flags -p, -l, -i, -F, -J and a few -o options, and refuses a remote command.

OpenCode’s docs don’t describe this connection yet. What happens is in the app’s own source, each step run in the server user’s login shell:

1. It looks for OpenCode’s background server already running there at the app’s own version, and uses it if it finds one.
2. Otherwise it checks the machine is Linux or macOS on x64 or arm64 and downloads OpenCode’s command-line build for that version from npm into ~/.opencode/desktop-ssh/, in a folder named for the version, or sends it over SSH if the server can’t download it. That is one file of about 200 MB, and it is not added to your PATH.
3. It runs opencode service start there and connects to it through an SSH port forward.

The server’s OpenCode keeps listening on 127.0.0.1 only, and the app reaches it through the SSH connection, so nothing new opens on the server’s network. What the server needs: SSH access, a shell with tar and either curl or wget, and the disk for that file. Your computer needs an OpenSSH client; on Windows that is ssh.exe. If the app can’t find one, it says so: “OpenSSH was not found.”

On a Tailscale network, the default SSH rule of a new network asks for a browser check on the device that connects, and again every 12 hours. Approve it first by logging in once with ssh from a terminal on the same computer; the app’s own connections from that computer then pass until the period runs out. Tailscale SSH for an agent’s server covers the rule and how to change it.

When the versions don’t match

The app and the server’s background server have to be the same version. If OpenCode’s server on that machine is already running another version, for instance from an opencode you installed there yourself or from an earlier version of the app, the app stops at “Server update required” with this message: “The remote service must match this Desktop version before connecting.” Its Update and reconnect button restarts the server’s background server at the app’s version.

A restart interrupts whatever is running. On OpenCode 2.1.2 on an Ubuntu server, a restart during a turn cancels the command that is running (“Command cancelled”). Once the server is back, OpenCode adds a note to the session (“The server restarted while you were working. Continue from where you left off without repeating completed work.”) and the agent carries on, deciding for itself what to run again. So update between tasks rather than during one. Since every OpenCode client on that account shares the one background server, keep the opencode you run in a terminal there at the same version as the app.

Without SSH: an address and a password

If the server’s OpenCode already listens on an address your computer can reach, such as its address on a private network like Tailscale, add it by address instead. Give the address and the server’s password, which opencode service get password prints on the server. Or paste a pairing link from opencode pair into the server address field; the web interface docs say this “connects the app the same way” as a browser. The commands that make the server listen there, and the reason not to use 0.0.0.0 on a machine with a public address, are in OpenCode on a remote server.

OpenCode’s web interface has the same Add server button under Settings, then Server, so a browser can switch between servers too. It doesn’t offer SSH, and a page opened over HTTPS can’t reach a server on plain HTTP. In a terminal, version 2 has no attach; the same job is opencode --server http://my-server:4096, with the server’s password in OPENCODE_PASSWORD. Without it, 2.1.2 stops with “requires a password; set OPENCODE_PASSWORD”.

What keeps running when you close the laptop

OpenCode’s background server is its own process on the server. On OpenCode 2.1.2 on Ubuntu 24.04, it is detached from the shell that starts it and keeps running after that shell exits, and a turn whose client goes away mid-command finishes on the server: the command completes, the agent replies, and the session is marked done. Ubuntu’s defaults don’t stop a user’s processes at logout, so closing the SSH connection doesn’t stop the work.

In the app, a dropped connection shows as “SSH connection inactive”, with this note: “Reconnect to view this session and continue working. Your remote session is preserved.” The session’s history lives in the server’s OpenCode database, under ~/.local/share/opencode/, so a browser through opencode pair or another computer sees the same sessions.

A reboot is different. Nothing starts the background server at boot, so after a restart it runs again only when a client starts it, which the app does when it reconnects over SSH. For a server that comes up with the machine, the docs point at running opencode serve under “a supervisor like systemd, Docker, or another environment that expects a foreground process”. You then connect by address and password, since the SSH route looks for the background server rather than a serve process. OpenCode’s docs don’t say what a reboot does to a turn that was running.

A server that stays on

All of this assumes a machine that is on when you open the app, and the point of moving the work is that a laptop sleeps. Everpod’s developer pod runs OpenCode: a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed, reached only through your own private network, from $24 a month. It accepts no incoming connections from the open internet: no open ports and no public SSH. A server your agent starts is reachable from your devices and from nowhere else. By default the machine does not start connections to your other devices.