Remote Terminal

HAPI provides remote terminal access to your coding sessions via xterm.js, allowing you to run commands on your development machine from your phone or any web browser.

Overview

Full Terminal Emulator

xterm.js provides a complete terminal experience in the browser

Real-Time Communication

Commands and output stream via Socket.IO with minimal latency

Mobile-Friendly

Touch keyboard with special keys (Esc, Tab, Ctrl, arrows)

Session-Linked

Terminal automatically connects to your active session’s machine

Accessing the Terminal

From Web App

Open Session

Navigate to any active session in the web app

Terminal Tab

Click the Terminal button or navigate to the terminal tab

Auto-Connect

Terminal automatically connects to the session’s machine

Start Typing

Use the terminal as you would locally

Route

The terminal is available at:

/sessions/:sessionId/terminal

Features

Full Terminal Emulation

256 colors and true color
Unicode characters
Cursor positioning and control sequences
Scrollback buffer for history
Text selection and copy/paste

Touch Keyboard

On mobile, HAPI provides quick-access buttons for special keys:

Esc

Escape key

Tab

Tab key for autocomplete

Ctrl

Control modifier (stays active)

Alt

Alt/Option modifier

Additional navigation keys:

Arrow keys (↑ ↓ ← →)
Home and End
Page Up and Page Down

Long-press / for ? and - for | — useful for command options.

Paste Functionality

Two ways to paste text:

Automatic: Tap Paste button to use clipboard (if browser supports)
Manual: If clipboard unavailable, a dialog appears for manual paste

iOS Safari has clipboard limitations. The manual paste dialog is a reliable fallback.

Real-Time Updates

Terminal output streams in real-time:

Instant feedback on commands
Live tailing of logs
Interactive programs (vim, nano, htop)
Tab completion works as expected

Technical Architecture

Communication Flow

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Browser   │         │  HAPI Hub   │         │  HAPI CLI   │
│  (xterm.js) │◄───────►│ (Socket.IO) │◄───────►│   (PTY)     │
└─────────────┘         └─────────────┘         └─────────────┘
      │                       │                       │
      │──terminal:create─────►│──terminal:create─────►│
      │                       │                       │ spawn shell
      │                       │◄──terminal:ready──────│
      │◄──terminal:ready──────│                       │
      │                       │                       │
      │──terminal:write──────►│──terminal:write──────►│
      │      (input)          │                       │ write to PTY
      │                       │                       │
      │◄──terminal:output─────│◄──terminal:output─────│
      │     (stdout)          │                       │ read from PTY

Components

Browser (xterm.js)
- Renders terminal in browser
- Captures keyboard input
- Displays output with ANSI colors
Hub (Socket.IO)
- Routes terminal events
- Manages terminal registry
- Handles connection state
CLI (PTY)
- Spawns shell process
- Reads/writes to pseudo-terminal
- Handles resize events

Socket.IO Events

Web → CLI

Event	Description
`terminal:create`	Request new terminal session
`terminal:write`	Send input to terminal
`terminal:resize`	Update terminal dimensions
`terminal:close`	Close terminal session

CLI → Web

Event	Description
`terminal:ready`	Terminal is ready for input
`terminal:output`	Output from terminal
`terminal:exit`	Terminal process exited
`terminal:error`	Error occurred

Use Cases

Quick Command Execution

Run simple commands without switching to terminal:

# Check git status
git status

# Run tests
npm test

# View logs
tail -f server.log

Emergency Fixes

Fix issues while away from your desk:

Get notified about production issue
Open terminal on phone
SSH to production server
Apply hotfix
Restart service

File Management

Manage files when AI can’t:

# Create directories
mkdir -p src/components/ui

# Move files
mv old-file.ts new-file.ts

# Change permissions
chmod +x deploy.sh

Interactive Programs

Run interactive CLI tools:

# Text editor
nano config.json

# Interactive git
git add -p

# Process monitor
htop

Connection States

Terminal shows connection status:

Connecting

Establishing Socket.IO connection

Connected

Ready for input (green indicator)

Offline

Disconnected or session inactive

Session Requirements

Terminal is only available when:

✅ Session is active (agent running)
✅ Machine is online
✅ CLI is connected to hub

If session is inactive, terminal shows:

Session is inactive. Terminal is unavailable.

Keyboard Shortcuts

