gRPC Daemon Socket

Updated August 1, 2026

The NetBird daemon exposes a local gRPC API that the NetBird CLI and desktop app use. Your integration can use the same socket to check status, manage the connection, inspect configuration, work with profiles and networks, and call other local daemon operations.

The gRPC socket is the primary local daemon API. If your integration cannot use gRPC or generated Protocol Buffer bindings, use the HTTP/JSON daemon socket instead.

Default Addresses

The HTTP/JSON gateway is optional. The gRPC socket is available whenever the NetBird daemon is running.

On Windows the daemon serves a named pipe. Which path that is depends on what the daemon may create: running as a service or elevated it serves \\.\pipe\ProtectedPrefix\Administrators\netbird, a namespace only administrators can create in, and otherwise it falls back to \\.\pipe\netbird. Clients try both and check who owns the pipe before using the plain name, so passing npipe://netbird is enough. Windows installations that predate the named pipe are migrated from tcp://127.0.0.1:41731 automatically.

On Linux installations that use an instance-specific systemd service, the socket can instead be under /var/run/netbird/<instance>.sock. The NetBird CLI automatically uses the only socket in that directory when the default socket does not exist. If multiple instance sockets exist, pass the intended address explicitly with --daemon-addr.

You can see the address option in the CLI help:

netbird --help

Configure the Address

Use the global --daemon-addr option when installing or reconfiguring the service. The address must use one of these formats:

unix:///path/to/netbird.sock
tcp://host:port
npipe://name

Use a Custom Unix Socket

sudo netbird service reconfigure \
  --daemon-addr unix:///var/run/netbird-integration-grpc.sock

The parent directory must already exist and be writable by the NetBird service. If you use a dedicated directory to restrict access, configure systemd or tmpfiles to recreate it securely because directories under /run do not persist across reboots.

After changing the socket, pass the same address to NetBird CLI commands that need to contact the daemon:

netbird --daemon-addr unix:///var/run/netbird-integration-grpc.sock status

Use a TCP Socket

sudo netbird service reconfigure \
  --daemon-addr tcp://127.0.0.1:41731

Then specify that address when using the CLI on platforms where it is not the default:

netbird --daemon-addr tcp://127.0.0.1:41731 status

Privileged Operations

On the default sockets any local user can connect, so the daemon authorizes operations by the identity of whoever calls it, read from the kernel rather than supplied by the client: SO_PEERCRED on Linux, LOCAL_PEERCRED on macOS, and the named-pipe client token on Windows. A caller whose identity cannot be established is refused.

Since 0.76.0 the following require root, or an administrator on Windows, because they decide who may obtain a shell on the machine:

Only the direction that creates the capability is guarded. Turning the SSH server or root login off, and re-enabling SSH authentication, are always allowed, and restating a value that is already set is not a change, so an integration that submits a whole settings form does not start failing once an administrator enables SSH.

Removing a profile is not refused. An unprivileged caller removes it locally and the daemon skips the deregistration, which leaves the peer registered on the management server rather than detached from it.

A profile written before the SSH server flag existed counts as having it enabled, because the daemon reads an unset flag the same way the engine does. The management URL and deregistration guards therefore apply on those installations even though nobody enabled SSH explicitly.

A refusal comes back as gRPC PermissionDenied carrying a google.rpc.ErrorInfo detail, so an integration can recognise it without parsing the message:

reason:   PRIVILEGE_REQUIRED
domain:   daemon.netbird.io
metadata: summary = "Enabling the NetBird SSH server requires root."
          command = "sudo netbird down; sudo netbird up --allow-server-ssh"

Render summary and command rather than the raw error: command is the same operation with the privileges it needs, ready to run.

Service Definition

The socket provides daemon.DaemonService. NetBird's client/proto/daemon.proto file lists the available methods, streaming types, and request and response schemas.

Here are a few common methods. Check daemon.proto for the full list.

The service also includes methods that change configuration, profiles, network selection, logging, and other daemon state. Only give socket access to processes that you trust to control the local NetBird client.

Test the Socket with grpcurl

