• The core. nerd sends no telemetry, and checks for updates only if you allowed it, and logs every check. The server locks itself into a macOS Seatbelt sandbox that denies it the network: nerd --sandbox-selftest shows the profile refusing it, and nerd --list shows whether each server has it. nerd's only network code is the proxy it runs for a plugin with network, or for a pane set to Only these providers: outside the server's sandbox, in a sandbox of its own, it connects only to the hosts and ports that the plugin's manifest or the chosen agents' manifests name. Everything that can leave nerd is in What leaves nerd; SECURITY.md says what each protection covers and what it does not.
• Terminal output is contained. Escape sequences printed by programs are interpreted inside nerd and never reach your terminal.
• What is stored. Everything is under ~/Library/Application Support/nerd/, private to your user:
• the layout, working directories, commands, and each agent's session id with the agent it belongs to;
• the resume command of each agent you confirmed when its hook was installed;
• whether nerd may check for a new release once a day, and when it last did (update-check, update-checked), the release you skipped (release-skipped), each server's last answer and the release its window's install click left (release.json, release-install), and while a check or an install runs, its download folder (release-<pid>, removed afterwards);
• pane text, written when the server stops and deleted when it starts again, kept out of Time Machine and Spotlight. It holds whatever your panes printed. Set restore_screens to false to turn it off.

Outside that folder, a terminal preset writes only on your word (Settings… → Terminal preset…, nerd --preset): it adds one marked block or line to that terminal's config, writes iTerm2's profile named nerd, and sets iTerm2's margins and default profile. It shows every change before making it, and undo takes them back.

• Dependencies are permissively licensed and checked with cargo deny.

How it works

nerd is a client and a server. nerd starts a server in the background if needed and connects to it. The server owns the panes, runs their programs and draws the screen; the client passes your keys and mouse to it and shows what it draws. Closing the window only disconnects the client.

Each pane is a pseudo-terminal read by a terminal emulator library. nerd reads each pane's process tree once a second to see which agent runs there; the hook reports a supported agent's state directly.

What leaves nerd

Each way out starts from something you do or approved, and writes a line to daemon.log.

Outside the table, and said here so nothing is implied:

• Panes. The programs in your panes, agents included, run as you unless their isolation says otherwise (see Isolation), outside the server's sandbox and outside this table: a shell you open, a log viewer nerd opens from a menu (less on its own log), or an agent's resume command you confirmed once, which a restored pane types for you. nerd also hands a message to an agent in a pane: at the end of its turn as its hook's own answer (block, deny or followup_message), through the pi or OpenCode extension, or, for an idle agent with no better path, typed in with nerd's frame line first and a carriage return after it; never into a pane waiting for your answer.
• The sandbox off. With sandbox set to false, or when the sandbox fails to start (the server keeps running; nerd --list and every window say so), the server is not kept off the network until the sandbox is back.

Links are found in the text a pane prints; OSC 8 hyperlinks are not read. Anything else that leaves nerd is a bug: report it as a vulnerability (see SECURITY.md).

What a program inside a pane can do

An agent in a pane runs shell commands as you, so it could type nerd --stop or nerd --update. The server refuses a connection from a process that descends from its own panes when it asks to stop, update, disconnect everyone or take the screen; the command prints refused: … from inside a pane, exits non-zero, and the server logs it. nerd --stop, --update and --disconnect without a name, run inside any nerd pane, refuse too: name the server, or set NERD_SOCKET or NERD_STATE_DIR to target a test server. Programs in panes may stop or update nerd, in Settings… → Messages, turns both refusals off. Plugins follow the same rule: from a pane, nerd --plugin-add only fetches, and the question comes up in nerd's own window, where only a click installs; --yes, --plugin-on and --plugin-remove are refused.

The way in is the message socket. Panes of admitted accounts reach it through /tmp/nerd-<uid>/, a folder only nerd's owner can write, checked before use, and reach nothing else of nerd. No path in nerd lets an agent change names, routes, isolation or that switch while nerd runs; from an isolated pane, no file can either.

This guards against accidents, not against code that means it: a program that detaches from the pane (a double fork) is no longer its descendant, and any program running as you can stop the server with a signal anyway.

Supported versions

Only the latest release receives security fixes.

Reporting a vulnerability

Report it privately through GitHub: Security → Report a vulnerability on this repository. Do not open a public issue, pull request or discussion.

Include what is affected, the steps to reproduce, and the impact you expect. You will get an answer when the report has been read; there is no guaranteed response time. Please allow a fix to be released before you disclose the issue publicly.

Scope

In scope:

• escape sequences or other pane output that reach the user's terminal or trigger actions in nerd;
• ways around the server's network sandbox;
• anything that leaves nerd other than what "What leaves nerd" in docs/privacy-and-security.md lists, or a plugin reaching more of the network than its permission says;
• a pane reaching more than its isolation allows (Files: This folder only or Another account; Network: Only these providers or None), or an agent changing names, routes, isolation or accounts while nerd runs;
• files written by nerd with wrong permissions or readable by other users;
• the installer, the release archive and its checksum.

Out of scope:

• what programs in a pane left at Everything and Open do, which nerd deliberately does not restrict;
• attacks that require local access as the same user;
• the binary not being notarized by Apple, which is documented.

What the protections cover

• The server's sandbox denies the network, and nothing else. The Seatbelt profile starts from (allow default): the file system and Mach services stay open to the server. Unix-domain sockets stay allowed, except mDNSResponder's, which is denied by name so that name lookups fail; the server can reach any other local socket its user can.
• A plugin reaches only its network tier. Its own Seatbelt profile allows nothing, or localhost only. With hosts and ports it reaches only the port of a proxy nerd runs for it alone, and the proxy connects only to those hosts on those ports: a name only at its public internet addresses, never this Mac or a network it is on; an IP address as the manifest writes it. A plugin never opens a terminal device, and does not read the credential folders and ~/Library listed in docs/plugins.md; it can read the command line and environment of the user's other programs, which macOS does not let a sandbox hide.
• The broker runs what the server asks. It starts panes and plugins outside the sandbox from the server's requests, so the server's sandbox is a guarantee about nerd's own code (no network, no telemetry), not a wall around a compromised server.
• A nerd reached over ssh is trusted like a local one. What the remote server sends reaches your terminal as it would from a local server.
• Panes are outside it. A helper started before the sandbox launches every pane. A pane left at Everything and Open keeps your full access to files and the network; its isolation (Isolation…) narrows that with a Seatbelt profile of its own, a proxy for Only these providers, or another account. An agent's own Seatbelt sandbox cannot run inside an isolated pane.
• open is outside it. Opening a file or link "the way the system would", and opening a new terminal window, go through LaunchServices, which starts those programs outside the sandbox.
• A sandbox that fails to start does not stop the server. The failure is written to daemon.log, shown by nerd --list, and shown in the window of every client that attaches.
• The .sha256 proves integrity, not origin. It comes from the same release as the archive, so it catches a damaged or truncated download, not a release replaced by someone who can replace both. The installer refuses an archive without one unless NERD_INSTALL_UNVERIFIED=1 is set.
• Both ends check the other's user on every connection. The server talks only to processes of its own user, and a client refuses a server socket another user created first, for example at a NERD_SOCKET in a shared directory, before it sends anything. Such a socket still keeps nerd from starting there: keep NERD_SOCKET in a directory only you can write.