Installing the noBGP Agent

The noBGP agent is a lightweight background process that connects your machines to noBGP networks, enabling secure encrypted communication with other nodes. Your AI assistant can execute authorized commands, monitor system status, and create secure tunnels for your services.

Getting Started

Run the install script and follow the prompts — it handles everything: installation, registration, and service setup.

Mac / Linux

curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo sh

Or on macOS with Homebrew:

brew install nobgp/tap/nobgp

Windows

One command, whether you're in Command Prompt or PowerShell:

powershell -NoProfile -Command "irm https://downloads.nobgp.com/agent/install.ps1 | iex"

The installer requires Administrator privileges. If not already elevated, it automatically requests UAC elevation.

The install script will:

1. Download and install the correct package for your platform
2. Open your browser to sign in with your noBGP account (Google, GitHub, etc.)
3. Let you choose which network the node should join
4. Install and start the agent as a system service

No keys or tokens needed — just run the script and follow the prompts.

tip

When using your AI assistant with noBGP integration, it can generate a ready-to-run install command using the register_node tool.

Platform Details

Installation Scripts

The install scripts from Getting Started detect your system and install the appropriate agent package. Here are platform-specific details and alternative installation methods.

Linux

Using curl:

# Install latest released version
curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo sh

# Keep the downloaded package file
curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo KEEP_PACKAGE=true sh

Or using wget:

# Using wget instead of curl
wget -qO- https://downloads.nobgp.com/agent/install.sh | sudo sh

The install.sh script supports:

• Alpine Linux 3.16+
• Arch Linux
• Amazon Linux 2023+
• Debian 11+ / Ubuntu 20.04+
• OpenWRT
• Synology DSM (see Synology DSM below)

On Debian and Ubuntu, the script does not require apt-get update to succeed (an EOL release with archived repositories fails it permanently), and if apt refuses the install because of pre-existing broken dependencies elsewhere on the host, it falls back to dpkg -i. See Debian and Ubuntu hosts for the same behavior during upgrades.

The script also installs the packages the shared drive needs — the FUSE kernel module and its userspace helper (fuse3, or kmod-fuse and fuse-utils on OpenWrt), falling back to davfs2 where the FUSE package cannot be installed. That fallback is only tried on Debian/Ubuntu, Alpine and RPM hosts, and only if FUSE fails, which it rarely does — Arch and OpenWrt install FUSE alone, and on Synology DSM the script installs neither. So most Linux nodes have no davfs2 and therefore no webdav backend to fall back to; install it by hand if you want that third option. This is best-effort either way: the filesystem is optional, so a host that cannot supply those packages still installs and runs, without the shared drive. See Shared drive is empty and never mounts if that is where you end up.

From agent 0.4.58 it also installs an NFSv4 client, so the node can take the nfs backend — which on Linux is what a host with no usable FUSE falls back to, rather than dropping all the way to WebDAV:

Platform	What is installed	Notes
Debian / Ubuntu	nfs-common, without recommended packages	About 2 MB. Dropping the recommendations leaves out python3
Amazon Linux / RHEL / Oracle / Rocky / AlmaLinux	nfs-utils, without weak dependencies
Arch Linux	nfs-utils
macOS	nothing	mount_nfs is part of the base system
Alpine, OpenWrt, Synology DSM	nothing	Deliberate — see below. FUSE already works on all three

It is installed beside the FUSE helper, not instead of it: the agent probes every backend and picks per host, so both are worth having — and from agent 0.4.65 a Linux node that has both prefers FUSE, with NFS as the fallback. Alpine is left out on cost — its nfs-utils hard-depends on rpcbind and python3, taking the install from 27 MB to 80 MB — and OpenWrt and Synology because FUSE serves them already.

From agent 0.4.70 no package is needed for NFS on Linux at all. With no mount helper on the host the agent makes the mount itself, so the nfs backend is available wherever the kernel has an NFSv4 client — a bare container included, with nothing installed. The packages above are still installed where the script installs them, and a helper that is present is still used, so nothing changes on a host that already has one; what changes is that Alpine, OpenWrt and Synology no longer need a hand-installed client to reach this backend. On those three, check the kernel half if nobgp status still reports nfs as unavailable — that is the only requirement left.

rpcbind is confined to loopback

On Debian, Ubuntu and Arch the NFS client package pulls in rpcbind, and a fresh install of it listens on every interface, TCP and UDP, on port 111 — a daemon NFSv4 does not use at all. When the installer is what brought rpcbind in, it writes /etc/systemd/system/rpcbind.socket.d/10-nobgp-loopback.conf to bind it to 127.0.0.1 and [::1] only, and restarts the socket. Local RPC consumers keep working; the node simply stops offering RPC to the network.

A machine that already had rpcbind is left exactly as its operator configured it. To undo the confinement, delete that file and run sudo systemctl daemon-reload && sudo systemctl restart rpcbind.socket.

FUSE is not the only backend a Linux node can use. The agent probes what the machine can actually do and mounts with the first of FUSE, NFSv4 and WebDAV that can serve — so a host with no fusermount but an NFSv4 client in its kernel mounts over NFS and needs nothing installed at all, which is why the missing FUSE helper is best-effort rather than fatal. The davfs2 fallback is the least of the three and the least available: the script reaches for it only when FUSE cannot be installed, which almost never happens on Debian, Alpine or Amazon Linux, and Synology cannot install it at all — synopkg has no WebDAV package, and DSM registers no NFSv4 client either, so a Synology node has FUSE and nothing behind it. Run nobgp status on the host to see every backend it could use and why each can or cannot serve, and see Which filesystem you get for the full picture.

macOS

Using Homebrew (recommended):

brew install nobgp/tap/nobgp

Using the install script:

curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo sh

macOS 13+ (Ventura and later) is supported on both amd64 and arm64 (Apple Silicon).

The shared drive needs nothing installed on macOS — it mounts over NFSv4 using mount_nfs, which is part of the operating system. FUSE and WinFsp have no macOS build at all, and installing macFUSE does not change that.

macOS: the agent's own service cannot read the mount

File operations and commands the agent runs for you against /Volumes/nobgp fail with Operation not permitted, at every identity including root. This is macOS TCC consent rather than a permission problem — running elevated fails identically, and a background LaunchDaemon has no way to ask you for consent.

Your own account reads the mount normally from Finder or Terminal; only the agent's service is blind. Granting the agent Full Disk Access removes the denial: System Settings → Privacy & Security → Full Disk Access → +, then ⌘⇧G (the picker hides /usr/local) and enter /usr/local/bin/nobgp — the daemon's own binary. The running daemon picks it up at once; there is nothing to restart or remount. Without the grant, reach the same files through the router — a network's share by network name, or the node's own area with storage: true — instead of by a path under the mount point.

Synology DSM

Run the install script over SSH on your Synology NAS:

curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo sh

DSM has a busybox-based userland with no native package manager, so the installer detects Synology and drops the static Alpine binary into /usr/local/bin/nobgp with a config directory at /etc/nobgp/. Only amd64 and arm64 NAS models are supported.

DSM 7

On DSM 7 (which ships systemd), nobgp register installs and starts the agent as a service automatically — no extra steps required.

DSM 6 and older

DSM 6 and older have no systemd, so the install script prints a warning and skips service auto-install. To start the agent on boot, create a Triggered Task in DSM Control Panel → Task Scheduler:

• Trigger: Boot-up
• User: root
• Run command: /usr/local/bin/nobgp agent

Both manual nobgp upgrade and router-driven auto-upgrade work on DSM. Since DSM has no package manager, the agent fetches the raw static binary (instead of the .apk) and atomically swaps it in place — see Upgrading.

Windows

Run the following. It is one command for every Windows shell — Command Prompt, PowerShell 5.1 and PowerShell 7 — so there is nothing to pick:

powershell -NoProfile -Command "irm https://downloads.nobgp.com/agent/install.ps1 | iex"

The installer requires Administrator privileges to write to C:\Program Files\nobgp, update the system PATH, and register a Windows Service. If not already elevated, it automatically requests UAC elevation and forwards any NOBGP_* environment variables to the elevated session.

Windows 10/11 and Windows Server 2019+ are supported on amd64 and arm64.

