scitex-ssh 1.0.1

SSH primitives for SciTeX (exec/copy/attach/tunnel; per-host allowlist)

SciTeX SSH (scitex-ssh)

Persistent SSH reverse tunnel for NAT traversal

Full Documentation · uv pip install scitex-ssh[all]

⚠ Heads-up — acceptable use: Before setting up reverse tunnels, check your organization's acceptable use policy and network terms of service. Reverse tunnels may bypass institutional firewalls or network policies. The authors accept no responsibility for any consequences arising from the use of this software.

---

Problem and Solution

#	Problem	Solution
1	Lab machines are behind NAT -- collaborator can't ssh lab-box from the conference	Persistent reverse tunnel -- scitex-ssh setup --port 8888 --bastion gw.example.com installs an autossh systemd service; survives reboots + flaky networks
2	Manual autossh + systemd unit authoring is tedious -- half the team never bothers	One-line lifecycle -- setup / status / remove commands handle the unit file, env vars, restart policy

Architecture

┌─────────────────────────────────────────┐     ┌──────────────────────┐     ┌──────────────────┐
│  Lab Workstation (behind NAT/firewall)  │     │   Bastion Server     │     │  Remote Client   │
│                                         │     │   (public IP)        │     │  (laptop, etc.)  │
│  ┌──────────────────────────────────┐   │     │                      │     │                  │
│  │ systemd service                  │   │     │                      │     │                  │
│  │ autossh-tunnel-{port}.service    │   │     │                      │     │                  │
│  │   ┌──────────────────────────┐   │   │     │  ┌────────────────┐  │     │                  │
│  │   │ autossh                  │   │   │     │  │ sshd listening │  │     │                  │
│  │   │ (auto-reconnect daemon)  │───┼───┼─────┼──│ on port {port} │──┼─────│  ssh -p {port}   │
│  │   │                          │   │   │     │  │                │  │     │  bastion-server  │
│  │   └──────────────────────────┘   │   │     │  └────────────────┘  │     │                  │
│  └──────────────────────────────────┘   │     │                      │     │                  │
│                                         │     │                      │     │                  │
│  localhost:22 (SSH server)              │     │                      │     │                  │
└─────────────────────────────────────────┘     └──────────────────────┘     └──────────────────┘
          ────── reverse tunnel ──────►               ◄─── SSH connection ───
     -R {port}:localhost:22 bastion-server         ssh -p {port} bastion-server

_{Figure 1. Architecture overview. The lab workstation initiates a reverse SSH tunnel to the bastion server. The remote client connects to the bastion server, which forwards the connection back through the tunnel to the lab workstation.}

How It Works

1. setup (requires sudo) writes a systemd unit file at /etc/systemd/system/autossh-tunnel-{port}.service that runs autossh with the reverse tunnel flag (-R {port}:localhost:22). The service is enabled (starts on boot) and started immediately.
2. autossh monitors the SSH connection and automatically re-establishes it if the connection drops — network interruptions, server reboots, or SSH timeouts are handled transparently.
3. systemd ensures the service survives host reboots (WantedBy=multi-user.target) and restarts on process failure (Restart=always, RestartSec=3).
4. A remote client connects to the bastion server on the forwarded port, and the connection is routed back through the tunnel to the lab workstation's SSH server (port 22).

Operation	What it does
setup	Creates a systemd service at /etc/systemd/system/autossh-tunnel-{port}.service that maintains a reverse SSH tunnel via autossh
status	Queries systemd for tunnel service state (systemctl status)
remove	Stops, disables, and deletes the systemd service file

_{Table 1. Three operations. Each maps to a CLI (Command-Line Interface) command, Python function, and MCP (Model Context Protocol) tool.}

Installation

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

pip install scitex-ssh

Configuration

Copy .env.example to .env (gitignored) at your project root, then edit:

cp .env.example .env
$EDITOR .env

CLI flags always override env vars. The full list of variables (with inline comments) lives in .env.example.

Local state directories

scitex-ssh reads optional config + cache from the canonical SciTeX local-state locations:

Path	Scope	Purpose
~/.scitex/ssh/	user-global	per-user config, credentials, cache
<proj-root>/.scitex/ssh/	project-local	overrides for the current repo

Project-local wins when both exist. Both are optional — CLI flags or .env work without either.

Alternative: No-sudo setup via ~/.bashrc (no root access needed)

If you do not have sudo access (e.g., shared HPC nodes, university servers), you can run autossh directly from your shell profile. Add to ~/.bashrc:

# Persistent reverse tunnel without sudo — starts on every login
# Checks if tunnel is already running before starting
if ! pgrep -f "autossh.*-R 2222:localhost:22" > /dev/null 2>&1; then
    autossh -M 0 -f -N \
        -o "PubkeyAuthentication=yes" \
        -o "PasswordAuthentication=no" \
        -o "ServerAliveInterval=30" \
        -o "ServerAliveCountMax=3" \
        -i ~/.ssh/id_rsa \
        -R 2222:localhost:22 [e-mail]
fi

Trade-offs vs. systemd approach:

• No sudo required
• Starts on user login (not on boot — requires an active login session)
• No automatic restart if autossh crashes between logins
• -f runs autossh in the background; -M 0 relies on SSH keepalives

