Architecture

Zero-trust by design.

Your terminal traffic never touches our servers. The relay resolves pairing codes — everything else is a direct encrypted connection through Cloudflare. Here's exactly how it works.

# Connection Architecture

CloudSH uses a zero-trust architecture where your servers are never exposed to the public internet. Every connection flows through Cloudflare's encrypted tunnel — no open ports, no attack surface, no exposed IPs.

connection flow

Phase 1 — Pairing (one-time setup)

cloudsh start

Starts server + cloudflared

CloudSH Relay

Maps CLOUD-XXXXXX → tunnel URL

User scans QR / enters code

Gets tunnel URL back

Phase 2 — Active Session (relay is gone)

Your Device

Browser + xterm.js

Cloudflare Edge

DDoS + TLS + CDN

Your Server

tmux + CloudSH + cloudflared

No relay involved during active sessions. All terminal I/O, file transfers, and service proxy traffic flows directly: Device ↔ Cloudflare ↔ Server. Encrypted end-to-end.

# Authentication

Multi-layer authentication ensures only authorized devices can access your servers. No passwords are ever stored on client devices.

auth flow
1

Pairing

Scan QR or enter 6-char code. Code expires in 10 minutes. One-time use.

2

Password

Server password verified against bcrypt hash. Never transmitted in plaintext — HTTPS only.

3

2FA (optional)

TOTP code from any authenticator app. Google Authenticator, Authy, 1Password, Bitwarden.

4

JWT Token

Short-lived JWT issued. Stored on device. No password stored on client. Token auto-refreshes.

# Where Your Data Lives

CloudSH is fundamentally different from managed cloud platforms. Your data stays on your hardware — always.

Your Server

  • Terminal session data
  • All files and file transfers
  • Running services and ports
  • Password hash (bcrypt)
  • 2FA secret (TOTP)
  • Server configuration

100% of your data. Always.

Cloudflare

  • • TLS termination (in-transit only)
  • • DDoS filtering
  • • Tunnel routing metadata

Passes through. Never stored.

CloudSH Relay

  • • Pairing code → tunnel URL map
  • • Expires after 10 minutes

Pairing codes only. No data.

# Tunnel Management

CloudSH automatically manages Cloudflare Tunnels. No configuration required — just have cloudflared installed.

tunnel lifecycle
1

Startup Detection

cloudsh start checks if cloudflared is installed. If found, creates a quick tunnel automatically.

2

Tunnel Creation

CloudSH launches cloudflared tunnel --url localhost:8585 and captures the generated URL. No Cloudflare account needed for quick tunnels.

3

Pairing Code Registration

The tunnel URL is registered with the CloudSH relay under a unique 6-character code (e.g., CLOUD-A7X9BK). A QR code is generated and displayed in the terminal.

4

Health Monitoring

CloudSH monitors the tunnel connection. If the tunnel drops, it automatically restarts cloudflared and re-registers the pairing code. Zero downtime.

# Session Persistence

Terminal sessions are backed by tmux and survive any kind of disruption. Your work is never lost.

Session Lifecycle

connect WebSocket opens → attaches to existing tmux session or creates new one
working Terminal I/O streams over WebSocket through Cloudflare Tunnel. Full PTY emulation via xterm.js.
disconnect WebSocket closes. tmux session keeps running. All processes continue. Nothing is lost.
reconnect New WebSocket → re-attaches to same tmux session. Scrollback buffer intact. Resume exactly where you left off.

Survives Everything

  • Network disconnects
  • WiFi ↔ cellular switches
  • Browser tab closed
  • Device sleep / wake
  • Tunnel reconnections
  • Server reboots (tmux restores via systemd)

Sessions persist until you explicitly close them.

# CloudSH vs. The Alternatives

Traditional approaches force you to choose between convenience and control. CloudSH gives you both.

CloudSH Traditional SSH VPN + SSH Managed Cloud
Open ports required None Port 22 VPN port N/A
DDoS protection Cloudflare None None Provider-level
Data location Your hardware Your hardware Your hardware Provider's servers
Browser access Yes No No Yes
Mobile access PWA & Mobile App SSH app VPN app + SSH Varies
Session persistence Automatic Manual tmux Manual tmux Varies
File management Built-in SCP/SFTP SCP/SFTP Varies
Service proxy Auto-detect SSH -L tunnels Manual config Varies
Setup time 60 seconds Key exchange Hours Minutes
Vendor lock-in None (MIT) None VPN provider High
Your own hardware Any device you own Your hardware Your hardware VMs only