The shared drive needs nothing installed on Windows: auto mounts it with the WebDAV client built into the operating system, mapped to a drive letter. That drive belongs to exactly one logon session, so a service, a scheduled task or an elevated Administrator prompt sees no drive at all on a machine where nobgp status says it is mounted.

WinFsp is the machine-wide alternative, and it is opt-in. Set fs: winfsp in the profile (Filesystem keys) to use it: the drive is then visible to every account and every service, and is not labelled DavWWWroot. It needs WinFsp 1.10 or newer installed — rclone, sshfs-win, Cygwin and MSYS2 all ship it — and an older version is refused by name and version rather than mounting and failing. auto does not select it yet, for two reasons it will also print on nobgp status: its locks stay on that machine, so two programs on two different nodes can both believe they hold an exclusive lock on the same file; and creating a file is slow — about a second each when it was last measured, which a bulk copy of many small files feels immediately.

WinFsp went read-only in agent 0.4.62 and read-write in 0.4.63, though a real mount only accepts writes from agent 0.4.65. From agent 0.4.73 the version floor is checked when the backend is probed, so an older WinFsp reports as unavailable in nobgp status — naming the version it found and the one it needs — instead of being selected and failing every mount.

The installation scripts support the following architectures:

• amd64 (x86_64)
• arm64 (aarch64)
• armv6 and armv7 (Debian/Ubuntu, for Raspberry Pi and similar devices; armv7 also on OpenWRT)

The install scripts guide you through registration (browser sign-in) and service installation. After the script completes, the agent is running and connected. If you installed via Homebrew or a manual package install, run sudo nobgp register to complete setup.

Docker and Automation

For Docker containers, CI/CD pipelines, and other non-interactive environments where a browser login isn't possible, use a registration key to register the agent automatically.

Get your registration key from the noBGP Add Node page or ask your AI assistant to retrieve it.

warning

Treat registration keys as secrets. Don't commit them to git repositories or share them publicly.

Docker Run

docker run --detach --restart unless-stopped \
  --cap-add NET_ADMIN \
  --cap-add SYS_ADMIN \
  --device=/dev/net/tun \
  --device=/dev/fuse \
  --security-opt apparmor=unconfined \
  -e NOBGP_KEY=<YOUR_REGISTRATION_KEY> \
  -e NOBGP_NAME=docker-node-1 \
  nobgp/nobgp

Docker Compose Example

services:
  nobgp:
    image: nobgp/nobgp
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
    devices:
      - /dev/net/tun
      - /dev/fuse
    environment:
      NOBGP_KEY: "<YOUR_REGISTRATION_KEY>"
      NOBGP_NAME: "docker-node-1"

Headless Registration with Key

On any system where interactive browser login isn't available, register with a key:

sudo nobgp register --key "<YOUR_REGISTRATION_KEY>" --name "web-server-1"

Or pass the key via the install script for a single-command setup:

Mac / Linux

curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo NOBGP_KEY=<YOUR_REGISTRATION_KEY> NOBGP_NAME=<NODE_NAME> sh

With NOBGP_KEY set, the script never prompts, so it runs unattended anywhere a shell can run — a cron job, a systemd unit, a cloud-init script, or a Synology DSM scheduled task, none of which have a terminal attached. Without a key, the script needs a terminal so you can complete the browser sign-in; if it can't reach one, it stops after the install and tells you to run sudo nobgp register yourself.

Windows

One command, whether you're in Command Prompt or PowerShell. The installer self-elevates, so you don't need to open an Administrator prompt first:

powershell -NoProfile -Command "Set-Item env:NOBGP_KEY '<YOUR_REGISTRATION_KEY>'; Set-Item env:NOBGP_NAME '<NODE_NAME>'; irm https://downloads.nobgp.com/agent/install.ps1 | iex"

Why Set-Item env: and not $env:

Both set the same variable, but only one survives being pasted into either shell. Written as $env:NOBGP_KEY="…" inside -Command "…", PowerShell expands the variable to empty before the installer runs, and the node registers without a key. With no $ in the command there is nothing to expand, so the identical text works in Command Prompt and PowerShell alike.

Drop-in Provisioning

For fleet management or temporary network access, you can provision agents by placing a config file directly in the config directory. The process manager detects new profiles within 5 seconds and automatically starts the agent.

Create a YAML file in the config directory (e.g., /etc/nobgp/support.yml):

registration-key: "<YOUR_REGISTRATION_KEY>"
router: "router.nobgp.com"
node-name: "web-server-1"

The agent will:

1. Detect the new profile automatically
2. Register with the specified network
3. Remove the registration key from the config file
4. Start running as a new profile

The agent then takes the file over: it rewrites it with its own recorded state, drops keys whose value is the default (router: "router.nobgp.com" above is one of them — it becomes a commented reference line), and does not preserve comments you wrote. Provision the values you need and read the result back with nobgp show rather than expecting the file to stay as you typed it.

This is useful for temporarily attaching a node to a support or monitoring network without affecting existing profiles.

To remove the profile later:

sudo nobgp remove support

Network Requirements

The agent requires outbound connectivity only — no inbound ports need to be opened.

