How to Tunnel the Orx Dashboard Service to a Remote SSH Host

Use orx up --remote <host> for automatic SSH tunneling, or manually run ssh -N -L 7777:localhost:7777 user@host after starting orx up on the remote machine.

The alphaXiv/OpenResearch repository provides the orx CLI for managing computational research workflows. When you run the Orx dashboard on a remote server, you must tunnel the orx dashboard service to a remote SSH host because the server binds exclusively to 127.0.0.1 for security. This guide explains the two supported methods for establishing this tunnel using the codebase's built-in SSH utilities.

Why the Orx Dashboard Requires SSH Tunneling

In src/commands/up.rs (lines 65-71), the dashboard server is explicitly bound to the loop-back address. This prevents unauthenticated exposure to the network. Because the service listens only on 127.0.0.1, a client on your local machine cannot connect directly to the remote server's public IP. The repository handles this through SSH local port forwarding, implemented across src/commands/up_remote.rs, src/remote.rs, and src/jobs/ssh.rs.

Method 1: Automatic Tunneling with orx up --remote

The recommended approach uses the --remote flag, which automates the entire workflow. When you run orx up --remote <host> from your local machine, the command executes orx up on the remote host and establishes an SSH tunnel back to your laptop.

Implementation Details

The client-side logic resides in src/commands/up_remote.rs (lines 3-7). This module launches the SSH client using the same abstractions found in the generic job backend (src/jobs/ssh.rs), specifically SshTarget and HostKeyPolicy (lines 37-38). The forward is established automatically, and the command waits for the remote dashboard to become ready before opening your local browser.

Usage Example

orx up --remote user@remote.example.com

This single command performs four steps:

1. Connects to the remote host via SSH.
2. Executes orx up on the remote machine, binding to 127.0.0.1.
3. Creates a local SSH forward (e.g., port 7777 on your machine to port 7777 on the remote loop-back).
4. Opens http://localhost:7777 in your default browser.

Method 2: Manual SSH Port Forwarding

For users who prefer explicit control over SSH options or need to integrate with complex network setups, you can manually forward the port. The Orx CLI detects when it is running inside an SSH session and prints the exact command needed.

Detecting the SSH Session

In src/remote.rs, the function detect_ssh_session() (lines 71-78) checks environment variables to determine if the current shell is an SSH session. When detected, SshSession::render_instructions (lines 51-84) generates the forwarding guidance instead of attempting to launch a browser on the remote host.

Step-by-Step Manual Tunneling

First, SSH into the remote machine and start the dashboard:

ssh user@remote.example.com
orx up

Because the session is detected as SSH, the output in src/commands/up.rs (lines 84-90) prints a message like:

orx up: dashboard on http://127.0.0.1:7777

# (or) paste this into your local terminal:

ssh -N -L 7777:localhost:7777 user@remotehost   # then open http://localhost:7777

Then, in a separate local terminal, establish the tunnel:

ssh -N -L 7777:localhost:7777 user@remote.example.com

Finally, open the dashboard locally:

open http://localhost:7777      # macOS

xdg-open http://localhost:7777  # Linux

Customizing SSH Options

Both methods support advanced SSH configurations. For the automatic method, pass custom options via command-line flags:

orx up --remote user@remote.example.com:2222 --ssh-key ~/.ssh/custom_key

This internally adds -p 2222 -i ~/.ssh/custom_key to the SSH invocation. For manual forwarding, simply add these flags to your ssh -L command.

Summary

• The Orx dashboard in alphaXiv/OpenResearch binds to 127.0.0.1:7777 (defined in src/commands/up.rs, lines 65-71), requiring SSH tunneling for remote access.
• Automatic tunneling via orx up --remote <host> (implemented in src/commands/up_remote.rs) handles SSH connection, remote startup, and port forwarding in one step.
• Manual tunneling relies on detect_ssh_session() in src/remote.rs (lines 71-78) to print the correct ssh -L command, giving you full control over SSH options.
• The underlying SSH implementation uses SshTarget and HostKeyPolicy from src/jobs/ssh.rs.

Frequently Asked Questions

Why does the Orx dashboard bind only to localhost?

The dashboard binds exclusively to 127.0.0.1 for security, preventing unauthenticated network exposure. This implementation in src/commands/up.rs ensures that no external traffic can reach the service without first traversing an authenticated SSH tunnel.

What is the default port for the Orx dashboard?

The default port is 7777. When you start the dashboard with orx up, it listens on http://127.0.0.1:7777 and prints this address along with forwarding instructions if running inside an SSH session.

Can I use a custom SSH port or identity file with the automatic mode?

Yes. The orx up --remote command accepts a port in the host string (e.g., user@host:2222) and an --ssh-key flag for non-default identity files. These map to the -p and -i options in the underlying SSH client defined in src/jobs/ssh.rs.

How does the automatic mode know when the dashboard is ready?

The up_remote.rs implementation polls the remote service after establishing the SSH tunnel. It waits for the HTTP endpoint to respond before launching the local browser, ensuring the tunnel is active and the dashboard has finished initializing.

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