netbird-embed-rs

Rust bindings for NetBird's client/embed package via Go C-shared FFI.

Embeds a full NetBird node (WireGuard mesh networking) into any Rust application — no separate VPN client needed.

Requirements

• Rust ≥ 1.85
• Go ≥ 1.25 (builds the C-shared library automatically via build.rs)

Cross-platform support

The core API works on all platforms (Linux, macOS, Windows). Direct mesh sockets (dial/listen/listen_udp) require Unix (socketpair-based). On Windows, use start_proxy to get a localhost port forwarding to a mesh peer.

Usage

Add to your Cargo.toml:

[dependencies]
netbird-embed = "0.3"

Connect and query peers

use netbird_embed::{Client, ClientOptions, ConnectionState};

let client = Client::new(ClientOptions {
    setup_key: Some("YOUR-SETUP-KEY".into()),
    management_url: Some("https://api.netbird.io".into()),
    device_name: Some("my-app".into()),
    ..Default::default()
})?;

client.start()?;

let status = client.status()?;
println!("Overlay IP: {}", status.ip);

for peer in client.peers()? {
    if peer.is_connected() {
        println!("{} ({})", peer.fqdn, peer.ip);
    }
}

Proxy to a peer (cross-platform)

// Forward localhost:random → peer's 10.200.0.1:8080 through the mesh
let port = client.start_proxy("10.200.0.1:8080")?;
let stream = std::net::TcpStream::connect(("127.0.0.1", port))?;

// Expose a local service on the mesh (reverse proxy)
client.start_reverse_proxy(9000, "127.0.0.1:8080")?;

Direct mesh sockets (Unix only)

// Dial a peer — returns a UnixStream (socketpair)
let stream = client.dial("tcp", "10.200.0.1:8080")?;

// Listen on the mesh — returns a Listener that yields UnixStreams
let listener = client.listen(":8080")?;
let conn = listener.accept()?;

// UDP datagrams
let sock = client.listen_udp(":9000")?;

The client is automatically stopped and freed on drop.

API

Architecture

┌─────────────────────────────┐
│  Your Rust application      │
│  ┌───────────────────────┐  │
│  │ netbird-embed (safe)  │  │
│  │  Client, Status, Peer │  │
│  └──────────┬────────────┘  │
│  ┌──────────▼────────────┐  │
│  │ FFI layer             │  │
│  │  extern "C" bindings  │  │
│  └──────────┬────────────┘  │
└─────────────┼───────────────┘
              │ integer handles + caller buffers
┌─────────────▼───────────────┐
│ libnetbird_embed.so (Go)    │
│  C-exported wrappers        │
│  └─► netbird/client/embed   │
│       └─► wireguard-go      │
└─────────────────────────────┘

Key design decisions:

• Integer handles — Go GC manages real objects. Rust holds an i32 handle. No Go pointers cross FFI.
• Caller-provided buffers — Status/peers returned as JSON into Rust-allocated buffers. Returns ERANGE if too small; caller retries with larger buffer (handled automatically).
• Socketpair for connections — dial() creates a Unix socketpair. Go pumps data between the mesh connection and one end; Rust gets the other as a UnixStream.
• Proxy for cross-platform — start_proxy() / start_reverse_proxy() use Go's own net.Listen on localhost, avoiding platform-specific socketpair APIs.
• No callbacks — Status is polled. Avoids cross-runtime threading complexity.

Building

# Build (Go C-shared library is compiled automatically by build.rs)
cargo build

# Run the example
NB_SETUP_KEY=your-key NB_MANAGEMENT_URL=https://api.netbird.io cargo run --example connect

Cross-compilation

build.rs detects the Rust target and sets GOOS/GOARCH accordingly. For Windows cross-compilation, set CC to a MinGW-w64 compiler:

CC=x86_64-w64-mingw32-gcc cargo build --target x86_64-pc-windows-gnu

Gotchas

License

BSD-3-Clause (matching NetBird's client license)