tunnel-proxy（隧道 Agent）

🚇 Security Warning

This skill enables remote command execution and file transfer on your machine.

Before use:

• Set TUNNEL_HOST=127.0.0.1 unless you intentionally expose the service
• Use random high ports (49152-65535) for public exposure
• Run TunnelProxy under a restricted user account
• Review the included scripts before execution
• Token authentication required for all operations

Do NOT use with untrusted third-party Agent services.

TunnelProxy Skill (v0.3.3+)

Overview

This skill enables AI agents running in cloud sandboxes to bypass network restrictions by utilizing the user's local TunnelProxy service. It provides:

• Remote command execution via one-time PTY Shell (random TCP port)
• Persistent agent sessions with unique Agent tokens
• Bidirectional file transfer via HTTP interface
• HTTP reverse proxy to access blocked resources through user's network
• Static file server for browsing and downloading files
• Web upload page for easy file upload from browser
• Unrestricted network access through user's local connection

Architecture

AI Agent (Cloud Sandbox)
│
├── HTTP API (command execution, result polling)
│   POST /api/exec → POST /api/heartbeat → GET /api/result/:task_id
│
├── One-Time PTY Session (interactive shell)
│   POST /api/session → get random port → nc <host> <port>
│
├── File Server (browse & download)
│   GET / → directory listing → GET /path/to/file → download
│
├── File Upload
│   POST /upload → binary upload with magic-word protocol
│   GET /upload → web upload page
│
└── HTTP Reverse Proxy
GET /proxy?url=https://blocked-site.com → fetch through user's IP

Quick Start

1. Register Your Agent & Get Token

import requests

host = "${TUNNEL_HOST:-127.0.0.1}"
http_port = "${TUNNEL_HTTP_PORT:-8080}"

resp = requests.post(f"http://{host}:{http_port}/api/register", json={
    "agent_id": "my-agent",
    "hostname": "sandbox",
    "username": "ai",
    "os": "linux"
})
token = resp.json()["token"]
print(f"Token: {token}")

1. Request a One-Time PTY Session

resp = requests.post(f"http://{host}:{http_port}/api/session", json={
    "token": token
})
pty_port = resp.json()["port"]
print(f"PTY port: {pty_port}")  # Random port (30001-65000), valid for 10 seconds

3a. Connect to Interactive Shell

# Connect within 10 seconds of requesting session
nc ${TUNNEL_HOST} ${pty_port}
# Directly drops into fish shell, no further auth needed

3b. Execute Commands via HTTP API

# Submit command
resp = requests.post(f"http://{host}:{http_port}/api/exec", json={
    "agent_id": "my-agent",
    "token": token,
    "cmd": "whoami && pwd"
})
task_id = resp.json()["task_id"]

# Poll for result
import time
while True:
    result = requests.get(f"http://{host}:{http_port}/api/result/{task_id}").json()
    if result["status"] == "complete":
        print(result["output"])
        break
    time.sleep(0.2)

1. Browse & Download Files

# Directory listing
import requests
html = requests.get(f"http://{host}:{http_port}/").text

# Download a file
with requests.get(f"http://{host}:{http_port}/path/to/file.txt", stream=True) as r:
    with open("file.txt", "wb") as f:
        for chunk in r.iter_content(8192):
            f.write(chunk)

# Using curl
curl http://${TUNNEL_HOST}:${TUNNEL_HTTP_PORT}/path/to/file -O

1. Upload Files

Via curl:

curl -X POST http://${TUNNEL_HOST}:${TUNNEL_HTTP_PORT}/upload --data-binary @file.txt

Via Python:

from http_transfer import TunnelHTTP
http = TunnelHTTP()
response = http.upload("./local_file.tar.gz")

Via browser: Visit http://${TUNNEL_HOST}:${TUNNEL_HTTP_PORT}/upload

1. HTTP Reverse Proxy (Access Blocked Resources)

# Access a blocked site through user's IP
curl "http://${TUNNEL_HOST}:${TUNNEL_HTTP_PORT}/proxy?url=https://pypi.org/simple/"

import requests
resp = requests.get(
    f"http://{host}:{http_port}/proxy",
    params={"url": "https://httpbin.org/ip"}
)
print(resp.text)  # Shows user's IP, not sandbox IP

1. Fetch Remote Content via User's Network