Destination	Protocol	Purpose
noBGP control plane	QUIC (UDP 443)	Preferred control plane transport (transport: auto); the endpoint is learned from the router automatically
router.nobgp.com:443	WebSocket (wss://)	Control plane transport and automatic fallback
downloads.nobgp.com	HTTPS	Package downloads and updates

If you're behind a corporate firewall or restrictive network, ensure these destinations are allowed for outbound traffic on port 443 (TCP for the HTTPS/WebSocket destinations, UDP for QUIC). If UDP 443 is blocked, the agent automatically falls back to the WebSocket transport over TCP, so connectivity is preserved — but allowing UDP 443 to the noBGP control plane lets the agent use the faster QUIC transport.

The shared drive needs no destination of its own: the agent mounts it over HTTPS against the same router.nobgp.com:443 endpoint listed above, so a host that can reach the control plane can mount it.

Configuration

The noBGP agent can be configured through multiple methods:

1. Web Interface: Manage certain configuration options through the noBGP web application
2. Configuration File: Local settings stored in a YAML file
3. Command Line Options: Options passed directly to the nobgp command
4. Interactive Configuration: Guided setup process
5. Environment Variables: System environment variables for automation

Configuration File

The noBGP agent uses a YAML configuration file. Default locations by platform:

• Linux: /etc/nobgp/default.yml
• macOS: /usr/local/etc/nobgp/default.yml
• Windows: C:\ProgramData\nobgp\default.yml

The agent owns this file and rewrites it whenever it records something for itself — and, since agent 0.4.36, once at startup, so a node upgraded from an older agent is converted on its first restart rather than waiting for a write that may never come. Since agent 0.4.35 it writes a key only when its value differs from the default — every other key appears as a commented # key: value line under a short explanatory block, so the file reads as the choices someone made rather than a copy of every default. Uncomment a line to pin that value; leave it commented and the node follows the default, including one that changes in a later release. Comments you add by hand do not survive the next rewrite. See Configuration File for the full shape.

So after a stock registration the settings section may be empty, with the file holding only what the agent recorded — the node's overlay slice, its local MCP port and token, the account captured at install:

overlay-cidr: 100.64.0.0/20
mcp-port: 51843
user: alice

note

Agent identity (keys and tokens) is stored in separate .key and .jwt files alongside the config, not in the YAML file itself. The registration key and node name are automatically removed from the config after successful registration.

tip

The noBGP agent monitors the configuration file for changes. When you modify the configuration file while the agent is running, the new settings will be automatically applied with minimal network disruption.

info

When you have a single profile, the agent uses default.yml in the config directory. The agent also supports multiple profiles (see Multi-Profile Support below).

Configuration Options

Config File Key	Command Line Option	Environment Variable	Description	Default
router	-r --router	NOBGP_ROUTER	Router FQDN, optionally host:port. Connects over wss:// (TLS); legacy wss:///ws:// URLs are accepted and normalized to the bare FQDN	router.nobgp.com
insecure	--insecure	NOBGP_INSECURE	Allow a plaintext (ws://) control channel — for local or self-hosted routers without TLS only	false
transport	--transport	NOBGP_TRANSPORT	Control-channel transport: auto, quic, or wss. auto negotiates the fastest available transport and falls back to WebSocket automatically	auto
quic-router	--quic-router	NOBGP_QUIC_ROUTER	QUIC control endpoint (host:port) override for self-hosted routers. Leave unset to use the endpoint learned from the router, falling back to the router's own domain	(learned from router)
debug	-d --debug	NOBGP_DEBUG	Enable debug mode	false
log-level	-l --log-level	NOBGP_LOG_LEVEL	Logging level (error, warning, info, debug, trace)	info
compress	-z --compress	NOBGP_COMPRESS	Enable compression	true
encrypt	-e --encrypt	NOBGP_ENCRYPT	Require encryption	true
idle-ttl	--idle-ttl	NOBGP_IDLE_TTL	Recycle a peer session after this much idle time with no data traffic (0 = defer to peer). Negotiated end-to-end as the shorter of the two peers' values; clamped to a 1m floor	1h
interface	-i --interface	NOBGP_INTERFACE	Network interface to use	auto
ping-interval	--ping	NOBGP_PING_INTERVAL	Interval for connection health checks	58s
mount	-m --mount		Filesystem mount point	Platform-dependent
fs			Which shared drive backend this node mounts with: auto, off, nfs, fuse, winfsp (agent 0.4.62+, Windows) or webdav. auto probes the host and takes the best one available — apart from winfsp, which auto has never chosen and which must be pinned to be used. Two reasons hold it back and nobgp status names both: its locks are node-local rather than forwarded to noBGP, and creating a file is slow. Both earlier reasons are closed — the write path that lost data was fixed in agent 0.4.69 and came off the printed line in 0.4.73, and case-sensitivity was fixed in agent 0.4.74 and came off the line in 0.4.75, so agent 0.4.74 alone prints a reason it had itself already answered. A pinned backend the host cannot serve is refused and reported, never quietly swapped for another; a value that isn't one of the six is a typo and falls back to auto with a warning. off mounts nothing and stops the local proxy too. Agent 0.4.57+	auto
fs-cache-ttl	--fs-cache-ttl	NOBGP_FS_CACHE_TTL	How long the shared drive may serve a cached directory listing before re-asking noBGP, clamped to [0, 10m]. A staleness window rather than a performance dial: it is how long this node may show a directory as it was before another node's newer write, and equally how often every mount re-asks about a directory nothing changed. 0 re-asks every time and still serves unchanged file contents from the local cache. Requires a unit — 30 means thirty nanoseconds and is ignored as a missing unit. Read by the nfs, fuse and winfsp backends from agent 0.4.67 (nfs alone in 0.4.66), including the timeouts the kernel caches with, which are mount options and so pick a changed value up on the next mount. Agent 0.4.66+	30s
nfs-port			Agent-written, not a setting you edit: the loopback port the nfs backend's server bound, recorded so a restart binds the same one and an existing mount is not orphaned. Per profile, so two profiles on a machine cannot collide. A remembered port that is taken is replaced with a new one and recorded. Agent 0.4.59+	(remembered)
last-mount-point			Agent-written, not a setting you edit: where this profile last had the shared drive actually mounted. It is never mounted on — it is read by one path only, the startup cleanup that removes a mount a killed agent left behind on a node that is not going to mount (fs: off, or no mount point), which is the one case that cannot name the point any other way. A stale value is harmless: only a mount whose source belongs to this agent is ever removed. Agent 0.4.78+	(remembered)
user	--user	NOBGP_USER	Account that command sessions, dispatched bus commands and file operations run as when the caller does not ask to be elevated. Installation records the account that ran the install (on Windows, whoever is signed in at the desktop), so this is typically that user. On a headless or container install where none was captured and the agent runs as root, unelevated calls are refused rather than run as root — set this, or have callers pass admin (unelevated never means root). An account that does not exist on the machine is refused, as is one that resolves to uid 0. The environment variable outranks the config file, which is how a container image or task definition ships a node with an account already named. On Windows the account is the node's second identity, governing file operations first and execution as well from agent 0.4.46 (0.4.44 and 0.4.45 refused an unelevated execution call there)	(the installing account)
overlay-cidr	--overlay-cidr	NOBGP_OVERLAY_CIDR	Overlay TUN CIDR: a /20 within 100.64.0.0/10 (auto-picked if unset)	auto-picked
mtu	--mtu	NOBGP_MTU	Overlay TUN MTU in bytes (clamped to [1280, 8000]; lower for a constrained path)	8000
runtime-dir		NOBGP_RUNTIME_DIR	Directory for ephemeral runtime files (locks, PID). Point it at the config directory on a mostly read-only rootfs where only the nobgp directory is writable	Platform-dependent (e.g. /run/nobgp)
auto-upgrade			Set to false to disable automatic router-driven upgrades	true

Local MCP server options (see Local MCP Server). What starts the agent's MCP server on 127.0.0.1 — so a local Claude Desktop or Claude Code can drive this node and its peers — is a node_grant from an Owner or Admin at the router. There is no on-device key that turns the endpoint on or off; both keys below are agent-written state, not settings you edit:

Config File Key	Description	Default
mcp-port	Loopback port to prefer. The agent binds it when free, otherwise takes one from the OS and records it here, so restarts usually keep the same port	(remembered)
mcp-token	Bearer token for that server, minted by the agent on first start and recorded here so registrations written by nobgp mcp install survive restarts	(remembered)

An mcp-proxy key left in a profile by an older agent is removed automatically, as is a windows-user-identity key left by agent 0.4.43 — on Windows a configured user is now the whole of the second identity, with no separate switch.

Capability options — the node owner's say over what this machine serves remotely (see Monitoring & Events). They cover MCP callers, event-bus sources and, since agent 0.4.33, published terminal services too, so dropping command closes the browser terminal along with the MCP tools. See Node Access Control.

Config File Key	Description	Default
allow-tools	Capability domains served on this node: fs, command (flag: --allow-tools). Dropping one refuses both its event source and its direct tool, with a reason, rather than going quiet. An explicit [] serves neither. Values that aren't domains are ignored with a log line, and if none survive the permissive default is restored — a typo never strands the box. Renamed from event-sources	[fs, command]
allow-roots	Directories the fs domain may reach on this node, e.g. [/etc, /var/log] — drive-qualified on Windows, e.g. [C:\ProgramData\app] (flag: --allow-roots). Anything outside them is refused, with symlinks resolved first, as is the agent's own configuration directory whatever this is set to. The whole-filesystem value is / (or \; both are accepted on either platform). Renamed from event-watch-roots	[/]
allow-admin	Whether callers may ask for elevated execution and admin-level file access (flag: --allow-admin). false refuses an elevated request rather than silently downgrading it, and drops the rest to user. Where there is no unprivileged identity to drop to — Windows, or a root-running agent with no user — false refuses remote execution on the node entirely, since the unelevated path is refused there too	true
api-socket-group	Group (name or numeric gid) granted access to the agent's local API socket. Unix only	(unset)
api-socket-mode	Octal mode for that socket, e.g. "0660". Only meaningful with api-socket-group set	0600
webdav-proxy-owners	Numeric uids allowed to reach the agent's local shared drive proxy on 127.0.0.1, which carries the node's credentials. Empty observes rather than allows: the agent logs the uid of the first local caller it sees and refuses nothing, so you can read the value to set before setting it. Linux and macOS only — a Windows node cannot learn a loopback caller's identity, so a list there refuses everything. Agent 0.4.53+	(unset — observe only)

Registration-specific options (used with nobgp register, cleaned up after registration):

Option	Environment Variable	Description
--key	NOBGP_KEY	Registration key for the network
--name	NOBGP_NAME	Node name (defaults to hostname)

Using the Register Command

If you installed via Homebrew or a manual package install (not the install script), register separately:

# Register interactively via OAuth browser login (recommended)
sudo nobgp register

# Register with a specific name and network
sudo nobgp register --name "web-server-1" --network "production"

# Register with a key (for Docker/automation — see Docker and Automation section)
sudo nobgp register --key "<YOUR_REGISTRATION_KEY>" --name "web-server-1"

After successful registration, the agent installs and starts the system service automatically — no prompt. Exit code 3 means the node enrolled but the service could not be started; fix the cause and run sudo nobgp service install.

Using the Config Command

Update runtime configuration for a registered agent:

# Set the router (bare FQDN, optionally host:port)
sudo nobgp config --router "custom-router.example.com"

# Enable debug mode
sudo nobgp config --debug

The command saves your settings to the configuration file for future runs.

Environment Variables

Environment variables override configuration settings without modifying the configuration file. This is useful for automation or containerized environments.

Example:

export NOBGP_DEBUG=true
export NOBGP_LOG_LEVEL="debug"
sudo -E nobgp agent

For key-based registration in automated environments (see Docker and Automation):

export NOBGP_KEY="<YOUR_REGISTRATION_KEY>"
export NOBGP_NAME="api-server-1"
sudo -E nobgp register

Command Line Options

Override configuration settings with command line options when running nobgp:

sudo nobgp agent --debug --log-level trace

Web Application Configuration

Manage your noBGP network through the web interface at https://app.nobgp.com:

• Network creation and management
• Registration key management
• Node authorization and discovery
• Network topology visualization
• Connection monitoring

Changes made through the web application to your network configuration automatically propagate to your nodes, potentially causing them to restart to apply new settings.

Multi-Profile Support

The noBGP agent supports running multiple profiles simultaneously, allowing you to connect a single machine to multiple noBGP networks.

How it works:

• Each profile is stored as a separate YAML file in the config directory (e.g., /etc/nobgp/production.yml, /etc/nobgp/staging.yml)
• Each profile has its own .key and .jwt credential files alongside the config
• When running as a service, the process manager automatically starts an agent instance for each profile
• The default profile is named default (file: default.yml)

Managing profiles:

# Register a named profile (interactive)
sudo nobgp register production --name "prod-server-1"

# Or with a key (for automation)
sudo nobgp register production --key "<KEY>" --name "prod-server-1"

# List all profiles
nobgp list

# Show details of a specific profile
nobgp show production

# Show default profile
nobgp show

# Check status of all running profiles
nobgp status

# Remove a profile (deletes .yml, .key, and .jwt files)
sudo nobgp remove staging

Running multiple profiles:

When installed as a service, all profiles in the config directory are automatically managed:

# Install service (manages all profiles)
sudo nobgp service install

# Start all profiles
sudo nobgp service start

# Check status
nobgp status

To run a specific profile manually:

# Run the production profile
sudo nobgp agent production

# Run the default profile
sudo nobgp agent

note

The profile name is specified as a positional argument (e.g., nobgp agent production), not as a flag.

Running the noBGP Agent

Running as a Standalone Process

Start the noBGP agent as a standalone process:

sudo nobgp agent

This connects to the router and sets up the required networking components.

For verbose output, add the debug flag or set the log level:

sudo nobgp agent --debug

Service Management (Recommended)

Run the noBGP agent as a system service for automatic startup. This is recommended for production environments. The service automatically starts on system boot and can be managed using standard system commands.

info

Most service commands do not work in Docker containers — use process management or orchestration tools instead. The exception is nobgp service logs: a containerized agent running in the foreground mirrors its output to an on-disk log file, so nobgp service logs works inside the container (as does docker logs).

The nobgp service subcommand names are consistent across platforms (the underlying service manager differs — systemd on Linux, launchd on macOS, Windows SCM on Windows):

# Install the service
sudo nobgp service install

# Check service status
sudo nobgp service status

# Start the service
sudo nobgp service start

# Stop the service
sudo nobgp service stop

# Restart the service
sudo nobgp service restart

# Uninstall the service
sudo nobgp service uninstall

On Windows, run these commands in an Admin PowerShell session (without sudo). The agent is registered as a Windows Service and managed through the Windows Service Manager.

On macOS, the agent is registered as a launchd daemon.

On Linux, the agent is registered as a systemd service.

When running as a service, the noBGP agent uses the settings from your configuration file.

Verifying Connection

Once the agent is running, verify it's connected:

1. Check service status:

   sudo nobgp service status

2. Ask your AI assistant:

   Show me all nodes in my default network

You should see your node listed as "online".

System Requirements

The noBGP agent requires:

• Operating System:
  • Linux: Alpine Linux 3.16+, Arch Linux, Amazon Linux 2023+, Debian 11+ / Ubuntu 20.04+, OpenWRT
  • Synology DSM (amd64 or arm64; DSM 7 recommended for service auto-install)
  • macOS 13+ (Ventura and later), amd64 or arm64 (Apple Silicon)
  • Windows 10/11 or Windows Server 2019+, amd64 or arm64
• Privileges: Root or sudo access (Linux/macOS); Administrator (Windows)
• Network: Connectivity to the noBGP router
• Architecture: amd64 (x86_64) or arm64 (aarch64) on all platforms; armv6/armv7 on Debian/Ubuntu (Raspberry Pi)
• Resources:
  • 512MB RAM minimum
  • 1GB disk space
  • Network interface with IP connectivity

Usage

When the noBGP agent runs on your system, you can access any other node on the same network by simply using their name. For example, if you have nodes named web-server and api-server in the same network, they can reach each other using those names.

Your AI assistant can also:

• Run commands on the node
• Start interactive shell sessions
• Publish services running on the node
• Monitor system status
• Transfer files

Troubleshooting

If you encounter issues:

1. Enable debug mode: sudo nobgp agent --debug
2. Check the logs (all platforms, needs root — an Administrator terminal on Windows): sudo nobgp service logs -f, or platform-specific:
   • Linux (systemd): sudo journalctl -u nobgp.service -f
   • Linux (Alpine/OpenRC): tail -f /var/log/nobgp.err
   • macOS: tail -f /var/log/nobgp.err.log
   • Windows: Get-Content -Path C:\ProgramData\nobgp\nobgp.log -Tail 50 -Wait (the agent mirrors its logs to this file, since the Windows Service Control Manager does not capture service output)
3. Check registration status: nobgp show
4. Verify the configuration file exists in the config directory
5. Check that the router URL is accessible from your machine
6. Verify that you have root/administrator privileges when running the noBGP agent

Common Issues and Solutions

Issue	Possible Cause	Solution
Connection failed	Not registered	Run sudo nobgp register
Service won't start	Missing permissions	Check sudo access
Node not visible	Firewall blocking	Check router access
Agent crashes	Incompatible OS	Verify OS version support
High CPU usage	Debug mode enabled	Disable debug in production
Windows CLI command refuses to run	Windows does not self-elevate	Re-run the named command from an Administrator terminal (Root privileges)
macOS service fails	SIP or permissions	Check /var/log/nobgp.err.log
macOS agent works but nothing starts at boot	Service was never installed by an older build	Upgrade to 0.4.21+, then sudo nobgp service install (see below)
Node flaps online/offline	Duplicate agent install	Stop/uninstall the redundant service (see below)
Node deauthorized	Credentials rejected	Re-enroll with sudo nobgp register (see below)
Node stays offline and nobgp status names an expired token	The registration token expired while the node was offline, and an expired token cannot refresh itself	Re-enroll with sudo nobgp register on agent 0.4.72+ (see below)
Agent version no longer supported	Agent older than 0.3.51	Reinstall the current agent (see below)
Certificate error during install or upgrade	Antivirus HTTPS scanning or a corporate proxy re-signing the connection	Exclude the download and router domains from inspection (see below)
Windows drive keeps disconnecting and reappearing	Mount health checked from the wrong logon session by an older build	Upgrade to 0.4.31+ (see below)
Shared drive is empty on Linux, node otherwise healthy	The FUSE userspace helper is not installed	Install fuse3 (fuse-utils on OpenWrt) and restart the agent (see below)

Detailed Troubleshooting

Agent Won't Start

Symptoms: Service fails to start or exits immediately

Solutions:

• Check system requirements are met
• Verify the agent is registered: nobgp show
• Look for error messages in logs
• Try running in standalone mode with --debug flag

Node Shows Offline in Dashboard

Symptoms: Agent is running but node appears offline

Solutions:

• Check firewall rules allow websocket connections
• Verify router URL is accessible: curl https://router.nobgp.com
• Verify registration status: nobgp show
• Restart the agent: sudo nobgp service restart

Node Repeatedly Flaps Online/Offline

Symptoms: The node cycles between online and offline every few seconds to a minute. The agent logs may show a rejection reason such as "re-registered more than 8 times in 10m0s while its existing connection is healthy".

Cause: Two agent processes are running with the same identity on one host. This happens when a machine ends up with more than one live install — a duplicate install (for example, both a package install and a script/manual install left a running service), an orphaned pre-upgrade process that was never stopped, or a legacy nobgp-agent.service unit from a pre-0.3 install still enabled alongside the current nobgp.service. Each process evicts the other's router connection on connect, so the node flaps.

Two safeguards catch this: the agent takes a per-profile single-instance lock, so a second process on the same host fails fast with an error like profile "default" is already running on this host … duplicate install or orphaned instance; and the router rejects a node that re-registers too rapidly while its existing connection is healthy, sending the reason in a close frame that lands in the rejected agent's local logs.

Solutions:

• Check for more than one running noBGP process/service on the host and stop or uninstall the extra one (sudo nobgp service uninstall for the redundant install):
  • Linux (systemd): systemctl status nobgp.service and look for stray nobgp agent processes (ps aux | grep nobgp)
  • macOS: sudo launchctl list | grep nobgp
  • Windows: check for a duplicate nobgp service in Services and any manual nobgp agent processes
• If you recently upgraded, restart the service so the old process is fully replaced: sudo nobgp service restart
• On Linux, a leftover legacy nobgp-agent.service unit is disabled and removed automatically the next time the agent upgrades or the service restarts — no manual action needed.
• On Windows, only one nobgp service can exist, so if it detects any other nobgp supervisor process started outside it (for example a Task Scheduler job, a Startup-folder shortcut, or a leftover console run) it logs a warning naming that process and the autostart to remove. Delete that autostart source so it does not return on the next reboot.
• Confirm each host registers under a unique node name

macOS: Agent Works, but No Service Was Installed

Symptoms: On macOS, registration completes and the agent runs fine when you start it by hand (sudo nobgp agent), but sudo nobgp service status reports the service is not installed and the node does not come back after a reboot.

Cause: Older agent builds wrote a launchd property list that launchd rejected when the service was installed, so the install step logged the failure and continued — leaving a working agent with no launchd daemon behind it. Fixed in 0.4.21.

Solutions:

• Upgrade the agent, then install the service explicitly:

  sudo nobgp upgrade
  sudo nobgp service install
  sudo nobgp service start

• Confirm with sudo nobgp service status (exit code 0 means running) and sudo nobgp service logs.
• If the agent is too old to upgrade itself, reinstall it with the install script or brew upgrade nobgp.

Certificate Error During Install or Upgrade

Symptoms: The install script or nobgp upgrade stops with a certificate validation failure against downloads.nobgp.com or your router domain, on a machine whose browser reaches the same sites fine.

Cause: Something on the machine or the network is re-signing HTTPS connections — consumer antivirus with a "web shield", or a corporate inspection proxy. The replacement certificate is not one the agent trusts.

Solutions:

• The installers and the agent name the certificate's owner in the error, and inspection products identify themselves there (Norton's certificate literally says it was generated for SSL/TLS scanning). That name tells you which product to configure.
• Exclude downloads.nobgp.com and your router domain from HTTPS/SSL scanning, or ask IT to add them to the proxy's inspection bypass list.
• Full per-vendor instructions are in Security software and VPNs.
• On a machine already running the agent, nobgp status reports the same finding continuously as router.tls_intercepted — see Environment interference.

Windows: Network Drive Keeps Disconnecting

Symptoms: On Windows, the noBGP drive letter disappears from Explorer and comes back every 30 seconds or so, and nobgp status reports fs.mounted: false even while file operations succeed.

Cause: Windows drive mappings belong to the logon session that created them. Once the agent moved the mapping into the interactive desktop session so Explorer could see it, its own health check — running as the SYSTEM service — could no longer see the mapping, judged the mount dead, and remounted it, on repeat. Fixed in 0.4.31.

Solutions:

• Upgrade the agent from an Administrator terminal (nobgp upgrade), then nobgp service restart.
• If the drive is mounted on a different letter than the one you configured, that is deliberate and unrelated: when the configured letter is already taken by something that is not a noBGP mount, the agent leaves it alone and mounts on the first free letter instead. nobgp status reports the letter actually in use under fs.mount.

Windows: Creating a File on a winfsp Drive Says "Access is denied"

Symptoms: On a Windows node pinned to the winfsp backend, the drive mounts and lists and reads perfectly, but every attempt to create a file on it is refused with Access is denied — from an Administrator prompt, from a scheduled task, from Explorer, from the agent itself. Nothing appears in the agent log, because nothing reached the agent. Agents 0.4.63 and 0.4.64.

Cause: Windows checks access against a security descriptor that WinFsp builds from what the filesystem reports about ownership, before any of the agent's code runs. The share has no per-file owner to report, and what the volume did report granted full access to an account identifier that no token on the machine holds — so the only permissions any real caller matched were read and execute. Reads passed, creates did not, for everyone.

Solutions:

• Upgrade the agent to 0.4.65 or later from an Administrator terminal (nobgp upgrade), then nobgp service restart. The mount is given an explicit descriptor granting full access to LocalSystem, Administrators and Authenticated Users.
• Make sure WinFsp is 1.10 (2022) or newer. Older builds reject the option that carries the descriptor, which refuses the mount outright — visible as fs.error in nobgp status through agent 0.4.72. From agent 0.4.73 the probe checks the version first, so such a host reports winfsp: unavailable (WinFsp <version> is installed at … but this backend needs 1.10 or newer …) in the backends list and the backend is not selected at all.
• To get a working drive back on an older agent, remove the fs: winfsp pin and restart the agent: the node returns to its WebDAV mount, which is read-write.

Windows: Appending to a File on a winfsp Drive Overwrites It

Symptoms: On a Windows node pinned to the winfsp backend, Add-Content, >> or any other append to a file the drive has recently written replaces the file's contents instead of adding to them. Every command reports success, and the bytes upload correctly — they are simply written at the wrong offset. Agents 0.4.67 and 0.4.68, the two releases where the volume both wrote and deferred its uploads. webdav, which every unpinned Windows node mounts, is not affected.

Cause: Windows asks for a file's size by name as well as through an open handle, and computes an append's write offset from the answer. The by-name answer came from the cached directory listing, which still held the size from before the write — 0 for a file just created — so the append landed at offset 0.

Solutions:

• Upgrade the agent to 0.4.69 or later from an Administrator terminal (nobgp upgrade), then nobgp service restart. A by-name size is answered from the open handle while one is open, and from the pending upload after the last handle closes. See Appending to a file the volume just wrote.
• On an older agent, remove the fs: winfsp pin and restart: the node returns to its WebDAV mount.
• Either way, write a file whole rather than appending to it on this backend, or write it through the file tools or the share's URL, until you are on 0.4.69 or later. The fix was confirmed on real hardware on 2026-08-11, and from agent 0.4.73 nobgp status stops naming it among the reasons auto declines winfsp. Two reasons remain from agent 0.4.75 — node-local locks and a slow create — so the backend is still opt-in.

macOS: Duplicate noBGP Volumes After Sleep

Symptoms: After the Mac wakes from sleep, the Computer view in Finder shows two nobgp volumes, one of which is dead. The agent logs an unmount that timed out or was refused around the same time.

Cause: The mount's health check reaches the router over the network, so a wake — or any brief connection reset — could fail the check on a mount that was perfectly healthy. The agent then tried to tear it down, the unmount was refused because the mount was live, and a second volume was mounted over the top, leaving Finder holding a row for a volume nobody unmounted. Fixed in 0.4.48: a mount must fail three consecutive checks, about a minute apart in total, before it is remounted, and the unmount on shutdown is given long enough to complete.

Solutions:

• Upgrade the agent (sudo nobgp upgrade), then sudo nobgp service restart.
• Clear an existing ghost by ejecting it in Finder, or with sudo diskutil unmount force /Volumes/nobgp. A dead row also disappears at the next reboot.
• nobgp status reports the mount the agent believes in under fs.mount and fs.mounted, which is the one to trust.

Use diskutil, not umount -f, on macOS

If sudo umount -f answers Operation not permitted — as root, with nothing open on the volume — that is macOS objecting to the volume going away rather than the mount being busy, and -f only overrides busy. sudo diskutil unmount force /Volumes/nobgp goes through the machinery that raised the objection and clears it. From agent 0.4.61 the agent escalates the same way on its own.

Shared Drive Times Out After an Agent Restart

Symptoms: On a node mounting over nfs, every operation on the drive hangs after the agent restarts or upgrades and then answers Operation timed out. nobgp status shows fs.type empty and fs.mounted: false while fs.backends still lists nfs: available — the node saying both that the backend it wants can serve and that it is not serving. On macOS a second nobgp volume may appear per restart. On 0.4.59 the same node reports fs.error: nfs: mount point /Volumes/nobgp: mkdir /Volumes/nobgp: file exists.

Cause: The agent's NFS server took a fresh loopback port on every start, while the kernel remembers the port the existing mount was made against. After a restart the mount pointed at a port nothing was listening on, and that leftover then held the mount point so the replacement mount failed too — a node retrying indefinitely with no way to repair itself. Agents 0.4.57 and 0.4.58 only, and only on the nfs backend.

Fixed in 0.4.59: the port is remembered per profile as nfs-port, so a restart binds the same one and the existing mount keeps working, and a mount left behind at the node's own mount point is cleared before mounting rather than stacked on top of.

Completed in 0.4.60. On 0.4.59 that clearing ran after the mount point was created, and a wedged mount makes its own mount point unanswerable — so creating it failed first and the clearing never ran, which is exactly the case it was written for. A node already stuck this way stayed stuck on 0.4.59 and needed an unmount by hand; from 0.4.60 the clearing runs first and the node repairs itself on its next mount cycle.

Completed on macOS in 0.4.61. On 0.4.60 the clearing ran at the right moment and could still be refused: a macOS unmount answers Operation not permitted — to root, with nothing holding the volume — when something has objected to the volume going away, and umount -f only overrides busy, which was never the problem. So a Mac already in this state stayed in it, every retry failing identically. From 0.4.61 the agent falls through to diskutil unmount force, which does override it, on both the shutdown path and the clearing.

Solutions:

• Upgrade the agent (sudo nobgp upgrade), then sudo nobgp service restart. On 0.4.60 and later that is enough on its own on Linux, and on 0.4.61 and later on macOS too — an already-wedged mount point is cleared on the next mount cycle, within about a minute.
• On earlier agents, clear a mount already stuck this way by hand — sudo diskutil unmount force /Volumes/nobgp on macOS, sudo umount -l /mnt/nobgp on Linux. Several mounts can be stacked at the same point, so repeat the command until it reports nothing is mounted there. The agent mounts again on its next cycle.
• On 0.4.59 and later, nobgp status names the reason there is no mount under fs.error, which is the field to read before assuming this is it. From 0.4.61 nobgp show answers the same question in its own output, as fs-backend and fs-error.

Linux: Shared Drive Is Empty and Never Mounts

Symptoms: On a Linux node, /mnt/nobgp is an empty directory, nobgp status reports fs.mounted: false, and everything else about the node is healthy. On agents before 0.4.51 the only sign in the logs is FUSE mount failed, will retry repeating once a minute, with no cause named.

Cause: A FUSE mount needs both halves — the kernel module and the userspace fusermount helper binary — and only the kernel half was declared by the packages. The kernel half being present is what makes the missing one invisible: /dev/fuse exists, so the agent correctly takes the FUSE path rather than falling back to WebDAV, and then cannot complete the mount. OpenWrt was the platform this actually happened on, because its packages are installed by install.sh rather than resolved by opkg, and neither the module nor the helper was being installed there.

Fixed in 0.4.51: every package declares the helper, the OpenWrt branch of the install script installs it explicitly, and a mount that fails for this reason is reported once as an error naming the package to install instead of as an endless retry warning.

Solutions:

• Read nobgp status first (agent 0.4.57+). Its fs block names the backend in use, why there is no mount under fs.error, and — under fs.backends — every backend this platform could use with the reason each can or cannot serve. That list is what tells you which package to install, and it may say the node has already mounted over NFSv4 instead, which needs nothing installed. See Which filesystem you get.
• Install the helper for your platform, then restart the agent:

  # OpenWrt
  opkg install kmod-fuse fuse-utils
  
  # Debian / Ubuntu
  sudo apt install fuse3
  
  # Alpine
  apk add fuse3
  
  # Amazon Linux / RHEL / Oracle / Rocky / AlmaLinux
  sudo dnf install fuse3
  
  sudo nobgp service restart

• Installing an NFSv4 client is an alternative to the FUSE helper, not only a fallback behind it — the node then mounts over NFS instead:

  # Debian / Ubuntu
  sudo apt install --no-install-recommends nfs-common
  
  # Amazon Linux / RHEL / Oracle / Rocky / AlmaLinux
  sudo dnf install nfs-utils
  
  # Arch Linux
  sudo pacman -S nfs-utils
  
  # Alpine
  apk add nfs-utils
  
  sudo nobgp service restart

  From agent 0.4.58 install.sh does this for you on Debian/Ubuntu, RPM hosts and Arch, so a node installed with that script or later already has it. Alpine, OpenWrt and Synology are deliberately left out. From agent 0.4.70 none of these commands is needed on Linux at all: with no mount helper installed the agent makes the NFS mount itself, so a host whose kernel has an NFSv4 client can take the backend with nothing installed. If nobgp status still reports nfs as unavailable on that release, the missing half is the kernel's client, and the message says so.
• sudo nobgp upgrade does not install the NFS client. No package declares it as a dependency — apt-get install would resolve that without ever running our installer, and it is the installer that confines the rpcbind the client drags in. So a node upgraded in place stays on whichever backend it can already serve; re-run the install script, or install the client by hand, to move it to NFS. On agent 0.4.70+ an in-place upgrade can move a node to NFS without any package, since only the kernel's own client is required there.
• Upgrade to agent 0.4.75 if a node has been sitting in this state. Until then each failed mount attempt left a background timer and a cleanup task behind it, and the retry runs every 30 seconds — so a node stuck this way accumulated roughly 2,880 of them a day, which on a router or a Pi-class box is memory it does not have. The node still could not mount, but it stopped paying for trying. It was the fuse backend alone; nfs and winfsp already cleaned up after a failed mount.
• Upgrade the agent (sudo nobgp upgrade) so a future recurrence names itself. On most package managers the upgrade also pulls the FUSE helper in, since the packages now declare it. RPM hosts are the exception: there it is a recommendation rather than a requirement, because EL7-class hosts (Amazon Linux 2, RHEL/Oracle/CentOS 7) have no fuse3 in their default repositories at all and a hard requirement would fail the whole install over an optional filesystem. dnf honours recommendations; yum and rpm ignore them, so those hosts still need the command above.
• The drive is optional. A node without it is fully functional otherwise — only the shared drive is unavailable, and the nobgp file commands fall back to the API automatically.

Linux: NFS Client Installed and the Drive Still Never Mounts

Symptoms: On a Linux node — in practice an embedded one, OpenWrt especially — the NFS client package is installed, nobgp status reports nfs: available, and the drive never comes up. fs.type is empty, fs.mounted is false, and the mount fails on every cycle without falling back to FUSE or WebDAV. Agents 0.4.61 and earlier.

Cause: An NFS client is two separate pieces, and on those distributions they are two separate packages: the userspace mount helper (nfs-utils, ~56 KB, which puts /sbin/mount.nfs4 on PATH) and the kernel's own NFSv4 client (kmod-fs-nfs-v4). The probe checked only the helper, so the node advertised a backend it could not mount with — and because a mount failure deliberately never falls through to another backend, it was left with no shared drive at all rather than the FUSE one it could have had.

Fixed in 0.4.62: the probe asks the kernel too, so such a host reports nfs as unavailable and auto moves on to FUSE. nobgp status names which half is missing, since the remedies differ — "install the NFS client" is useless advice to someone who just did.

Solutions:

• Install the kernel half as well, matching the running kernel, then restart the agent:

  # OpenWrt
  opkg install kmod-fs-nfs-v4
  
  nobgp service restart

  kmod-fs-nfs without -v4 is not enough — the agent mounts NFSv4 only, and a v2/v3-only kernel cannot serve it.
• Or upgrade the agent (sudo nobgp upgrade) and let it fall back: on 0.4.62+ a host in this state mounts over FUSE instead of not mounting at all.
• Installing the module is enough on its own — the agent asks the kernel to load it and retries that every five minutes, so the drive appears on a later mount cycle without waiting for a reboot.
• On agent 0.4.70+ the kernel module is the only half that matters on Linux: the userspace package is no longer required, so kmod-fs-nfs-v4 (or your distribution's equivalent) is the whole remedy, and a container that cannot load modules is served by the host kernel loading them on demand.

Linux/macOS: The Drive Never Comes Back and the Error Says "Resource busy"

Symptoms: The drive goes away and never returns. nobgp status shows fs.type empty and fs.mounted: false, fs.backends still says the backend is available, and fs.error reports a mount failure ending in Resource busy or mount point is busy — on every retry, indefinitely. Nothing is listed in the machine's mount table for that path.

Cause: The old mount was torn down, so there is nothing left for the agent to unmount, but some process still holds the mount-point directory open — a shell sitting in it, a Finder window, an editor, a backup agent. The kernel refuses to mount over a directory in that state, and the agent has nothing it can safely do about it: a forced unmount cannot dislodge a live holder, and killing whatever is holding the directory is not a decision the agent takes on your behalf.

Solutions:

• On agent 0.4.70+, read fs.error — it names the processes and their PIDs (held by bash(4821), Finder(512), which must exit before the mount can recover). End those, and the mount retry that is already running brings the drive back on its next cycle. No restart is needed.
• On an older agent, find them yourself with lsof /mnt/nobgp (/Volumes/nobgp on macOS) — or fuser -v on Linux — and do the same.
• If the message says no holder could be named, lsof is either missing or defeated by the wedge. A reboot always clears it.
• Switching backends is not a way out, because the directory is what is pinned and every backend on the platform mounts on the same one. Through agent 0.4.74 only an nfs mount reported the wedge at all: a Mac pinned to fs: webdav hit the same refusal with fs.error left empty, which is the shape to recognise on those versions — fs.mounted: false, a backend reported as available, and no reason given. From agent 0.4.75 webdav reports it in the same words, and from 0.4.78 so does fuse — which matters most on Linux, where fuse is what the majority of nodes mount with, and where through 0.4.77 the answer was generic advice to go and run fuser -m on the box yourself. A winfsp volume is the one that still says nothing: a refused mount there reports no reason for us to pass on, and Windows has no lsof to name a holder with, so on that backend the shape above is still what you have to recognise.

Linux/macOS: The Drive Path Hangs on a Node That Mounts Nothing

Symptoms: nobgp status says fs.mounted: false — often with fs.type empty because the node is set to fs: off, or has no mount point at all — and yet reading the mount path hangs or errors instead of showing an empty directory. The machine's own mount table (mount | grep nobgp, or mount on macOS) still has an entry for that path.

Cause: A previous agent was killed while the drive was mounted — a SIGKILL, an out-of-memory kill, a host reset, a crash in the mount driver — so it never got to unmount, and the agent that replaced it was configured not to mount anything. Through agent 0.4.77 those startup paths returned before ever looking at the mount table, so the leftover was never touched again and the agent's report genuinely did not describe the kernel. An orderly stop or restart was never affected.

Solutions:

• Upgrade the agent (sudo nobgp upgrade) and restart the service. From agent 0.4.78 the leftover is cleared at startup — the kernel is asked what is mounted there and only a mount made by this agent's own backends is removed, so nothing else on that path is disturbed. See A mount left behind when the node is not going to mount.
• On an older agent, or if the unmount is refused (it is not forced on this path, and is retried at the next start), clear it by hand: sudo umount -l /mnt/nobgp on Linux, sudo diskutil unmount force /Volumes/nobgp on macOS.
• Windows is not covered by the automatic clearing. A leftover there is a drive mapping — remove it with net use <letter>: /delete.

Linux: The Shared Drive Is Mounted but Bulk Copies Crawl

Symptoms: On a Linux node mounting over nfs, the drive mounts, lists and reads correctly, and nothing reports an error — but copying anything large onto or off it takes tens of times longer than it should. An 8 MiB write takes seconds where a fuse mount on the same machine takes a fraction of one. Agents 0.4.70 and earlier.

Cause: The kernel's NFS client sizes each read and write from what the server advertises as its maximum, not from the rsize/wsize the mount asked for. The agent's server advertised no maximum, and Linux reads that as an unknown one and falls back to its own 1 KiB floor — so a mount that asked for 128 KiB got 1 KiB, and every transfer was split into ~128× as many requests. macOS honours the requested size either way and was never affected.

Solutions:

• Upgrade to agent 0.4.71+ (sudo nobgp upgrade) and let the drive remount. The server advertises the size it serves, and the client negotiates 128 KiB. Nothing needs configuring.
• Confirm what the mount actually settled on — the mount options do not tell you, since these are the negotiated values:

  nfsstat -m                      # or:
  grep nobgp /proc/mounts         # rsize=131072,wsize=131072 once fixed

• On an agent you cannot upgrade yet, a Linux host with a usable /dev/fuse and fusermount mounts over FUSE by default; if the node is on nfs because fs: nfs is pinned, unpinning it moves the node to a backend this never touched.

Node Restarts Every Time the Machine Wakes

Symptoms: A laptop or desktop that sleeps shows its node dropping offline and coming back around each wake, and nobgp status reports a small uptime_secs even though the machine itself has been up for hours. On macOS a dead nobgp volume may be left behind by the restart.

Cause: In the first seconds after a wake the resolver has no servers yet and the interface has not been handed its address back, so the agent's first attempt to reach the router fails with a name-resolution or no-route error. Until 0.4.49 that was treated as fatal: the agent exited, the filesystem mount came down with it, and the service manager restarted it with its backoff — for a machine that was seconds away from being fine. Fixed in 0.4.49: registration and the mid-run reconnect retry in place for up to five minutes while the only thing wrong is that the network is absent, logging the network looks absent, retrying in … as they wait.

Solutions:

• Upgrade the agent (sudo nobgp upgrade), then sudo nobgp service restart.
• On 0.4.49 and later, read the agent's own line before assuming this is it: only the absent-network errors are retried, so a restart at wake that logs anything else — a rejected credential, for example — is a different problem. See Credentials Rejected / Node Deauthorized.
• A node that stays unreachable for longer than five minutes after a wake still restarts, which is intended — beyond that, a clean start is more likely to help than more waiting.

Can't Reach Other Nodes

Symptoms: Node is online but can't communicate with other nodes

Solutions:

• Verify all nodes are in the same network
• Check that all nodes show as "online"
• Ensure encryption settings match across nodes
• Review network-level firewall rules
• Run nobgp status on both ends: an environment.tunnels entry means another VPN client on that machine holds an active adapter and may be swallowing overlay traffic — see Security software and VPNs

Credentials Rejected / Node Deauthorized

Symptoms: The agent logs the router rejected this node's credentials, and the node stays offline.

Cause: The node was deleted, its key was revoked, or the network was removed on the server side, so the router no longer accepts this node's credentials.

Solutions:

• Re-enroll the node: sudo nobgp register.
• Or remove the install entirely: sudo nobgp service uninstall.
• Until you act, the agent paces its retries (roughly every 15 minutes) instead of hammering the router.

Registration Token Expired

Symptoms: The node is offline and nobgp status reports the profile under unavailable with registration token expired <instant> — the router refuses its connections; re-register with 'nobgp register'. nobgp show prints the same instant on a token-expired line.

Cause: The node's registration token expired while it was offline. A token is normally refreshed over the node's authenticated connection, and an expired one cannot make that connection — so nothing on the node can repair it on its own.

Solutions:

• Re-enroll the node: sudo nobgp register. On agent 0.4.72+ this replaces the expired token under the node's existing identity key, so the node keeps its place in the network.
• On 0.4.71 and earlier that command answers Agent is already registered. and does nothing. Upgrade first (sudo nobgp upgrade -f, which needs no registration), then re-register.
• Before 0.4.72 the reason above is not reported either: the profile reads as an ordinary stopped agent, because the agent is being started, is refused, and is paced fifteen minutes out — so nobgp status almost always catches it between attempts. On such a node, treat start it with 'nobgp service start' that never helps as a reason to check the token.

Agent Version No Longer Supported

Symptoms: The node never comes online, and the agent logs a rejection reason such as agent version no longer supported (pre-0.3.51): reinstall the current agent.

Cause: The agent build is older than the minimum supported version. Agents below that floor are refused at registration — no node record is created or modified, so nothing on the server side needs cleaning up.

Solutions:

• Run sudo nobgp upgrade -f on the host. This is the smallest fix: it does not require the node to be registered, and on an unregistered machine it installs the stable channel version.
• If the agent binary is too old to upgrade itself, reinstall it with the install script.
• Then confirm the result with nobgp version and nobgp show.

Upgrading

Minimum Supported Agent Version

The router refuses registration from agents older than 0.3.51. Those builds predate the current overlay addressing model and cannot operate on the network, so they are rejected with a clear reason (agent version no longer supported) rather than being allowed to connect and fail later.

Any agent on 0.3.51 or newer registers normally. Nodes with auto-upgrade enabled stay well ahead of this floor on their own — this only affects machines that have been offline or pinned to an old build for a long time. Recovering one is a reinstall or a single sudo nobgp upgrade -f.

Manual Upgrade

Run the upgrade command on any registered node:

Linux / macOS

sudo nobgp upgrade               # Upgrade to this node's channel version
sudo nobgp upgrade -y            # Same, without confirmation prompts

Windows

nobgp upgrade                    # Upgrade to this node's channel version
nobgp upgrade -y                 # Same, without confirmation prompts

Run in an Administrator terminal.

Without a version, nobgp upgrade installs this node's release-channel version — the same version automatic upgrades install. On a machine that isn't registered, the stable channel is used. A test or pre-release build is never installed unless you name its version explicitly.

To upgrade to a specific version:

sudo nobgp upgrade 0.4.2

Anything off the safe path asks for confirmation first (with a "no" default). A version ahead of the node's channel, or one that can't be verified, is answered by -y. A downgrade or reinstall requires -f — -y alone won't authorize it (so a stray -y in a script can never downgrade a node):

sudo nobgp upgrade 0.4.2 -f      # Downgrade or reinstall without prompts

-f covers everything -y does. Run bare sudo nobgp upgrade -f to converge a node that is ahead of its channel back down to the channel version.

warning

Don't downgrade a node below the minimum supported version (0.3.51). The install itself succeeds, but the router then refuses the node's registration and it stays offline until you upgrade it again.

Running agents detect the new binary and restart automatically — no manual service restart needed.

Auto-Upgrade

The agent supports automatic upgrades driven by the router. When a new version is released, the router signals all connected agents and they upgrade themselves in the background.

Auto-upgrade is enabled by default. To disable it, add this to your configuration file:

auto-upgrade: false

Since agent 0.4.35 the key is already in the file as a commented default (# auto-upgrade: true) — uncommenting that line and setting it to false does the same thing. Either way the agent keeps the key, because its value is now a choice rather than the default.

tip

Auto-upgrade is safe to leave enabled. It never downgrades, never reinstalls the same version, and requires SHA-256 checksum verification. Only packages from the official CDN are accepted.

How Upgrades Work

Regardless of whether the upgrade is manual or automatic:

1. The agent downloads the platform-appropriate package from downloads.nobgp.com
2. The SHA-256 checksum is verified (required — upgrade fails if unavailable)
3. A lock flag prevents the service from being stopped mid-upgrade
4. The package is installed via the platform's native package manager
5. The running agent detects the new binary via mtime polling and restarts

Step 5 waits for step 4 to finish. Since 0.4.48 the watcher holds off while an upgrade is installing, so a slow install — a Raspberry Pi Zero spends about a minute unpacking a package — is not interrupted by the restart it is about to trigger. Before that, such a node came up on the new version but logged auto-upgrade failed and paused for five minutes before it would try again.

How the restart happens depends on how the agent runs:

• On systemd (Linux) and Windows: the whole service is restarted, so both the background supervisor and the agent it manages come up on the new binary — this prevents the supervisor from being stranded on the old version. Expect a brief reconnect while the service restarts.
• In containers, in the foreground, and on macOS: the agent re-execs itself in place. The old binary inode stays open until the restart, so in-flight connections are not interrupted.

On Windows the running executable is renamed and the new binary is moved into place atomically, with automatic rollback if the replacement fails.

On macOS and Synology DSM there is no package manager, so step 4 instead downloads the raw static binary and atomically swaps it into place. On DSM the agent fetches the binary published alongside the Alpine .apk rather than the .apk itself.

Resilient downloads

The package download in step 1 is resumable, so upgrades survive flaky or slow connections:

• If a transfer is interrupted, the next attempt continues from where it left off instead of starting over — the partially downloaded file is kept between attempts.
• A stalled connection (no data received for 60 seconds) is aborted and retried automatically rather than hanging.
• Before writing, the agent checks that the staging filesystem has enough free space and fails early with a clear error if it doesn't.

Because progress is preserved, an auto-upgrade on an unreliable link makes forward progress each time the router re-offers it, rather than repeatedly re-downloading from the beginning. The SHA-256 checksum is still verified against the fully assembled package before anything is installed.

Debian and Ubuntu hosts

Step 4 normally installs the .deb with apt-get. Two host conditions make apt refuse the install outright, and the agent recovers from both on its own:

• The host's own dependency tree is broken. If unrelated packages on the machine have unmet dependencies (a common cause is a hand-installed .deb from a different release), apt refuses every install, including ours. The agent falls back to dpkg -i, which enforces only the noBGP package's own dependencies (iptables, procps, ca-certificates — already present on any host running the agent) and leaves the pre-existing breakage exactly as it found it. The agent deliberately does not run apt --fix-broken install, because that removes whichever of your packages conflict — a decision for you to make, not a side effect of an upgrade.
• A previous package operation was interrupted. If dpkg's journal was left stranded (E: dpkg was interrupted, you must manually run 'dpkg --configure -a'), the agent runs that repair once and retries the install.

Neither fallback touches a package operation you are running yourself: lock contention from a concurrent apt/dpkg is left alone, and the upgrade is simply retried later.

If the fallback also fails, the agent reports both errors and the node stays on its current version. That means your host genuinely needs attention — resolve the broken dependencies with sudo apt --fix-broken install (reviewing what it proposes to remove) and the next upgrade attempt will succeed.

The install script applies the same apt → dpkg fallback, so a first-time install on a host with a broken dependency tree works too.

Uninstallation

The simplest way to remove noBGP on any platform is the built-in nobgp uninstall command. It stops and removes the service, deletes the binaries, and clears runtime files in one step:

# Keep the node identity so a reinstall re-enrolls as the same node
sudo nobgp uninstall

# Fully remove the agent, including configuration and credentials
sudo nobgp uninstall --purge

By default the command keeps the profile's identity files (.key, .jwt, .yml) so that reinstalling later restores the machine as the same node. Add --purge to remove the configuration directory too, so a subsequent reinstall enrolls a brand-new node. Pass --force (-f) to skip the confirmation prompt. On Windows, run it from an Admin PowerShell session.

If you installed via a package manager and prefer to remove noBGP that way instead, the manual steps below still work.

Linux

# Stop and uninstall service
sudo nobgp service uninstall

# Remove the agent binary (location varies by distro)
# Ubuntu/Debian:
sudo apt purge nobgp

# Alpine:
sudo apk del nobgp

# Or manually:
sudo rm $(which nobgp)

# Remove configuration
sudo rm -rf /etc/nobgp/

info

apt remove vs apt purge:

• apt remove leaves configuration files intact
• apt purge completely removes configuration files
• If configuration files are present when reinstalling, the device will be automatically restored to its previously configured state

macOS

# If installed via Homebrew
brew uninstall nobgp

# If installed via install.sh
sudo nobgp service uninstall
sudo rm $(which nobgp)
sudo rm -rf /usr/local/etc/nobgp/

Windows

Run the following in an Admin PowerShell session:

# Stop and uninstall service
nobgp service uninstall

# Remove the agent binary and configuration
# (The installer places nobgp.exe in C:\Program Files\nobgp\)
Remove-Item -Recurse -Force "C:\Program Files\nobgp"
Remove-Item -Recurse -Force "C:\ProgramData\nobgp"

Next Steps

Now that your agent is installed:

• Provision Additional Nodes - Create cloud instances through your AI assistant
• Publish Services - Expose web applications and terminals
• Interactive Terminals - Use browser-based shells
• Raspberry Pi Setup - Connect your Pi devices

Support and Resources

• Official Documentation: https://docs.nobgp.com/
• Official Website: https://www.nobgp.com/
• Contact Support: https://www.nobgp.com/contact

License

The noBGP agent and noBGP router are proprietary software. All rights reserved. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited. Users of the software must comply with the terms of the license agreement.

For licensing inquiries, please contact licensing@nobgp.com.