Desktop

All standard terminal shortcuts work:

Shortcut	Action
`Ctrl+C`	Interrupt (SIGINT)
`Ctrl+D`	EOF / Exit
`Ctrl+L`	Clear screen
`Ctrl+R`	Reverse search
`Ctrl+A`	Move to start of line
`Ctrl+E`	Move to end of line
`Ctrl+K`	Kill to end of line
`Ctrl+U`	Kill to start of line

Mobile

Use the quick-access keyboard:

Ctrl button: Tap to enable, then tap any key for Ctrl+Key
Alt button: Tap to enable, then tap any key for Alt+Key
Arrow keys: Navigation without virtual keyboard

Ctrl and Alt buttons stay highlighted when active. They reset after sending a key combination.

Best Practices

Session Management

Keep terminal tab open for continuous connection
Close terminal when done to free resources
One terminal per session (multiple tabs share same PTY)

Mobile Usage

Use landscape mode for more screen space
Rely on quick-access keys for special characters
Use paste dialog for long commands

Security

Terminal has same permissions as CLI process
No isolation — use caution with destructive commands
Consider read-only mode for sensitive environments

Performance

Avoid commands with massive output
Use head, tail, or grep to limit output
Close terminal when not needed

Limitations

Known Limitations:

Single terminal per session: Multiple tabs share the same PTY
No terminal multiplexing: Use tmux/screen for multiple shells
Session-dependent: Requires active HAPI session
Limited resize: Terminal dimensions may not match all programs

Troubleshooting

Terminal Not Connecting

Check:

Session is active (green indicator)
CLI is connected to hub
Socket.IO connection is established
No firewall blocking WebSocket

Solution: Refresh page or restart session

Input Not Working

Check:

Terminal shows “Connected” status
Click terminal area to focus
Try quick-access keys on mobile

Solution: Tap terminal area or reload page

Garbled Output

Cause: Terminal size mismatchSolution:

Resize browser window
Run reset command
Close and reopen terminal

Process Exited Unexpectedly

Displayed:

[process exited with code 1]

Solution: Close and reopen terminal tab to spawn new shell

Paste Not Working (iOS)

Cause: iOS Safari clipboard restrictionsSolution: Use the manual paste dialog that appears automatically

Security Considerations

Authentication

Terminal inherits session authentication
Requires valid JWT token
No separate terminal password

Permissions

Terminal runs as same user as CLI
Has access to all files CLI can access
No sandboxing or isolation

Network

Uses WebSocket (secure if HTTPS)
Data is not encrypted beyond TLS
Consider VPN for sensitive environments

Terminal has full access to your machine. Only use on trusted networks or with proper tunneling (Cloudflare Tunnel, Tailscale).

Remote Control

Switch between local and remote modes

File Browser

Browse files and view diffs

Permissions

Control what agents can do

Get Started

Core Concepts

Features

Agents

Deployment

Advanced

Resources

​Overview

Full Terminal Emulator

Real-Time Communication

Mobile-Friendly

Session-Linked

​Accessing the Terminal

​From Web App

​Route

​Features

​Full Terminal Emulation

​Touch Keyboard

Esc

Tab

Ctrl

Alt

​Paste Functionality

​Real-Time Updates

​Technical Architecture

​Communication Flow

​Components

​Socket.IO Events

​Web → CLI

​CLI → Web

​Use Cases

​Quick Command Execution

​Emergency Fixes

​File Management

​Interactive Programs

​Connection States

Connecting

Connected

Offline

​Session Requirements

​Keyboard Shortcuts

​Desktop

​Mobile

​Best Practices

​Limitations

​Troubleshooting

​Security Considerations

​Authentication

​Permissions

​Network

​Related Features

Remote Control

File Browser

Permissions

Build docs developers (and LLMs) love

Overview

Accessing the Terminal

From Web App

Route

Features

Full Terminal Emulation

Touch Keyboard

Paste Functionality

Real-Time Updates

Technical Architecture

Communication Flow

Components

Socket.IO Events

Web → CLI

CLI → Web

Use Cases

Quick Command Execution

Emergency Fixes

File Management

Interactive Programs

Connection States

Session Requirements

Keyboard Shortcuts

Desktop

Mobile

Best Practices

Limitations

Troubleshooting

Security Considerations

Authentication

Permissions

Network

Related Features