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

There are two ways to set up your noBGP agent: using a configuration code (recommended) or manual configuration.

Quick Start with Configuration Code (Recommended)

The simplest way to install and configure the noBGP agent is using a configuration code. This method automatically sets up your agent with the correct network key and node name in a single command.

How it works:

1. Generate a configuration code through the noBGP web application or via your AI assistant
2. The code is valid for 1 hour and contains your network configuration
3. Run the installation command with the code
4. Your agent is automatically installed and configured

Installation with configuration code:

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

Replace YOUR_CODE_HERE with the 8-character code you received. This command:

• Downloads and installs the correct package for your platform
• Retrieves your network configuration from the noBGP router
• Sets up your agent with the appropriate network key and node name
• Creates the configuration file at /etc/nobgp/default.yml
• Enables the agent to connect immediately

tip

When using your AI assistant with noBGP integration, it can generate the configuration code and provide you with the complete installation command automatically.

Alternative: Manual Configuration

If you prefer to manually configure your agent, you can obtain a network key from the web dashboard:

1. Visit https://app.nobgp.com
2. Create an account or sign in
3. Navigate to the "Networks" section
4. Create a new network or select an existing one
5. Copy the network key (base64 format, e.g., VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ=)

The network key authenticates your nodes and connects them securely to your private network. You can modify or revoke this key via the web interface or generate new keys with different permissions for the same network.

warning

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

Installation

Quick Installation

noBGP provides an installation script that detects your system and installs the appropriate agent package. You can use either curl or wget:

Using curl:

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

# Install a specific version
curl -sSL https://downloads.nobgp.com/agent/install.sh | sudo NOBGP_VERSION=0.2.1 sh

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

Or using wget:

# Download and run the installation script
wget -qO- https://downloads.nobgp.com/agent/install.sh | sudo sh

The installation script supports:

• Alpine Linux 3.16+
• Amazon Linux 2023+
• Debian 11+ / Ubuntu 20.04+

And the following architectures:

• amd64 (x86_64)
• arm64 (aarch64)

After installation, the nobgp command will be available in your system. After configuration, you can run the noBGP agent as a standalone process or system service.

Docker Installation

To run nobgp within a docker container, add the following options:

docker run -it --cap-add NET_ADMIN --device=/dev/net/tun alpine

Once within the container, you can install curl and then run through the installation script.

Docker Compose Example

Using configuration code (recommended):

version: '3.8'
services:
  nobgp:
    image: alpine:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - NOBGP_CONFIG=YOUR_CODE_HERE
    command: >
      sh -c "apk add --no-cache curl &&
             curl -sSL https://downloads.nobgp.com/agent/install.sh | NOBGP_CONFIG=${NOBGP_CONFIG} sh &&
             nobgp agent"
    restart: unless-stopped

Using manual configuration:

version: '3.8'
services:
  nobgp:
    image: alpine:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - NOBGP_NETWORK_KEY=your_network_key_here
      - NOBGP_NODE_NAME=docker-node-1
    command: >
      sh -c "apk add --no-cache curl &&
             curl -sSL https://downloads.nobgp.com/agent/install.sh | sh &&
             nobgp agent"
    restart: unless-stopped

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 located at /etc/nobgp/default.yml. A minimal configuration file looks like:

network-key: "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="
node-name: "web-server-1"
router: "wss://router.nobgp.com"

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 configuration, the agent uses /etc/nobgp/default.yml as the default configuration file. The agent also supports multiple configurations (see Multi-Configuration Support below).

Configuration Options

Config File Key	Command Line Option	Environment Variable	Required	Description	Default
network-key	-k --key	NOBGP_NETWORK_KEY	Yes	Authentication key for the network	(required)
node-name	-n --name	NOBGP_NODE_NAME	No	Name of the node in the network	Hostname
router	-r --router	NOBGP_ROUTER	No	URL of the noBGP router	wss://router.nobgp.com
debug	-d --debug	NOBGP_DEBUG	No	Enable debug mode	false
log-level	-l --log-level	NOBGP_LOG_LEVEL	No	Logging level (error, warning, info, debug, trace)	info
compress	-z --compress	NOBGP_COMPRESS	No	Enable compression	true
encrypt	-e --encrypt	NOBGP_ENCRYPT	No	Require encryption	true
interface	-i --interface	NOBGP_INTERFACE	No	Network interface to use	auto
ping-interval	--ping	NOBGP_PING_INTERVAL	No	Interval for connection health checks	58s

