Control remote nodes over SSH

Remote Nodes lets one OcHub desktop control OcHub state on a machine that has no desktop environment. The remote machine only needs OpenSSH; if ochcli is not installed yet, the desktop can install it over SSH after confirmation. Configuration and AI coding tools continue to run on that machine.

This is especially useful when your editor or terminal runs in WSL, on a Linux development machine, or on a remote workstation. Instead of opening an SSH shell and remembering several config paths every time an API endpoint changes, select the machine in OcHub and switch its existing connection from the desktop.

Why use a remote node

Remote Nodes keeps the execution environment and its credentials where they belong while giving you one visual control surface:

• Switch Claude Code, Codex, OpenCode, and other supported tools on a development machine without editing their files by hand.
• See whether each node is online, which ochcli version it runs, and its platform before connecting.
• Preview the exact remote config change before it is applied.
• Start or stop the remote OcHub Gateway and run remote diagnostics.
• Reuse your existing OpenSSH aliases, SSH agent, ProxyJump, system keychain, and hardware-backed keys.

Closing OcHub does not move a running tool back to the local computer. A switch writes the tool’s native configuration on the selected remote node, so that tool keeps working there afterward.

What the current version can manage

Remote Nodes currently supports:

The workspace selector scopes the existing product pages. Their databases, tool configuration, sessions, paths, and network requests belong to the selected node. Desktop language, tray/login behavior, themes, and actions such as “Open in Finder” intentionally remain properties of the controlling computer.

OcHub does not expose arbitrary shell execution or automatically create a Gateway data-plane tunnel. The desktop can negotiate the capabilities an older node advertises, but the complete workspace requires a current remote ochcli. A missing or legacy CLI is reported explicitly and can be installed or upgraded to the managed version from the connection row.

Requirements

Prepare all of the following:

• OcHub Desktop 0.4.22 or later on the controlling computer.
• System ssh and ssh-keyscan on the controlling computer.
• A reachable OpenSSH server on the remote machine.
• A writable home directory for the remote user so OcHub can install managed ochcli, or an existing manual installation.
• SSH key or agent authentication that succeeds without an interactive password prompt. OcHub connects with BatchMode=yes.
• At least one provider already stored on the remote node if you want to switch connections.

Test the same path OcHub will use from the controlling computer:

ssh -V
ssh -o BatchMode=yes devbox ochcli remote probe

Replace devbox with your SSH alias. The second command should return node, runtime, version, policy, and capability information without asking for a password or passphrase.

Install ochcli on the remote machine

You normally do not need to log in and install it first. Add the SSH node as described below. If detection says that OcHub CLI is not installed, choose Install. OcHub detects the OS and CPU, downloads and verifies the official signed executable on the desktop, then uploads it over the host-key-pinned SSH connection. It writes only to the current SSH user’s directories, uses no sudo, and opens no port. Afterward it starts the owner, verifies the reported version with the real remote protocol, and saves the stable absolute path, so the non-interactive shell does not need ~/.local/bin in PATH.

The same action appears as Upgrade for a legacy, non-executable, or wrong-architecture CLI. Use the manual fallback below only when the desktop cannot fetch the release or automatic installation does not support the remote platform.

Download the headless CLI archive for the remote platform from the latest release. It contains one ochcli executable. On Linux or WSL, unpack it and install a managed node:

tar -xzf OcHub_*_linux_x86_64_cli.tar.gz
chmod +x ochcli
./ochcli node install

ochcli version
ochcli node status
ochcli remote probe

The installer retains releases in a user-owned version directory, atomically points a stable current entry at the active one, and exposes ~/.local/bin/ochcli. It installs a launchd or systemd user service when one is available. WSL without systemd uses a background owner that the next SSH session starts again after WSL restarts.

Make sure ~/.local/bin is available to non-interactive SSH sessions. You can also enter its absolute ochcli path when adding the node; this is the most reliable fix for “ochcli not found.”

If the tool already has a working live configuration, import it into the remote OcHub database before connecting:

ochcli app list
ochcli provider import-live --app codex
ochcli provider list --app codex

