netbird-docs/src/pages/client/json-socket.mdx

import { Note, Warning } from '@/components/mdx'

export const description =
  'Use the NetBird daemon HTTP/JSON socket to build local integrations in environments where gRPC is unavailable.'

# HTTP/JSON Daemon Socket

The NetBird daemon can expose its local API over HTTP with JSON request and response bodies. A [gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) receives those HTTP/JSON requests and passes them to the daemon's gRPC API.

The daemon's primary local API is documented in [gRPC Daemon Socket](/client/grpc-socket). Use that socket when your integration supports gRPC and generated Protocol Buffer bindings.

Use the JSON socket when your integration cannot use gRPC. For example, it works well in runtimes that only have an HTTP client, local monitoring agents, and application sandboxes where adding a gRPC client and generated protobuf bindings is not practical.

<Note>
  The HTTP/JSON daemon socket requires NetBird client v0.75.0 or later.
</Note>

<Note>
  The HTTP/JSON socket controls the **local NetBird daemon**. It is separate
  from the NetBird Management API and does not replace it.
</Note>

## Enable the JSON Socket

The JSON socket is disabled by default. To enable it while installing the NetBird service, run:

```shell
sudo netbird service install --enable-json-socket
```

The default address is:

```text
unix:///var/run/netbird-http.sock
```

<Warning>
  **Security warning:** The default Unix socket allows read and write access for
  local users. The API exposes control operations as well as status. If you
  require local-user isolation, place a custom socket inside a restricted
  directory and ensure that the directory is recreated securely at boot.
</Warning>

