Stage 1 • Setup Environment

Get Started with NSB

Install NSB and prepare your environment in just a few minutes. Pick your platform, install dependencies, build from source, and verify each step before moving on.

Continue to Quickstart Browse Documentation

Estimated time: 10–15 minutesmacOS • Linux • Windows (WSL2)

How NSB Connects

Application

NSB

(Daemon)

Network
Simulator

NSB (Network Simulation Bridge) is open-source middleware that connects real applications to network simulators. It lets your application send and receive messages through a simulated network without changing your application code.

Learn more in the docs →

What You'll Need

The following packages must be installed before building NSB. Also requires Python 3.7+ or a C++17 compiler.

Package

Purpose

CMake

Configure and build the project

pkg-config

Package configuration (required on macOS)

Protobuf

Message serialization

Redis

In-memory storage of payloads via Redis server

Abseil

Required for Protobuf support and logging

yaml-cpp

Parses YAML configuration files

hiredis

C client library to connect to the Redis server

If you have a previous installation of gRPC (which bundles Protobuf), conflicting Protobuf versions may cause build errors. Use the platform-specific instructions below to manage this.

Installation

Choose your platform and follow the steps.

Install Dependencies

Install all prerequisites in a single command using Homebrew.

bash

brew install cmake pkg-config abseil protobuf yaml-cpp redis hiredis

Clone and Build NSB

Clone the repository, create the build directory, and configure with CMake.

bash

git clone https://github.com/nsb-ucsc/nsb_beta.git
cd nsb_beta

Create the build directory at the top level of the project:

bash

mkdir build

Your directory should now look like:

text

nsb/
├── build/
├── proto/
├── python/
├── cpp/
├── CMakeLists.txt
├── config.yaml
└── README.md

bash

cd build
cmake ..
cmake --build . --parallel

For a clean rebuild instead, use cmake --build . --clean-first.

Expected output

text

[cmake] -- Checking target libraries:
[cmake] -- ✓ Found target: yaml-cpp::yaml-cpp
[cmake] -- ✓ Found target: protobuf::libprotobuf
[cmake] -- ✓ Found target: absl::base
[cmake] -- ✓ Found target: absl::log
[cmake] -- ✓ Found target: absl::time
[cmake] -- ✓ Found target: absl::log_internal_check_op
[cmake] -- ✓ Found target: absl::log_initialize
[cmake] -- ✓ Found target: PkgConfig::hiredis

Install NSB

Install the compiled library, headers, and daemon binary.

bash

cmake --install .

Installed to:

Type

Location

Library

[install_path]/nsb/lib/libnsb.*

Headers

[install_path]/nsb/include/

NSB Daemon

[install_path]/nsb/bin/nsb_daemon

pkg-config

[install_path]/lib/pkgconfig/nsb.pc

Python Setup

Install the Python client library in development mode.

bash

cd python/
pip install -r requirements.txt
pip install -e .
echo 'export PYTHONPATH="${PYTHONPATH}:/.../nsb/python"' >> ~/.zshrc

Verify Installation

Confirm the daemon binary and Python proto bindings both load correctly.

bash

/[your/install/path]/nsb/bin/nsb_daemon --help

Test the Python proto bindings:

python

python3 - <<'EOF'
import proto.nsb_pb2 as nsb_pb2
print("NSB Python proto loaded from:", nsb_pb2.__file__)
EOF

Expected: prints the proto file path without error.

Success Checkpoint

Confirm all steps before continuing to the Quickstart.

Dependencies installed without errors

Build successful — all targets found

Installation completed — NSB daemon ready

Verification passed — Python proto loads

Common Issues

The most frequently encountered problems during installation.

cmake says "could not find Protobuf"

CMake cannot locate Protobuf. Verify the required version is installed and rebuild your project configuration.

View solution

gRPC / Protobuf version conflict

Older gRPC installations may introduce conflicting Protobuf headers. Remove previous installations and rebuild.

View solution

Python proto import fails

Generated Python proto bindings are not being discovered. Verify your PYTHONPATH and generated files.

View solution

NSB

nsb_daemon: command not found

The daemon binary is not available from your current shell. Use the installation path or update PATH.

View solution

Ready for your first simulation?

Continue to Quickstart

Launch NSB, start a mock simulator, and send your first message in under 10 minutes.

Start Quickstart