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.
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.
Pairing
Scan QR or enter 6-char code. Code expires in 10 minutes. One-time use.
Password
Server password verified against bcrypt hash. Never transmitted in plaintext — HTTPS only.
2FA (optional)
TOTP code from any authenticator app. Google Authenticator, Authy, 1Password, Bitwarden.
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.
Startup Detection
cloudsh start checks if cloudflared is installed. If found, creates a quick tunnel automatically.
Tunnel Creation
CloudSH launches cloudflared tunnel --url localhost:8585 and captures the generated URL. No Cloudflare account needed for quick tunnels.
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.
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
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 | 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 |