Documentation

Get started in 60 seconds.

# Installation

CloudSH runs on Linux and macOS (Intel + ARM). Requirements: Python 3.10+ and tmux.

Homebrew (macOS / Linux)

$ brew tap JongoDB/cloudsh

$ brew install cloudsh

Install script

$ curl -fsSL https://cloudsh.io/install.sh | bash

From source

$ git clone https://github.com/JongoDB/cloudsh.git

$ cd cloudsh/packages/server

$ pip install -e .

# Quick Start

1

Start the server

$ cloudsh start

Starts on port 8585 and displays a pairing code.

2

Open the app

Go to app.cloudsh.io on any device.

3

Enter your pairing code

Type the CLOUD-XXXXXX code from your terminal. Done.

# 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

# 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. The pairing code routes through the tunnel automatically.

# 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