buildwithnexusv0.21.0
Menu

What leaves your machine

buildwithnexus has no account, no telemetry and no analytics. It talks to the model provider you chose and checks the npm registry for a new version at most once a day. It contacts other hosts only when you attach a page with @url: or @web:, or when a tool, a hook or an MCP server you set up needs them. The npm launcher downloads the binary from GitHub once per version. This page lists what bwn sends where, what stays on your machine, and how to keep everything local.

What is sent to the provider

Every model request carries the conversation so far. The remote providers are Anthropic, OpenAI, OpenRouter, Groq, Hugging Face, and any gateway you set as base_url. With any of them, bwn sends all of the following to the provider:

Helper agents, /compact summaries, /review and /commit drafts use the same provider. The provider's terms, not bwn, decide what happens to the data there, such as retention or training. bwn sends nothing else. It sends no machine identifier, usage statistics or crash reports.

Your API key

When you enter a key at setup, with /model or with /login, bwn saves it in ~/.buildwithnexus/.env.keys, and only you can read that file. It has mode 0600 on Linux and macOS, and on Windows bwn uses icacls to restrict it to your user. An environment variable such as ANTHROPIC_API_KEY overrides the stored key. bwn sends a key only to its provider, and only over HTTPS or to a loopback address. It does not follow redirects, so the key never reaches another host. bwn removes key-like strings from the error messages it shows.

bwn saves a key for an OpenAI-compatible endpoint, such as a gateway or a local server, for that endpoint only. It goes in the same file, under the name CUSTOM_API_KEY@<scheme://host[:port]>, and bwn never sends it to another address. A CUSTOM_API_KEY set in the environment goes only to the first custom endpoint bwn uses in that run. A saved key that names no endpoint is tied to the custom endpoint in your own settings. If your own settings name no custom endpoint, bwn keeps the key unused until you say which endpoint it belongs to.

Commands the agent runs inside the sandbox do not inherit your API keys. bwn removes HF_TOKEN and every variable ending in _API_KEY, _API_TOKEN, _TOKEN, _SECRET, _SECRETS or _PASSWORD, and every AWS_* variable, from every command the agent runs, sandboxed or not, and from every MCP server bwn starts over stdio. A server's own env entry still sets what it needs. An approved env therefore cannot put a key into the conversation. List what a build needs, such as GITHUB_TOKEN or AWS_PROFILE, in shell_env_passthrough to keep it. Hooks keep their environment.

What stays on your machine

bwn stores everything under ~/.buildwithnexus (or NEXUS_HOME). Some of these files go into the system prompt, as listed above. A skill's text goes to the provider when the agent loads the skill, and a command's text when you run the command. Each key and sign-in token goes only to its own server. bwn uploads nothing else from this folder:

PathWhat it holds
.env.keysAPI keys (see above)
settings.jsonYour settings and "always allow" answers, per project
sessions/Every conversation, so /resume can reopen it. Each file is JSON Lines. See Session files.
checkpoints/Copies of files from before each edit, for /undo
traces/Tool calls, hooks and skill loads, for /trace
historyPrompts you typed, for ↑ and Ctrl+R
memory.mdFacts saved with /memory (sent with each prompt, as above)
Agents.md, AGENTS.md, system.mdAgent roles, your own instructions and your own system prompt. All three go into the system prompt, as above. bwn writes a starter Agents.md when none exists. A project's own .buildwithnexus/Agents.md replaces this one.
workflows/Logs of background workflows
mcp-auth/<server>.jsonThe sign-in token of an MCP server you logged in to with mcp login. Only you can read it, and bwn binds it to that server's URL. mcp logout asks the authorization server to revoke it, if that server offers revocation, and deletes the file.
exports/, notices.json, key-checks.jsonConversations written by /export, which upgrade notices bwn has shown, and whether each saved key passed its last check. key-checks.json stores a hash, never the key.
bin/<version>/The binary the npm launcher downloaded

bwn writes pasted images to the system temp directory as bwn-paste-*.png.

Session files

A session is one file, ~/.buildwithnexus/sessions/<id>.json (or under NEXUS_HOME). This is the file a hook receives as transcript_path. Ids are a 16-digit millisecond timestamp, a hyphen, and 8 hex digits. An older id that is only those 16 digits still loads.

The file is JSON Lines, schema 2: one JSON object per line. The example below is broken across lines so it can be read on a phone. An older session that is one JSON object still opens. bwn rewrites it in this layout the first time it saves it. There is no setting that keeps the old format.

