nbox

Terminal UI and CLI for NetBox: fast search, IPAM lookups, and device context.

nbox answers the questions you ask at the terminal (what is this IP, where is this device, what owns this prefix) from the shell, a k9s-style TUI, or an MCP server for AI agents. It is one static binary against NetBox 4.2+. Reads are the default; a small set of safe writes (reserve an IP or prefix, set a status or description, add or remove a tag) runs plan-first behind --allow-writes and a confirmation. nbox is pre-1.0.

Documentation · Install · Releases · Changelog

Quick start

cargo install nbox                    # or: brew install lance0/tap/nbox
nbox                                  # first run: guided setup, then the TUI; press ? for keys

Or set up a profile from the shell and look things up directly:

nbox profile add work https://netbox.example.com --token-env NETBOX_TOKEN
nbox profile use work
export NETBOX_TOKEN=...

nbox search edge01                    # ranked search across every object type
nbox ip 10.44.208.55                  # address, parent prefix, VLAN, scope
nbox device edge01 --json             # device, interfaces, IPs, cables, VLANs
nbox next-prefix 10.0.0.0/8 --length 26

What it does

Task	Command or guide
What is this IP?	nbox ip 10.44.208.55: the address, its most-specific parent prefix (VRF-scoped), that prefix's VLAN and scope. --vrf when the address is in several VRFs.
Where is this device, and what's on it?	nbox device edge01: interfaces, IPs, cables, VLANs, and services in one lookup. nbox interface edge01 xe-0/0/1 traces the cable path A↔Z.
Find something by name	nbox search edge: one ranked, deduped query across devices, IPs, prefixes, VLANs, circuits, VMs, and more, with --site/--tenant/--tag/--vrf filters.
Find the next free address or block	nbox next-ip 10.44.208.0/24 --count 4, nbox next-prefix 10.0.0.0/8 --length 26 (read-only). Claim one with nbox ip reserve / nbox prefix reserve.
Pull data into a script	--json, --fields, --envelope, -o csv, stable exit codes. Scripting
Export for other tools	nbox export prometheus-sd, address-list, device-inventory. Structured exports
Browse interactively	The TUI: navigation rail, live preview, prefix tree, dashboard, cross-object jumps, twelve themes. Keybindings
Change something safely	--dry-run previews a plan; --allow-writes --confirm applies it. Features · ADR-0001

Every command and flag is in the CLI reference. For when to use nbox versus the NetBox web UI, curl, or pynetbox, see the comparison.

For agents

nbox serve is an MCP server, read-only by default. It returns the same JSON view models the CLI prints, through eleven read tools and an nbox://{kind}/{ref} resource template. As a static binary it is MCP-ready in about 9 ms (benchmarks).

claude mcp add nbox -e NBOX_TOKEN=nbt_xxx.yyy -- nbox serve
nbox serve --print-config             # mcpServers JSON for other hosts

Writes over MCP are opt-in: --local-writes for a local stdio host using your profile token, or --allow-writes over HTTP/OIDC with a per-user token vault. For a shared multi-user server, --netbox-token-passthrough forwards each caller's own NetBox token, so NetBox permissions apply per user. Host setup, tools, transports, and the security model are in docs/MCP.md. Agents driving the CLI directly should read AGENTS.md; SKILL.md is an installable Agent Skill.

Install

The installation guide covers every channel, build features, shell completions, and man pages.

• Cargo: cargo install nbox (Rust 1.88+)
• Homebrew (macOS, Linux): brew install lance0/tap/nbox
• Install script (Linux, macOS): curl -fsSL https://raw.githubusercontent.com/lance0/nbox/master/scripts/install.sh | sh (review it first)
• Pre-built binaries: Linux x86_64/ARM64, macOS, and Windows from GitHub Releases, with SHA256SUMS
• Docker: docker run --rm ghcr.io/lance0/nbox:latest --help

Platform support

Release binaries cover Linux (x86_64, ARM64), macOS (Apple Silicon, Intel), and Windows x86_64; the GHCR image is amd64/arm64. nbox needs NetBox 4.2+ and is verified through 4.6. It adapts to API differences between releases at runtime; see compatibility.

Documentation

Start with the documentation index, or go directly to your task:

Task	Guide
Install and set up	Installation · Configuration · Tokens
Use the TUI	Keybindings · Config modal · Themes
Script or automate	Scripting · CLI reference · AGENTS.md
Connect an AI agent	MCP server
Troubleshoot	Troubleshooting · Known issues
Compare with other tools	Comparison (NetBox web UI, curl, pynetbox)
Understand internals or contribute	Architecture · ADRs · CI · Contributing · Roadmap · Security

License

Licensed under either of MIT or Apache-2.0 at your option.