# clsh

> clsh gives you real terminal access to your Mac from your phone via a single command, streaming a real PTY session over a secure tunnel to any browser or PWA.

clsh is an open-source tool that turns your Mac into a pocket-sized terminal server. Run `npx clsh-dev`, scan the QR code on your phone, and you have a real PTY session — not SSH emulation, not a simulation — streamed securely to your mobile browser or installed PWA. The project is MIT-licensed and hosted on GitHub under the `my-claude-utils` organization.

## What It Is

clsh is a phone-first remote terminal client for macOS (and Linux). It spawns real shell sessions using `node-pty` on your local machine, wraps them optionally in tmux for persistence, and exposes them over HTTPS via a 3-tier tunnel system (ngrok → localhost.run SSH → local Wi-Fi). A custom React + xterm.js frontend renders the terminal with full color, vim support, and a purpose-built mobile keyboard. The project is particularly aimed at developers who want to run AI coding agents like Claude Code from their phone and watch them work in real time.

## How the Tunnel Architecture Works

clsh uses a layered fallback approach so it works in almost any network environment:

- **ngrok (static domain)** — recommended for PWA home screen use; same URL survives restarts
- **localhost.run SSH tunnel** — zero signup, works anywhere, auto-fallback
- **Local Wi-Fi** — zero dependencies, LAN-only

The tunnel can be forced via environment variables (`TUNNEL=ssh`, `TUNNEL=local`). A one-time bootstrap token with a 5-minute TTL and QR code delivery authenticates the phone on first connect; subsequent connections use JWT.

## Security Model

Because clsh grants remote shell access to your machine, the project treats security as a first-class concern. Key protections include:

- One-time bootstrap tokens (single-use, 5-min TTL) passed in the URL hash fragment (never sent to servers)
- scrypt password hashing (N=16384, 64-byte key, random salt) with constant-time comparison
- WebAuthn / Face ID biometric auth for PWA lock screen
- HTTPS enforced via tunnel, CORS restricted to known origins, security headers (CSP, X-Frame-Options, X-Content-Type-Options)
- Auth endpoint rate limiting (5–10 requests per 15 minutes)
- WebSocket origin validation, 64KB max payload, resize dimension bounds checking
- Responsible disclosure policy at security@clsh.dev with a stated 48-hour response time

## Mobile-First Terminal Experience

The frontend is built specifically for phone use, not adapted from a desktop UI:

- **Custom keyboard** with two layouts: iOS Terminal (6-row, large keys) and MacBook (5-row, compact)
- **Sticky modifiers** — tap Shift/Ctrl/Opt/Cmd once, it latches for the next key
- **Key repeat** — hold any key for auto-repeat (400ms delay, 60ms interval)
- **Context strip** — quick-access row for Esc, F1–F5, commit, diff, plan, Ctrl+C
- **6 keyboard skins** — iOS Terminal, MacBook Silver, Gamer RGB, Custom Painted, Amber Retro, Ice White
- **PWA install** — fullscreen standalone mode, iOS keyboard suppressed, safe-area insets for Dynamic Island and notch devices
- **Session grid** — up to 8 concurrent PTY sessions with live 2-column card previews

## Tech Stack

The project is a TypeScript monorepo managed with Turborepo and npm workspaces:

| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript, Vite 6, Tailwind CSS v4, xterm.js (WebGL) |
| Backend | Node.js 20+, Express, ws, node-pty, tmux (control mode), better-sqlite3 |
| Tunnel | @ngrok/ngrok SDK, localhost.run SSH fallback |
| Auth | jose (JWT), scrypt, WebAuthn (Face ID/Touch ID), one-time bootstrap tokens |

## Update: v0.1.9 — Native Keyboard Support

The latest release is **v0.1.9**, published in March 2026 and titled "Native Keyboard Support." The repository was last updated in September 2026 and has accumulated 526 stars and 54 forks since its creation in March 2026. The roadmap lists upcoming features including remote cloud containers, team session sharing with presence, native iOS/Android apps, and Claude Code tool extensions.

## Features
- Real PTY terminal sessions via node-pty
- Phone-first mobile UI with custom keyboard
- 3-tier tunnel: ngrok → SSH → Wi-Fi
- Up to 8 concurrent terminal sessions
- Session persistence via tmux control mode
- QR code + JWT authentication
- WebAuthn / Face ID biometric lock screen
- One-time bootstrap tokens (5-min TTL)
- 6 keyboard skins with Skin Studio
- PWA install with fullscreen standalone mode
- Session grid with live terminal previews
- Sticky modifier keys and key repeat
- Claude Code streaming support
- Demo mode for showcasing without backend
- Lid-close mode for persistent connectivity

## Integrations
ngrok, localhost.run, tmux, Claude Code, xterm.js, WebAuthn / Face ID, Node.js, Turborepo

## Platforms
MACOS, LINUX, ANDROID, IOS, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.9

## Links
- Website: https://clsh.dev
- Documentation: https://github.com/my-claude-utils/clsh#readme
- Repository: https://github.com/my-claude-utils/clsh
- EveryDev.ai: https://www.everydev.ai/tools/clsh