Skip to content
SHELLWATCH

Introduction

ShellWatch is a Human-in-the-Loop platform for agent-driven SSH. It’s passkey-first and passkey-only — no passwords anywhere — with an SSH-agent proxy that forwards signing requests end-to-end to a user’s WebAuthn passkey. Every agent action surfaces in realtime notifications, persists in a tamper-evident audit log, and can be gated behind explicit human approval before it touches the remote host.

You can drive it three ways:

  • Web UI — open SSH sessions in an in-browser terminal (xterm.js), watch them, take over, or just observe.
  • MCP — let an AI agent (Claude Desktop, Claude Code, MCP Inspector, etc.) create sessions, send keys, and read output programmatically.
  • SSH agent proxy — let your local ssh (and anything that talks SSH_AUTH_SOCK: scp, git, rsync, ansible, your AI coding agent’s shell) authenticate with ShellWatch-managed passkeys. The broker only mediates the signature; the SSH session is established directly from your host to the target.

The Web UI and MCP share the same session manager — a session created via MCP appears in the UI immediately, and vice versa, so anything the agent does you can watch live. The agent proxy is the other shape: ShellWatch is not on the wire for the session, only on the wire for the passkey signature. You give up live observation in exchange for a fully trustless path.

Two human-in-the-loop models

Section titled “Two human-in-the-loop models”

ShellWatch offers two ways to put a human gate in front of an SSH session, and you can mix them per endpoint or per agent:

Broker-mediated session (Web UI / MCP)Direct SSH via agent proxy
Who holds the SSH connection?ShellWatchYour local ssh client
What does the broker see?The full session — input, output (live only; not persisted)Only the signature ceremony — no session bytes
Live observation / takeover?YesNo
Trust in the broker?Trusted intermediary (also self-hostable)Trustless — even a fully compromised broker cannot read or alter your session
Typical useAn AI agent runs commands on a target; you watch and approveYour local tooling (or a local AI coding agent) hits target hosts directly, with a passkey tap per connection

Both models give every privileged operation the same human-in-the-loop signing flow. The difference is whether the broker is on the session path or only on the auth path.

What’s in the box

Section titled “What’s in the box”
  • In-browser terminal with xterm.js, multi-session sidebar, and an Observer grid view for watching several of your own sessions at once.
  • MCP server at /mcp (streamable HTTP) with seven tools, debounced output notifications, and per-agent session isolation.
  • OAuth 2.1 + Dynamic Client Registration, backed by Ory Hydra and gated by your passkey — every client (the web UI, MCP clients like Claude Desktop, and shellwatch-agent) enrols through the same browser login + consent flow and gets a scoped, refreshable access token. No API keys to mint, paste, or rotate.
  • SSH agent proxy with a Go thin client (shellwatch-agent) — brew install rado0x54/tap/shellwatch-agent, run shellwatch-agent login once, and any local ssh (workstation, dev box, CI runner, the box your AI coding agent runs on) authenticates against the broker without the broker ever seeing the session. Native Windows support via a named pipe is included.
  • WebAuthn passkeys for both human login and SSH key signing — every signature ceremony goes through a registered passkey authenticator. Sensitive passkey-management actions (add, revoke, invite a second device) require a fresh step-up assertion before they take effect.
  • PendingAction approval flow — every sensitive action becomes a /sign/:id page that you (or another approver on the same account) confirm with a touch.
  • Tamper-evident audit log — every session open/close and every signing-request outcome (approved / denied / expired / cancelled) is persisted and viewable per account at /audit/sessions and /audit/signings. See Concepts → Audit log.
  • Web Push (PWA) for sign-request notifications when no browser tab is open — turn your phone into the approval device for what your local agents and ssh clients are doing.
  • PAM module (pam-ssh-agent-webauthn) — verify a sudo / login password prompt against a forwarded WebAuthn passkey, end-to-end. Standalone repo; no runtime dependency on ShellWatch.
  • Self-hosted option — run the Docker compose stack (ShellWatch + Ory Hydra, both on file SQLite — no separate database server) in your own infrastructure if app.shellwatch.ai doesn’t fit. See Self-hosting.

Why ShellWatch?

Section titled “Why ShellWatch?”

ShellWatch is for teams and individuals who want to give AI agents real shell access without giving them keys, credentials, or unmonitored execution. Every meaningful action can be gated on a passkey approval and observed live, with every sign request and session open/close written to a tamper-evident audit log. (Session input/output itself is not persisted by the broker — host-side tools like auditd, shell history, or session recorders are the right place for that.)

It is also useful as a personal browser-accessible SSH bastion — your keys live on app.shellwatch.ai (or your own broker), your browser plus a passkey is the only credential you carry, and any ssh client on your machines authenticates through the same passkey via the agent proxy without the broker ever seeing the session.

How to use this site

Section titled “How to use this site”