@omniterm/host

OmniTerm

Your agent terminals, accessible everywhere.

Why OmniTerm?

• Built for AI agents — run Claude Code, Codex, or any CLI agent in a terminal
• Always running — 24/7, persist across browser closes, network drops, and device switches
• Work from anywhere — start on your desktop / cloud, continue from your iPad, smartphone
• Easy setup — one command to start, accessible through the browser. No SSH tunnels
• Lightweight — fast first load; editor grammars load on demand, so you only download the languages you open

Quick Start

Install dependencies first:

# macOS
brew install tmux ttyd

# Ubuntu/Debian
sudo apt install tmux
sudo snap install ttyd --classic

Then install and run:

npm install -g @omniterm/host
omniterm
# Open http://localhost:17717

The npm package is @omniterm/host; the command it installs is omniterm. No install? Run it directly with npx @omniterm/host.

Custom port:

omniterm --port 8080

OmniTerm uses ports 7700-7799 internally for terminal sessions. If this range conflicts, override it:

omniterm --ttyd-ports 8800-8899

Run omniterm --help for all options.

Plugins

omniterm is domain-agnostic — extra functionality is added at runtime via plugins, without touching the host. Enable one with the repeatable --plugin flag (by published package name or local path):

omniterm --plugin @omniterm/shiplight-debugger-plugin   # YAML test debugger

What You Get

Terminals

• Multiple tabs, each containing one or more terminal panes
• Split terminals side-by-side or top/bottom within a tab
• Drag to reorder tabs, double-click to rename
• Sessions survive browser disconnects and server restarts
• Mouse wheel scrollback, native text selection

Workspaces

• Switch between git repos, worktrees, and directories
• Clone repos or browse the server filesystem to add new workspaces
• Create and manage git worktrees with one click
• Discovers existing tmux sessions automatically — start a session from SSH, see it in the browser

File Explorer & Editor

• Browse files, edit with syntax highlighting and Cmd+S save
• Supports TypeScript, Python, JSON, Markdown, CSS, HTML
• Auto-refreshes file tree and editor content on window focus
• Unsaved changes protection when switching files

Mobile & Desktop

• Full terminal experience on phones and tablets
• Add to home screen for a native app feel (PWA)
• Desktop: overlay panels for workspaces and files
• Mobile: full-screen views with touch navigation

Use Cases

AI Agent Fleet

Run multiple AI agents in parallel, each in its own workspace. Split terminals to monitor two agents side by side. Review their output in the editor.

Remote Development

Code on a powerful cloud server from any device. Start a build on your desktop, check results from your iPad. The terminal never stops.

Pair Programming with AI

One pane for your agent, another for your build server, the editor on the side. The agent writes code, you review and edit — all in one browser tab.

Remote Access

Access via SSH tunnel or VPN:

ssh -L 17717:localhost:17717 your-server
open http://localhost:17717

Or directly via Tailscale:

open http://your-server.tailnet:17717

Telemetry

omniterm collects anonymous usage and performance telemetry to help improve the tool. It is tied only to a random installation id — no personal data, file contents, file paths, repository names, or hostnames are ever collected.

What's collected: coarse usage events (server started, session created/adopted/ closed, file opened by language, cleanup) and session timing metrics, plus the omniterm version, OS platform, and Node version.

It's opt-out and off in automated contexts. Disable it any of these ways:

omniterm telemetry off          # persistent, saved to settings
omniterm telemetry status       # show current state
omniterm --no-telemetry         # disable for a single run

export OMNITERM_TELEMETRY=0     # env: omniterm's own opt-out
export DO_NOT_TRACK=1           # env: the standard cross-tool opt-out

You can also toggle it in the Settings panel under Privacy → Telemetry (the same persistent setting omniterm telemetry off writes). Env signals override the saved setting. Telemetry is also automatically disabled in CI/test environments. Performance timings are always available locally (even when opted out) at GET /api/metrics/perf, and nothing leaves your machine when telemetry is off.

License

MIT