hypershell-app

HyperShell

HyperShell is a self-hosted browser workspace for SSH operations. It combines a WebSocket terminal, host and credential management, SFTP, remote editing, snippets, port forwards, Docker tools, audit logs, and settings into one local-first app.

The default runtime is simple: a Rust server listens on localhost:3100, serves the built React app, and brokers SSH/SFTP/tmux/Docker work from your machine.

What You Get

Area	Capabilities
Terminal	xterm.js 6, tabs, split panes, tmux attach/detach, session recording, sharing, search, inline images, link detection
Hosts	SSH host inventory, tags, groups, favorites, credential vault, host-key acceptance, connection tests
Files	Dual-pane SFTP, upload/download, cross-host transfers, preview, chmod, rename, delete, resumable upload checks
Editor	CodeMirror 6, remote file tabs, syntax highlighting, status bar, save and conflict handling
Networking	Local, remote, and dynamic port forwards with lifecycle cleanup
Docker	Remote container list, start/stop/restart, logs, exec shells
Automation	Reusable snippets with variable substitution and multi-host execution
Operations	Audit log, device metrics, notification webhooks, PWA offline shell
Security	Age-encrypted credential storage, RBAC checks, passkeys, magic links, step-up gates, rate limiting

Quick Start

Prerequisites

Tool	Version	Why
Rust	1.95+	Builds and tests the Axum server
Node.js	22+	Runs the web toolchain and CLI
pnpm	10+	Installs the workspace
Docker	Current	Optional SSH/tmux test fixture

Install

git clone <repo-url>
cd hypershell
pnpm install

Run In Development

Start the backend and frontend in separate terminals:

cargo run --manifest-path apps/server/Cargo.toml

pnpm --filter web dev

Open http://localhost:3101. Vite proxies /api and /ws to the Rust server on localhost:3100.

Optional SSH Fixture

The integration fixture starts an OpenSSH container on localhost:2222 with tmux installed.

docker compose up -d openssh-server
./scripts/verify-ssh-test-server.sh

Fixture credentials:

host: localhost
port: 2222
user: testuser
pass: testpass

CLI

The npm package is named hypershell-app and exposes a hypershell binary.

# Start the local server, serve the built frontend, and open the browser.
npx hypershell-app

# Start without opening a browser.
npx hypershell-app --no-browser

# Use another port.
npx hypershell-app --port 8080

# Add a host through the local API.
npx hypershell-app host add --name "prod" --address 10.0.0.5 --port 22 --user deploy

CLI reference:

hypershell [--no-browser] [--port <port>]
hypershell host add --name <name> --address <host> [--port <port>] [--user <user>] [--password <password>] [--favorite] [--api-origin <url>] [--token <token>]

Verification

# Rust + TypeScript type checks
pnpm typecheck

# Rust tests, including SSH/tmux tests when the fixture is available
cargo test --manifest-path apps/server/Cargo.toml -- --test-threads=1

# Frontend unit/component tests
pnpm --filter web test

# Full workspace test command
pnpm test

# Lint Rust and TypeScript
pnpm lint

# Production build
pnpm build

The Rust SSH/tmux tests expect the Docker fixture on localhost:2222. Run ./scripts/verify-ssh-test-server.sh first if those tests report connection setup errors.

Configuration

Variable	Default	Description
HYPERSHELL_PORT	3100	Rust server listen port
HYPERSHELL_DB_PATH	hypershell.db	SQLite database path
HYPERSHELL_STATIC_DIR	unset	Built frontend directory for production serving
HYPERSHELL_ACCESS_TOKEN	unset	Bearer token for protected API routes
HYPERSHELL_NO_BROWSER	0	Set to 1 to skip browser launch from the CLI
HYPERSHELL_CONFIG_PATH	~/.config/hypershell/config.json	First-run CLI config path
HYPERSHELL_API_URL	http://localhost:3100	API origin used by hypershell host add
HYPERSHELL_CLOUDFLARE_WORKER_ORIGIN	unset	Allowed Cloudflare Worker origin for agent relay WebSockets
RUST_LOG	info	Rust tracing filter

Repository Map

Path	Purpose
apps/server/	Rust Axum server, SQLite migrations, SSH/SFTP/tmux/Docker handlers
apps/web/	React 19 + TanStack Router + Vite frontend using Cloudflare Kumo
packages/shared/	Shared TypeScript contracts
bin/hypershell.js	Node CLI entry point
scripts/	Packaging, local CLI helpers, SSH fixture verification
docker/openssh/	OpenSSH fixture init scripts
prebuilt/	Prebuilt server binaries used by the npm package

For system details, read ARCHITECTURE.md. For contributor workflow, read CONTRIBUTING.md.

Documentation

Document	Use it for
Getting Started	First install, local server, SSH fixture, first host
User Guide	Feature-by-feature workflows for terminal, files, editor, snippets, Docker, and audit
Configuration	Environment variables, first-run config, ports, auth token behavior
Security	Threat model, credential handling, auth, RBAC, WebSocket protections
Troubleshooting	Common setup, SSH, tmux, WebSocket, and build failures
Testing	Test tiers, fixtures, commands, and what each gate proves
API Reference	HTTP and WebSocket route map for local integrations

Build For Distribution

pnpm run build:package

This builds the Rust server in release mode, builds the frontend, copies the platform server binary into prebuilt/<platform>-<arch>/, and writes an npm tarball to dist-package/.

Current Deployment Status

This checkout includes the local Rust server plus server-side validation for Cloudflare agent relay WebSockets. It does not include an apps/cloudflare/ worker package or a hypershell deploy CLI command. Keep relay/deploy documentation tied to real files when that target is added.

Security Notes

Credential secrets are encrypted at rest with age before storage. The API includes RBAC, rate limiting, WebSocket auth rules, step-up checks for sensitive operations, passkey flows, and audit records for connection and file activity.

Please do not open issues containing private keys, passwords, hostnames, access tokens, database files, or terminal recordings.

License

MIT. See LICENSE.