buildwithnexus

buildwithnexus Security

buildwithnexus is a single static binary that runs entirely on your machine. There is no server, no daemon, and no account. The security model is the security model of a local CLI: keep your keys safe, keep the agent confined to the project you point it at, and never let an automated run do something destructive without a human in the loop.

The model at a glance

Key storage
API keys live in ~/.buildwithnexus/.env.keys at 0600, or come from the environment. Never transmitted except to your chosen provider over HTTPS.
Filesystem confinement
File tools (read, write, edit, list) are confined to the working directory. Paths that escape the project are rejected.
Confirmation gates
Mutating tools ask before acting. Sensitive paths and catastrophic commands still require confirmation even in auto mode.
Deny-only hooks
Project hooks run only after you trust the folder, and can deny a tool call. They can never silently grant one.

Where your keys live

API keys for remote providers (Anthropic, OpenAI, OpenRouter, Groq, Hugging Face) are stored on disk in your home directory, not in the project, and not on any server.

Property
Value
Location
~/.buildwithnexus/.env.keys
Permissions
0600 — owner read/write only
Environment override
Set ANTHROPIC_API_KEY, OPENAI_API_KEY, etc. to skip the file entirely
Transmission
Sent only to the provider you configured, only over HTTPS
In errors & output
Key-like tokens are redacted from surfaced error messages

If you prefer to keep keys out of any file, export them in your shell — environment variables take precedence over .env.keys:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

buildwithnexus

Local providers (Ollama, llama.cpp server, LM Studio) need no key at all. They are detected automatically at setup and run on your own hardware, so nothing leaves the machine.

Filesystem confinement

The agent's file tools — read_file, list_dir, write_file, edit_file — are scoped to the working directory you launched in. A path that resolves outside the project tree is rejected before the tool runs. The agent cannot wander up into your home directory, read unrelated repositories, or write files outside the folder you handed it.

Permission modes

Every run operates under one of three permission modes. The default, ask, puts a human in the loop before anything changes.

Mode
Behavior
ask
Default. Prompts for confirmation before each mutating tool call (writes, edits, commands).
auto
Runs mutating tools without prompting — except for sensitive paths and catastrophic commands, which always require confirmation.
readonly
No writes, edits, or commands. The agent can read and plan but cannot change anything on disk.

What stays gated, even in auto

auto mode is a convenience, not a blank check. Two classes of action always pause for a human:

Sensitive paths
Touching ~/.ssh, .env files, *.pem keys, or the buildwithnexus key store requires explicit confirmation regardless of mode.
Catastrophic commands
Commands that could wipe data or do irreversible damage are flagged and held for confirmation even when auto mode would otherwise run them.

Hooks: trusted, and deny-only

buildwithnexus supports Claude-Code-compatible lifecycle hooks — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, and SessionEnd — configured in settings.json:

Scope
File
User
~/.buildwithnexus/settings.json
Project
.buildwithnexus/settings.json

Because a project's hooks ship inside a repository you may have just cloned, they are treated as untrusted code. Project hooks run only after you explicitly trust the folder (tracked in ~/.buildwithnexus/trusted.json). Until then they are inert.

Even once trusted, hooks are strictly deny-only. A PreToolUse hook can block a tool call — by exiting with code 2, or by returning a JSON permissionDecision of deny — but it can never grant a permission the user hasn't. A hook can tighten the policy; it can never loosen it.

// .buildwithnexus/settings.json — deny edits to the lockfile
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "edit_file",
        "command": "test \"$TOOL_INPUT_PATH\" != \"package-lock.json\""
        // non-zero / exit 2 -> the edit is denied
      }
    ]
  }
}

Network behavior

There is no listening socket, no localhost server, and no background process. The only outbound traffic is the request to the model provider you configured:

Your prompt & project files (local)
↓  HTTPS only — keyed providers refuse non-HTTPS endpoints
Remote provider API (Anthropic / OpenAI / OpenRouter / Groq / HF)
— or —
Local model on your machine (Ollama / llama.cpp / LM Studio) — nothing leaves

API keys are never sent to a non-HTTPS endpoint. If you point a keyed provider at a plaintext URL, the request is refused rather than leaking the credential.

Where data lives on disk

Everything buildwithnexus writes stays under ~/.buildwithnexus/. Session transcripts are plain files you own — they are not uploaded anywhere.

Path
Contents
.env.keys
Provider API keys, mode 0600
config.json
Default provider, model, and permission settings
settings.json
User-scope lifecycle hooks
trusted.json
Folders you have trusted to run project hooks
sessions/
Saved run transcripts (continue, resume)
models/
Detected local model metadata
history
REPL command history

Practical guidance

Keep ask mode for unfamiliar work
Reserve auto for tasks you understand and trust; use readonly when you only want analysis.
Never commit your keys
Keep .env.keys out of version control, or use environment variables on shared machines.
Trust folders deliberately
Only trust a project to run its hooks once you have looked at its .buildwithnexus/settings.json.
Go fully local when needed
For sensitive code, point buildwithnexus at a local model — no prompt or file ever leaves your machine.

Reporting a vulnerability

If you find a security issue, please do not open a public issue. Report it privately through the repository's security policy at github.com/Garretts-Apps/buildwithnexus so it can be fixed before disclosure. buildwithnexus is open source under the MIT license.