SSH backends

The SSH backends extend the sandbox to remote hosts. Every sandbox capability — filesystem operations, shell execution, and network requests — can run on a remote machine over SSH with the same API as local execution.

Connection pooling

SSH connections are pooled and multiplexed. All three capabilities — filesystem, shell, and network — share channels on the same underlying TCP connection rather than opening separate connections. This reduces connection overhead and avoids the per-connection authentication round-trips that make naive SSH usage slow.

The connection pool manages the full lifecycle:

• Reuse — Connections are reused across requests. A filesystem operation and a shell command targeting the same host share the same TCP connection.
• Reconnection — If a connection drops, simse reconnects automatically before the next operation. Reconnection uses exponential backoff configured in the sandbox settings.
• Concurrency — Multiple operations can run concurrently on the same connection through independent channels.

Transport security includes cipher negotiation, host key verification against a known-hosts file, and public-key or password authentication.

Remote filesystem

The remote filesystem implements the same VFS API as the local disk-backed mode, over SFTP:

• Read, write, append files
• List directories, stat paths
• Create and remove directories
• Rename and move files

From the caller's perspective, the remote filesystem behaves identically to the local one. Shadow history is not available on remote filesystems — file changes on remote hosts are not tracked.

Remote shell

Remote shell execution opens an SSH exec channel for each command. The command runs in the remote host's shell, with stdout and stderr streamed back over the channel.

Session state (environment variables, working directory) is transmitted to the remote host on each command invocation. Each command starts a fresh shell invocation with the configured environment applied.

Timeout enforcement works the same as the local shell: if the remote command does not complete within the configured timeout, the SSH channel is closed and the command is considered failed.

Remote network

Remote network routing sends HTTP requests through an SSH tunnel, making them appear to originate from the remote host's network. This is useful when a target endpoint is only reachable from a specific network (for example, an internal API only accessible from a corporate network).

The VNet's mock and allow rules still apply — the interception layer evaluates rules before deciding whether to forward the request through the tunnel.

Drop-in replacement for local backends

The SSH backends are designed to be drop-in replacements for local backends. Switching from local to SSH execution requires only a configuration change at the platform level. No other changes are needed — the filesystem, shell, and network capabilities all route through the SSH connection transparently.

Configuration

SSH backend configuration is set at the platform level. The configuration specifies the remote host, authentication method, and connection parameters:

{
  "type": "ssh",
  "ssh": {
    "host": "remote.example.com",
    "port": 22,
    "username": "deploy",
    "auth": {
      "type": "key",
      "privateKeyPath": "~/.ssh/id_ed25519"
    },
    "maxChannels": 10,
    "keepaliveIntervalMs": 15000
  }
}

Key-based authentication is strongly recommended over password authentication. Ed25519 keys are preferred for their compact size and security properties.