中文 | English

Web Claude Terminal

Lightweight web terminal for accessing Claude Code and a shell from a mobile browser.

Features

• Password login + Google Authenticator 2FA
• Recovery code login when the 2FA device is unavailable
• Multiple projects open at the same time, each with isolated terminal sessions
• Dual terminal tabs for Claude and Shell
• Claude session auto-continue with --continue, configurable in Settings
• Mobile-friendly virtual keyboard with paste, Tab, arrow keys, Ctrl+C, paging, and more
• Real-time sync between the text input and terminal prompt
• Shell compatible with Bash, Fish, and other shells
• Smart Starship prompt detection that skips decorative prompt glyphs like ❯
• Fish autosuggestion sync after accepting suggestions with →
• Nerd Font rendering with bundled JetBrainsMono Nerd Font
• Automatic WebSocket reconnect
• Persistent file-based sessions that survive restarts
• Settings page for password changes, 2FA management, and recovery code status
• Security hardening with CSP, rate limiting, request timeouts, and security headers
• Included systemd and Nginx deployment configs

Installation

git clone https://github.com/yourname/web-claude-terminal.git
cd web-claude-terminal
npm install

Configuration

Copy and edit the .env file:

cp .env.example .env

Required:

WEB_TERMINAL_PASSWORD=your_secure_password_here

Optional:

# Session secret. Auto-generated if unset, but should be fixed in production.
WEB_TERMINAL_SESSION_SECRET=

# Workspace root directory (default: ~/projects)
WEB_TERMINAL_WORKSPACE_ROOT=

# Shell command (default: use $SHELL first, then fall back to /bin/bash)
WEB_TERMINAL_SHELL=/usr/bin/fish

# Listen host and port
HOST=127.0.0.1
PORT=8765

Notes:

• Local development can use http://127.0.0.1:8765
• Public deployments should run behind an HTTPS reverse proxy such as Nginx + Certbot
• The data/ directory stores runtime state and should not be committed to Git

Generate a fixed session secret:

openssl rand -hex 32

Run

# Production
npm start

# Development with auto-reload
npm run dev

For local development, open http://127.0.0.1:8765. For production, access the app through an HTTPS domain.

systemd Deployment

sudo cp deploy/web-claude-terminal.service /etc/systemd/system/
sudo nano /etc/systemd/system/web-claude-terminal.service
sudo systemctl daemon-reload
sudo systemctl enable --now web-claude-terminal
sudo journalctl -u web-claude-terminal -f

Nginx Reverse Proxy

sudo cp deploy/nginx.conf /etc/nginx/sites-available/web-claude-terminal
sudo nano /etc/nginx/sites-available/web-claude-terminal
sudo ln -s /etc/nginx/sites-available/web-claude-terminal /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

HTTPS

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Security

Feature	Description
Password protection	All pages except the login page require authentication
2FA	Optional Google Authenticator support with recovery codes
Rate limiting	5 login attempts per 5 minutes, persisted to disk
Persistent sessions	File-based session storage survives restarts
CSP headers	Restricts script, style, image, and font sources
API timeout	/api/* requests time out after 30 seconds
Path validation	Prevents directory traversal outside the workspace root
Project isolation	Only web-created projects can be deleted
Idle cleanup	Terminal sessions are closed after 2 hours of inactivity

Architecture

Browser (xterm.js) <-WebSocket-> Node.js (Express + node-pty) <-PTY-> claude / fish

• Frontend: vanilla HTML/CSS/JS + xterm.js + FitAddon with a Catppuccin Mocha theme
• Backend: Express + WebSocket (ws) + node-pty
• Auth: express-session + file session store + speakeasy TOTP
• Deployment: systemd service + Nginx reverse proxy

FAQ

claude command not found

Make sure claude is available in the system PATH:

which claude

node-pty installation failed

# Debian/Ubuntu
sudo apt install build-essential python3
npm install

WebSocket connection failed

Check the Nginx WebSocket upgrade headers and firewall settings.

Local development works but login state is not preserved

Make sure you are using the current version of the code. This project supports session cookies on local HTTP during development, while production should still use HTTPS.

License

MIT. See the root LICENSE file.

Roadmap

• Custom terminal themes
• Terminal output search
• File manager with upload/download
• Multi-user support with isolated passwords and projects
• Terminal recording and playback
• Better mobile gesture support
• Dockerized deployment