Nexus Shell Agent Bridge

Agent Bridge: your Mac SSH workspace, connected to your coding agent

Nexus Shell is an MCP server. Your own agent — Claude Code, Codex, anything that speaks the Model Context Protocol — drives your SSH connections, terminals, SFTP and keys through the app. Bridge tools do not return stored passwords or private keys. Terminal tools open visible tabs; headless execution opens no tab.

Shipped in v1.5.9. Off by default. Available in the direct-download and Homebrew builds; compiled out of any Mac App Store variant.

Canonical URL: https://nexusshell.app/agent-bridge

What Agent Bridge adds to your workflow

Keep saved connections, terminal sessions and file operations in one native Mac workspace while using Claude Code, Codex or another MCP client. Agent Bridge exposes those app capabilities to your existing agent, with per-agent approval and an audit trail of tool calls. Ask the agent to inspect a container, read a selected configuration file or open a terminal, then review the result in the app. You keep your choice of model and coding client.

Follow the first VPS check with Claude Code or Codex: saved connection setup, agent approval, a copyable task, expected results and setup troubleshooting.

How it's locked down

• No network port. Unix domain socket at ~/Library/Application Support/NexusShell/agent-bridge.sock, chmod 0600. At the filesystem layer, only your user can reach it.
• Same-uid enforcement. After accept, getpeereid must report the caller's uid matches the app's own — otherwise the connection is dropped before any protocol logic runs.
• The app derives the agent's identity itself — LOCAL_PEERPID → parent pid → proc_pidpath. Whatever the client claims about itself is treated as spoofable and used only for display. Consent is keyed on the path the app resolved.
• Per-agent consent. The first tool call from a given agent raises an approval dialog inside Nexus Shell. Revocable whenever you like.
• Stored credentials are omitted from connection reads. Create/update tools can accept passwords; configure authentication in the app first, rather than sending it to your agent. Output and files can still contain secrets.
• Everything is audited. One JSONL record per tool call and connection event. password, passphrase, content, content_base64 and data are replaced with a redaction marker; command and text truncate at 200 characters. Rotates at 5 MB, written 0600.
• You can watch and take over. Terminals the agent opens are real tabs, badged as agent-opened.

26 tools

Group	Tools	Notes
Connections	list_connections, get_connection, create_connection, update_connection, delete_connection, test_connection	Reads omit stored credentials; create/update inputs can contain passwords.
Terminals	open_terminal, list_terminals, run_command, send_text, read_terminal, close_terminal	Real, visible, badged tabs. Session-logged when logging is on.
Headless exec	exec_command	No tab, not session-logged. Returns stdout, stderr, exit status.
SFTP	sftp_list, sftp_read_file, sftp_write_file, sftp_upload, sftp_download, sftp_mkdir, sftp_delete, sftp_rename	sftp_write_file is an atomic replace.
Keys	list_keys, generate_key, deploy_public_key	Private keys are never returned — only referenced by id.
Observability	list_monitors, list_session_logs	Read-only. Log listing returns metadata only.

What it deliberately can't do

• No create, edit or delete tools for monitors.
• No settings-mutation tools of any kind — an agent cannot reconfigure the app, and cannot turn off its own audit trail.
• list_session_logs returns metadata only: server, title, time, duration, size. Never the recorded terminal content.

Start with a guided server check

The first VPS check walkthrough covers a saved test connection, agent approval and two commands in a visible terminal. Configure credentials in Nexus Shell before starting. After the check succeeds, choose a specific inspection or file task and review its permissions before allowing changes.

Requirements

macOS 14.2 or later on Apple Silicon. The direct-download or Homebrew build — brew install --cask viewer12/tap/nexus-shell. Any MCP client; we test against Claude Code and Codex.

FAQ

Does the agent get my SSH passwords or private keys? Connection-reading tools omit stored passwords and private keys. Configure authentication in the app first: password inputs to create/update tools have already entered the client. Hostnames, usernames, notes, command output and file content can still reach the agent.

Is there a network port open? No. It's a Unix domain socket with mode 0600, so only local processes running as you can connect — and the same-uid check happens before any protocol parsing. Nothing is relayed through nexusshell.app.

Is this just a chatbot bolted onto a terminal? The opposite. Nexus Shell is the server; you bring the agent. There's no model, no prompt and no vendor lock-in in this feature. (Nexus Shell does also have a separate built-in AI assistant on ⌘L / ⌘K that uses your own API key. Different feature.)

What happens if the agent does something dumb? Terminal tools open visible tabs; headless execution does not. Audit records identify tool calls, but do not guarantee secret-free command text. Remote commands retain the SSH account's permissions. Revoking future access does not undo completed work or guarantee termination of remote background processes. Start with a test server and a limited account.

Is it stable? It ships marked experimental. The security boundary is the part we're most confident in; the ergonomics are still moving. Report problems to support@nexusshell.app.

Pricing

Free tier is free forever. Register and you get a 7-day full-feature Pro trial — no card, nothing charged when it ends. Pro is $12.88 once, not per month. See https://nexusshell.app/pricing.md.

Machine-readable

Agent-skills spec: https://nexusshell.app/.well-known/agent-skills/agent-bridge.md

Permission boundary

Commands inherit the SSH account's permissions. This is not a command sandbox; root connections retain root privileges. Output and remote files can contain sensitive data. Use a suitably restricted test account for a first run.