hypershell-app

HyperShell

A production-quality, web-based SSH client — like Termius, but as a self-hosted web application. Manage remote servers through a modern browser UI with a full-featured terminal, SFTP file manager, code editor, and more.

Features

Terminal

• xterm.js 6 terminal with WebGL rendering, split panes, and tabs
• Searchable terminal output with web-link detection and inline image support
• Session recording and playback
• Configurable themes, fonts, and scrollback

SFTP File Manager

• Dual-pane file browser with drag-and-drop
• File previews (text, image, PDF)
• Cross-host file transfer and batch operations
• Upload and download with progress tracking

Code Editor

• CodeMirror 6 editor with syntax highlighting (JavaScript, Python, Rust, YAML, Markdown)
• Multi-tab editing with conflict detection and auto-save
• Diff/merge view for unsaved changes

Tmux Integration

• Create, attach, and detach tmux sessions from the UI
• Visual session list with one-click attach

Networking

• Port forwarding — local, remote, and dynamic SOCKS proxy
• ProxyJump / bastion host chaining
• Tailscale peer discovery for zero-config LAN access

Command Snippets

• Save and organize reusable command snippets
• Multi-host parallel execution

Security

• Age-encrypted credential vault (passwords, SSH keys)
• Role-based access control (admin / operator / viewer)
• Authentication via magic link email and WebAuthn (passkeys)
• Full audit logging of connections and actions

Infrastructure

• Docker container management (list, inspect, logs, exec)
• Device metrics collection and dashboards
• Notification webhooks
• Collaboration / session sharing
• PWA with offline support

Architecture

HyperShell is a monorepo with three deployment targets:

hypershell/
├── apps/
│   ├── server/       # Rust backend (Axum, russh, SQLite, age)
│   ├── web/          # TanStack Start frontend (React 19, Vite, TailwindCSS 4)
│   └── cloudflare/   # Cloudflare Workers + Durable Objects (Hono)
├── packages/
│   └── shared/       # Shared TypeScript types and constants
├── bin/              # CLI entry point (npx hypershell)
├── scripts/          # Build, deploy, and CLI helper scripts
├── docker/           # Docker SSH test server configuration
└── prebuilt/         # Pre-built server binaries (per platform)

Deployment Modes

Mode	Description
Local	Rust server + built frontend served on localhost:3100. Single-binary, zero-cloud.
Cloudflare	Hono Workers + D1 database + R2 storage + Durable Objects for WebSocket relay.
Hybrid	Local Rust server with a WSS uplink to Cloudflare for remote/mobile access.

Prerequisites

Tool	Version	Required
Rust	1.95+	Yes (local/hybrid mode)
Node.js	22+	Yes
pnpm	10+	Yes
Docker	Latest	For SSH test server
Tailscale	Latest	Optional — peer discovery
Cloudflare account	—	For Cloudflare/hybrid mode

Getting Started

1. Clone and install dependencies

git clone <repo-url> && cd hypershell
pnpm install

2. Start the SSH test server (optional)

docker compose up -d
# SSH available at localhost:2222 (user: testuser / pass: testpass)

3. Start the development servers

Run the Rust backend and Vite dev server concurrently:

# Terminal 1 — Rust server (API on :3100)
cargo run --manifest-path apps/server/Cargo.toml

# Terminal 2 — Vite frontend dev server (on :3101, proxies API to :3100)
pnpm --filter web dev

Open http://localhost:3101 in your browser.

Environment Variables

Variable	Default	Description
HYPERSHELL_PORT	3100	Rust server listen port
HYPERSHELL_DB_PATH	hypershell.db	SQLite database file path
HYPERSHELL_STATIC_DIR	—	Path to built frontend assets (production)
HYPERSHELL_HYBRID_RELAY_URL	—	WSS relay URL for hybrid mode
HYPERSHELL_ACCESS_TOKEN	—	Bearer token for protected API routes
HYPERSHELL_NO_BROWSER	0	Set to 1 to skip auto-opening the browser
HYPERSHELL_CONFIG_PATH	~/.config/hypershell/config.json	Override config file location
RUST_LOG	info	Rust log level filter

Development Commands

Build

# Full build (Rust server + frontend)
pnpm build

# Rust server only
cargo build --manifest-path apps/server/Cargo.toml

# Frontend only
pnpm --filter web build

Test

# Run all tests (148 Rust + 125 frontend + 24 Cloudflare)
pnpm test

# Rust tests only
cargo test --manifest-path apps/server/Cargo.toml -- --test-threads=1

# Frontend tests only
pnpm --filter web test

# Cloudflare tests only
pnpm --filter cloudflare test

Lint

pnpm lint

Runs cargo clippy (with -D warnings) and ESLint across all TypeScript packages.

Typecheck

pnpm typecheck

Runs cargo check and tsc --noEmit across all packages.

CLI Usage

HyperShell ships a CLI entry point that can be used via npx:

# Start the local server (builds if needed) and open browser
npx hypershell

# Start in hybrid mode (local + Cloudflare relay)
npx hypershell --hybrid

# Start without opening the browser
npx hypershell --no-browser

# Use a custom port
npx hypershell --port 8080

# Add a host via CLI
npx hypershell host add --name "prod-server" --address 10.0.0.5 --port 22 --user deploy

# Deploy to Cloudflare
npx hypershell deploy

# Dry-run deployment (validate without mutating)
npx hypershell deploy --dry-run

CLI Reference

hypershell [--hybrid] [--no-browser] [--port <port>]
hypershell host add --name <name> --address <host> [--port <port>] [--user <user>]
hypershell deploy [options]

See npx hypershell --help for the full list of options.

Cloudflare Deployment

The Cloudflare deployment uses Workers, D1 (SQLite), KV, R2, and Durable Objects.

# Deploy Workers + Pages to Cloudflare
npx hypershell deploy

# Or use wrangler directly for the Worker
cd apps/cloudflare && npx wrangler deploy

Resources provisioned by hypershell deploy:

Resource	Name	Purpose
Worker	hypershell-cloudflare	API + WebSocket relay
D1 Database	hypershell-db	Host/session metadata
KV Namespace	KV	Auth tokens, sessions
R2 Bucket	hypershell-recordings	Terminal session recordings
R2 Bucket	hypershell-transfers	Cross-host file transfers
Durable Object	SSHSessionRelay	Per-session WebSocket relay

Building for Distribution

pnpm run build:package

This builds the Rust server, the frontend, and assembles the npm package with pre-built binaries and static assets ready for npm publish.

Project Structure

Path	Description
apps/server/	Rust backend — Axum HTTP/WS server, russh SSH client, SQLite via rusqlite, age encryption
apps/server/src/handlers/	API route handlers (hosts, terminal, SFTP, auth, snippets, docker, metrics, etc.)
apps/server/src/ssh/	SSH connection pool, SFTP, port forwarding, tmux management
apps/server/src/db/	SQLite schema migrations and queries
apps/web/	TanStack Start + React 19 frontend with Vite
apps/web/src/features/	UI feature modules (terminal, SFTP, editor, docker, settings, snippets, etc.)
apps/cloudflare/	Hono-based Cloudflare Worker with Durable Objects relay
packages/shared/	Shared TypeScript types (HostSummary, HealthStatus, API constants)
bin/hypershell.js	CLI entry point
scripts/	Build packaging, deploy automation, local CLI runtime
docker/	OpenSSH test server Docker configuration

License

See LICENSE for details.