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. Stored passwords and private keys are not returned by bridge tools.
Terminal tools open visible tabs; headless execution opens no tab.
Apple Silicon · macOS 14.2+ · Direct-download or Homebrew build
Agent Bridge is off by default. It is available in the direct-download and
Homebrew builds; it is compiled out of any Mac App Store variant.
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. The tool list below explains
which actions are available and which sessions you can watch.
How access is controlled
Commands inherit the remote SSH account’s permissions. Agent Bridge is not a command sandbox: a root connection still permits root-level actions. Command output and files can contain sensitive data even when stored credentials are not returned.
No network port. The bridge listens on a 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. Connection-reading tools omit saved passwords and private keys. Create/update tools can accept passwords, so enter credentials in the app rather than supplying them through your agent.
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. It's a forensic trail, not a second copy of your data.
You can watch and take over. Terminals the agent opens are real tabs labeled with the agent's name (Claude Code, Codex, Cursor…). Grab the keyboard at any point.
Private keys are never returned — only referenced by id.
Observability
list_monitors, list_session_logs
Read-only. Log listing returns metadata only, never recorded terminal content.
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 with Claude Code or Codex
walks through a saved test connection, agent approval and two commands
in a visible terminal. It includes a copyable task, expected results
and help for setup failures.
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.
Questions people actually ask
Does the agent get my SSH passwords or private keys?
Connection-reading tools omit stored passwords and private keys. Configure the connection in the app first: passwords supplied 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; the bridge is local IPC between two processes on your Mac.
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 — if you switch from Claude Code to something else next month, the bridge doesn't care. (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 that sensitive command text is removed. Commands inherit 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. If something behaves badly we want to hear about it — [email protected].
Try it on your own Mac
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.
