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

> Easily tunnel the Orx dashboard service to a remote SSH host using automatic or manual methods. Learn how to access your Orx dashboard securely from anywhere.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/up_remote.rs), [`src/remote.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/remote.rs), and [`src/jobs/ssh.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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

```bash
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`](https://github.com/alphaXiv/OpenResearch/blob/main/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:

```bash
ssh user@remote.example.com
orx up

```

Because the session is detected as SSH, the output in [`src/commands/up.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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:

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

```

Finally, open the dashboard locally:

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

```bash
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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/jobs/ssh.rs).

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

The [`up_remote.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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.