CloudSH

Your Cloud, Self-Hosted.

CloudSH gives you the convenience of managed cloud platforms with the privacy and control of self-hosting. Install the server on any machine, then access it from app.cloudsh.io on your phone, tablet, or desktop browser. Enterprise-grade security, Cloudflare DDoS protection, and complete data privacy — without giving up control.

Website: cloudsh.io · App: app.cloudsh.io · License: MIT

Quick Start

Up and running in 60 seconds.

1. Install

# Homebrew (macOS / Linux)
brew tap JongoDB/cloudsh
brew install cloudsh

# Or install directly
curl -fsSL https://cloudsh.io/install.sh | bash

# Or from source
git clone https://github.com/JongoDB/cloudsh.git
cd cloudsh/packages/server
pip install -e .

2. Start the server

cloudsh start

On first start, CloudSH will:

1. Create a Cloudflare tunnel (if cloudflared is installed)
2. Display a QR code and pairing code in your terminal
3. Prompt you to set a password

3. Connect from any device

Open app.cloudsh.io and scan the QR code or enter the pairing code (CLOUD-XXXXXX). That's it.

Features

• Persistent Terminal Sessions — Powered by tmux. Survive disconnects, reboots, and network changes. Pick up where you left off.
• File Browser — Browse, upload, download, rename, and delete files directly from the web. No SCP or SFTP needed.
• Service Discovery & Proxy — Auto-detects running services and proxies them through the browser. No SSH tunnels to manage.
• Cloudflare DDoS Protection — Every connection routes through Cloudflare's global edge network. Built-in DDoS mitigation and HTTPS everywhere.
• Zero-Trust Security — End-to-end encryption, TOTP 2FA, bcrypt auth, short-lived JWTs. No open ports, no attack surface.
• Any Device, Anywhere — Phone, tablet, laptop, desktop. PWA works in any modern browser.
• Fully Self-Hosted — Your servers, your data, your rules. Terminal traffic never touches our infrastructure. Open source, MIT licensed.
• Infinite Scalability — Raspberry Pi, VPS, bare metal — manage them all from one dashboard.

CLI Commands

cloudsh start                 # Start the server (default: 0.0.0.0:8585)
cloudsh start --port 9090     # Start on a custom port
cloudsh status                # Check if the server is running
cloudsh pair                  # Generate a new pairing code
cloudsh password              # Change the server password
cloudsh link <token>          # Link to CloudSH relay for remote access

Architecture

Zero-trust by design. Your terminal traffic never touches our servers.

┌─────────────┐       HTTPS        ┌─────────────────┐      Tunnel      ┌──────────────┐
│ Your Device │ ◄──────────────► │ Cloudflare Edge │ ◄──────────────► │ Your Server  │
│             │    encrypted       │  DDoS + TLS     │    encrypted     │ tmux + CloudSH│
└─────────────┘                    └─────────────────┘                  └──────────────┘
      │                                                                        │
      │  CLOUD-XXXXXX                                                          │
      └──────────────► CloudSH Relay ──────────────────────────────────────────┘
                       (pairing only)

The relay only resolves pairing codes. During active sessions, all terminal I/O, file transfers, and service proxy traffic flows directly: Device ↔ Cloudflare ↔ Server. Encrypted end-to-end. The relay never sees your data.

Remote Access

For access outside your local network, install cloudflared:

brew install cloudflared            # macOS
sudo apt install cloudflared        # Debian/Ubuntu

CloudSH auto-detects cloudflared and creates a tunnel on startup. Without it, CloudSH works on your local network at http://localhost:8585.

Security

• All connections encrypted (HTTPS via Cloudflare Tunnel or your own TLS)
• Password authentication with bcrypt hashing
• Optional TOTP two-factor authentication
• JWT-based device tokens — no passwords stored on client
• Pairing codes expire after 10 minutes
• Relay only routes connections — terminal traffic goes directly between client and server
• No open ports, no exposed IPs, no attack surface

Configuration

All settings via environment variables with CLOUDSH_ prefix:

Variable	Default	Description
CLOUDSH_PORT	8585	Server port
CLOUDSH_PASSWORD	(setup prompt)	Server password (bcrypt hashed)
CLOUDSH_TUNNEL_ENABLED	true	Enable Cloudflare tunnel
CLOUDSH_JWT_ACCESS_MINUTES	15	JWT access token lifetime
CLOUDSH_JWT_REFRESH_DAYS	7	JWT refresh token lifetime
CLOUDSH_MAX_SESSIONS	10	Maximum concurrent terminal sessions

Requirements

• Python 3.10+
• tmux
• cloudflared (optional, for remote access)

Links

• Website: cloudsh.io
• Web App: app.cloudsh.io
• Docs: cloudsh.io/docs
• Architecture: cloudsh.io/architecture

License

MIT