buildwithnexus

Installation

Get buildwithnexus running in seconds. It's a single ~2.3 MB static binary written in Rust — no Python, no Docker, no async runtime, just a fast coding agent in your terminal.

Quick Start

npm install -g buildwithnexus
buildwithnexus

The first run walks you through a short setup: pick remote or local models, add a key (or auto-detect models already on your machine), choose a model, and set a permission mode. After that, buildwithnexus (or the shorter bwn) drops you into the interactive REPL.

npm version

Requirements

Requirement
Details
Node.js
≥ 18 (only used by the npm installer)
A model
A remote API key or a local model (Ollama, llama.cpp, LM Studio)
Cargo
Optional — only if you build from source

The binary itself has no runtime dependency on Node. The npm package simply downloads and verifies the prebuilt static binary for your platform.

Installation Methods

npm (Recommended)

npm install -g buildwithnexus

This fetches the prebuilt static binary for your platform and verifies it against a published SHA-256 checksum before installing. Two commands land on your PATH:

Primary
buildwithnexus
The full command name.
Alias
bwn
A short alias for the same binary.

From Source (cargo)

If you have a Rust toolchain, you can build the binary yourself:

git clone https://github.com/Garretts-Apps/buildwithnexus.git
cd buildwithnexus
cargo build --release
./target/release/buildwithnexus

The result is a self-contained static binary with just 4 runtime dependencies — copy it anywhere on your PATH.

First-Run Onboarding

The first time you launch buildwithnexus, an interactive setup gets you to a working agent in a few prompts:

1
Remote or local
Choose models served over an API, or models running on your own machine.
2
Connect a model
Paste an API key for a remote provider, or let setup auto-detect local models by scanning the Ollama API and your GGUF folder.
3
Pick a model
Select the specific model you want the agent to use.
4
Choose a permission mode
ask (default — confirm each change), auto, or readonly.

Built-in providers

buildwithnexus ships with 8 providers across two wire protocols — the Anthropic Messages API and the OpenAI chat-completions API (which also covers the rest).

Remote · API key
Anthropic · OpenAI · OpenRouter · Groq · Hugging Face
Local · auto-detected
Ollama · llama.cpp server · LM Studio

Where Things Live

Configuration and state live under ~/.buildwithnexus/:

~/.buildwithnexus/
  config.json      # settings (selected model, permission mode, ...)
  .env.keys        # API keys, stored at 0600
  history          # REPL command history
  sessions/        # saved transcripts of every run
  models/          # local model metadata
  settings.json    # user-level lifecycle hooks
  trusted.json     # folders you've trusted for project hooks

API keys are written to .env.keys with 0600 permissions. They're never sent to a non-HTTPS endpoint, and key-like tokens are redacted from surfaced errors. You can also supply a key via environment variable, e.g. export ANTHROPIC_API_KEY=....

Verify Installation

buildwithnexus --version
buildwithnexus --help

Uninstall

npm uninstall -g buildwithnexus
rm -rf ~/.buildwithnexus

Troubleshooting

"Command not found: buildwithnexus"

Make sure npm global bins are on your PATH:

npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"

No models available

If setup can't find a model, either add a remote API key, or start a local server (Ollama, llama.cpp, or LM Studio) and re-run setup so it can auto-detect it. You can re-run the onboarding any time from the REPL with /init.

Checksum mismatch on install

The installer verifies the downloaded binary against a published SHA-256 checksum and refuses to install on a mismatch. Clear your npm cache (npm cache clean --force) and reinstall; if it persists, open an issue on GitHub.

Source