Quick start

You need Bayesian SSH 2.13 or later, a few hosts saved in bssh, and an agent that speaks MCP.

Connect your agent

Add bssh to your agent’s MCP configuration:
```
bssh ai install claude-code
```
The same command works with codex, cursor, vscode and claude-desktop. It adds one entry named bssh and leaves everything else in the file alone, after a backup. --dry-run prints the change without writing it:
```
{
  "mcpServers": {
    "bssh": {
      "type": "stdio",
      "command": "/usr/bin/bssh",
      "args": ["ai", "mcp", "--policy", "default"]
    }
  }
}
```
Any other MCP client works too: point it at bssh ai mcp over stdio.
Restart the agent. It now has 15 bssh tools, starting with list_hosts.
Ask it something about a host:

Why is nginx returning 502 on web-1?

A typical session: list_hosts, observe for the failed units, search_logs on the nginx journal, read_file on the site configuration. None of it asks you anything, because none of it can change the host.

What the agent may do at first

Until you write a policy, bssh uses the built-in observe profile on every host you have saved: the agent can read, and every write is refused. It acts for you, so it sees the hosts you already have, never more.

Check how a command would be treated, here or at any time:

$ bssh ai explain --host web-1 "journalctl -u nginx --since '10 min ago' | grep -i error"
command: journalctl -u nginx --since '10 min ago' | grep -i error
tags:    read
commands:
  1. journalctl -u nginx --since 10 min ago
     tags:     read
     rule:     journalctl read
  2. grep -i error
     tags:     read
     rule:     grep
policy:  default  host: web-1
decision: allow - analyzer: every command is read-only

Let it fix things

Give the default policy the operate profile and a scope. Policies live under ai.policies in your configuration file, ~/.config/bayesian-ssh/environments/default/config.json:

"ai": {
  "policies": {
    "default": {
      "profile": "operate",
      "scope": { "tags": ["staging", "prod"] },
      "approval": { "in_client": ["staging"], "two_person": ["prod"] },
      "write_paths": ["/etc/nginx/**"]
    }
  }
}

Now the agent can propose changes on hosts tagged staging or prod, and edit files under /etc/nginx. Every change asks first. On staging, a low-risk change can be confirmed in the agent’s own client; anything else goes to the desktop app or the terminal. See Policies for every field.

Approve the first change

Ask the agent to fix what it found. It sends a change plan: the steps, the diff, how to check the fix and how to undo it. The desktop app shows it in its AI section; in a terminal:

bssh ai approve

bssh ai approve lists what is waiting, shows the request in full and asks for a decision. --deny --reason "…" refuses with a reason the agent receives. Once approved, bssh runs exactly the approved steps, then the plan’s verify steps, and the agent reports back.

See what happened

bssh ai log                  # recent runs
bssh ai log <run> --report   # hosts touched, changes with diffs, approvals, undo points
bssh ai status               # running agents, pending approvals, active grants
bssh ai stop                 # end a run now

Everything above also sits in a signed, hash-chained log on your machine.

Keep agents on the bssh path

An agent that also has a shell tool can still try plain ssh. For Claude Code, bssh can install a hook that blocks ssh, scp, sftp and rsync to the hosts bssh knows and points the agent to the bssh tools instead:

bssh ai install claude-code --guard

Next steps

Policies: profiles, paths, deny rules, budgets, and testing a policy in CI.
Host setup: the low-privilege agent user, the read-only jail and approval-bound certificates.
Approvals: plans, grants and the desktop app.