convez.ai
MCP ServerAutomaçãoIntermediário
marshallku

tabd – Controlador de Navegador Headless via SSH

marshallku/tabd

Browser headless automático para agentes IA, daemon Rust, CLI JSON, SSH-friendly

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server em Rust que fornece um daemon de navegador headless controlável por CLI, ideal para agentes de IA executarem automação web em ambientes remotos. Oferece um binário estático único (~7 MB) que gerencia uma sessão Chromium compartilhada com suporte a secrets, cookies, screenshots e interações DOM.

Instalação

$npx convez-ai marshallku/tabd

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v0.1.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automação web em ambientes headless/remote sem Node ou Python
  • Captura de screenshots e métricas de páginas para agentes IA
  • Login e preenchimento de formulários com secrets vault AES-256-GCM

Veredito

Ferramenta sólida e leve para automação web server-side, elimina dependências pesadas (Node/Python) com um binário Rust. Excelente para agentes IA que precisam interagir com páginas web, embora requeira Chromium instalado e conhecimento de CLI para integração.

README

A tradução para o português deste README ainda está na fila.

tabd

SSH-friendly headless browser controller for AI agents (and humans). Single Rust binary, daemon-shared Chromium session, JSON over Unix domain socket. Replaces the earlier TypeScript MCP server (retired in phase 3i) with a smaller, faster, dependency-free CLI surface.

Highlights

  • Single static Rust binary (~7 MB). No Node, no Python.
  • One long-running daemon per user. Multiple CLI calls share the same Chromium and its cookies, storage, console history, and tabs.
  • Auto-spawn — the first CLI call boots the daemon if none is running.
  • Crash-restart supervisor — if Chromium dies the daemon brings up a fresh one within seconds.
  • AES-256-GCM secrets vault — secret-put / type-secret for login automation; plaintext never goes on argv.
  • --json everywhere — every action accepts --json for scriptable output; --out FILE decodes binary payloads (e.g. PNG screenshots) to disk.

Install

See INSTALL.md. Short version — no build from source needed:

curl -fsSL https://raw.githubusercontent.com/marshallku/tabd/master/install.sh | sh

Downloads the right pre-built binary for your platform (Linux x64, macOS Intel/Apple Silicon), verifies its SHA256, and installs to ~/.local/bin/tabd. From source instead: cargo install --path crates/tabd.

AI agent skill (optional)

If you use Claude Code or Codex CLI, install the embedded skill so the agent automatically uses tabd for browser-automation requests:

tabd skill install            # auto-detects Claude / Codex, installs to both
tabd skill install --target codex --force   # explicit one-target, overwrite
tabd skill install --path .claude/skills/tabd   # project-local

