GitHub - Leask/Tabminal: Tab(ter)minal, a Cloud-Native terminal and ACP agent workspace for desktop, tablet, and phone.

t> Tabminal

Tab(ter)minal , a Cloud-Native terminal and ACP agent workspace for desktop, tablet, and phone.

Tabminal combines persistent server-side terminal sessions, a built-in workspace, multi-host access, and Agent Client Protocol (ACP) integrations in one UI.

It is designed for people who want a real terminal, real files, and real agent tooling without being tied to a desktop-only client let you code from your desktop, tablet, or phone with an intelligent, persistent, and rich experience.

What It Does

switches.

• Persistent terminal sessions that survive refreshes, reconnects, and device

• Built-in workspace tabs for files, images, agents, and pinned terminals.

viewers, permission requests, plans, and usage HUDs.

• ACP agent support with managed terminals, live tool calls, diffs, code

state.

• Multi-host cluster support from a single UI, with per-host auth and heartbeat

install support.

• Browser-first mobile and tablet UX, including compact workspace mode and PWA

OpenAI or OpenRouter is configured.

• Terminal-native AI assistance for shell history and auto-fix flows when

More screenshots

Current Highlights

ACP Agent Workspace

Tabminal now has a full ACP agent surface, not just an AI chat box.

• Agent tabs live beside files and terminal tabs in the same workspace bar.

and file paths inline.

• Tool calls can render live terminal output, diffs, code/resource payloads,

running.

• Jump in moves you into the managed terminal session while it is still

and usage data are first-class UI elements.

• Agent plans, running-terminal summaries, slash-command menus, permissions,

navigation.

• The agent composer supports provider-defined slash commands and keyboard

managed terminal relationships.

• Agent state restores across refreshes, including transcript history and

Built-in agent definitions currently include:

• Gemini CLI

• Codex CLI

• Claude Agent

• GitHub Copilot CLI

• ACP Test Agent ( TABMINAL_ENABLE_TEST_AGENT=1 )

Each definition is detected per host. Availability depends on the runtime environment of that host and any required local auth or API keys.

Terminal-Native AI Assistant

Tabminal still includes the original terminal-native assistant path.

current terminal context.

• Prefix a shell prompt with # to ask the built-in assistant about your

error output.

• Failed commands can trigger an automatic AI follow-up using recent history and

ACP agent integrations.

• This path uses your configured OpenAI or OpenRouter key and is separate from

Multi-Host Cluster

One UI can manage multiple Tabminal backends.

• Add hosts from the sidebar.

• Open sessions on any connected host.

• Auth is host-scoped.

• The main host controls the global login modal.

• Sub-host auth failures stay local to that host.

• Host registry is persisted on the main host and restored after refresh.

Built-In Workspace

• Monaco-based file editor

• File tree and image preview

• Terminal, file, and agent tabs in one shared workspace bar

• Managed terminal previews in the sidebar

• Restore-aware terminal pinning and workspace switching

Mobile and Tablet UX

• PWA install support

• Safe-area aware responsive layout

• Compact workspace mode for small or short screens

• Touch-friendly controls and virtual keyboard support

the composer usable on tablets and phones

• Small-screen agent config controls collapse into icon-only selectors to keep

Getting Started

Requirements

• Node.js >= 22

• A secure environment. Tabminal is a high-privilege app by design.

• Optional provider credentials:

• OpenAI or OpenRouter for the built-in terminal-native assistant

• Google Search API key and CX for web search augmentation

• Local CLI/auth for ACP agents such as Codex, Gemini, Claude, or Copilot

Security Warning

Tabminal provides direct read/write access to the host file system and can run commands on that host.

• Do not expose it directly to the public internet.

• Use a VPN, Tailscale, or a Zero Trust layer such as Cloudflare Access.

command context may be sent to your configured provider.

• If AI features are enabled, terminal history, paths, env hints, or recent

• --accept-terms is required to start the server.

Quick Start

Terminal only:

npx tabminal --accept-terms

With OpenAI:

npx tabminal --openai-key " YOUR_API_KEY " --accept-terms

With OpenRouter:

npx tabminal --openrouter-key " YOUR_API_KEY " --accept-terms

Docker

docker run --rm -it -p 9846:9846 \

leask/tabminal \ --accept-terms

With AI enabled:

docker run --rm -it -p 9846:9846 \

leask/tabminal \ --openai-key " YOUR_API_KEY " \ --accept-terms

