Install

Installing takes one command, and nothing runs during npm install. The first launch downloads the binary for your platform, verifies its checksum, and starts setup.

You need Node.js 18 or later, plus either an API key (Anthropic, OpenAI, OpenRouter, Groq or Hugging Face) or a local model server such as Ollama.

npm install -g buildwithnexus
bwn                   # or the full name: buildwithnexus

First run

The first time you run bwn in a terminal, setup asks you to choose a provider, a model, and a permission mode. For the provider, paste a key or pick a local server. Before it saves anything, setup sends the model a one-token request. For Ollama it only checks that the model is installed, because a request could take minutes to load a large model. After the check, setup saves your choices to ~/.buildwithnexus/. Then describe a task, as the Quickstart shows. To change these choices later, run bwn init, or switch models mid-session with /model. Data & privacy lists what bwn sends to a remote provider and what stays on your machine.

Without a terminal, as in CI or docker run without -t, nobody can answer setup. A headless run such as bwn run "<task>" then uses the provider from --provider or the first API key in the environment, for example ANTHROPIC_API_KEY, and saves nothing. Plain bwn, with or without a task, runs setup instead. When stdin is empty, as in CI, setup prints the provider menu and reads no answer. It then saves nothing and exits with code 1.

If you use LM Studio, llama.cpp or another OpenAI-compatible server, start it before you run setup. Setup then lists the models it serves.

To upgrade later, run buildwithnexus update or npm install -g buildwithnexus@latest.

Try it in a sandbox

There are two ways to try buildwithnexus where it cannot reach the files on your machine.

GitHub Codespaces. Open a codespace on the repo to run it in your browser. The devcontainer preinstalls the binary, so run bwn when the terminal appears. To talk to a remote model, add ANTHROPIC_API_KEY or OPENAI_API_KEY as a Codespaces secret, or export it in the terminal.

Docker. This runs locally in a scratch container that Docker deletes on exit, so nothing the agent does can reach your files:

docker run -it --rm -e BWN_ALLOW_BOOTSTRAP=1 -e ANTHROPIC_API_KEY \
  node:22-slim npx -y buildwithnexus

Drop --rm to keep the sandbox between runs. To let it work on a real project, add -v "$PWD":/work -w /work, which mounts the current directory as the container's working directory.

Requirements

On Windows, clipboard image paste, background-server control and API-key file permissions (via icacls) work natively. Hook scripts run through PowerShell, cmd, Python or Git Bash. Ctrl+Break and closing the console restore the terminal. On Windows, bwn also picks up .ps1, .cmd and .bat scripts in ~/.buildwithnexus/hooks/<Event>/ without a settings.json entry. Two things are still missing on Windows. bwn runs background servers there as plain processes instead of in tmux. The sandbox has no backend on Windows, and it has none inside WSL either.

Auto-updates

By default buildwithnexus tells you about updates and never installs them. At most once a day, a background check asks the npm registry for the latest version. When a newer one exists, the next launch prints a one-line notice that tells you to run buildwithnexus update. Startup never waits on the network. Set the auto_update policy in ~/.buildwithnexus/settings.json:

{ "auto_update": "notify" }       // default: check daily, print a notice, never install
{ "auto_update": "install" }      // check daily, silently npm install -g patch releases, announce a new minor or major
{ "auto_update": "install-any" }  // check daily and silently npm install -g any newer release
{ "auto_update": "off" }          // no checks, no notices

BWN_NO_AUTO_UPDATE=1 still works and caps "install" and "install-any" back to "notify". bwn never auto-updates cargo and source installs, because both install policies apply only when npm installed the binary. Headless runs never check. BWN_UPDATE_REGISTRY, or else the npm_config_registry environment variable, points the check at a mirror. bwn does not read the registry from .npmrc.

New in 0.15. "install" installs only patch releases within your minor version and announces a new minor or major release. "install-any" installs any newer release, as "install" did before 0.15. When a newer release exists and npm installed bwn, buildwithnexus update installs it with npm install -g. For any other install it prints the release download link and the npm and cargo commands, then exits with code 10. When bwn is already current, it prints up to date and exits with code 0. buildwithnexus update --check only reports, and exits with code 10 when a newer release exists. See What's new in 0.15.