Using the Config Command

Create or update your configuration using the nobgp config command:

# Set the network key
sudo nobgp config --key "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ="

# Set the node name
sudo nobgp config --name "web-server-1"

# Set the router URL
sudo nobgp config --router "wss://custom-router.example.com"

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

Quick Configuration

For a quick setup, run the nobgp config command without parameters:

sudo nobgp config

This starts an interactive session where you'll be prompted to enter or confirm values for required configuration options:

Agent Configuration
===================
Press Enter to keep current values, or type new values.

network-key:
node-name: web-server-1

Configuration saved to /etc/nobgp/default.yml

Environment Variables

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

Example:

export NOBGP_NETWORK_KEY="your_key_here"
export NOBGP_NODE_NAME="api-server-1"
export NOBGP_DEBUG=true
sudo -E nobgp agent

Command Line Options

Override configuration settings with command line options when running nobgp:

sudo nobgp agent --key "YOUR_NETWORK_KEY" --name "web-server-1" --debug

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-Configuration Support

The noBGP agent supports running multiple configurations simultaneously, allowing you to connect a single machine to multiple noBGP networks or use different network keys on the same host.

How it works:

• Each configuration is stored as a separate YAML file in /etc/nobgp/
• Configuration files are named by their configuration name (e.g., /etc/nobgp/production.yml, /etc/nobgp/staging.yml)
• When running as a service, the process manager automatically starts an agent instance for each configuration file
• The default configuration is named default (file: /etc/nobgp/default.yml)

Managing configurations:

# List all configurations
sudo nobgp list

# Show details of a specific configuration
sudo nobgp show production

# Show default configuration
sudo nobgp show

# Remove a configuration
sudo nobgp remove staging

# Create or update a named configuration
sudo nobgp config --name production --key "YOUR_NETWORK_KEY" --node-name "prod-server-1"

Running multiple configurations:

When installed as a service, all configurations in /etc/nobgp/ are automatically managed:

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

# Start all configurations
sudo nobgp service start

# Check status of all running instances
sudo nobgp service status

To run a specific configuration manually:

# Run the production configuration
sudo nobgp agent --config production

# Run the default configuration (can omit --config)
sudo nobgp agent

note

When using nobgp config without specifying a configuration name, it modifies the default configuration. To create or modify a named configuration, use the --name 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.

important

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

# 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

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-based system
  • Alpine Linux 3.16+
  • Amazon Linux 2023+
  • Debian 11+ / Ubuntu 20.04+
• Privileges: Root or sudo access
• Network: Connectivity to the noBGP router
• Architecture: amd64 (x86_64) or arm64 (aarch64)
• 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: sudo journalctl -u nobgp.service -f (when running as a service)
3. Verify the configuration file: cat /etc/nobgp/default.yml
4. Ensure your network key is valid and correctly entered
5. Check that the router URL is accessible from your machine
6. Verify that you have root privileges when running the noBGP agent

Common Issues and Solutions

Issue	Possible Cause	Solution
Connection failed	Invalid network key	Verify key in web interface
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

Detailed Troubleshooting

Agent Won't Start

Symptoms: Service fails to start or exits immediately

Solutions:

• Check system requirements are met
• Verify network key format (should be base64)
• 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
• Check network key hasn't been regenerated
• 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

Uninstallation

To completely remove noBGP:

# Stop and uninstall service
sudo nobgp service stop
sudo nobgp service uninstall

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

# Alpine:
sudo apk del nobgp

# Or manually:
sudo rm $(which nobgp)

# Remove configuration
sudo rm -rf /etc/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/
• GitHub Repository: https://github.com/nobgp/nobgp-agent
• 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.