OpenCode V2 plugin for SSH remote connections with @-mention targeting.
- Commands:
/ssh <server1> [server2] ...,/disconnect_ssh <server1> [server2] ... | all,/list_ssh - Dynamic @-mentions (
@servername) for connected servers - Targeted bash execution: only wraps bash commands when connected servers are @-mentioned; otherwise runs locally
- Hybrid validation: checks
~/.ssh/config, falls back to raw host specs - Per-session connections with automatic cleanup on session end
- Parallel execution for multiple mentioned servers
- Node.js 18+ and npm
- SSH configured with
ssh-agent(or keychain) so connections don't prompt for passphrases - OpenCode V2
git clone https://github.com/ABDsheikho/opencode-remote-ssh
cd opencode-remote-ssh
npm install
npm run buildThe included opencode.jsonc intentionally keeps plugins empty so the plugin
never loads twice in this directory (two copies mean two separate in-memory
registries — see "Deploying" below). To load locally, add
"plugins": ["./dist"] (directory form — file paths are rejected by current
OpenCode with "configured plugin path must be a directory").
- Build the plugin as above
- Copy it to your project, e.g.
.opencode/plugins/opencode-remote-ssh/(includedist/,package.json, etc.) - Or add to your project's
opencode.jsonc:
Create ~/.config/opencode/plugins/opencode-remote-ssh/ and copy the built
files there. OpenCode will auto-discover plugins in
~/.config/opencode/plugins/.
- Run
opencodein the directory where the plugin is configured - Use
/ssh myserverto connect - Use
@myserver echo helloto run commands on that server - Use
/list_sshto list connections - Use
/disconnect_ssh myserveror/disconnect_ssh all
Plain sentences work too once connected — ask about a server by name and the
model runs it remotely (via shell + mention, or the ssh_exec tool).
Run one command on several servers at once — output is grouped per server:
@web1 @web2 uptime
Each connection registers @servername as a reference pointing at a small
descriptor file in ~/.ssh/opencode-refs/ (namespaced like the sockets, deleted
on disconnect). Attaching the reference injects a few lines (host, workspace,
mention syntax) — never filesystem content.
[!NOTE] The client caches the reference list per process and the server currently emits no invalidation when plugins update it, so
@servernameappears in@completions only after a full TUI restart (a new session in the same TUI is not enough). Routing itself needs no restart — mentions work in any session once connected.Tracked upstream:
ctx.reference.reload()is a no-op — TUI reference list never refreshes
npm install
npm run typecheck # src + tests, no emit
npm run build # emits dist/ from src only
npm testUnit tests (npm test, 49 tests) cover mention parsing, the namespace decision
table, quoting, and command building. The following need a live OpenCode server:
- Thrown message reaches the model verbatim. Mention a server connected in
another workspace (e.g.
@web1 lsfrom a different directory). The shell tool call must fail with exactlyserver web1 is not connected, and the model should see that text. - Cross-directory isolation.
/ssh web1in directory A, then@web1 ...from a session in directory B. Expect the failure from (1), never silent local execution. A mention of a server connected nowhere stays a normal local command. - Reference visibility.
@serverreferences are registered location-global (union across namespaces), so tab-completion may suggest a server that the current workspace cannot use — that mention then fails per (1) by design. - One copy at a time. If the global config and a project config each load a copy of this plugin in the same server process, they get separate in-memory registries (verified: the same entrypoint loaded twice). Disable one copy when testing the other.
- Tool id. The hook matches both
bash(historic) andshell(current tool id, verified live). If mentions stop rewriting after an OpenCode upgrade, check the tool id first.
npm run build emits two files: dist/index.js + dist/core.js (index.js
imports ./core.js). Loading is via a single absolute-path entry in the global
config — ~/.config/opencode/opencode.jsonc:
{
"plugins": ["/path/to/opencode-remote-ssh/dist"]
}[!WARNING] Configured plugin paths must be directories (file paths are rejected). Keep the project-local
opencode.jsoncwith an emptypluginsarray — loading two copies in one server process creates two separate registries.
- opencode-ssh — session-wide remote
mode: say
ssh <host>and every command runs on that one server. - opencode-remote-ssh by TyRoden — provider-based remote workspaces via a Go stub installed on each host.
This plugin is developed using AI tools and agents, with human review of every change.
MIT — see LICENSE.
{ "$schema": "https://opencode.ai/config.json", "plugins": ["./path/to/opencode-remote-ssh/dist"] }