Nagi

Touch-friendly web-based terminal optimized for vibe coding. Access your terminal from iPad/iPhone without a hardware keyboard and enjoy coding from anywhere - your couch, bed, or cafe.

Supports fullscreen applications like tmux and Claude Code.

> Security: Token-based authentication is enabled by default. Tailscale authentication is also supported for secure access within your Tailnet.

日本語版 README

Features

- Touch-optimized: Fully usable without a hardware keyboard
- Special keys: Ctrl, Alt, Esc, Tab, Enter, Arrow keys, etc.
- tmux support: Quick button panel for tmux operations
- File browser: Browse files, view source code with syntax highlighting, play videos and images
- Color themes: Dark/Light mode with 12 accent colors
- Custom buttons: Add your own command buttons (default: yes, commit & push)
- Text input: Modal for pasting long text or CJK characters
- Auto-execute: Run commands automatically on connection
- Token auth: Secure access with auto-generated token
- Tailscale auth: Zero-config authentication via Tailscale network
- QR code: Scan to connect from your phone instantly
- xterm.js: Full-featured terminal emulation

File Browser

Click the Files button (top-right) to open the side panel file browser.

- Directory navigation: Browse folders, go up with ↑ button
- Syntax highlighting: View source code with highlight.js (Python, Go, Rust, TypeScript, etc.)
- Video streaming: Play videos with seek support
- Image viewer: View images with fullscreen support
- Hidden files: Toggle visibility with checkbox

Installation

$3

``bash
npm install -g nagi-terminal
`

$3

`bash
git clone https://github.com/shi3z/nagi.git
cd nagi
uv sync
`

Usage

$3

`bash
nagi
nagi -p 8080 # Custom port
nagi -c /path/to/config.json # Custom config file
`

$3

`bash
uv run python main.py
`

On startup, the access URL with token and QR code will be displayed. Scan the QR code with your phone to connect instantly.

Configuration

Edit config.json:

`json
{
"startup_command": "tmux a || tmux new",
"shell": "/bin/bash",
"port": 8765,
"auth": {
"mode": "tailscale",
"allowed_users": []
}
}
`

| Option | Description | Default |
|--------|-------------|---------|
| startup_command | Command to run on connection | tmux a \|\| tmux new |
| shell | Shell to use | /bin/bash |
| port | Listen port | 8765 |
| token | Fixed access token (optional) | Random on startup |
| auth.mode | Authentication mode: token or tailscale | token |
| auth.allowed_users | Allowed Tailscale users (empty = all) | [] |

$3

Token mode (default): Uses auto-generated or fixed token. QR code displayed on startup.

Tailscale mode: Authenticates via Tailscale network. No token needed - only users within your Tailnet can access. Users outside your Tailnet are completely blocked.

`json
{
"auth": {
"mode": "tailscale",
"allowed_users": ["user@example.com"]
}
}
`

You can also set NAGI_TOKEN environment variable to use a fixed token (token mode only).

Control Panel

$3

- Ctrl / Alt: Modifier keys (toggle)
- Esc / Tab / Enter: Special keys
- Arrow keys: Cursor movement
- Home / End / PgUp / PgDn: Navigation

$3

- ^C: Interrupt (Ctrl+C)
- ^D: EOF (Ctrl+D)
- ^Z: Suspend (Ctrl+Z)

$3

Expand with the tmux button:
- c: New window
- n / p: Next/Previous window
- d: Detach
- % / ": Split vertical/horizontal
- o: Switch pane
- z: Zoom
- [: Copy mode

$3

Click the Text button to open a modal for pasting long text or CJK characters.

$3

Click the 🎨 button to open the theme selector. Choose between Dark/Light mode and 12 accent colors. Your selection is saved in the browser.

$3

Click Cmd to toggle custom command buttons. Default buttons include yes and commit & push.

To customize, create ~/.nagi/buttons.html:

`html



`

Available attributes:
| Attribute | Description | Example |
|-----------|-------------|---------|
| data-cmd | Send command + Enter | data-cmd="ls -la" |
| data-send | Send text (use \n for newline) | data-send="hello\n" |
| data-ctrl | Send Ctrl+key | data-ctrl="c"` |

Requirements

- Python 3.10+
- FastAPI
- uvicorn
- websockets

License

MIT