scitex-tunnel 0.1.0

Persistent SSH reverse tunnel for SciTeX (NAT traversal)

SciTeX Tunnel (scitex-tunnel)

Persistent SSH reverse tunnel for NAT traversal

Full Documentation · pip install scitex-tunnel

---

Problem

Machines behind NAT or institutional firewalls cannot receive incoming SSH connections. Researchers running long experiments on lab workstations, HPC nodes, or edge devices need reliable remote access without manual port forwarding or VPN setup. Existing solutions (ngrok, cloudflared) often require external accounts or lack systemd integration for persistent, auto-recovering connections.

Solution

SciTeX Tunnel creates persistent reverse SSH tunnels using autossh and systemd. Each tunnel runs as a managed service that auto-restarts on failure, survives reboots, and requires only a bastion server with SSH access.

Host (behind NAT) --[reverse tunnel]--> Bastion Server <--[SSH]--> Client

Operation	What it does
setup	Creates a systemd service that maintains a reverse SSH tunnel via autossh
status	Queries systemd for tunnel service state
remove	Stops, disables, and deletes the systemd service

_{Table 1. Three operations. Each maps to a CLI command, Python function, and MCP tool.}

Installation

Requires autossh on the host machine (sudo apt install autossh).

pip install scitex-tunnel

SciTeX users: pip install scitex already includes tunnel support.

Quick Start

# Set up a persistent reverse tunnel
scitex-tunnel setup -p 2222 -b [e-mail] -s ~/.ssh/id_rsa

# Check tunnel status
scitex-tunnel status

# Remove a tunnel
scitex-tunnel remove -p 2222

Three Interfaces

Python API

import scitex_tunnel

# Set up tunnel
result = scitex_tunnel.setup(2222, "[e-mail]", "~/.ssh/id_rsa")

# Check status
result = scitex_tunnel.status()
result = scitex_tunnel.status(port=2222)

# Remove tunnel
result = scitex_tunnel.remove(2222)

Full API reference

CLI Commands

scitex-tunnel --help-recursive                # Show all commands
scitex-tunnel setup -p 2222 -b user@host -s ~/.ssh/id_rsa
scitex-tunnel status                          # All tunnels
scitex-tunnel status -p 2222                  # Specific port
scitex-tunnel remove -p 2222                  # Remove tunnel
scitex-tunnel list-python-apis                # List Python API
scitex-tunnel mcp list-tools                  # List MCP tools

Full CLI reference

MCP Server — for AI Agents

AI agents can manage tunnels autonomously.

Tool	Description
tunnel_setup	Set up a persistent SSH reverse tunnel
tunnel_status	Check status of SSH reverse tunnels
tunnel_remove	Remove a persistent SSH reverse tunnel

_{Table 2. Three MCP tools. All tools accept JSON parameters and return JSON results.}

scitex-tunnel mcp start

Full MCP specification

Part of SciTeX

Tunnel is part of SciTeX. When used inside the SciTeX framework, tunnel management integrates with the orchestrator:

import scitex

# Manage tunnels through the unified interface
result = scitex.tunnel.setup(2222, "[e-mail]", "~/.ssh/id_rsa")
scitex.tunnel.status()

The SciTeX ecosystem follows the Four Freedoms for researchers:

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because research infrastructure deserves the same freedoms as the software it runs on.

---