The gateway runs inside the daemon and re-dials it locally, so it reads the identity
of its own HTTP client and forwards it, which is what lets the daemon authorize the
request as that user rather than as the daemon itself. The
[privileged operations](/client/grpc-socket#privileged-operations) therefore behave
the same over HTTP as over gRPC, and a refusal comes back as HTTP 403 with the same
`PRIVILEGE_REQUIRED` detail. Metadata headers reserved for that forwarding are
dropped when a client supplies them.

To enable it on an existing installation, reconfigure the service:

<Warning>
  **Connectivity warning:** Every `netbird service reconfigure` command on this
  page restarts NetBird and can briefly interrupt tunnel connectivity, routes,
  and DNS.
</Warning>

```shell
sudo netbird service reconfigure --enable-json-socket
```

NetBird saves this setting with the service configuration, so it stays enabled after a restart.

### Use a Custom Unix Socket

Pass an address with the `unix://` scheme to change the socket path:

```shell
sudo netbird service reconfigure \
  --enable-json-socket \
  --json-socket unix:///var/run/netbird-integration-http.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.

`--json-socket` configures an HTTP endpoint. Query it with an HTTP client such as `curl`; do not pass this address to `netbird --daemon-addr`.

```shell
curl --silent --show-error \
  --unix-socket /var/run/netbird-integration-http.sock \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --write-out '\n' \
  http://localhost/daemon.DaemonService/Status
```

### Use a TCP Socket

Pass an address with the `tcp://` scheme to expose the gateway over TCP:

```shell
sudo netbird service reconfigure \
  --enable-json-socket \
  --json-socket tcp://127.0.0.1:8080
```

<Warning>
  **Security warning:** The gateway does not add authentication or TLS. Keep TCP
  listeners bound to a trusted interface such as `127.0.0.1` and do not expose
  them to an untrusted network. The API includes operations that can read or
  change the local NetBird daemon's state.

  A TCP connection carries no caller identity, so the gateway cannot tell who is
  calling and every
  [privileged operation](/client/grpc-socket#privileged-operations) is refused on
  such a socket, whoever runs the client.
</Warning>

To disable the gateway again, run:

```shell
sudo netbird service reconfigure --enable-json-socket=false
```

## Make Requests

Each daemon RPC is exposed as an HTTP `POST` endpoint using this path format:

```text
/daemon.DaemonService/<MethodName>
```

Send the request message as JSON with the `Content-Type: application/json` header. If an RPC has no required request fields, send an empty JSON object (`{}`). Responses use the standard [Protocol Buffers JSON mapping](https://protobuf.dev/programming-guides/json/).

### Query Status Through the Unix Socket

With the default socket path:

```shell
curl --silent --show-error \
  --unix-socket /var/run/netbird-http.sock \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --write-out '\n' \
  http://localhost/daemon.DaemonService/Status
```

The response is a JSON representation of the daemon's status response. For example, it includes the daemon status and version:

```json
{
  "status": "Connected",
  "daemonVersion": "..."
}
```

The exact fields and values depend on the client version and current connection state.

### Query Status Through a TCP Socket

If the gateway is listening on `tcp://127.0.0.1:8080`, use a normal HTTP request:

```shell
curl --silent --show-error \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --write-out '\n' \
  http://127.0.0.1:8080/daemon.DaemonService/Status
```

### Call the API from an Integration

The following Python example calls the status endpoint over a Unix socket using only the standard library:

```python
from http import client
from json import dumps, load
from socket import AF_UNIX, SOCK_STREAM, socket


class UnixHTTPConnection(client.HTTPConnection):
    def __init__(self, socket_path):
        super().__init__("localhost")
        self.socket_path = socket_path

    def connect(self):
        self.sock = socket(AF_UNIX, SOCK_STREAM)
        self.sock.connect(self.socket_path)


connection = UnixHTTPConnection("/var/run/netbird-http.sock")
connection.request(
    "POST",
    "/daemon.DaemonService/Status",
    body=dumps({}),
    headers={"Content-Type": "application/json"},
)
response = connection.getresponse()

if response.status != 200:
    raise RuntimeError(f"NetBird returned HTTP {response.status}: {response.read().decode()}")

status = load(response)
print(status["status"])
connection.close()
```

For a TCP listener, any standard HTTP client can call the same path and JSON body without Unix-socket support.

## Map gRPC Methods to HTTP

The gateway exposes every method in `daemon.DaemonService`, and every endpoint uses
`POST`. Add the method name to the service path:

```text
daemon.DaemonService/Status
          ↓
/daemon.DaemonService/Status
```

For example:

| gRPC method    | HTTP endpoint                        |
| -------------- | ------------------------------------ |
| `Status`       | `/daemon.DaemonService/Status`       |
| `GetConfig`    | `/daemon.DaemonService/GetConfig`    |
| `ListNetworks` | `/daemon.DaemonService/ListNetworks` |
| `Up`           | `/daemon.DaemonService/Up`           |
| `Down`         | `/daemon.DaemonService/Down`         |

The [`DaemonService` protobuf definition](https://github.com/netbirdio/netbird/blob/main/client/proto/daemon.proto)
is the complete API reference for method names and request and response schemas.
See [gRPC Daemon Socket](/client/grpc-socket#service-definition) for an overview of
the service and guidance on using the protobuf definition.

### Server-Streaming Methods

Server-streaming RPCs use the same path. The HTTP request stays open and returns
JSON messages until the stream ends or the caller closes the connection. Check the
protobuf definition for streaming methods and their response types.

The gateway exposes control operations as well as read-only methods. Only give
socket access to processes that you trust to control the local NetBird client.

## Troubleshooting

### The Socket File Does Not Exist

Confirm that the service was installed or reconfigured with `--enable-json-socket`, then check the service status:

```shell
sudo netbird service status
```

If you supplied `--json-socket` without `--enable-json-socket`, NetBird rejects the configuration. Setting a custom address does not enable the gateway on its own.

### Curl Reports Permission Denied

Verify that the process running the integration can access the socket and every parent directory in its path. A custom restricted directory can prevent access even when the socket itself allows it.

### A Request Is Refused With 403

The operation is one of the
[privileged operations](/client/grpc-socket#privileged-operations) and the HTTP
client is not root, or not an administrator on Windows. The response body carries a
`PRIVILEGE_REQUIRED` detail in domain `daemon.netbird.io`, with a summary and the
command that performs the same operation with the privileges it needs. On a TCP
gateway socket these operations are always refused.

### A TCP Request Cannot Connect

Confirm that the host and port in the request match the value passed to `--json-socket`. Prefer `127.0.0.1` over `0.0.0.0` unless remote access is explicitly required and protected by an additional security boundary.