# 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:

- What you type, and what you attach: `@path` files, `@url:` pages, pasted or dropped images, and the frames and metadata sampled from a video. bwn sends up to 1 MiB of text piped into `bwn run`, `bwn plan` or `bwn brainstorm`, as the task or after it.
- The contents of files the agent reads with `read_file`, the results of `grep_files`, `find_files` and the other search tools, the full text of each skill it loads, and the edits it writes.
- The output of the commands it runs through `run_command` and `check_work`, such as your tests, builds and linters, and the output of MCP tools. A `!cmd` you run yourself, and its output, appear only on your screen.
- What your hooks tell the model. bwn adds the output of a `UserPromptSubmit` hook to your message. bwn adds a `PostToolUse` hook's reason or `additionalContext` to the tool result. When a `Stop` or `SubagentStop` hook asks the agent to go on, bwn sends its reason as the next message.
- Pages the web tools fetched, and search results.
- The system prompt: bwn's own instructions and tool definitions, your own `~/.buildwithnexus/AGENTS.md`, your project's `AGENTS.md` or `CLAUDE.md`, your `system.md`, saved memory (`memory.md`), the agent roles in `Agents.md`, skill names and descriptions, the paths of your working folder and your home folder, and which common tools, such as git, rg and node, are installed, with their versions. It also lists your active hooks, with each one's command, script path or URL. With `--add-dir` or `/add-dir`, it names each added folder and includes the `AGENTS.md` or `CLAUDE.md` at its root.

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](https://buildwithnexus.dev/docs/hooks) 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:

| Path | What it holds |
| --- | --- |
| `.env.keys` | API keys (see above) |
| `settings.json` | Your 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` |
| `history` | Prompts you typed, for ↑ and Ctrl+R |
| `memory.md` | Facts saved with `/memory` (sent with each prompt, as above) |
| `Agents.md`, `AGENTS.md`, `system.md` | Agent 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>.json` | The 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.json` | Conversations 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
      }
    ]
  }
}
```

- The first object is the header. `title` is the first prompt. `name` is present only after `/rename`. `updated_ms` and `messages` (how many message lines follow) are padded with spaces, because bwn updates those two numbers in place when it appends. A JSON parser still reads them as numbers. `bwn sessions` and `/resume` read this line and nothing else.
- Every later line is `{"msg": …}`. The message is `System` or `User` (a string), `UserImages` (`text`, and `images` as media-type and base64 pairs), `Assistant` (`text` and `calls`, each call an `id`, `name` and `input`) or `Tool` (a list of `id`, `content`, `is_error`, and `images` when there are any). Skip a line that has no `msg`. A later version may add other records without a new schema number.
- After each tool round the new lines are appended and flushed to disk before the next request. A last line that is not a whole JSON object is a round that did not finish: drop that line and keep the rest. After a crash, `messages` and `updated_ms` in the header can be one round behind the lines that follow.
- bwn rewrites the whole file when earlier messages change: compaction, `/rewind`, `/rename`, a new model, and the first save of a run, which is also when a schema 1 file is converted.

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](https://github.com/Garretts-Apps/buildwithnexus/blob/main/docs/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

| What | Host | When |
| --- | --- | --- |
| `fetch_url`, `headless_browser`, `wait_for_url`, `open_browser` | The URL's host | When 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_search` | `lite.duckduckgo.com` | The search query, when the model searches. Outside `auto`, bwn asks first, as it does for a fetch. |
| `@url:` and `@web:` attachments | The URL's host | When 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 servers | The servers you configure | Tool arguments go to the server. A stdio server runs on your machine. |
| `http` hooks | The URLs you configure | bwn 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 server | When 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_url` | A page on this machine, in a local Chrome, Chromium or Edge | For 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 check | `registry.npmjs.org` | A 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 download | `github.com`, and the `*.githubusercontent.com` host it redirects to | Once 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

- Use a [local model](https://buildwithnexus.dev/docs/models#local-models).
- Set `"auto_update": "off"` in `~/.buildwithnexus/settings.json`.
- Configure no MCP servers that reach other hosts.
- Don't attach pages with `@url:` or `@web:`.
- Set `"network": {"deny": ["*"]}` to refuse every host for the network tools in every mode.

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

For IT and security reviews, the [IT and security guide](https://github.com/Garretts-Apps/buildwithnexus/blob/main/SECURITY.md#for-it-and-security-teams) lists the processes bwn starts, the hosts it connects to and the files it writes.

MIT licensed · Made by [Garrett Eaglin](https://garretteaglin.com/)