Change codex to the relevant app ID. Use ochcli provider add --help when you need to create additional remote connections. Secrets should be supplied on the remote machine, not copied through the desktop connection.

You do not have to install a second daemon binary or start it by hand. The same managed ochcli runs the persistent owner, and the first normal Remote Nodes session starts it when needed.

Prepare the SSH connection

Put a concrete alias in the SSH config on the controlling computer:

Host devbox
    HostName 192.0.2.40
    User alice
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30

OcHub reads ~/.ssh/config and its Include files. On Windows this means %USERPROFILE%\.ssh\config, not /home/<user>/.ssh/config inside WSL. Concrete Host aliases are listed in the Add dialog; wildcard-only blocks provide defaults but are not shown as selectable machines.

ProxyJump, SSH agent, system keychain, ControlMaster, and hardware keys continue to be handled by system OpenSSH. Confirm that this succeeds before opening OcHub:

ssh -o BatchMode=yes devbox ochcli remote probe

Add and connect a node

1. Open Remote nodes in the OcHub sidebar.
2. Select Add. OcHub reads the controlling computer’s SSH config and lists the concrete aliases it found.
3. Select an alias and choose Add, or use Add manually.
4. For a manual entry, provide a display name, SSH target, real hostname or IP for key scanning, SSH port, and remote ochcli path.
5. OcHub runs ssh-keyscan and shows each key type and SHA256 fingerprint. Compare the fingerprint with a trusted source such as a cloud console or administrator.
6. Choose Trust and connect only after the fingerprint matches.

Approved keys are stored in OcHub’s dedicated ~/.ochub/ssh/known_hosts file with private permissions. Existing entries in your normal ~/.ssh/known_hosts remain valid too. OcHub never silently sets StrictHostKeyChecking=no.

The connection list then shows live online state, ochcli version, platform, and last successful connection. The workspace selector at the top of the sidebar lets you move between This Mac and saved remote nodes.

Failures are shown as localized categories such as CLI not installed, node or desktop upgrade required, SSH authentication failure, changed host key, timeout, or incompatible system libraries. Choose Details for recovery guidance, the SSH exit code, and raw diagnostics; raw errors no longer crowd the connection row. Recoverable CLI failures also show Install or Upgrade.

If the selected node is offline, its SSH handshake times out, or capability negotiation fails, product pages immediately clear that node’s cached data and disable remote writes. OcHub never falls back to executing the action on This Mac. Reconnect the node before continuing with providers, gateway, settings, sync, tools, or updates.

After changing workspace, paths shown in product pages are paths on the selected node. For example, /srv/backup/OcHub.sql in Tools, the data directory in Settings, and sync/backup files are resolved remotely and do not use the controller’s HOME. File pickers, opening a web page or Finder, and desktop preferences remain local.

Update a remote node with one click

The connection row shows the installed ochcli version and an update action when the node advertises managed update support. OcHub first asks the node for its version and target platform, then reads the signed headless.json release manifest. Choose a strategy in the update dialog:

• Automatic uses direct download when the node can reach its exact release asset, otherwise it uses the desktop relay.
• Download on node makes the node download the signed executable itself.
• Relay through this computer downloads and verifies the executable on the desktop, then streams it to the node over SSH.

The relay does not trust the desktop alone: the node checks the expected node ID, target, byte count, SHA-256 digest, and release signature again. For either route, activation switches one stable current link, restarts the owner, and checks the version it reports. A failed health check restores the previous version automatically. You can also roll back on the node:

ochcli --yes node rollback

Update installation is enabled by the default policy. Set allowUpdateInstall = false and reconnect if you want to disable it for a node. For a node from before managed update support, choose Upgrade in the connection row to perform the first managed installation; later releases use the direct/relay update dialog. Managed installation and self-update currently support macOS and Linux, including WSL.

Switch a provider on the remote node