Writes SKILL.md + the four docs/*.md references into ~/.claude/skills/tabd/ and/or ~/.codex/skills/tabd/. Restart the client afterwards so it reloads skill metadata.

Surface

47 action subcommands + 4 daemon controls.

CategoryCommands
Tabsnavigate, open-tab, close-tab, list-tabs, activate-tab, back, forward, reload
DOMget-html, get-text, query, summary
Interactionclick, type, hover, mouse-move, scroll, press-key, select-option, check, upload
Capturescreenshot, metrics
Emulationset-viewport
Executioneval
Waitwait-selector, wait-url, wait-text, wait-network-idle, wait-download
Cookiescookies-get, cookies-set, cookies-delete
Storagestorage-get, storage-set, storage-clear
Monitorconsole-logs, page-errors, network-logs, dialogs, downloads
Dialogsdialog-policy (JS dialogs auto-handled by the daemon — never wedge automation)
Downloadsdownload-dir (opt-in capture → known dir), wait-download
Secretssecret-put, secret-list, secret-delete, type-secret
Daemondaemon start, daemon stop, daemon ping, daemon health

Every action that targets a specific tab accepts --tab N (1-based index). Defaults to the active tab.

Quick start

# 1. Boot daemon (auto-spawn on first action also works).
tabd daemon start &

# 2. Drive it.
tabd navigate https://example.com
tabd get-text --selector h1                    # → "Example Domain"
tabd screenshot --out /tmp/example.png
tabd daemon health                             # daemon + chromium pids, RSS, restart count

# 3. Multi-tab.
tabd open-tab https://news.ycombinator.com     # returns {tabId, targetId, url}
tabd list-tabs --json                          # all open tabs with active flag
tabd activate-tab --tab 1
tabd back

# 4. Monitor what just happened.
tabd console-logs --json
tabd network-logs --method GET --status 2xx --limit 20

# 5. Login automation (passphrase-mode secrets vault).
export TABD_VAULT_KEY="$(pass show tabd/vault 2>/dev/null || echo 'change-me')"
echo -n "$GITHUB_PASSWORD" | tabd secret-put --label github --stdin
# → {"secretId":"a1b2c3...", "label":"github", "preview":"****", ...}
tabd navigate https://github.com/login
tabd type     '#login_field' marshallku
tabd type-secret '#password' --secret-id a1b2c3...
tabd click    '[name=commit]'
tabd wait-url 'https://github.com/*' --pattern-type glob

# 6. Stop when done.
tabd daemon stop

Architecture

tabd CLI ──┐
           ├── /tmp/…/daemon.sock ──> tabd daemon ──> chromium (CDP/WS)
tabd CLI ──┘                              │
                                          ├── supervise task
                                          └── secrets vault (AES-256-GCM)
  • Daemon owns one Chromium and a TabRegistry (targetId → sessionId + per-tab ring buffers for console/page-errors/network).
  • Reader task routes CDP events into the matching TabState — no RPC calls from inside the reader (would self-deadlock the registry mutex).
  • Supervise task checks Chromium liveness every 2 s (try_wait() on the owned child — cross-platform); on crash it rebuilds the Chromium + CDP client with exponential backoff (5 attempts).
  • CLI dispatcher auto-spawns the daemon if no socket exists, then routes the subcommand to the matching daemon action over UDS.
  • Secrets vault is a single AES-256-GCM file at $XDG_CONFIG_HOME/tabd/secrets.enc, key derived from $TABD_VAULT_KEY via PBKDF2-SHA256 (200 000 iters). secret-list never decrypts.

--json and --out

Every dispatched subcommand accepts:

  • --json — emit the daemon response payload as compact JSON instead of the default pretty rendering. String results become quoted JSON literals; null becomes null; objects/arrays serialize compactly.
  • --out FILE — for actions that return a base64 data URL or {base64,mimeType} object (screenshot), decode the bytes and write the file. No stdout payload.

Development

# Build
cargo build --release --manifest-path crates/tabd/Cargo.toml

# Test
cargo test --bins --manifest-path crates/tabd/Cargo.toml         # 120 unit
bash tests/cli-direct-smoke.sh                                          # CLI smoke (auto-spawn, render, error contracts)
bash tests/spike-daemon-compat.sh                                       # 39 cases (real Chromium)

crates/tabd/src/:

  • main.rs — clap router for daemon ... + external_subcommand → cli::run
  • cli.rs — argv parser, dispatch table, daemon auto-spawn, render
  • daemon.rs — UDS server, action handlers, supervisor, vault state
  • cdp.rs — JSON-RPC over WS, multi-tab registry, event routing
  • browser.rs — Chromium launch + DevTools port discovery
  • secrets.rs — AES-GCM + PBKDF2 file vault
  • cmd/ — helper expressions (text/AX/find-all) used by the daemon handlers

Docs

  • docs/commands.md — per-action reference: positional args, every --flag, return shapes, error strings. The thing you'll actually keep open while writing a script.
  • docs/cookbook.md — full scenarios stitched together: 2FA login + data extract, three patterns for capturing API responses, session save/restore, infinite scroll, isolated CI daemon, gotchas.
  • docs/architecture.md — why tabd is shaped this way (daemon, multi-tab registry, reader task, supervisor, secrets vault).
  • docs/operations.md — running tabd as a long-lived service: systemd user unit, launchd LaunchAgent, shell-rc fallback, drain semantics, health watchdog, troubleshooting.
  • docs/history/ — phase 0-3 migration plans, kept as immutable historical record. Not documentation of current behavior.
Ver o original no GitHub

Bom para

Relacionados