How to Set Up Reasonix Remote Workbench Access Over SSH

Reasonix projects can expose the full desktop workbench on a remote machine by forwarding the workbench protocol over an SSH channel, requiring only a functional SSH daemon and authorized public key on the remote host.

The DeepSeek-Reasonix repository (esengine/DeepSeek-Reasonix) provides a complete remote development environment that projects your local desktop workbench onto any SSH-accessible server. Setting up Reasonix remote workbench access over SSH involves configuring the transport layer, establishing trust through host key verification, and launching the runtime server on the remote host.

Architecture Overview

The remote workbench system consists of three main components that coordinate over SSH:

• Desktop SSH Transport – Implements the Transport interface in internal/remote/workbench/transport/transport.go and forwards the desktop workbench protocol over an SSH channel.
• Workbench Peer Identity – Validates the remote host’s SSH key fingerprint and key type before establishing the projection, implemented in desktop/workbench_ssh.go.
• Remote Workbench Runtime – Runs on the remote host in internal/remote/workbench/runtime/server.go, providing SFTP, HTTP gateway, and the RuntimeAPI that the Desktop consumes.

Prerequisites

Before configuring the workbench, ensure you have basic SSH connectivity to the target host. The transport relies on the standard OpenSSH client (or the Go SSH library), so the only prerequisite on the remote side is a functional SSH daemon and an authorized public key for the user that runs Reasonix.

Verify connectivity with:

ssh <user>@<host>

Confirm that the remote host accepts the same public key that your local ssh-agent offers.

Step-by-Step Configuration

Add the Host to Reasonix's Trust Store

Reasonix must know the host’s public key fingerprint and its allowed key type before establishing any projection. The trust package stores this information in internal/remote/workbench/trust/trust.go. Use the CLI to add the host:

reasonix remote trust add <host> ssh-ed25519 <fingerprint>

Under the hood, this invokes the trust.Add() function, which persists the host identity for subsequent connections. You can also programmatically add trust entries:

package main

import (
    "log"
    "reasonix/internal/remote/workbench/trust"
)

func main() {
    err := trust.Add("my-remote", "ssh-ed25519", "SHA256:AbCdEfGh1234...", []string{"deepseek/chat"})
    if err != nil {
        log.Fatalf("cannot add trust: %v", err)
    }
}

Configure the Desktop Layout (Optional)

While not strictly required for SSH access, configuring the desktop to use the workbench layout improves the remote experience. In your reasonix.toml configuration file, set:

layout_style = "workbench"

This setting is referenced in the example configuration at reasonix.example.toml.

Launch the Remote Workbench

The Desktop creates a workbench projection via internal/remote/workbench/target/manager.go and initiates the connection workflow. First, the Desktop discovers the remote host’s SSH configuration using the embedded parser in internal/remote/sshconfig.go. If the remote host lacks a compatible Reasonix CLI, the Desktop automatically downloads the appropriate binary and installs it under ~/.reasonix/remote/workbench/<build-id>/reasonix.

Start the remote workbench from your local machine:

reasonix remote runtime-workbench --workspace <remote-path> --socket /tmp/rs-workbench.sock

This command, defined in internal/cli/remote_attach_workspace.go, spawns a child process that connects back to the remote host via SSH, opens a forwarded-tcpip channel, and runs the remote workbench server.

You can also launch this programmatically:

package main

import (
    "os/exec"
)

func main() {
    // Replace with your remote host and workspace path
    cmd := exec.Command("reasonix", "remote", "runtime-workbench",
        "--workspace", "/home/remoteuser/project",
        "--socket", "/tmp/rs-workbench.sock")
    // The command will automatically SSH to the remote host,
    // start the workbench server, and forward the socket.
    if err := cmd.Run(); err != nil {
        panic(err)
    }
}

Verify the Projection

Once connected, the Desktop UI opens a new tab titled "Remote Workbench". Internally, the projection is created by the manager in internal/remote/workbench/target/manager.go. You can query the projection’s status via the RuntimeAPI:

package main

import (
    "fmt"
    "reasonix/internal/remote/workbench/client"
    "reasonix/internal/protocol"
)

func main() {
    wb := client.New(/* transport factory */)
    resp, err := wb.Call(protocol.MethodWorkspaceChanges, nil)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Workspace changes: %s\n", resp)
}

This example mirrors the implementation pattern found in desktop/workspace_changes.go.

Accessing Remote Resources

The remote server exposes additional data planes beyond the workbench UI. The SFTP filesystem implementation in internal/remote/sftpfs/sftpfs.go and the HTTP gateway in internal/remote/workbench/runtime/server.go are automatically bound to the same SSH channel. Because these services multiplex over the existing SSH connection, no extra firewall configuration or additional ports are required.

Summary

• Reasonix remote workbench access requires only SSH connectivity and an authorized public key on the remote host.
• Host trust is established via reasonix remote trust add or the trust.Add() API in internal/remote/workbench/trust/trust.go.
• The Desktop handles CLI installation automatically, downloading the correct binary to ~/.reasonix/remote/workbench/<build-id>/reasonix if needed.
• Transport layer implementations in internal/remote/workbench/transport/transport.go forward the full workbench protocol over standard SSH channels.
• Runtime services including SFTP and HTTP are multiplexed over the same SSH connection, requiring no additional network configuration.

Frequently Asked Questions

What are the minimum requirements on the remote host for Reasonix workbench access?

The remote host only needs a functional SSH daemon and an authorized public key for the connecting user. The Reasonix Desktop automatically installs the necessary CLI binaries under ~/.reasonix/remote/workbench/ if they are not already present, so no manual installation is required on the server.

How does Reasonix verify the identity of remote hosts?

Reasonix validates the remote host’s SSH key fingerprint and key type before establishing any projection. This Workbench Peer Identity verification is implemented in desktop/workbench_ssh.go and uses the trust store defined in internal/remote/workbench/trust/trust.go. You must explicitly add the host fingerprint using reasonix remote trust add before the first connection.

Can I access files on the remote host through the workbench connection?

Yes. The remote workbench runtime automatically exposes an SFTP server via internal/remote/sftpfs/sftpfs.go and an HTTP gateway via internal/remote/workbench/runtime/server.go. These services are tunneled through the same SSH channel used for the workbench protocol, providing seamless file access without additional configuration.

What happens if the remote workbench build ID does not match the Desktop version?

If the remote host does not already have a compatible Reasonix CLI, the Desktop detects the version mismatch when requesting the workbench build ID (remote workbench-build-id). The Desktop then automatically downloads the appropriate binary and installs it under ~/.reasonix/remote/workbench/<build-id>/reasonix before spawning the runtime process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}