Skip to main content

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.

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

Or on macOS with Homebrew:

brew install nobgp/tap/nobgp

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

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).

Windows​

Run the following in an Admin PowerShell session (run as Administrator):

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. It will exit with a clear error message if not elevated — there is no automatic UAC prompt.

If you're working from Command Prompt (cmd.exe), use this wrapper:

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

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

The installation scripts support the following architectures:

  • amd64 (x86_64)
  • arm64 (aarch64)
  • armv6 and armv7 (Debian/Ubuntu only, for Raspberry Pi and similar devices)

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 -it --cap-add NET_ADMIN --device=/dev/net/tun \
  -e NOBGP_KEY=<YOUR_REGISTRATION_KEY> \
  -e NOBGP_NAME=docker-node-1 \
  alpine

Once within the container, install curl and run the installation script.

Docker Compose Example​

version: '3.8'
services:
  nobgp:
    image: alpine:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - NOBGP_KEY=<YOUR_REGISTRATION_KEY>
      - NOBGP_NAME=docker-node-1
    command: >
      sh -c "apk add --no-cache curl &&
             curl -fsSL https://downloads.nobgp.com/agent/install.sh | NOBGP_KEY=${NOBGP_KEY} sh &&
             nobgp agent"
    restart: unless-stopped

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:

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

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: "wss://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

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.

DestinationProtocolPurpose
router.nobgp.com:443WebSocket (wss://)Persistent control plane connection
downloads.nobgp.comHTTPSPackage downloads and updates
files.nobgp.comHTTPSFile sharing (WebDAV/FUSE backend)

If you're behind a corporate firewall or restrictive network, ensure these destinations are allowed for outbound traffic on port 443.

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

After registration, a typical configuration file looks like:

router: "wss://router.nobgp.com"
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 KeyCommand Line OptionEnvironment VariableDescriptionDefault
router-r
--router		NOBGP_ROUTERURL of the noBGP routerwss://router.nobgp.com
debug-d
--debug		NOBGP_DEBUGEnable debug modefalse
log-level-l
--log-level		NOBGP_LOG_LEVELLogging level (error, warning, info, debug, trace)info
compress-z
--compress		NOBGP_COMPRESSEnable compressiontrue
encrypt-e
--encrypt		NOBGP_ENCRYPTRequire encryptiontrue
interface-i
--interface		NOBGP_INTERFACENetwork interface to useauto
ping-interval--pingNOBGP_PING_INTERVALInterval for connection health checks58s
mount-m
--mount		Filesystem mount pointPlatform-dependent
user--userDefault user for command sessions and filesystem
auto-upgradeNOBGP_AUTO_UPGRADESet to false to disable automatic router-driven upgradestrue

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

OptionEnvironment VariableDescription
--keyNOBGP_KEYRegistration key for the network
--nameNOBGP_NAMENode 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 prompts to install and start the system service.

Using the Config Command​

Update runtime configuration for a registered agent:

# Set the router URL
sudo nobgp config --router "wss://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
  • Network 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

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.

important

Service commands do not work in Docker containers. Use process management or orchestration tools instead.

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
    • 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; Linux and macOS only)
  • 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): 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-WinEvent -FilterHashtable @{LogName='Application';ProviderName='nobgp'}
  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​

IssuePossible CauseSolution
Connection failedNot registeredRun sudo nobgp register
Service won't startMissing permissionsCheck sudo access
Node not visibleFirewall blockingCheck router access
Agent crashesIncompatible OSVerify OS version support
High CPU usageDebug mode enabledDisable debug in production
Windows install failsNot running as AdminRun PowerShell as Administrator
macOS service failsSIP or permissionsCheck /Library/Logs/nobgp/

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

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

Upgrading​

Manual Upgrade​

Run the upgrade command on any registered node:

sudo nobgp upgrade               # Upgrade to the latest version
sudo nobgp upgrade -y            # Upgrade without confirmation prompt
sudo nobgp upgrade -f            # Force install even if same or older version

To upgrade to a specific version:

sudo nobgp upgrade 0.3.0

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

Or set the environment variable before starting the agent:

export NOBGP_AUTO_UPGRADE=false
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 itself

On Linux 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.

Uninstallation​

To completely remove noBGP:

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:

Support and Resources​

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.