# Agent Bridge — Nexus Shell as an MCP server

Nexus Shell ships **Agent Bridge**: the app exposes its SSH connections,
terminals, SFTP and key management to your own local AI agent over the
**Model Context Protocol**. Shipped in v1.5.9 (2026-07-17).

This is not a built-in chatbot. Nexus Shell is the **MCP server**; the
client is whatever agent you already run — Claude Code, Codex, or any
other MCP client.

## Why this exists

The usual way to let an agent touch a server is to hand it credentials —
a private key path in a JSON config, or a raw shell. Agent Bridge
inverts that: the agent gets *capabilities*, never *secrets*, and every
action lands in a GUI the user is watching.

## Availability

- Requires the **direct-download or Homebrew build** of Nexus Shell.
  Agent Bridge is compiled out of any Mac App Store variant.
- macOS 14.2+, Apple Silicon.
- **Off by default.** Enable in Nexus Shell → Settings → Agent Bridge.

## Setup

Settings → Agent Bridge shows a one-paragraph instruction. Paste it into
your agent and the agent registers the MCP server and links the skill
folder itself. No manual JSON editing.

## Tool surface — 26 tools

| Group | Tools |
|---|---|
| Connections | `list_connections`, `get_connection`, `create_connection`, `update_connection`, `delete_connection`, `test_connection` |
| Terminals (real, visible tabs) | `open_terminal`, `list_terminals`, `run_command`, `send_text`, `read_terminal`, `close_terminal` |
| Headless exec (no tab) | `exec_command` |
| SFTP | `sftp_list`, `sftp_read_file`, `sftp_write_file`, `sftp_upload`, `sftp_download`, `sftp_mkdir`, `sftp_delete`, `sftp_rename` |
| Keys | `list_keys`, `generate_key`, `deploy_public_key` |
| Read-only observability | `list_monitors`, `list_session_logs` |

### Choosing a tool

- One-shot check (`uname -a`, `df -h`, `systemctl status nginx`) →
  `exec_command`. Returns stdout, stderr, exit status. Opens no tab and
  is not session-logged.
- Work the user should watch, or several ordered steps →
  `open_terminal` once, then `run_command` per step. This is a real
  terminal tab, badged as agent-opened, captured by session logging when
  the user has it on.
- Interactive or full-screen programs (`vim`, `top`, `less`, password
  prompts) → `send_text` + `read_terminal`. `run_command` waits for
  output to fall quiet, which never happens for programs that don't
  return.

### Deliberate omissions

- No create/edit/delete tools for monitors.
- No settings-mutation tools of any kind.
- `list_session_logs` returns **metadata only** — server, title, time,
  duration, size. Never the recorded terminal content.

## Security model

Enforced in the app, outside-in:

1. **Unix domain socket, no network port.** The socket lives at
   `~/Library/Application Support/NexusShell/agent-bridge.sock`,
   `chmod 0600` — at the filesystem layer only this user can connect.
2. **Same-uid check.** After `accept`, `getpeereid` must report the
   caller's uid equals the app's own uid, or the connection is dropped
   *before any protocol logic runs*.
3. **The server derives the agent's identity itself** — `LOCAL_PEERPID`
   for the shim pid → parent pid → `proc_pidpath`. The shim's
   self-reported identity is treated as spoofable and used only for
   display. Consent records are keyed on the server-resolved executable
   path.
4. **Per-agent consent.** The first tool call from a given agent raises a
   one-time approval dialog inside Nexus Shell. Revocable at any time.
5. **Secrets never cross the boundary.** Stored passwords and private
   keys are not readable by any tool; connections are referenced by
   `connection_id`.
6. **Everything is audited.** One JSONL record per tool call and
   connection event. `password`, `passphrase`, `content`,
   `content_base64` and `data` values are replaced with a redaction
   marker; `command` and `text` are truncated to 200 characters. The log
   rotates at 5 MB and is written `0600`. It is a forensic trail, not a
   data-exfiltration surface.

## What this is not

- Not a hosted service. Nothing is relayed through nexusshell.app;
  the bridge is local-only IPC between two processes on the same Mac.
- Not a remote-access channel. Only local processes running as the same
  user can connect. There is no listening TCP port.
- Not the same as the in-app AI assistant (⌘L / ⌘K), which is a separate
  feature that calls an AI provider with your own API key.

## Related

- Landing page: <https://nexusshell.app/agent-bridge>
- Pricing: <https://nexusshell.app/.well-known/agent-skills/pricing.md>
- Download: <https://nexusshell.app/.well-known/agent-skills/download.md>
- Support: support@nexusshell.app