# How to Set Up Reasonix Remote Workbench Access Over SSH

> Learn how to set up Reasonix remote workbench access over SSH. Access your full desktop workbench remotely with SSH and public key authorization. Quick and secure setup.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workbench_ssh.go).
- **Remote Workbench Runtime** – Runs on the remote host in [`internal/remote/workbench/runtime/server.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/remote/workbench/trust/trust.go). Use the CLI to add the host:

```bash
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:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) configuration file, set:

```toml
layout_style = "workbench"

```

This setting is referenced in the example configuration at [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml).

### Launch the Remote Workbench

The Desktop creates a workbench projection via [`internal/remote/workbench/target/manager.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

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

```

This command, defined in [`internal/cli/remote_attach_workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/remote/workbench/target/manager.go). You can query the projection’s status via the RuntimeAPI:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/remote/sftpfs/sftpfs.go) and the **HTTP gateway** in [`internal/remote/workbench/runtime/server.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workbench_ssh.go) and uses the trust store defined in [`internal/remote/workbench/trust/trust.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/remote/sftpfs/sftpfs.go) and an HTTP gateway via [`internal/remote/workbench/runtime/server.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.