Alternative: Persistent session via screen, tmux, or nohup (no root, survives logout)

For long-running sessions on HPC or shared servers where you want the tunnel to survive logout:

# Option 1: screen (detaches from terminal)
screen -dmS tunnel autossh -M 0 -N \
    -o "ServerAliveInterval=30" -o "ServerAliveCountMax=3" \
    -i ~/.ssh/id_rsa -R 2222:localhost:22 [e-mail]

# Reattach:  screen -r tunnel
# Kill:      screen -S tunnel -X quit

# Option 2: tmux
tmux new-session -d -s tunnel "autossh -M 0 -N \
    -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
    -i ~/.ssh/id_rsa -R 2222:localhost:22 [e-mail]"

# Reattach:  tmux attach -t tunnel
# Kill:      tmux kill-session -t tunnel

# Option 3: nohup (simplest, no terminal multiplexer needed)
nohup autossh -M 0 -N \
    -o "ServerAliveInterval=30" -o "ServerAliveCountMax=3" \
    -i ~/.ssh/id_rsa -R 2222:localhost:22 [e-mail] \
    > /dev/null 2>&1 &

# Kill:      pkill -f "autossh.*-R 2222:localhost:22"

Trade-offs: No sudo needed. Survives logout (unlike ~/.bashrc approach). Does not survive reboot — you must restart manually or add the command to a cron @reboot job.

Alternative: Direct shell scripts (no Python required)

If you have sudo access but prefer not to install Python, use the shell scripts directly:

# Download the scripts (one-time)
curl -o ~/.local/bin/setup-autossh-service.sh \
  https://raw.githubusercontent.com/ywatanabe1989/scitex-ssh/main/src/scitex_ssh/scripts/setup-autossh-service.sh
curl -o ~/.local/bin/remove-autossh-service.sh \
  https://raw.githubusercontent.com/ywatanabe1989/scitex-ssh/main/src/scitex_ssh/scripts/remove-autossh-service.sh
chmod +x ~/.local/bin/setup-autossh-service.sh ~/.local/bin/remove-autossh-service.sh

# Usage (requires sudo)
setup-autossh-service.sh -p 2222 -b [e-mail] -s ~/.ssh/id_rsa
remove-autossh-service.sh -p 2222

Four Interfaces

Python API ⭐

import scitex_ssh

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

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

# Remove tunnel
result = scitex_ssh.remove(2222)

Full API reference

CLI Commands ⭐⭐⭐ (primary)

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

Note: setup and remove write systemd unit files under /etc/systemd/system/ and call systemctl, so they prompt for sudo the first time. status, list-python-apis, and mcp ... do not.

Full CLI reference · run scitex-ssh --help-recursive for the live tree.

MCP Server ⭐⭐

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 (JavaScript Object Notation) parameters and return JSON results.}

scitex-ssh mcp start

Full MCP specification · run scitex-ssh mcp list-tools for the live registry.

Skills ⭐⭐

Bundled _skills/scitex-ssh/ for AI-agent discovery (loaded by Claude Code, MCP-aware tools, or newb):

File	Purpose
SKILL.md	Index — what this package does + tag map
01_quick-start.md	30-second tour
02_python-api.md	Python API surface
10_cli-commands.md	CLI reference
11_mcp-tools-for-ai-agents.md	MCP tool catalog
20_environment-variables.md	SCITEX_SSH_* env vars

scitex-ssh skills list
scitex-ssh skills get quick-start

Full skills directory

Demo

End-to-end flow — from a one-line setup to a remote ssh reaching the lab box behind NAT:

sequenceDiagram
    participant Lab as Lab Workstation<br/>(behind NAT)
    participant Sys as systemd + autossh
    participant Bas as Bastion Server<br/>(public IP)
    participant Cli as Remote Client

    Lab->>Sys: scitex-ssh setup -p 2222 -b user@bastion -s ~/.ssh/id_rsa
    Sys->>Sys: write autossh-tunnel-2222.service
    Sys->>Bas: autossh -R 2222:localhost:22 (reverse tunnel)
    Note over Sys,Bas: Tunnel persistent — survives reboots & flaky links
    Cli->>Bas: ssh -p 2222 user@bastion
    Bas->>Lab: forward via reverse tunnel
    Lab-->>Cli: SSH session established

_{Figure 2. Demo flow. One setup call installs a persistent autossh systemd unit; remote clients then reach the NAT-bound lab workstation via ssh -p 2222 bastion.}

# On the lab workstation (one-time, requires sudo):
$ scitex-ssh setup -p 2222 -b [e-mail] -s ~/.ssh/id_rsa
[ok] systemd unit autossh-tunnel-2222.service installed and started

$ scitex-ssh status -p 2222
autossh-tunnel-2222.service — active (running)

# From any remote client:
$ ssh -p 2222 [e-mail]
# → reaches the lab workstation through the reverse tunnel

Part of SciTeX

scitex-ssh is part of SciTeX. Install via the umbrella with pip install scitex[ssh] to use as scitex.ssh (Python) or scitex ssh ... (CLI).

SciTeX follows the Four Freedoms for Research below, inspired by the Free Software Definition:

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 we believe research infrastructure deserves the same freedoms as the software it runs on.

---