{
  "schema_version": 2,
  "id": "…",
  "title": "…",
  "cwd": "…",
  "model": "…",
  "created_ms": 1790000000000,
  "updated_ms": 1790000004211,
  "messages": 4
}
{
  "msg": {
    "System": "…"
  }
}
{
  "msg": {
    "User": "fix parser"
  }
}
{
  "msg": {
    "Assistant": {
      "text": "…",
      "calls": [
        {
          "id": "c1",
          "name": "read_file",
          "input": {
            "path": "src/p.rs"
          }
        }
      ]
    }
  }
}
{
  "msg": {
    "Tool": [
      {
        "id": "c1",
        "content": "…",
        "is_error": false
      }
    ]
  }
}

An older session can be one JSON object whose messages sit in msgs. bwn still lists, exports and resumes those files, and reading one does not change it. The --json event stream is a separate format. Event types, exit codes and the rest of the versioning contract are in VERSIONING.md.

With a local model, nothing goes to a provider

With Ollama, llama.cpp, LM Studio or another server on your machine or your network, the prompts, code and command output go to that server and nowhere else. The only other traffic is in the list below, and you can turn off each item.

Other hosts bwn contacts

WhatHostWhen
fetch_url, headless_browser, wait_for_url, open_browserThe URL's hostWhen the model uses them. Outside auto, bwn asks before it contacts each new host and port. In auto, fetch_url and headless_browser still ask before reaching localhost or a private, CGNAT or unique-local address, unless network.allow names the host.
web_searchlite.duckduckgo.comThe search query, when the model searches. Outside auto, bwn asks first, as it does for a fetch.
@url: and @web: attachmentsThe URL's hostWhen you type @url:<address> or @web:<address> in a prompt. bwn runs curl to fetch the page without asking, follows redirects and gives up after 5 seconds. It sends up to 8,000 characters of the page with your message. network rules do not apply to this fetch.
MCP serversThe servers you configureTool arguments go to the server. A stdio server runs on your machine.
http hooksThe URLs you configurebwn POSTs each matching event to the hook's URL as JSON. A hook from a project's own settings runs only after you trust the folder. network.deny applies, and bwn does not follow redirects.
MCP sign-in (mcp login)The server's authorization serverWhen you run mcp login, which opens the sign-in page in your browser. bwn also contacts the authorization server to refresh a token, and to revoke one when you run mcp logout. Sign-in uses HTTPS only, or plain HTTP to this machine. bwn sends the token only to the server it was saved for, in the Authorization header. Headless runs never open a browser.
screenshot_urlA page on this machine, in a local Chrome, Chromium or EdgeFor models that take images. The browser runs headless with a throwaway profile and no provider keys. A proxy inside bwn refuses every other request the browser makes. The tool opens a page on another host only if network.allow or an allow rule names that host. The picture goes to the model provider.
Update checkregistry.npmjs.orgA version lookup, at most once a day. "auto_update": "off" stops it. BWN_UPDATE_REGISTRY or npm_config_registry points it at a mirror.
First-run downloadgithub.com, and the *.githubusercontent.com host it redirects toOnce per version, the npm launcher downloads the binary and verifies its checksum. Outside a terminal it downloads only with bwn --bootstrap or BWN_ALLOW_BOOTSTRAP=1. BWN_SKIP_INSTALL=1 turns the download off.

If pdftotext from poppler is installed, read_file runs it on your machine to read a PDF. buildwithnexus acp starts only when an editor launches it, and it talks to that editor on stdin and stdout. Permission modes, rules, hooks, folder trust and the sandbox apply there as they do in the terminal.

Commands you approve run with your permissions and can reach the network themselves, for example git push, npm install or curl. In ask mode you see the whole command first. The sandbox defaults to auto. With it on, "sandbox_network": false cuts off their network access. Command hooks run on your machine, outside the sandbox, so sandbox_network does not limit them. An http hook sends its event to its URL, as the table above shows.

bwn sends its own requests through the proxy that HTTPS_PROXY, HTTP_PROXY or ALL_PROXY names and skips it for hosts that NO_PROXY matches. It always reaches loopback addresses directly. It also connects directly to private network addresses, such as 10.x, 192.168.x, link-local and tailnet addresses, and to host names that resolve only to them, unless you set BWN_PROXY_PRIVATE=1. The npm launcher's first-run download uses HTTPS_PROXY and NO_PROXY too, on Node 18 and later.

Keeping everything local

{
  "auto_update": "off",
  "network": { "deny": ["*"] }
}

For IT and security reviews, the IT and security guide lists the processes bwn starts, the hosts it connects to and the files it writes.