Package security

The npm package is built to pass supply-chain scanners without warnings:

• It has no install scripts, so nothing runs during npm install.
• No bundled sources or blobs. The main package is about 40 KB of readable JavaScript. The binary is not in the tarball. On first run the launcher downloads the binary for your os/cpu and verifies its checksum. It saves the binary in ~/.buildwithnexus/bin/<version>/, or in $NEXUS_HOME/bin/<version>/ when NEXUS_HOME is an absolute path. Both are outside the npm package, so an npm update does not delete the binary. BWN_INSTALL_IN_PACKAGE=1 keeps it inside the package, as before 0.15. If your home directory is mounted noexec, set NEXUS_HOME to an absolute path on a filesystem that can run programs. Nothing is installed from buildwithnexus-<os>-<cpu> packages.
• Verified binaries. Every release binary carries a build-provenance attestation that ties it to the exact GitHub Actions run that built it. The attestation is the primary integrity control, and gh attestation verify checks it. Each binary also has a .sha256 file that detects corruption in transit. The launcher checks the download against checksums.json in the npm package instead. The publish workflow writes that file only after it checks each binary's attestation, so the launcher refuses a binary that someone replaced on the release after publishing.
• The package has no eval calls and no minified code. Update checks run inside the CLI itself, not in the npm package.
• Consent-gated first-run download. The launcher downloads the binary from the GitHub release and verifies its checksum. On a TTY it does this automatically, because installing the package counts as your consent. In non-interactive environments such as CI and pipes, it downloads only with bwn --bootstrap or BWN_ALLOW_BOOTSTRAP=1. Nothing downloads during npm install. The launcher always consumes --bootstrap; to pass the literal text to a task, put it after --.
• The launcher runs the new binary once before it reports that the binary is ready. If the binary cannot run, the launcher says why and what to do instead. Causes include glibc older than 2.34, a musl/Alpine system, and endpoint protection that blocks the binary.

Managed and corporate machines

Endpoint protection such as CrowdStrike Falcon or Microsoft Defender may block or quarantine the Windows binary. The binary is new and has few installs. The launcher also downloads it on first run and then runs it. That is the same pattern a malware loader follows, even though the launcher verifies the download's checksum. The file itself matches its release checksum and attestation, so ask IT to allowlist it.

• Identifiable binary. The Windows .exe carries a version resource that names the product buildwithnexus and the original file name buildwithnexus.exe. It also carries an asInvoker manifest, so it never asks for elevation.
• SBOM. Every release includes buildwithnexus.cdx.json, a CycloneDX list of every crate compiled in.
• Code signing. The project is setting up Authenticode signing through the SignPath Foundation. Get-AuthenticodeSignature buildwithnexus.exe shows whether a file is signed.
• Blocked binary. When endpoint protection blocks or removes the binary, the launcher prints its path and SHA-256, names the security product it finds, and does not download it again on its own.
• Fixed location. IT can place a verified binary in a fixed path and set BWN_BIN to it, with BWN_SKIP_INSTALL=1 so nothing downloads into the user profile.

The IT and security guide lists what bwn launches, which hosts it connects to and which files it writes. It also explains how to allowlist bwn by hash, signer or path, and includes a request you can send to your IT team.

cargo install

With Rust 1.94 or later and a C compiler, install from crates.io. API docs are on docs.rs.

cargo install buildwithnexus --locked   # installs `buildwithnexus` and the `bwn` alias
bwn --version

--locked builds with the exact dependency versions the release was tested with, because the lockfile ships in the crate. The bwn crate installs only the short name. Install it instead of buildwithnexus, not in addition, because cargo refuses a second crate that provides the same bwn binary.

Build from source

git clone https://github.com/Garretts-Apps/buildwithnexus
cd buildwithnexus
cargo build --release --manifest-path harness/Cargo.toml

Next: Quickstart →