Reverse Tunnel (SSH Service Sharing)

What It Does

Reverse Tunnel lets you expose a service running on your local machine to other Torus mesh users — without opening firewall ports, without a public IP, and without any special VPN tier. It works by creating an SSH reverse tunnel through a shared jump host.

Example: You are running a web app on localhost:3000. With one command, other mesh users can reach it through the jump host on a port you choose.

Available to: All tiers (Community, Plus, Pro).

How It Works

YOUR MACHINE                    TORUS MESH                  OTHER MESH USER

┌──────────────┐    SSH tunnel (port 2222)    ┌────────────────────┐
│              │─────────────────────────▶│                    │
│  Local       │   reverse-forward :10080  │   Jump Host        │
│  Service     │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│   Docker container │
│  :3000       │   traffic forwarded back  │   port 2222        │
│              │                           │                    │
└──────────────┘                           └────────────────────┘
                                                    ▲
      ┌───────────────────┐                        │
      │ WireGuard Tunnel  │    Torus mesh network  │
      │ (Torus VPN)       │──────────────────────┘
      └───────────────────┘
                                    │
                           ┌────────┴────────┐
                           │                 │
                           ▼                 ▼
                    ┌────────────┐    ┌────────────┐
                    │ Mesh User  │    │ Mesh User  │
                    │ Alice      │    │ Bob        │
                    │            │    │            │
                    │ Connects   │    │ Connects   │
                    │ to jump    │    │ to jump    │
                    │ host:10080 │    │ host:10080 │
                    └────────────┘    └────────────┘

Traffic Flow (Step by Step)

1. You start your local service (e.g. python3 -m http.server 3000)

2. You create an SSH reverse tunnel:
   ssh -p 2222 -R 10080:localhost:3000 tunnel@jump.ring.nekotopia.io
       │            │         │              └── jump host user (shared)
       │            │         └── your local service port
       │            └── remote port on the jump host
       └── jump host SSH port

3. Jump host opens port 10080 and binds it to your tunnel

4. Mesh user connects to the jump host on that port
   (the jump host address is shown in the dashboard)

5. Jump host forwards the request through your SSH tunnel to localhost:3000

6. Your service responds → jump host → mesh user

Setup Guide

Step 1: Generate an SSH Key

On your local machine, create a dedicated key pair:

ssh-keygen -t ed25519 -f ~/.ssh/nekotopia_jump -C "my-laptop"

Press Enter twice to skip the passphrase (or set one if you prefer). This creates:

~/.ssh/nekotopia_jump — private key (keep safe, never share)
~/.ssh/nekotopia_jump.pub — public key (upload this to the dashboard)

Step 2: Upload Your Public Key

Log in to the Nekotopia dashboard
Navigate to Edge Services → Reverse Tunnel in the sidebar
Copy the contents of your public key: cat ~/.ssh/nekotopia_jump.pub
Paste it into the SSH Public Key field
Add a description (e.g. "MacBook Pro")
Click Save Key

The status badge should change from NOT CONFIGURED to CONFIGURED.

Step 3: Start Your Local Service

Run whatever service you want to share:

# Simple file server
python3 -m http.server 8000

# Node.js app
node app.js    # listening on port 3000

# Docker container
docker run -p 5000:5000 myapp

Step 4: Create the Tunnel

ssh -i ~/.ssh/nekotopia_jump \
    -p 2222 \
    -R 10080:localhost:8000 \
    tunnel@jump.ring.nekotopia.io

Flag	Meaning
`-i ~/.ssh/nekotopia_jump`	Use your dedicated key
`-p 2222`	Jump host SSH port
`-R 10080:localhost:8000`	Forward remote port 10080 to your localhost:8000
`tunnel@jump.ring.nekotopia.io`	Jump host user and hostname

You will see: Tunnel-only access for your_username. This is normal — the jump host blocks interactive shells. The tunnel is active as long as this SSH session stays open.

Tell other mesh users to connect to the jump host on port 10080. They must be connected to the Torus VPN. The jump host address is shown in the dashboard connection info panel.

Step 6 (Optional): Register the Port

In the dashboard, click + Register Port and enter the port number and a description. This is for your own tracking — it helps you remember what is running on which port.

Port Range

You can use any port from 10000 to 60000. Ports below 10000 are reserved for infrastructure. Pick a port and stick with it. If another user is already using the same port, SSH will report Warning: remote port forwarding failed — just pick a different port.

Keeping the Tunnel Alive

SSH tunnels drop if the connection goes idle. Add keepalive flags:

ssh -i ~/.ssh/nekotopia_jump \
    -p 2222 \
    -R 10080:localhost:8000 \
    -o ServerAliveInterval=30 \
    -o ServerAliveCountMax=3 \
    tunnel@jump.ring.nekotopia.io

For persistent tunnels that auto-reconnect, use autossh:

# Install: brew install autossh (macOS) or apt install autossh (Linux)
autossh -M 0 \
    -i ~/.ssh/nekotopia_jump \
    -p 2222 \
    -R 10080:localhost:8000 \
    -o ServerAliveInterval=30 \
    -o ServerAliveCountMax=3 \
    -N \
    tunnel@jump.ring.nekotopia.io

The -N flag tells SSH not to execute a remote command (tunnel only). autossh will automatically reconnect if the connection drops.

Multiple Services

Forward multiple ports in a single SSH session:

ssh -i ~/.ssh/nekotopia_jump \
    -p 2222 \
    -R 10080:localhost:3000 \
    -R 10081:localhost:8080 \
    -R 10082:localhost:5432 \
    tunnel@jump.ring.nekotopia.io

This exposes three services at once on ports 10080, 10081, and 10082.

Comparison with Other Features

	Reverse Tunnel	Port Mapping	Hosted Services
Tier required	All	Pro only	Plus / Pro
Access scope	Mesh only	Public internet	Public / Mesh
Setup method	SSH CLI	Web UI	Web UI
Persistence	Session-based	Permanent	Permanent
Firewall rules	None	Automatic (MikroTik)	Automatic (MikroTik)
Public IP needed	No	Yes (BYOIP)	Yes (BYOIP)
Use case	Dev / demos / temp	Production services	Production services

Use Reverse Tunnel when: Quick demos for mesh users, temporary dev/test access, you are on Community tier, or you don’t need permanent access.

Use Port Mapping / Hosted Services when: Permanent service hosting, public internet access needed, you want it listed in the Torus directory, or it needs to survive reboots.

Troubleshooting

Problem	Solution
`Permission denied (publickey)`	Key not uploaded or not synced. Check dashboard status shows CONFIGURED. Use `-i ~/.ssh/nekotopia_jump`.
`remote port forwarding failed`	Port already in use by another user. Pick a different port.
Tunnel connects but no traffic	Check your local service is running. Verify port order: `-R REMOTE:localhost:LOCAL`.
Connection drops after minutes	Add `-o ServerAliveInterval=30`. Use `autossh` for auto-reconnect.
Other users can’t reach the URL	They must be on Torus VPN. Verify WireGuard tunnel is up and routing.

Security Notes

The jump host restricts your SSH key to port forwarding only — no shell access, no file transfer, no agent forwarding.
Services are accessible to all mesh users. Don’t expose anything sensitive without its own authentication.
The tunnel is encrypted end-to-end (SSH + WireGuard).
Your SSH key can be removed from the dashboard at any time, immediately revoking access.