Cloudflare Shell Tunnel

Cloudflare Shell Tunnel

A lightweight remote shell service that exposes a local HTTP shell over a public Cloudflare Tunnel URL. Designed for agent-based remote invocation (e.g. Claude Code, Codex, OpenCode, etc.) so an AI agent can execute commands, upload, and download files on a remote machine (Colab, VPS, laptop, etc.).

• Server side: Python HTTP server (shell_tunnel.py) + Cloudflare Tunnel
• Client side: Simple Bash CLI (shell_tunnel.sh) that talks to the public tunnel URL

graph TD

    subgraph Server["Server Side (Remote Machine)"]
        Py["shell_tunnel.py"]
        HTTP["HTTP Server
:8787"]
        ShellExec["Shell / Filesystem"]
    end
    
    subgraph Internet
        CF["Cloudflare Tunnel
(*.trycloudflare.com)"]
    end

    subgraph Client["Client Side"]
        Agent["AI Agent
(Claude Code / Cursor / etc.)"]
        Shell["shell_tunnel.sh"]
        Site["site.txt
(tunnel URL)"]
    end

    Agent -->|exec / upload / download| Shell
    Shell -->|reads| Site
    Shell -->|HTTPS requests| CF
    CF -->|forwards| HTTP
    HTTP --> Py
    Py --> ShellExec

Features

• POST /exec – run any shell command and get stdout, stderr, returncode
• POST /upload – upload a file (base64 encoded)
• GET /download?path=... – download a file
• Automatic download of the correct cloudflared binary
• Temporary public URL via Cloudflare Tunnel (no account required for quick tunnels)
• Zero configuration beyond running the server

Repository Structure

.
├── shell_tunnel.py    # HTTP shell server + Cloudflare Tunnel
├── shell_tunnel.sh    # Client CLI (Bash)
└── site.txt           # (created by you) contains the tunnel URL

Installation

1. Clone the repository

git clone https://github.com/Erickrus/cloudflare_shell_tunnel.git
cd cloudflare_shell_tunnel

2. Make the client executable

chmod +x shell_tunnel.sh

3. (Optional) Create a virtual environment

``