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

npm (Recommended)

npm install -g nagi-terminal

Manual Installation

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

Usage

npm

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

Manual

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:

{
    "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) | [] |

Authentication Modes

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.

{
    "auth": {
        "mode": "tailscale",
        "allowed_users": ["[email protected]"]
    }
}

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

Control Panel

Basic Keys

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

Shortcuts

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

tmux Panel

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

Text Input

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

Color Themes

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

Custom Buttons

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

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

<div class="button-row">
    <button class="btn" data-cmd="yes">yes</button>
    <button class="btn" data-cmd="commit &amp; push">commit & push</button>
    <button class="btn" data-ctrl="c">^C</button>
</div>

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