opencode-remote-login

Dispatch opencode sessions to remote hosts via SSH. Migrate context, execute tasks remotely, and optionally pull results back.

Install

opencode plug -g opencode-remote-login

Use -g to install globally into ~/.config/opencode/opencode.jsonc. Without -g, the plugin is installed into the current project's .opencode/ directory instead.

Configure hosts

Host config is loaded from these locations (later files override earlier):

1. Global: ~/.config/opencode/hosts.json (or hosts.jsonc)
2. Project: <projectDir>/hosts.json (or hosts.jsonc)
3. Project: <projectDir>/.opencode/hosts.json (or hosts.jsonc)

Inline plugin options take the highest priority. JSONC (comments, trailing commas) is supported everywhere.

Create ~/.config/opencode/hosts.json:

{
  "hosts": {
    "dev-box": {
      "host": "[email protected]",
      "port": 2222,
      "os": "linux",
      "agent": "build",
      "model": "opencode/big-pickle"
    }
  }
}

Alternatively, configure inline in opencode.jsonc:

{
  "plugin": [
    ["opencode-remote-login", {
      "hosts": {
        "dev-box": { "host": "[email protected]" }
      }
    }]
  ]
}

Host fields

| Field | Required | Description | | ------- | -------- | ------------------------------------------------ | | host | Yes | SSH address (user@host) | | port | No | Custom SSH port (default: 22) | | os | No | linux or windows; auto-detected if omitted | | agent | No | Override agent on the remote | | model | No | Override model in provider/id format |

Only host names are shown to the LLM. SSH addresses stay on disk.

SSH setup

ssh-copy-id [email protected]

Password prompts are not supported. Configure key-based SSH access before dispatching a session.

Windows hosts

Windows remotes are supported via OpenSSH and PowerShell. Set "os": "windows" in host config to skip auto-detection, especially when using a custom SSH port.

Windows round-trip dispatch uses Task Scheduler (schtasks) instead of detached child processes. This avoids Windows OpenSSH killing child processes when the SSH session exits.

Requirements on the Windows host:

• OpenSSH server with key-based login
• powershell.exe and schtasks.exe
• opencode available in the user's PATH

If round-trip times out, check the diagnostic logs printed by the tool. They are written under the remote %TEMP% directory and include launcher, runner, and command logs.

Usage

You can ask naturally. opencode will call remote_login when the task should move to a configured remote host.

Examples:

Use dev-box to fix the auth bug.
Run this on gpu-box and continue there.
Use windows-box, finish the task, then bring the result back here.
Debug this on dev-box in /home/dev/projects/app.

Help

Ask the LLM how to configure hosts, or call the tool directly:

How do I set up remote hosts?

One-way

Use one-way handoff when the work should continue on the remote host and the local conversation should stop.

Use dev-box to finish this task.
Move this session to gpu-box and continue there.

Round-trip

Use round-trip when the remote host should do the work and then merge the updated session back locally. The original agent and model are restored automatically on return.

Use dev-box to find the memory leak, then bring the result back.
Run this on windows-box and return here when done.

Target directory

Use dev-box in /home/dev/projects/app to fix the build.

Omit to default to ~.

Direct tool calls such as remote_login host=dev-box mode=round-trip also work, but they are optional.

How it works

local                                      remote
-----                                      ------
export session JSON
patch agent/model per host config  --->    SCP + import session
                                           run opencode on remote
                                           Linux: nohup
                                           Windows: schtasks runner
[round-trip] poll for completion     <---  export session JSON
[round-trip] restore agent/model
[round-trip] import back