# Let user's machine fetch blocked content for you
echo "curl -s https://pypi.org/simple/" | nc ${TUNNEL_HOST} ${pty_port}

# Download large file via user's network
echo "curl -sL https://example.com/large.iso -o /tmp/large.iso" | nc ${TUNNEL_HOST} ${pty_port}

1. Handle Binary Files

For binary data, use http_transfer.py which properly handles multipart form-data:

from http_transfer import TunnelHTTP

http = TunnelHTTP()
http.upload("./screenshot.png")
http.download("/remote/binary.dat", "./local.dat")

API Reference

Agent Management

Method Path Description POST /api/register Register new agent POST /api/heartbeat Agent heartbeat keep-alive GET /api/agents List all online agents POST /api/session Request one-time PTY session (returns random port)

Command Execution

Method Path Description POST /api/exec Submit command for execution GET /api/result/:task_id Poll command result

File Operations

Method Path Description GET /* Browse files (directory listing) or download GET /upload Web upload page POST /upload Upload file (binary, magic-word protocol)

Network

Method Path Description GET /proxy HTTP reverse proxy (?url=https://...)

Environment Variables

Variable Default Description TUNNEL_HOST 127.0.0.1 TunnelProxy host address TUNNEL_HTTP_PORT 8080 HTTP API port TUNNEL_AGENT_TOKEN - Pre-configured agent token TUNNEL_TIMEOUT 60 Default timeout in seconds UPLOAD_MAGIC MY_MAGIC_2025_FILE_HEAD Upload verification token TUNNEL_DOC_ROOT ./www Static files root directory TUNNEL_UPLOAD_DIR ./uploads Upload destination directory

Included Scripts

This skill includes two minimal scripts:

· tunnel_login.py – Verify HTTP API connectivity and login · http_transfer.py – Binary-safe file upload/download

Common Use Cases

Bypass PyPI blocking for pip install

import socket

s = socket.socket()
s.connect(("${TUNNEL_HOST}", pty_port))
s.send(b"pip download torch --no-deps -d /tmp\
")
s.close()

# Then pull the file
from http_transfer import TunnelHTTP
http = TunnelHTTP()
http.download("/tmp/torch.whl", "./torch.whl")

Access internal company resources

echo "curl -s http://internal-company-server/api/data" | nc ${TUNNEL_HOST} ${pty_port}

Transfer large files with progress

http = TunnelHTTP()
http.download("/system/fonts/NotoSansCJK.ttc", "./font.ttc")

Use as HTTP proxy for Python packages

import requests
resp = requests.get(
    f"http://{host}:{http_port}/proxy",
    params={"url": "https://pypi.org/simple/requests/"}
)

Error Handling

import socket
from http_transfer import TunnelHTTP

try:
    s = socket.socket()
    s.settimeout(10)
    s.connect(("${TUNNEL_HOST}", pty_port))
    s.send(b"ls\
")
    result = s.recv(4096).decode()
except socket.timeout:
    print("Command timeout - increase TUNNEL_TIMEOUT")
except ConnectionRefusedError:
    print("TunnelProxy not running - start the service first")
except Exception as e:
    print(f"Error: {e}")
finally:
    s.close()

Security Notes

This skill grants the agent complete control over commands executed on the user's machine. Only use with:

· Fully trusted AI agents you control · Users who understand the security implications · In environments with additional safeguards (firewalls, UPLOAD_MAGIC) · Token authentication enabled on the server

Troubleshooting

Issue Solution Connection refused TunnelProxy not running → start with iex -S mix invalid token Check agent registration or preset agent config PTY session timeout Request new session (ports discarded after 10s) Command returns empty Use HTTP API for persistent result collection Binary file corrupted Use http_transfer.py instead of manual socket Upload fails Check if UPLOAD_MAGIC matches server configuration

📖 Practical Tips & Common Pitfalls

For detailed usage patterns, troubleshooting, and advanced techniques, see TIPS.md.

Quick reference:

Problem Solution (see TIPS.md for details) Empty output Add ; echo MARKER or use stty -echo Binary corruption Use HTTP channel, not PTY Command timeout Wrap with timeout command Large file transfer Use http_transfer.py, not cat Stuck command Avoid interactive commands Exit code capture Echo $? after command

TL;DR: Use nc for commands, http_transfer.py for files.