Skip to content

desktop: SSH remote service start failure reported as "failed to establish SSH connection" #54059

Open

Description

@cendh666

Summary

When adding a host via Desktop → Add SSH server, a failure to start the remote OpenCode service (here: the remote managed service port was already in use) is reported as error.connection — "Could not establish an SSH connection. Check your network and SSH settings." SSH itself connects fine, and the real remote error is captured but never surfaced.

Environment

  • opencode version: Desktop 2.0.26 (auto-installed remote CLI 2.0.26); local opencode CLI 2.0.24
  • OS: macOS 15 (Darwin 25.5.0, arm64); remote host Linux (Ubuntu 22.04, x86_64)
  • Terminal: iTerm.app ($TERM=xterm-256color) — issue is in the Desktop app, not the TUI
  • Shell: /bin/zsh
  • Install/channel: OpenCode Desktop release 2.0.26 (ai.opencode.desktop)
  • Active plugins: none found in local config

Reproduction

  1. On the remote Linux host, make the managed service bind all interfaces: opencode service set hostname 0.0.0.0.
  2. Make sure something holds the remote's default managed service port. Here an unrelated established outbound connection used port 49374 as its source port (172.17.0.1:49374 → 172.17.0.3:6379, host Docker bridge → Redis container). 49374 is OpenCode's default managed port and lies inside the Linux ephemeral range (32768–60999).
  3. In Desktop, open the command palette → Add SSH server (or server settings → + Add server → Add SSH server) and select the host from ~/.ssh/config.
  4. Observe the generic error.

Expected Behavior

  • The UI should distinguish "SSH connected, but the OpenCode server did not become ready" from "could not establish an SSH connection". An error.service string already exists in the SSH i18n set and fits this case exactly.
  • Ideally the remote command's stderr (which already contains the actionable cause) should be shown, or the app should fall back to a free port automatically.

Actual Behavior

The dialog shows only error.connection:

Could not establish an SSH connection. Check your network and SSH settings.

SSH is in fact fine:

  • ssh -o BatchMode=yes <user>@<host> succeeds using key auth.
  • The app's own local forward works: ssh ... -L 127.0.0.1:<local>:127.0.0.1:<remote-port> <host> establishes and the tunneled endpoint responds (HTTP 401 = reachable; auth is handled by the app).

The real cause is only visible in the remote log (~/.local/share/opencode/log/opencode.log):

level=ERROR message="cli process failed"
cause="... Managed service port 49374 on 0.0.0.0 is already in use by another process. Configure another port with `opencode service set port <port>` and start the service again. ..."
args="[\"service\",\"start\"]"

And the same when run manually:

$ <cli> service start
Error: Server process exited with code 1
Error: Managed service port 49374 on 0.0.0.0 is already in use by another process. Configure another port with `opencode service set port <port>` and start the service again.
exit=1

Additional Context

  • The remote setup maps any non-zero exit of the remote ssh ... <cli> service start to error.connection (the error payload carries the captured stderr), rather than error.service or a surfaced detail. There is no details/diagnostics affordance in the 2.0.26 bundle (copyDiagnostics / showDetails keys are absent), so the captured stderr is effectively hidden from the user and the message points them at network/SSH instead.
  • Secondary robustness issue: the default managed service port 49374 is inside the Linux ephemeral range (32768–60999), and serve --service binds a fixed port. A transient outbound connection can claim that port as a source port; binding 0.0.0.0 then fails with EADDRINUSE, while binding 127.0.0.1 succeeds (verified). Consider a default port outside the ephemeral range and/or falling back to a free port on EADDRINUSE.
  • Workaround that fixed it: opencode service set port 27777 && opencode service restart on the remote host; the same Desktop flow then connects.
  • Frequency: reproduced consistently on the affected host while the port stayed occupied; a second host without the collision connected normally.