1. Choose the remote node from the workspace selector or the Remote Nodes connection list.
2. Connect, then select the remote application you want to change.
3. Find an existing provider and choose Preview switch.
4. Review the target node, SSH alias, current provider, target provider, configuration path, and revision.
5. Choose Apply change.
6. Refresh or make a short request from the tool on the remote machine to verify the new connection.

OcHub checks the revision again immediately before applying the change. If the tool or another process edited the config after the preview, the apply is rejected instead of overwriting the newer state. Refresh the node, inspect the new current state, and create another preview.

Mutations use an idempotency key and a remote operation journal. If SSH drops during an apply, reconnect and inspect Recent operations before retrying; the protocol can return the stored result instead of blindly performing the same write twice.

Operate Gateway and run diagnostics

The connected node page shows remote Gateway state. Starting it launches Gateway on the remote owner; stopping it affects only that node. This is useful for WSL or a development machine whose local AI tools already point to that machine’s loopback Gateway.

The SSH control session does not expose the remote Gateway to the controlling computer. If you deliberately need local access, create a separate tunnel after reviewing the remote port:

ssh -N -L 8765:127.0.0.1:<remote-port> devbox

Use Run diagnostics to combine the remote ochcli doctor result with SSH session diagnostics. Recent operations show remote actor, time, operation ID, and outcome without copying provider secrets to the desktop.

WSL setup

For OcHub Desktop on Windows controlling a WSL distribution:

1. Install the OpenSSH server and OcHub CLI inside WSL:

   sudo apt update
   sudo apt install openssh-server
   sudo service ssh start

   On a systemd-enabled distribution, sudo systemctl enable --now ssh can replace the last command.

2. Install the single ochcli inside WSL with ochcli node install as described above.

3. Configure key-based access from Windows to the WSL Linux user.

4. Add the alias to Windows %USERPROFILE%\.ssh\config:

   Host wsl-dev
       HostName 127.0.0.1
       User <your-wsl-user>
       Port 22
       IdentityFile ~/.ssh/id_ed25519

5. Test from PowerShell:

   ssh -o BatchMode=yes wsl-dev ochcli remote probe

6. Add wsl-dev from OcHub’s Remote Nodes dialog.

If Windows already uses port 22, configure WSL sshd on another port and use that port in the alias. A stopped WSL distribution or stopped sshd appears offline; start the distribution and SSH service before connecting. OcHub uses Windows OpenSSH and does not launch wsl.exe automatically.

The practical benefit is that Claude Code or Codex can remain fully inside WSL—Linux paths, credentials, sessions, and processes included—while provider switching becomes a two-click desktop action.

Security and remote policy

Remote Nodes adds no HTTP or TCP management listener. SSH supplies transport encryption, host authentication, and user authentication; OcHub runs the allowlisted ochcli remote serve --stdio protocol over that SSH process. Requests are typed operations, not shell command strings.

By default the remote policy permits status reads, diagnostics, provider switching (including new secrets), Gateway lifecycle, and update installation. Backup restore remains disabled. Inspect the effective policy on the remote node with:

ochcli remote policy show
ochcli remote policy validate

The optional policy file is ~/.ochub/remote.toml. For a read-only node:

schemaVersion = 1
enabled = true
allowWrite = false
allowGatewayLifecycle = false
allowBackupRestore = false
allowUpdateInstall = false

Set enabled = false to reject Remote Nodes sessions entirely. An ordinary SSH account still has all permissions of that Unix user; the policy becomes a strong authorization boundary only when the SSH key is restricted to OcHub’s forced command. See the Remote Nodes design and security model for that deployment pattern and protocol details.

To restore a database or import SQL/cc-switch data from the desktop, explicitly enable backup restore on the remote node. Update installation is already enabled by default, but can also be stated explicitly:

allowBackupRestore = true
allowUpdateInstall = true

The desktop editor reads live secrets over the encrypted SSH session, matching the local workspace. Untouched masked placeholders still preserve the remote value instead of writing ****** back. Policy changes apply to the next SSH control session.

Troubleshooting and current limits

Removing a node from OcHub deletes only the local connection record. It does not remove remote providers, tool configuration, ~/.ochub, the daemon, or Gateway data.