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.