Activity

  1. opencode-agent commented on Oct 9, 2026

    @opencode-agent
    Contributor

    Thanks for the detailed report. I was able to reproduce this.

    I couldn't run the Desktop GUI here, so I ran the Desktop SSH bootstrap code from source against a "remote" with CLI 2.0.26. A fake ssh that always connects successfully stood in for the real one. I set opencode service set hostname 0.0.0.0 and kept port 49374 on 0.0.0.0 busy. The bootstrap got through the checking step and into starting the service, then failed with code connection, which the dialog shows as "Could not establish an SSH connection…". The remote CLI's actual error ("Managed service port 49374 on 0.0.0.0 is already in use…") was captured but only kept as a hidden detail.

    The cause seems to be that any non-zero exit from the remote command is treated as an SSH connection failure, including a failed service start. The SSH code is unchanged in the latest v2 (eefe85d), and it still happens there. The script below reproduces it.

    The default port having no fallback when it's taken is tracked separately in #52234 and #50672. Until this is fixed, your workaround of setting another port with opencode service set port <port> on the remote works.

    Reproduction script (repro.sh)
    #!/usr/bin/env bash
    # Reproduces #54059: Desktop SSH bootstrap reports remote `service start` failure as "connection".
    # Needs: @opencode/cli@2.0.26 on PATH, python3, bun, an opencode v2 checkout at $REPO.
    set -u
    REPO=${REPO:-/workspace/repo}
    VERSION=${VERSION:-2.0.26}
    WORK=$(mktemp -d)
    
    # 1. "Remote" host = this machine. Stage the CLI where Desktop installs it.
    mkdir -p "$HOME/.opencode/desktop-ssh/$VERSION"
    ln -sf "$(command -v opencode)" "$HOME/.opencode/desktop-ssh/$VERSION/opencode"
    opencode service stop >/dev/null 2>&1 || true
    opencode service set hostname 0.0.0.0
    
    # 2. Occupy the default managed port 49374 on 0.0.0.0.
    python3 -c "import socket,time;s=socket.socket();s.bind(('0.0.0.0',49374));s.listen();time.sleep(600)" &
    HOLDER=$!; trap 'kill $HOLDER 2>/dev/null' EXIT; sleep 1
    
    # 3. Fake `ssh` that succeeds at "connecting" and runs the remote command locally.
    mkdir -p "$WORK/bin"
    cat > "$WORK/bin/ssh" <<'SH'
    #!/bin/sh
    eval "last=\${$#}"
    exec sh -c "$last"
    SH
    chmod +x "$WORK/bin/ssh"
    
    # 4. Run the Desktop SSH bootstrap from source.
    cat > "$REPO/packages/gui-extensions/src/ssh/repro-54059.ts" <<TS
    import { Effect, Layer } from "effect"
    import { NodeServices } from "@effect/platform-node"
    import { FetchHttpClient } from "effect/unstable/http"
    import { bootstrap } from "./bootstrap"
    import { parseTarget } from "./command"
    const exit = await Effect.runPromiseExit(
      bootstrap({ target: parseTarget("remote-host"), version: "$VERSION", env: process.env, stage: (s) => Effect.log("stage", s) })
        .pipe(Effect.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer))),
    )
    console.log(JSON.stringify(exit, null, 2))
    TS
    cd "$REPO/packages/gui-extensions" && PATH="$WORK/bin:$PATH" bun src/ssh/repro-54059.ts
    rm -f "$REPO/packages/gui-extensions/src/ssh/repro-54059.ts"

    Run it: bash repro.sh

  2. argszero commented on Oct 10, 2026

    @argszero
    Contributor

    I'd like to work on this.

    The diagnosis matches what I see in the source: runSsh turns every non-zero exit into SshFailure("connection"), and the dialog renders error.${code}, so a remote service start that exits 1 is reported as a connection problem while the real remote stderr is captured but kept only in the hidden detail.

    I have a fix in progress that re-tags the failure of the start step alone as SshFailure("service", <captured detail>), keeping genuine transport failures (OpenSSH's own exit 255, which fails an earlier step on the same connection) as connection. It comes with a test that drives the real bootstrap against a stand-in ssh reading the remote script from stdin: the reported case yields connection before the change and service after it.

    The default managed port colliding with the ephemeral range and falling back to a free port is out of scope here, since it is tracked separately in #52234 and #50672.

  3. ai-nikolai commented on Nov 12, 2026

    @ai-nikolai

    @argszero - this is still broken.

    When ssh connection (with password) stop (e.g. computer shutdown, etc.) then opencode cannot reconnect to the remote machine (throws a generic error message) and the port is still in use.

    @cendh666 @Hona

  4. ai-nikolai commented on Nov 12, 2026

    @ai-nikolai

    @Hona - created a PR with a fix:
    #63542

  5. ai-nikolai commented on Nov 17, 2026

    @ai-nikolai

    @Hona @Brendonovich - this issue is really persisting and quite annoying.

    Basically, reconnecting to a remote server requires manually sshing into it and then killing the process manually and only then login works again.

    The PR should fix this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions