feat(ssh): native SSH support via an allowlisted ssh_exec tool

Lets the agent run commands on remote machines without giving up the
security boundary. The agent targets hosts by NAME (e.g. \"staging\"),
never by free-form user@host strings — even with prompt injection,
the model can only pick from the user's enrolled allowlist.

Components:

- src/ssh/config.ts — reads + validates ~/.codebase/ssh.json (user-wide)
  and <cwd>/.codebase/ssh.json (project, project wins on name conflict).
  Rejects host fields that smell like smuggled user@host:port syntax;
  enforces name pattern, port range, identityFile shape.
- src/ssh/store.ts — atomic add/list/rm of user-wide hosts; writes the
  file at mode 0600.
- src/ssh/cli.ts — `codebase ssh add | list | rm | test | keygen`.
  keygen defaults to Ed25519 (faster, smaller, modern); --rsa generates
  RSA-4096 for compliance / legacy infra. Files chmod 0600 on the
  private key, 0644 on the public key. Passphrase-less by design
  (the agent must run non-interactively), documented in the keygen
  output with the `ssh-keygen -p` recipe if the user wants to add
  one later.
- src/tools/ssh-exec.ts — wraps `ssh` with safe defaults:
  BatchMode=yes (no password prompts ever), ConnectTimeout=10s,
  StrictHostKeyChecking=accept-new (TOFU on first connection, strict
  after), ServerAliveInterval=30s, IdentitiesOnly=yes when --key is
  set. Applies the local shell-validator to the remote command too —
  rm -rf / over SSH blocks the same way.

Tests: 20 new (config + store + tool integration). 774 total passing.
Docs: SSH section in CLAUDE.md covering enrollment, security model,
config schema.

Author: halfaipg

CLAUDE.md

@@ -271,6 +271,88 @@ default — only an actual exit-2 blocks.
 }
 ```
 
+## SSH (remote machine access)
+
+The agent can run shell commands on remote machines via the `ssh_exec`
+tool. The host list is an allowlist managed by the user — the agent
+picks a name from the enrolled set, not arbitrary `user@host` strings.
+
+### Enrollment
+
+```sh
+# Generate a key (default Ed25519, --rsa for RSA-4096 if your
+# compliance / legacy infra requires it). Passphrase-less by default
+# because the agent runs non-interactively.
+codebase ssh keygen staging
+
+# Print the pubkey + a one-liner to install it on the remote.
+
+# Register the host:
+codebase ssh add staging staging.example.com --user deploy --key ~/.codebase/ssh/staging
+
+# Verify connectivity:
+codebase ssh test staging
+
+# Inspect / remove:
+codebase ssh list
+codebase ssh rm staging
+```
+
+### How the agent uses it
+
+When asked to "deploy the build to staging", the model issues:
+
+```ts
+ssh_exec({ host: "staging", command: "cd /app && systemctl restart codebase" })
+```
+
+The host argument is the registered NAME, not a hostname. The tool
+resolves it against `~/.codebase/ssh.json` and (optionally) project
+overrides at `<cwd>/.codebase/ssh.json`. Project entries override
+user entries with the same name.
+
+### Security model
+
+- **Allowlist by name, not free-form.** The agent can target `staging`
+  only if the user enrolled `staging`. Even with prompt injection,
+  the model can't pick a destination the user didn't pre-approve.
+- **Same shell-validator as the local `shell` tool.** `rm -rf /`,
+  fork bombs, raw writes to `/dev/sda` etc. are blocked before the
+  ssh spawn, regardless of which host they target.
+- **BatchMode=yes.** Never prompts for a password. If the key isn't
+  accepted, the call fails fast instead of stalling.
+- **StrictHostKeyChecking=accept-new.** First connection pins the
+  host key (TOFU); a later host-key mismatch refuses to connect.
+- **ConnectTimeout=10s + ServerAliveInterval=30s.** Unreachable
+  hosts fail in seconds, dead network paths are detected during
+  long-running commands.
+- **IdentitiesOnly=yes when --key given.** Predictable auth path —
+  ssh doesn't fall back to other keys in the agent.
+
+The validator is advisory, not a security boundary. Real isolation
+for hostile workloads still belongs in container / sandbox
+boundaries on the remote.
+
+### Config schema (`~/.codebase/ssh.json` and `<cwd>/.codebase/ssh.json`)
+
+```json
+{
+  "hosts": [
+    {
+      "name": "staging",
+      "host": "staging.example.com",
+      "user": "deploy",
+      "port": 22,
+      "identityFile": "~/.codebase/ssh/staging",
+      "description": "staging app server (us-east-1)"
+    }
+  ]
+}
+```
+
+`name` must match `[a-z0-9][a-z0-9_-]*`. `host` rejects anything
+that looks like `user@host:port` syntax — use separate fields.
+
 ## In-flight features
 
 - **MCP**: real MCP client support hasn't shipped (the `/mcp`

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.59",
+	"version": "2.0.0-pre.60",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",

package.json

@@ -6,6 +6,7 @@ import { runAuthSubcommand } from "./auth/cli.js";
 import { loadDotEnv } from "./dotenv/loader.js";
 import { type HeadlessOutputFormat, runHeadless } from "./headless/run.js";
 import { runProjectSubcommand } from "./projects/cli.js";
+import { runSshSubcommand } from "./ssh/cli.js";
 import { App } from "./ui/App.js";
 import { installTerminalRestoreHandlers } from "./ui/terminal-restore.js";
 import { setTerminalTitle } from "./ui/terminal-title.js";
@@ -56,6 +57,8 @@ if (argv[0] === "--version" || argv[0] === "-v") {
 	process.exit(0);
 } else if (argv[0] === "auth") {
 	runAuthSubcommand(argv).then((code) => process.exit(code));
+} else if (argv[0] === "ssh") {
+	runSshSubcommand(argv).then((code) => process.exit(code));
 } else if (argv[0] === "project" || argv[0] === "projects") {
 	runProjectSubcommand(argv).then((code) => process.exit(code));
 } else if (argv[0] === "app-server") {
@@ -157,6 +160,9 @@ function printHelp(): void {
 			"  codebase auth status         show current sign-in",
 			"  codebase auth refresh        force-refresh the access token",
 			"  codebase auth <cbk_xxx>      save a manual API key (for SSH / headless)",
+			"  codebase ssh add <name> <host>    enroll a remote machine the agent can target",
+			"  codebase ssh list / rm / test     manage enrolled SSH hosts",
+			"  codebase ssh keygen <name>        generate an Ed25519 (or --rsa) keypair",
 			"  codebase project list        list your projects on codebase.design",
 			"  codebase project pull <id>   download a project as a ZIP",
 			"  codebase app-server          JSON-RPC server on stdio (for IDE extensions)",