CloudSSH

A Serverless Web SSH Terminal built on Cloudflare Workers: Connect and manage your servers directly from the browser.

Ultra-lightweight · Out-of-the-box · Cyberpunk UI

Highlights · Features · Deployment · Architecture · License

简体中文 | English

Tip

CloudSSH utilizes Cloudflare Workers' TCP Sockets support to handle SSH protocol parsing and forwarding at edge nodes, providing a low-latency Web Terminal experience.

Demo

Imagine opening your browser anytime, anywhere, and connecting to your server with a highly futuristic cyberpunk UI, without installing any SSH client.

Table of Contents

• Highlights
• Features
• Architecture
• Quick Deployment
  • GitHub Integration
  • Local CLI Deployment
  • Configure Turnstile
  • Configure GitHub OAuth
• Development
  • Local Development
  • Tech Stack
• License

Highlights

Ultimate Serverless

• Zero Server Cost: Pure frontend deployment + Cloudflare Workers, no need to build your own backend servers.
• Edge Acceleration: Benefit from Cloudflare's global edge network, enjoying low-latency SSH connections from anywhere.

Out of the Box

• One-Click Deployment: Build and deploy the project with a single command using the Wrangler CLI.
• Modern Frontend Stack: TypeScript + Vite + Tailwind CSS, paired with xterm.js to provide a silky smooth terminal experience.

Secure and Reliable

• End-to-End Encryption: Complete SSH-2.0 protocol implementation supporting Curve25519-SHA256 (preferred) and ECDH-NISTP256 key exchange, AES-256-GCM (preferred) / AES-128-GCM / AES-256-CTR data encryption, and HMAC-SHA2-256/512 integrity verification.
• Multi-Algorithm Host Key Verification: Supports Ed25519, ECDSA P-256, and RSA signature verification, with SHA-256 fingerprint display on first connection (TOFU mode).
• Security Hardening: Built-in SSRF protection against IPv6 and reserved IPs, API rate limiting (anti-brute force), and local AES-256-GCM encryption for your stored server credentials.
• Human Verification: Supports Cloudflare Turnstile verification to prevent malicious bot abuse.
• Isolated Session State: Leveraging Cloudflare Durable Objects and the Hibernation API, every terminal session runs securely and persistently within its sandbox.
• Zero Credential Exposure: One-Time-Token mechanism ensures passwords/private keys never pass through the frontend, securely flowing entirely within the Worker.

Features

• Pure TypeScript SSH-2.0 Implementation: Fully self-developed SSH protocol stack, with no dependency on any third-party SSH libraries, implementing all cryptographic operations based on Web Crypto API.
• Multi-Algorithm Key Exchange: Supports Curve25519-SHA256 (preferred) and ECDH-NISTP256 KEX algorithms, compatible with various SSH servers (including Dropbear).
• IPv4/IPv6 Dual Stack: Full support for both IPv4 and IPv6 address connections, including automatic handling of IPv6 bracket notation.
• Multiple Auth Methods: Supports standard SSH password authentication as well as Ed25519 plaintext private key authentication.
• MitM Protection (TOFU): Automatically extracts and prints the server's Host Key (SHA-256 fingerprint) on the first connection, supporting Ed25519/ECDSA/RSA signature verification.
• Geek Terminal Experience: Powered by @xterm/xterm and the @xterm/addon-webgl hardware acceleration rendering engine, ensuring silky smooth scrolling even with massive log outputs.
• Customizable UI: Switch seamlessly between classic terminal themes like Cyberpunk, Glacier, and Gruvbox, fully optimized for mobile devices.
• Native File Transfer: Integrated with trzsz.js, supporting trz (upload) / tsz (download) commands for file transfer, fully compatible with tmux sessions. Also supports drag-and-drop file upload to the terminal, directory transfer, and resumable transfers. (Requires trzsz installed on the remote server)
• GitHub OAuth Integration: Supports GitHub login, allowing users to save and manage frequently used SSH servers for one-click connections.

Architecture

System Architecture

