Skip to content
SHELLWATCH

Quick start

This walks you through your first session on app.shellwatch.ai. You’ll need a browser and a passkey-capable device (Touch ID / Windows Hello / a hardware key like a YubiKey).

1. Create your account

Section titled “1. Create your account”
  1. Go to app.shellwatch.ai/register.
  2. Pick an account name and register a passkey on your device.
  3. You’re logged in. There are no passwords to set, recover, or lose.

2. Add an SSH endpoint

Section titled “2. Add an SSH endpoint”

Go to Settings → Endpoints and add a target host:

  • Label — anything you’ll recognise.
  • Address — [user@]host[:port] (defaults: user=shellwatch, port=22).

You’ll need to give that host a passkey-derived public key before the connection succeeds.

3. Authorize a passkey on the target

Section titled “3. Authorize a passkey on the target”

Open Settings → Passkeys. Each registered passkey shows an OpenSSH-format public key — type webauthn-sk-ecdsa-sha2-nistp256@openssh.com. Copy it and append it to the target host’s ~/.ssh/authorized_keys:

Terminal window
# On the remote host
echo "webauthn-sk-ecdsa-sha2-nistp256@openssh.com AAAA... my-passkey" \
  >> ~/.ssh/authorized_keys

There’s no per-endpoint “assign a passkey” step in the UI — when you open a session, ssh2 presents all of the account’s registered passkeys and sshd accepts whichever one matches authorized_keys. So registering the passkey on the account and authorizing its public key on each target is the whole wiring.

Tip: a touch alone only proves User Presence (UP) — that something was pressed. User Verification (UV) is stronger: it requires a biometric or PIN unlock on the authenticator, so the signature attests to who approved. To make UV load-bearing end-to-end, configure the target’s sshd to reject signatures without the UV bit — see SSH agent proxy → Enforcing UV.

4. Open a session

Section titled “4. Open a session”

Click Connect on the endpoint in the sidebar. A /sign/:id page pops up — touch your authenticator to approve the WebAuthn ceremony, the SSH handshake completes, and a terminal opens.

5. (Optional) Connect Claude — or another MCP agent

Section titled “5. (Optional) Connect Claude — or another MCP agent”

Point your MCP client (Claude Desktop, Claude Code, MCP Inspector, …) at the bare /mcp URL — the integrated OAuth flow handles credentials, no keys to mint or paste:

{
  "mcpServers": {
    "shellwatch": {
      "type": "streamable-http",
      "url": "https://app.shellwatch.ai/mcp"
    }
  }
}

On the first request the client registers itself, opens your browser for a passkey login + consent, and stores an mcp-scoped OAuth token (with a refresh token, so the browser step happens roughly once a month per client). Headless / CI setups currently still need that one-time browser login — a device flow is a planned follow-up.

See Guides → MCP integration for the full agent setup.

6. (Optional) Sign your local ssh with a ShellWatch passkey

Section titled “6. (Optional) Sign your local ssh with a ShellWatch passkey”

Install shellwatch-agent on any host you ssh from — your workstation, a dev box, the machine running your AI coding agent. Default server is app.shellwatch.ai, so for the hosted broker there’s nothing to configure:

Terminal window
brew install rado0x54/tap/shellwatch-agent
shellwatch-agent login                    # browser passkey flow, credentials land in your OS keyring
brew services start shellwatch-agent      # daemon under launchd / systemd-user
eval "$(shellwatch-agent --print-env)"    # tell your shell where the socket is

login runs an OAuth 2.1 loopback PKCE flow (the same browser passkey login an MCP client uses), stores a refresh token in your platform credstore (macOS Keychain, Linux libsecret, Windows DPAPI; 0600 file fallback when no keyring is reachable), and the daemon mints short-lived agent-scoped access tokens from it automatically. Self-hosted instances: pass --server https://your-host to both login and the daemon. Native Windows is supported via a named pipe — see the SSH agent proxy guide.

From then on, every local ssh user@host (and scp, git, ansible, …) triggers a passkey ceremony in your browser before the connection completes. The session itself is direct: ShellWatch only mediates the signature, never the session bytes. This is the trustless half of ShellWatch — no live observation, but the broker is not on the wire.

Where to next

Section titled “Where to next”