Local Development

git clone https://github.com/leask/tabminal.git

cd tabminal

npm install

npm start -- --accept-terms

Configuration

Configuration precedence is:

• built-in defaults

• ~/.tabminal/config.json

./config.json

• CLI flags

• environment variables

If no password is provided, Tabminal generates a temporary password at startup and prints it to the terminal.

CLI Flags and Environment Variables

Argument Env Variable Description Default

-p , --port TABMINAL_PORT Server port 9846

-h , --host TABMINAL_HOST Bind address 127.0.0.1

-a , --password TABMINAL_PASSWORD Access password generated at startup

-s , --shell TABMINAL_SHELL Default shell executable system default

-k , --openrouter-key TABMINAL_OPENROUTER_KEY OpenRouter API key null

-o , --openai-key TABMINAL_OPENAI_KEY OpenAI API key null

-u , --openai-api TABMINAL_OPENAI_API OpenAI-compatible base URL null

-m , --model TABMINAL_MODEL Built-in assistant model ID gpt-5.2 with OpenAI, gemini-3-flash-preview with OpenRouter

-f , --cloudflare-key TABMINAL_CLOUDFLARE_KEY Cloudflare Tunnel token null

-g , --google-key TABMINAL_GOOGLE_KEY Google Search API key null

-c , --google-cx TABMINAL_GOOGLE_CX Google Search Engine ID null

-d , --debug TABMINAL_DEBUG Enable debug logs false

--heartbeat TABMINAL_HEARTBEAT WebSocket heartbeat interval in ms, minimum 1000 10000

--history TABMINAL_HISTORY Terminal history limit in characters 1048576

-y , --accept-terms TABMINAL_ACCEPT / TABMINAL_ACCEPT_TERMS Required risk acknowledgement false

Notes:

• --openrouter-key and --openai-key are mutually exclusive.

historyLimit / history-limit .

• config.json also supports heartbeatInterval / heartbeat-interval and

Persistence Files

Tabminal stores runtime state under ~/.tabminal/ :

• config.json : optional home-level config

• cluster.json : multi-host registry

• agent-tabs.json : ACP agent tab restore state

• agent-config.json : saved per-agent setup/config values

For multi-host:

• The main host token stays in browser local storage.

• Sub-host tokens are persisted in the main host's cluster.json .

ACP Agent Notes

ACP availability is discovered per host. A backend may show different results if its runtime environment differs from your interactive shell.

Typical requirements:

• Codex: codex login

• Gemini: gemini --acp or npx @google/gemini-cli@latest --acp

Claude:

npx @zed-industries/claude-code-acp@latest plus required Anthropic

or Vertex configuration

• Copilot: copilot --acp --stdio or gh copilot -- --acp --stdio

On hosts where the CLI lives in a user-local bin directory such as ~/.local/bin , Tabminal augments the agent runtime PATH so discovery is more reliable.

Keyboard Shortcuts

• Ctrl + Shift + T : New terminal

• Ctrl + Shift + W : Close terminal

• Ctrl + Shift + E : Toggle file workspace pane

• Ctrl + Shift + A : Open agent menu

• Ctrl + Up / Down : Move focus between workspace and terminal

• Ctrl + Shift + [ / ] : Switch session

• Ctrl + Alt + [ / ] : Switch workspace tab

• Ctrl + Shift + ? : Show shortcuts help

• Ctrl / Cmd + F : Find in terminal

such as menus

• Esc : Stops a running ACP prompt when supported, or closes transient agent UI

Touch

• The virtual keyboard exposes terminal-friendly modifier keys.

• Workspace and agent controls are optimized for touch and compact screens.

Architecture Snapshot

• Backend: Node.js , utilitas , Koa , node-pty , WebSocket , ACP SDK

• Frontend: Vanilla JS 😝 , xterm.js , Monaco Editor

• Persistence: host-local files under ~/.tabminal

• Native clients and packaging work live under:

• apps/Apple

• apps/ghostty-vendor

Troubleshooting

- On macOS, node-pty may need:

chmod +x node_modules/node-pty/prebuilds/darwin- * /spawn-helper

- If a sub-host keeps asking for login, check whether Cloudflare Access or another auth layer requires an interactive browser login for that host.

- If an ACP agent is missing, verify the CLI is installed on the backend host and available in that host's runtime environment.

Quality Checks

Recommended before shipping changes:

npm run lint

npm test

npm run build

License

MIT

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。