flowchart TB
    subgraph "Browser Client"
        UI["Frontend UI<br/>TypeScript + xterm.js"]
        Trzsz["trzsz File Transfer"]
    end
    
    subgraph "Cloudflare Edge Network"
        Worker["Worker<br/>Routing + API"]
        SSH_DO["SSHSessionDO<br/>SSH Session Management"]
        User_DO["UserDBDO<br/>User Data Management"]
    end
    
    subgraph "Target Server"
        SSH["SSH Server<br/>(OpenSSH/Dropbear)"
    end

    UI <-->|"WebSocket<br/>Terminal I/O"| Worker
    Trzsz <-->|"trzsz Protocol"| UI
    Worker <-->|"WebSocket"| SSH_DO
    Worker <-->|"Internal API"| User_DO
    SSH_DO <-->|"TCP Socket<br/>@cloudflare/sockets"| SSH

Core Components

Component	File	Responsibility
Worker Entry	src/worker/index.ts	HTTP routing, API handling, WebSocket upgrade
SSHSessionDO	src/worker/durable-object.ts	SSH session lifecycle management, SSRF protection
UserDBDO	src/worker/user-db.ts	User data, server configs, rate limiting (SQLite)
SSHSession	src/worker/ssh-session.ts	SSH protocol state machine (connect→version→kex→auth→interactive)
SSH Protocol Stack	src/ssh/*.ts	Pure TypeScript SSH-2.0 implementation (transport, crypto, auth, channels)
Frontend Terminal	frontend/src/terminal.ts	xterm.js wrapper, trzsz integration, WebSocket management

SSH Protocol Implementation

This project implements a complete SSH-2.0 protocol stack:

Layer	Implementation	Supported Algorithms
Key Exchange	kex-curve25519.ts / kex-ecdh.ts	curve25519-sha256, ecdh-sha2-nistp256
Data Encryption	crypto.ts	aes256-gcm, aes128-gcm, aes256-ctr, aes192-ctr, aes128-ctr
Integrity	crypto.ts	hmac-sha2-256, hmac-sha2-512, hmac-sha1
Host Keys	ssh-session.ts	Ed25519, ECDSA P-256, RSA
User Auth	auth.ts	Password authentication, Ed25519 public key authentication
Channel Management	channel.ts	Session channel, PTY, shell, window-change

Data Flow

1. The user enters the host IP, username, and password on the frontend (or selects a saved server via GitHub OAuth).
2. The frontend establishes a WebSocket connection with the backend Durable Object.
3. SSHSessionDO receives the credentials and establishes a TCP connection with the target SSH server using @cloudflare/sockets.
4. SSHSession executes the complete SSH protocol negotiation (version exchange → key exchange → authentication → channel open → PTY → Shell).
5. Encrypted terminal data is bidirectionally forwarded between the frontend and SSH server via WebSocket.

Quick Deployment

Prerequisites

• A Cloudflare account.
• Node.js environment (v18+).
• Cloudflare Workers Free Plan enabled (required for TCP Sockets and Durable Objects features).

Steps

Method 1: Deploy via GitHub Integration (Recommended)

1. Fork this repository to your GitHub account.
2. Create Worker App: Log in to Cloudflare, go to Workers & Pages, click Create Application, connect your GitHub account, and select the forked repository.
3. Build Command: During deployment settings, enter pnpm run build:frontend as the Build command, then save and deploy.
4. Access the App: After successful deployment, access via the default domain https://cloudssh.<your-subdomain>.workers.dev.
5. Bind Custom Domain (Optional): Go to Worker Settings → Domains & Routes → Add, enter your domain and confirm.

Note

: To deploy a test environment, repeat the above steps on the test branch to create a separate Worker (e.g., cloudssh-test). Both Workers share the same DO class names for data synchronization.

Method 2: Local CLI Deployment

1. Clone the Repository

   git clone https://github.com/newbietan/CloudSSH.git
   cd CloudSSH
   

2. Install Dependencies

   npm install -g pnpm
   pnpm install
   cd frontend && pnpm install
   

3. Login to Cloudflare

   npx wrangler login
   

4. Deploy Production

   pnpm run deploy
   

5. Deploy Test Environment (Optional)

   pnpm run deploy:test
   

Environment	Command	Default Domain	Description
Production	pnpm run deploy	cloudssh.<subdomain>.workers.dev	main branch code
Test	pnpm run deploy:test	cloudssh-test.<subdomain>.workers.dev	test branch code, shares DO data with production

Note

: Both environments bind to Durable Objects with the same class_name, sharing data completely. After deployment, you can bind different custom domains for each environment in the Cloudflare Dashboard (Settings → Domains & Routes).

Optional: Configure Turnstile Human Verification

To prevent malicious bot abuse, it is recommended to enable Cloudflare Turnstile verification:

1. Create Turnstile Widget: Log in to Cloudflare Dashboard, go to the Turnstile page and create a new Widget.
2. Get Keys: After creation, you will receive a Site Key (public) and a Secret Key (private).
3. Configure Environment Variables: In the Cloudflare Dashboard Workers settings, go to "Settings" → "Variables and Secrets", add the following environment variables:
   • TURNSTILE_SECRET = your Secret Key (Type: Secret)
   • TURNSTILE_SITEKEY = your Site Key (Type: Text)
4. Redeploy: Run the deployment command to apply the configuration.

Note

: Turnstile verification is session-level. After verification, all features are available for the current session. Closing the browser will require re-verification.

Optional: Configure GitHub OAuth Login & Server Management

With GitHub OAuth enabled, users can log in with their GitHub account and save/manage their frequently used SSH servers in a personal dashboard for one-click connections. When not configured, this feature is automatically hidden and does not affect the anonymous SSH connection functionality.

1. Create a GitHub OAuth App:

   • Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
   • Application name: CloudSSH (customizable)
   • Homepage URL: https://your-domain.com (your deployed domain)
   • Authorization callback URL: https://your-domain.com/api/auth/callback
   • After creation, note the Client ID, then click Generate a new client secret to get the Client Secret (shown only once, save it immediately)

2. Configure Environment Variables: In the Cloudflare Dashboard Workers settings, go to "Settings" → "Variables and Secrets", add the following environment variables:

   • GITHUB_CLIENT_ID = your Client ID (Type: Text)
   • BASE_URL = https://your-domain.com (your deployed domain, Type: Text)
   • GITHUB_CLIENT_SECRET = your Client Secret (Type: Secret)

3. Redeploy: If you just added the variables and are enabling the feature for the first time, you must delete the old deployment and redeploy to initialize the database.

Note

: Server credentials (passwords/private keys) are encrypted with AES-256-GCM before storage. The local encryption key is automatically generated and safely stored in the database (you can also manually override it by setting SESSION_SECRET in environment variables). During connection, credentials never pass through the frontend — they are securely transmitted via a one-time-token mechanism.

Important

: Enabling this feature for the first time requires a clean deployment (delete the old Worker first, then redeploy) to initialize the new Durable Object. Use npx wrangler delete cloudssh to remove the old Worker, then run pnpm run deploy to redeploy.

Development

Project Structure

This project uses pnpm monorepo workspace structure:

CloudSSH/
├── src/                    # Backend source (Cloudflare Worker)
│   ├── ssh/                # SSH protocol pure implementation layer
│   └── worker/             # Worker entry and Durable Objects
├── frontend/               # Frontend source (independent workspace)
│   ├── src/                # TypeScript + xterm.js + trzsz
│   └── package.json        # Frontend dependencies
├── scripts/                # Build scripts
├── pnpm-workspace.yaml     # pnpm workspace configuration
└── wrangler.toml           # Cloudflare deployment configuration

Local Development

Environment Setup

1. Fork and Clone the Repository

   git clone https://github.com/<your-username>/CloudSSH.git
   cd CloudSSH
   

2. Install Dependencies (root and frontend separately)

   pnpm install
   cd frontend && pnpm install
   

3. Login to Cloudflare (required on first run, credentials are cached afterward)

   npx wrangler login
   

   Note

   : When using Wrangler Dev for local development, it connects to your Cloudflare account to access Durable Objects and TCP Sockets. Real SSH TCP traffic is forwarded through Cloudflare's infrastructure.

Start Development Server

pnpm run dev

This command builds the frontend and starts the Wrangler local development environment, supporting:

• Automatic rebuild on frontend code changes
• Automatic reload on Worker code changes
• Full Durable Objects and TCP Sockets functionality

After the dev server starts, visit the local address shown in the terminal (usually http://localhost:8787) to start debugging.

Common Development Commands

Command	Description
pnpm run dev	Build frontend + start Wrangler dev server
pnpm run build:frontend	Build frontend only (output to frontend/dist/)
pnpm test	Run tests

Submitting a PR

1. Create your feature branch from main: git checkout -b feat/your-feature
2. Develop and test locally
3. Submit a PR to the main branch

Note

: The test branch is a pre-release branch for deploying the test environment. For regular development, work based on the main branch.

Tech Stack

Layer	Technology	Description
Frontend	TypeScript + Vite + xterm.js	Web terminal emulator, WebGL hardware acceleration
UI Framework	Tailwind CSS (CDN)	Cyberpunk-style dark theme
File Transfer	trzsz.js	Supports trz/tsz commands, drag-and-drop upload, resumable transfers
Backend	Cloudflare Workers	Serverless edge computing
Session Management	Durable Objects	SSH session isolation, Hibernation API
Data Storage	Durable Objects SQLite	User data, server configurations
Package Manager	pnpm (workspace)	Monorepo dependency management

License

This project is open-sourced under the Apache License 2.0.

Special Notice: Commercial use and modifications are permitted, but you must clearly attribute the original author.

Issues and Pull Requests are welcome to help build the community. If you find this project helpful, please consider giving it a ⭐ Star. Thank you very much for your support!

Star History