ShellWatch

Passkey-Backed SSH for Humans and Agents

ShellWatch is a Human-in-the-Loop platform for agent-driven SSH. Passkey-first and passkey-only — no passwords anywhere — with an SSH-agent proxy that delivers end-to-end secure SSH authentication to your local client. 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.

Passkey-only auth — WebAuthn for UI login, agent enrollment, and SSH authentication via OpenSSH's [email protected] signature algorithm
End-to-end SSH-agent proxy — local ssh/scp/git reach a passkey via ShellWatch with explicit browser approval per signature
Agent forwarding into sessions — your passkey-backed SSH agent is forwarded into every ShellWatch session, so you can hop to additional hosts and enable SSH-agent-based PAM integration
PAM integration — pair with pam-ssh-agent-webauthn to gate sudo (or any PAM-aware step) behind a passkey approval surfaced through ShellWatch
Human-in-the-loop for agents — MCP agents request, humans approve; sensitive actions can require per-action consent
Realtime notifications — sign requests arrive as Web Push and in-UI toasts
Tamper-evident audit log — every signing request and session event is recorded for later review
Three ways in — web UI for humans, MCP for AI agents, and native ssh/scp/git from your workstation (via the shellwatch-agent daemon)

Requirements

[email protected] support requires:

Server (sshd): OpenSSH 8.4+, with the algorithm explicitly enabled in /etc/ssh/sshd_config:
```
PubkeyAcceptedAlgorithms=+webauthn-sk-ecdsa-sha2-nistp256@openssh.com
```
Client (ssh): OpenSSH 10.3+ — only when using the SSH agent proxy. The PAM-from-inside-a-session path uses our PAM module talking to $SSH_AUTH_SOCK directly, and plain ShellWatch sessions opened from the UI or MCP have no client-side OpenSSH requirement.

Quick start

git clone https://github.com/rado0x54/ShellWatch.git
cd ShellWatch
pnpm install
cp config.sample.yaml config.yaml
pnpm dev

pnpm dev runs Fastify on :3000 (API, WebSocket, MCP, agent-proxy) and a Vite dev server on :3001 for the SvelteKit UI with hot reload — open http://localhost:3001 in dev. Vite proxies WS/API/MCP traffic to Fastify, so everything works on the one URL.

See config.sample.yaml for all options. Endpoints, keys, and passkeys are managed in the web UI; the config file only handles initial seeding and security settings.

Minimal config.yaml for local dev (UI at :3001):

server:
  externalUrl: http://localhost:3001

security:
  rpId: localhost
  trustedWebauthnOrigins:
    - http://localhost:3001
    - http://localhost:3000
  allowedNetworks:
    - 127.0.0.1/32
    - "::1/128"

Production

pnpm build   # tsc + SvelteKit
pnpm start   # serves the pre-built client from dist/client/

Then open http://localhost:3000 — Fastify auto-detects dist/client/ and serves the built UI off the same port as the API, WebSocket, MCP, and agent-proxy.

Endpoints

Path	Interface
`/`	Web UI
`/observer`	Multi-session grid
`/settings/*`	Endpoints, keys, passkeys, API keys
`/api/*`	REST API
`/ws`	WebSocket (terminal I/O + events)
`/mcp`	MCP (streamable HTTP)
`/agent-proxy`	SSH agent proxy (WebSocket, API key auth)
`/health`	Health check

Reverse proxy

When ShellWatch runs behind nginx/Caddy/an ALB/Cloudflare, set server.trustProxy to the CIDR(s) of the proxy you control so real client IPs reach the allowlist and audit log:

server:
  externalUrl: https://shellwatch.example.com
  trustProxy:
    - 10.0.0.0/8

Do not set trustProxy: true in production. That trusts X-Forwarded-For from any source, letting clients spoof their IP. Pin to the CIDR of the proxy you actually run. Make sure the proxy itself sets X-Forwarded-For. See Fastify's docs for the full grammar.

MCP

ShellWatch exposes an MCP server over streamable HTTP at /mcp.

Tool	Description
`shellwatch_create_session`	Create a new terminal session
`shellwatch_list_sessions`	List this agent's active sessions
`shellwatch_send_keys`	Send keystrokes/text to a session
`shellwatch_read_output`	Read session output (with offset)
`shellwatch_close_session`	Close a session
`shellwatch_manage_endpoints`	List, create, update, or delete SSH endpoints
`shellwatch_manage_keys`	List available SSH keys

Each MCP client gets an isolated AgentSession — agents only see their own sessions.

Connecting an MCP client

Point your client (Claude Desktop, Claude Code, any MCP-aware tool) at the /mcp URL — the integrated OAuth flow handles credentials, no manual API key paste needed:

https://your-shellwatch-host/mcp

OAuth mints an mcp-scoped API key after browser approval. For headless setups you can still seed a static key via seedAdminApiKey in config.yaml, or create one under Settings → API Keys.

Push notifications (PWA)

ShellWatch is an installable PWA with Web Push for sign requests, so approvers don't need the tab open. Generate VAPID keys and add them to config.yaml:

npx web-push generate-vapid-keys

vapid:
  subject: "mailto:[email protected]"
  publicKey: "BEl62i..."
  privateKey: "UGo..."

Enable push under Settings → Notifications. When vapid is unset, the feature is hidden.

SSH agent proxy

ShellWatch can act as an SSH agent for system clients (ssh, scp, git), so your local commands authenticate via passkeys managed by ShellWatch.

agentSocket:
  proxyEnabled: true

Run shellwatch-agent on your workstation:

brew install rado0x54/tap/shellwatch-agent
# Defaults to app.shellwatch.ai; pass `--server https://your-host` to point at a self-hosted instance.
shellwatch-agent login
brew services start shellwatch-agent
eval "$(shellwatch-agent --print-env)"

Every signing request requires explicit browser approval. To make user-verification load-bearing on the server, set PubkeyAuthOptions verify-required in sshd_config. Full usage, OAuth/static-key flows, and troubleshooting in the agent-client README.