grpcurl is a command-line tool for invoking gRPC methods. Because it needs access to the .proto files to perform requests, we need to download the repository at the same version that the daemon to not have a mismatch on the Protocol Buffer definition.

export NETBIRD_VERSION=v$(netbird version)
git clone --depth 1 \
  --branch "$NETBIRD_VERSION" \
  https://github.com/netbirdio/netbird.git
cd netbird

Run the following examples from the root of the cloned netbird repository.

Query Status Through the Unix Socket

grpcurl \
  -plaintext \
  -unix \
  -import-path ./client/proto \
  -proto daemon.proto \
  -d '{}' \
  unix:///var/run/netbird.sock \
  daemon.DaemonService/Status

To request full peer status, set fields from StatusRequest in the JSON request body:

Sensitive output: Full peer status may contain network topology, endpoint, route, and peer information. Review or redact it before sharing the output.

grpcurl \
  -plaintext \
  -unix \
  -import-path ./client/proto \
  -proto daemon.proto \
  -d '{"getFullPeerStatus": true}' \
  unix:///var/run/netbird.sock \
  daemon.DaemonService/Status

Query Status Through a TCP Socket

This applies to a custom loopback TCP listener, since grpcurl cannot dial a Windows named pipe and the Windows default is therefore not reachable this way. Use a client that can open the pipe, or configure a TCP listener for testing and accept that privileged operations are refused on it:

grpcurl \
  -plaintext \
  -import-path ./client/proto \
  -proto daemon.proto \
  -d '{}' \
  127.0.0.1:41731 \
  daemon.DaemonService/Status

-plaintext is required because the local daemon socket does not use TLS. For a Unix socket, pass the full unix:///... URI and include -unix. The URI form also avoids a Unix-socket regression in some grpcurl 1.9.x builds.

Subscribe to Status Changes

Server-streaming methods remain connected and print each response as it arrives. For example:

grpcurl \
  -plaintext \
  -unix \
  -import-path ./client/proto \
  -proto daemon.proto \
  -d '{}' \
  unix:///var/run/netbird.sock \
  daemon.DaemonService/SubscribeStatus

Press Ctrl+C to end the stream.

Build an Integration

For a long-running integration, generate a gRPC client from the same daemon.proto revision as the installed NetBird client:

1. Download or vendor client/proto/daemon.proto from the NetBird repository.
2. Generate client bindings with the Protocol Buffer and gRPC tools for your language.
3. Create a local gRPC channel to the configured Unix or TCP address without TLS. That does not make the socket safe to expose remotely.
4. Create a daemon.DaemonService client from that channel.
5. Call unary methods or consume server streams using the generated request and response types.

Use a protobuf definition and generated bindings that match your deployed NetBird version. A newer client may call methods or use fields that an older daemon does not support.

The HTTP/JSON gateway exposes this service for environments where generated gRPC clients are unavailable. See HTTP/JSON Daemon Socket for setup and HTTP examples.

Troubleshooting

The Unix Socket Does Not Exist

Check that the service is running:

sudo netbird service status

If you use an instance-specific service, inspect /var/run/netbird/ for its socket or pass the configured address with --daemon-addr.

A Tool Reports That Reflection Is Unsupported

This is expected. Supply daemon.proto with your tool's equivalent of the grpcurl -proto and -import-path options, or use a descriptor set generated from that file.

A Client Receives an Unavailable or Connection-Refused Error

Confirm that the daemon is running and that the integration uses the same socket address as the service. For a Unix socket, also verify access to the socket and each parent directory. For TCP, verify the host and port and ensure the listener remains bound to a trusted interface.

A Call Is Refused With PermissionDenied

The operation is one of the privileged operations and the caller is not root, or not an administrator on Windows. Check the ErrorInfo detail on the error: PRIVILEGE_REQUIRED in domain daemon.netbird.io means the daemon identified the caller and refused the change, rather than failing to reach it. On a TCP socket every such operation is refused, because the transport carries no caller identity.

A Method or Field Is Unimplemented

The integration's generated bindings may be newer than the installed NetBird daemon. Compare the installed client version with the revision of daemon.proto used to generate the bindings, then use a compatible schema or upgrade NetBird.