opencode-ssh-session

An OpenCode plugin that provides persistent SSH session tools. Connect to a remote host once, then run multiple commands with shell state (working directory, environment variables, etc.) preserved between calls.

Installation

Add the plugin to your OpenCode configuration (opencode.json):

{
  "plugin": ["opencode-ssh-session"]
}

OpenCode will automatically install the package via Bun at startup.

Permissions

The plugin uses OpenCode's native permission system before connecting, running remote commands, or transferring files. Connection approval defaults to ask; an explicit user setting overrides that default.

{
  "permission": {
    "ssh_connect": {
      "*": "ask",
      "dev-*": "allow",
      "production": "deny"
    },
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff *": "allow"
    },
    "read": "allow",
    "edit": "ask",
    "external_directory": "ask"
  }
}

Permission mapping:

| Operation | Permission | Resource | | --------- | ---------- | -------- | | Connect | ssh_connect | SSH host | | Run a command | bash | Exact remote command | | Upload | read, then edit | Resolved local source, then host:remotePath | | Download | read, then edit | host:remotePath, then resolved local destination | | Access outside the worktree | external_directory | Resolved local path |

Rejecting a permission prevents the associated SSH or filesystem operation. Remote commands use the same bash rules as local shell commands, including agent-specific rules.

Host verification

ssh_connect runs OpenSSH non-interactively. After connection approval, OpenSSH uses StrictHostKeyChecking=accept-new: first-time host keys are added to the user's normal known-hosts database, while changed host keys are rejected. The plugin does not bypass changed-key warnings.

Password, passphrase, keyboard-interactive, and other terminal prompts are not supported. Configure key-based authentication or an SSH agent before connecting. Connection errors include OpenSSH's stderr output.

Tools

The plugin registers six tools:

ssh_connect

Open a persistent SSH session to a remote host.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------- | | host | string | yes | SSH host (e.g. user@server, myalias, 192.168.1.10) | | options | string | no | Extra SSH flags (e.g. -p 2222, -i ~/.ssh/mykey) |

ssh

Execute a command on the active SSH session. Shell state persists across calls.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | command | string | yes | Shell command to run on the remote host | | timeout | number | no | Timeout in milliseconds (default: 120000 = 2m) |

ssh_disconnect

Close the active SSH session. Shell state is lost. You can reconnect later with ssh_connect.

No parameters.

ssh_info

Get the connected host, session duration, and command status for the current SSH session.

No parameters.

ssh_upload

Upload a local file to the remote host through the active SSH session using base64 encoding.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------- | | localPath | string | yes | Absolute path to the local file | | remotePath | string | yes | Destination path on the remote host |

ssh_download

Download a file from the remote host to the local machine through the active SSH session.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------- | | remotePath | string | yes | Path to the file on the remote host | | localPath | string | yes | Destination path on the local machine |

Hooks

The plugin automatically registers hooks that improve the SSH experience:

Bash guard (tool.execute.before)

Detects when the AI tries to run ssh, scp, sftp, or rsync through the built-in bash tool and injects a reminder to use the SSH session tools instead.

Session cleanup (event)

Automatically cleans up orphaned SSH processes when an OpenCode session errors out.

Commands & Skills

The plugin ships example commands and a skill in the examples/ directory. Copy them to your OpenCode config to use them.

Commands

Copy to .opencode/commands/ (project) or ~/.config/opencode/commands/ (global):

| Command | File | Description | | -------------- | --------------------------------- | ---------------------------------------- | | /ssh <host> | examples/commands/ssh.md | Quick connect to a host | | /ssh-status | examples/commands/ssh-status.md | Check connection status with diagnostics |

Skill

Copy to .opencode/skills/ (project) or ~/.config/opencode/skills/ (global):

| Skill | Directory | Description | | ---------------- | -------------------------------------- | -------------------------------------------- | | ssh-remote-dev | examples/skills/ssh-remote-dev/ | Remote development best practices for the AI |

The skill teaches the AI patterns for deployments, debugging remote services, file transfers, and common pitfalls to avoid.

How It Works

The plugin spawns at most one ssh child process for each OpenCode session and communicates with it through stdin/stdout using unique markers to delimit command output. This avoids reconnection overhead and preserves shell state between commands.

• Commands are non-interactive only (no vim, top, password prompts, etc.)
• Commands within a session execute one at a time
• Aborting or timing out ssh_connect or ssh closes that session's SSH connection
• File transfers use base64 encoding over the existing connection
• Remote paths are shell-quoted before transfer commands run
• Session deletion, errors, and plugin shutdown clean up their associated SSH processes

Requirements

• OpenCode with plugin support (@opencode-ai/plugin >= 1.18.25)
• ssh available on the host machine's PATH

License

MIT