CLI Reference
Complete command-line reference for the noBGP agent. This covers all commands, options, and configuration methods.
Overview
The nobgp command-line tool provides:
- User authentication — log in from your personal machine to manage your infrastructure
- Remote operations — execute commands, open shells, and manage services on your nodes
- File management — upload, download, list, and delete files on the shared filesystem
- Network and node management — list, create, and register infrastructure
- Agent runtime — registration, configuration, service control, and upgrades
Command Structure
nobgp [command] [options]
Commands
nobgp agent
Run the noBGP agent as a standalone process. If not yet registered, the agent will auto-register non-interactively (requires a registration key in config or environment).
Usage:
nobgp agent [profile] [options]
Examples:
# Run with default profile from /etc/nobgp/default.yml
sudo nobgp agent
# Run a specific profile
sudo nobgp agent production
# Run with debug output
sudo nobgp agent --debug
# Run with custom log level
sudo nobgp agent --log-level debug
Global Options (available on all commands):
| Option | Short | Type | Description |
|---|---|---|---|
--router | -r | string | Router WebSocket URL (default: wss://router.nobgp.com) |
--debug | -d | boolean | Enable debug mode (shortcut for --log-level debug) |
--log-level | -l | string | Log level: error, warning, info, debug, trace (default: info) |
--compress | -z | boolean | Enable compression (default: true) |
--encrypt | -e | boolean | Require encryption (default: true) |
--interface | -i | string | Network interface to use (default: auto) |
--ping | duration | Ping interval for health checks (default: 58s) | |
--mount | -m | string | Filesystem mount point (default: platform-dependent) |
--user | string | Default user for command sessions and filesystem |
Exit Codes:
0- Clean shutdown1- General error2- Configuration error3- Network error
nobgp register
Register the agent with a noBGP network. Opens your browser for OAuth login by default. For Docker/automation, pass a registration key with --key for non-interactive registration.
Usage:
nobgp register [profile] [options]
Examples:
# Register via OAuth browser login (recommended)
sudo nobgp register
# Register with a specific name and network
sudo nobgp register --name "my-server" --network "production"
# Register a named profile
sudo nobgp register production --name "prod-server-1"
# Register with a key (for Docker/automation)
sudo nobgp register --key "<YOUR_REGISTRATION_KEY>" --name "my-server"
Options:
| Option | Type | Description |
|---|---|---|
--key | string | Registration key for the network |
--name | string | Node name (defaults to hostname) |
--network | string | Network name (for OAuth login flow) |
After successful registration, the agent prompts to install and start the system service.
Login vs Register
The nobgp CLI has two authentication concepts that serve different purposes:
nobgp login | nobgp register | |
|---|---|---|
| Purpose | Authenticate you (the user) | Authenticate a device (the node) |
| When to use | On your personal machine — laptop, desktop, workstation | On a remote server, VM, Raspberry Pi, or container |
| What it does | Stores your user credentials so you can run management commands (network, node, exec, shell, proxy) | Enrolls the machine as a node in a noBGP network and starts the agent |
| Requires | A browser (opens OAuth login) | Either a browser or a registration key (--key) |
| Runs as | Your user account | Root / Administrator |
Typical workflow:
- On your laptop, run
nobgp loginto authenticate yourself. This lets you manage your infrastructure from the command line. - On a remote server, run
sudo nobgp register(or use a registration key) to join the machine to your network as a node. - From your laptop, use
nobgp exec,nobgp shell,nobgp proxy, etc. to operate on your remote nodes.
You don't need to install or run the agent on your laptop — nobgp login is enough to use the management commands.
nobgp login
Log in to noBGP from your personal machine. Opens your browser for OAuth sign-in and stores credentials in your system keyring.
Usage:
nobgp login
Credentials are stored in the platform's native credential store:
- macOS: Keychain
- Linux: Secret Service (GNOME Keyring, KDE Wallet, etc.)
- Windows: Credential Manager
Once logged in, you can use all management commands (network, node, exec, shell, proxy) without the agent running locally.
Example:
$ nobgp login
Opening browser for login...
Login successful!
If the browser doesn't open automatically, the CLI prints a URL you can copy and paste.
nobgp logout
Clear stored credentials from your system keyring.
Usage:
nobgp logout
Example:
$ nobgp logout
Logged out.
nobgp network
Manage noBGP networks. Requires nobgp login first.
Usage:
nobgp network <subcommand> [options]
Subcommands:
list
List all your networks, nodes, and published services. Nodes are grouped by online/offline status.
nobgp network list [options]
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Filter by network name |
--json | boolean | Output as JSON |
Examples:
# List everything
nobgp network list
# Filter to one network
nobgp network list --network production
# Machine-readable output
nobgp network list --json
Example output:
production
Online:
web-server (debian) 550e8400-e29b-41d4-a716-446655440000
staging-app https://a1b2c3d4.nobgp.com
api-server (debian) 660f9500-f39c-42e5-b827-557766550111
Offline:
old-server (ubuntu) 770a0600-a40d-53f6-c938-668877660222
create
Create a new network.
nobgp network create --name <name> [options]
Options:
| Option | Type | Description |
|---|---|---|
--name | string | Network name (required, DNS-compatible) |
--json | boolean | Output as JSON |
Example:
nobgp network create --name staging
add-node
Generate install commands for adding a node to your network. The output is meant to be copied and run on the target machine.
nobgp network add-node [options]
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Network name (uses default if you have one network) |
--node | string | Node name (defaults to hostname on the target machine) |
--json | boolean | Output as JSON |
Example:
$ nobgp network add-node --network production --node web-server-2
── Run on the target machine ──────────────────────────
Linux/macOS:
curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo NOBGP_KEY=... NOBGP_NAME=web-server-2 sh
Windows (PowerShell):
$env:NOBGP_KEY="..."; $env:NOBGP_NAME="web-server-2"; irm https://downloads.nobgp.com/agent/install.ps1 | iex
Windows (CMD):
set "NOBGP_KEY=..." && set "NOBGP_NAME=web-server-2" && curl -fsSL https://downloads.nobgp.com/agent/install.cmd -o install.cmd && install.cmd
────────────────────────────────────────────────────────
The registration key shown above (NOBGP_KEY=...) can be reused across multiple nodes and does not expire. You can disable it at any time from the noBGP dashboard.
nobgp exec
Execute a command on a remote node and print the output. The remote process's exit code is propagated to the local shell.
Requires nobgp login first.
Usage:
nobgp exec -c <command> [options]
Options:
| Option | Short | Type | Description |
|---|---|---|---|
--command | -c | string | Command to execute (required) |
--node-id | string | Node UUID | |
--network | string | Network name | |
--node | string | Node name | |
--username | string | OS user to run as | |
--workdir | string | Working directory | |
--timeout | int | Max seconds to wait for command to complete (default 300) |
You must specify the target node using either --node-id or both --network and --node.
Examples:
# Run a command by network and node name
nobgp exec -c "df -h" --network production --node web-server
# Run a command by node UUID
nobgp exec -c "systemctl status nginx" --node-id 550e8400-e29b-41d4-a716-446655440000
# Run as a specific user in a specific directory
nobgp exec -c "git pull" --network production --node api-server --username deploy --workdir /srv/app
# Run a long command with a custom timeout (default is 300s)
nobgp exec -c "pg_dump mydb | gzip > /tmp/backup.sql.gz" --network production --node db-server --timeout 600
Exit codes:
The remote command's exit code is forwarded. This means you can use nobgp exec in scripts:
nobgp exec -c "test -f /etc/nginx/nginx.conf" --network prod --node web-1 && echo "nginx configured"
nobgp shell
Open an interactive shell session on a remote node. Provides a full terminal experience with raw mode, resize handling, and support for interactive programs (vim, htop, etc.).
Requires nobgp login first.
Usage:
nobgp shell [options]
Options:
| Option | Type | Description |
|---|---|---|
--node-id | string | Node UUID |
--network | string | Network name |
--node | string | Node name |
--command | string | Shell command (default: login shell) |
--username | string | OS user |
--workdir | string | Working directory |
You must specify the target node using either --node-id or both --network and --node.
Examples:
# Open a shell on a node
nobgp shell --network production --node web-server
# Open a shell as a specific user
nobgp shell --network production --node api-server --username deploy
# Run a specific command instead of the default shell
nobgp shell --network production --node db-server --command "psql -U postgres"
nobgp shell is not yet supported on Windows clients. All other CLI commands work on Windows. You can still open shells on Windows nodes — the limitation is on the client side.
nobgp proxy
Manage published services (proxy and terminal endpoints). Requires nobgp login first.
Usage:
nobgp proxy <subcommand> [options]
Subcommands:
list
List all published services across your networks.
nobgp proxy list [options]
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Filter by network name |
--json | boolean | Output as JSON |
Example:
$ nobgp proxy list
staging-app https://a1b2c3d4.nobgp.com production / web-server svc_abc123
my-terminal https://x9y8z7w6.nobgp.com production / api-server svc_def456
publish
Publish a new service with a public HTTPS URL.
nobgp proxy publish [options]
Options:
| Option | Type | Description |
|---|---|---|
--node-id | string | Node UUID |
--network | string | Network name |
--node | string | Node name |
--title | string | Service title |
--proxy-url | string | URL to proxy (e.g. http://localhost:8080) |
--command | string | Terminal command to run |
--username | string | OS user |
--workdir | string | Working directory |
--no-auth | boolean | Disable authentication (public access) |
--share | string | Comma-separated email addresses to authorize |
--json | boolean | Output as JSON |
You must specify the target node using either --node-id or both --network and --node. Provide --proxy-url for a proxy service or --command for a terminal service. Omit both for a default shell terminal.
Examples:
# Publish a web app
nobgp proxy publish --network production --node web-server --proxy-url http://localhost:8080 --title "My App"
# Publish a browser terminal
nobgp proxy publish --network production --node api-server --title "Admin Shell"
# Publish a public (no auth) service
nobgp proxy publish --network production --node web-server --proxy-url http://localhost:3000 --no-auth
# Publish a terminal that runs a specific command
nobgp proxy publish --network production --node db-server --command "psql -U postgres" --title "DB Console"
Example output:
https://a1b2c3d4.nobgp.com svc_abc123 (proxy)
update
Update an existing service.
nobgp proxy update --id <service-id> [options]
Options:
| Option | Type | Description |
|---|---|---|
--id | string | Service ID (required) |
--title | string | Service title |
--proxy-url | string | URL to proxy |
--command | string | Terminal command |
--username | string | OS user |
--workdir | string | Working directory |
--enabled | boolean | Enable or disable service |
--no-auth | boolean | Disable authentication (public access) |
--json | boolean | Output as JSON |
Examples:
# Disable a service (the = is required for boolean false values)
nobgp proxy update --id svc_abc123 --enabled=false
# Re-enable a service
nobgp proxy update --id svc_abc123 --enabled
# Change title and make public
nobgp proxy update --id svc_abc123 --title "Production App" --no-auth
# Re-enable authentication on a public service
nobgp proxy update --id svc_abc123 --no-auth=false
Boolean flags like --enabled and --no-auth default to true when present. To set them to false, you must use the = syntax: --enabled=false, --no-auth=false. Writing --enabled false won't work as expected.
delete
Delete a published service.
nobgp proxy delete --id <service-id> [options]
Options:
| Option | Type | Description |
|---|---|---|
--id | string | Service ID (required) |
--json | boolean | Output as JSON |
Example:
nobgp proxy delete --id svc_abc123
share
Manage the authorized email list for a service.
nobgp proxy share <action> --id <service-id> [emails...]
Actions:
| Action | Description |
|---|---|
list | Show authorized emails for a service |
add | Grant access to one or more email addresses |
remove | Revoke access for one or more email addresses |
revoke | Clear all authorized emails |
Options:
| Option | Type | Description |
|---|---|---|
--id | string | Service ID (required) |
--json | boolean | Output as JSON |
Examples:
# List authorized emails
nobgp proxy share list --id svc_abc123
# Grant access to specific people
nobgp proxy share add --id svc_abc123 alice@example.com bob@example.com
# Grant access to an entire domain
nobgp proxy share add --id svc_abc123 '*@company.com'
# Revoke access for one person
nobgp proxy share remove --id svc_abc123 bob@example.com
# Revoke all access
nobgp proxy share revoke --id svc_abc123
nobgp file
Transfer files to and from your network's shared filesystem. Works from any machine where you're logged in — the agent doesn't need to be running locally.
When the shared filesystem is mounted (e.g., /Volumes/nobgp on macOS, /mnt/nobgp on Linux), commands operate on the local mount directly for best performance. Otherwise, they fall back to the noBGP API automatically.
Requires nobgp login first.
Usage:
nobgp file <subcommand> [options]
Subcommands:
upload
Upload one or more local files to the remote filesystem. The shell expands globs, so *.txt becomes multiple file arguments.
nobgp file upload <local-path>... [remote-path]
If the last argument starts with /, it's treated as the remote destination. For multiple files, the remote path must end with / (a directory).
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Network name (auto-detected if you have one network) |
-R, --recursive | boolean | Upload directories recursively |
Examples:
# Upload a single file to the root
nobgp file upload report.pdf
# Upload to a specific remote path
nobgp file upload report.pdf /docs/report.pdf
# Upload to a remote directory (note the trailing /)
nobgp file upload report.pdf /docs/
# Upload multiple files (shell expands the glob)
nobgp file upload *.log /logs/
# Upload specific files to a directory
nobgp file upload app.log error.log /logs/
# Upload a directory recursively
nobgp file upload -R ./project/ /backups/project/
download
Download files from the remote filesystem. Supports glob patterns for downloading multiple files at once — quote the pattern to prevent shell expansion.
nobgp file download <remote-path> [local-path]
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Network name (auto-detected if you have one network) |
-R, --recursive | boolean | Download directories recursively |
Examples:
# Download a single file to the current directory
nobgp file download /docs/report.pdf
# Download to a specific local path
nobgp file download /docs/report.pdf ./downloads/report.pdf
# Download to a local directory
nobgp file download /docs/report.pdf ./downloads/
# Download multiple files with a glob pattern (quote to prevent shell expansion)
nobgp file download '/logs/*.log' ./local-logs/
# Download all files matching a pattern
nobgp file download '/backups/db-*.sql.gz' ./
# Download a directory recursively
nobgp file download -R /backups/project/ ./local/
Always quote remote glob patterns ('*.log') so your shell doesn't try to expand them locally.
ls
List files and directories in the remote filesystem.
nobgp file ls [remote-path] [options]
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Network name (auto-detected if you have one network) |
--long | boolean | Show detailed listing (type, size, modification time) |
--json | boolean | Output as JSON |
Examples:
# List root directory
nobgp file ls
# List a subdirectory
nobgp file ls /docs/
# Detailed listing
nobgp file ls /docs/ --long
# Machine-readable output
nobgp file ls /docs/ --json
Example output:
$ nobgp file ls /docs/ --long
d 0 2026-03-15 12:00:00 drafts/
- 10240 2026-03-14 09:30:00 report.pdf
- 256 2026-03-12 15:45:00 notes.txt
rm
Remove files or directories from the remote filesystem. Supports multiple paths and glob patterns.
nobgp file rm <remote-path>... [options]
Options:
| Option | Type | Description |
|---|---|---|
--network | string | Network name (auto-detected if you have one network) |
Examples:
# Remove a single file
nobgp file rm /tmp/old-backup.sql
# Remove multiple files
nobgp file rm /tmp/old-backup.sql /tmp/cache.dat
# Remove files matching a glob pattern
nobgp file rm '/logs/*.log'
# Remove a directory and its contents
nobgp file rm /tmp/scratch/
nobgp file rm deletes files permanently. There is no confirmation prompt or trash/recycle bin.
nobgp config
Create or update the agent configuration file. If the agent is not yet registered, prompts for registration.
Usage:
nobgp config [profile] [options]
Examples:
# Interactive configuration for default profile
sudo nobgp config
# Configure a named profile
sudo nobgp config production
# Enable or disable a profile
sudo nobgp config production --enabled
sudo nobgp config staging --disabled
Options:
All global options from nobgp agent are supported, plus:
| Option | Type | Description |
|---|---|---|
--enabled | boolean | Enable this profile (default: true) |
--disabled | boolean | Disable this profile |
Values provided are saved to the platform config file (see Configuration File).
nobgp status
Show agent status including system information and per-profile runtime status.
Usage:
nobgp status [options]
Options:
| Option | Short | Description |
|---|---|---|
--json | -j | Output as JSON |
--yml | -y | Output as YAML (default) |
Example output (YAML):
version: "1.0.0"
platform: debian
architecture: amd64
hostname: web-server-1
config_dir: /etc/nobgp
service: running
profile:
pid: 1234
uptime_secs: 3600
registration:
node_id: "550e8400-e29b-41d4-a716-446655440000"
agent_key_id: "a1b2c3d4"
signing_key: "e5f6g7h8"
router:
url: "wss://router.nobgp.com"
connected: true
network:
local_ip: "10.0.1.5"
gateway_ip: "10.0.1.1"
tun_device: "nobgp0"
domain: "default.nobgp"
fs:
type: fuse
mount: /mnt/nobgp
mounted: true
nobgp list
List all available profiles.
Usage:
nobgp list
nobgp show
Show the configuration and status details of a profile.
Usage:
nobgp show [profile]
If no profile is specified, shows the default profile.
nobgp remove
Remove a profile and all associated files (.yml, .key, .jwt).
Usage:
nobgp remove [profile] [options]
Options:
| Option | Description |
|---|---|
--force | Force removal without confirmation |
nobgp upgrade
Upgrade the agent to the latest or a specific version.
Usage:
nobgp upgrade [version] [options]
Examples:
# Upgrade to the latest version
sudo nobgp upgrade
# Upgrade to a specific version
sudo nobgp upgrade 1.2.3
# Skip confirmation
sudo nobgp upgrade -y
# Force install even if same or older version
sudo nobgp upgrade -f
Options:
| Option | Short | Description |
|---|---|---|
--force | -f | Force install even if version is the same or older (allows downgrade) |
--yes | -y | Skip confirmation prompt |
nobgp service
Manage the noBGP agent as a system service.
Service commands do not work in Docker containers. The underlying service manager depends on the platform: systemd on most Linux distributions, OpenRC on Alpine Linux, procd on OpenWRT, launchd on macOS, and Windows Service Manager on Windows.
Usage:
nobgp service <subcommand>
Subcommands:
install
Install the noBGP agent as a system service.
sudo nobgp service install
Registers the agent as a system service and enables it to start on boot. On Linux this creates a systemd unit (or OpenRC/procd script depending on the init system); on macOS a launchd plist; on Windows a Windows Service.
uninstall
Remove the noBGP system service.
sudo nobgp service uninstall
Stops the service, disables it, and removes the service unit file.
start
Start the noBGP service.
sudo nobgp service start
stop
Stop the noBGP service.
sudo nobgp service stop
restart
Restart the noBGP service.
sudo nobgp service restart
Equivalent to stop followed by start.
status
Check the status of the noBGP service.
sudo nobgp service status
Exit codes:
0- Service is running1- Service is stopped2- Service is not installed
logs
View service logs. Does not require root.
nobgp service logs
Options:
| Option | Short | Default | Description |
|---|---|---|---|
--lines | -n | 100 | Number of lines to show |
--follow | -f | false | Follow log output in real-time |
# Show last 50 lines
nobgp service logs -n 50
# Follow logs in real-time
nobgp service logs -f
--follow is not supported on Windows.
nobgp version
Display the noBGP agent version.
Usage:
nobgp version
Example output:
nobgp version 1.0.0
nobgp help
Display help information.
Usage:
nobgp help [command]
Examples:
# General help
nobgp help
# Help for specific command
nobgp help agent
nobgp help config
nobgp help service
Configuration File
Location
The configuration file path depends on the platform:
| Platform | Path |
|---|---|
| Linux | /etc/nobgp/default.yml |
| macOS | /usr/local/etc/nobgp/default.yml |
| Windows | C:\ProgramData\nobgp\default.yml |
Format
YAML format. After registration, a typical configuration file looks like:
router: "wss://router.nobgp.com"
debug: false
log-level: "info"
compress: true
encrypt: true
interface: "auto"
ping-interval: "58s"
mount: "/mnt/nobgp"
auto-upgrade: true
The registration-key and node-name fields are only used during initial registration and are automatically removed from the config file after successful registration. Agent identity is stored separately in .key and .jwt files alongside the config.
Configuration Priority
Configuration is loaded in this order (later values override earlier):
- Configuration file (
/etc/nobgp/default.ymlon Linux,/usr/local/etc/nobgp/default.ymlon macOS,C:\ProgramData\nobgp\default.ymlon Windows) - Environment variables
- Command-line options
Example Configuration Files
Minimal (after registration):
router: "wss://router.nobgp.com"
Production:
router: "wss://router.nobgp.com"
log-level: "warning"
compress: true
encrypt: true
ping-interval: "58s"
Development:
router: "wss://router.nobgp.com"
debug: true
log-level: "debug"
compress: false
Environment Variables
All configuration options can be set via environment variables:
| Variable | Equivalent Config | Example |
|---|---|---|
NOBGP_KEY | registration-key | export NOBGP_KEY="abc..." |
NOBGP_NAME | node-name | export NOBGP_NAME="server1" |
NOBGP_ROUTER | router | export NOBGP_ROUTER="wss://router.nobgp.com" |
NOBGP_DEBUG | debug | export NOBGP_DEBUG=true |
NOBGP_LOG_LEVEL | log-level | export NOBGP_LOG_LEVEL="debug" |
NOBGP_COMPRESS | compress | export NOBGP_COMPRESS=true |
NOBGP_ENCRYPT | encrypt | export NOBGP_ENCRYPT=true |
NOBGP_INTERFACE | interface | export NOBGP_INTERFACE="eth0" |
NOBGP_PING_INTERVAL | ping-interval | export NOBGP_PING_INTERVAL="120s" |
Usage:
export NOBGP_KEY="<YOUR_NETWORK_KEY>"
export NOBGP_NAME="server1"
export NOBGP_DEBUG=true
sudo -E nobgp agent
Use -E flag with sudo to preserve environment variables.
Log Levels
The --log-level option controls output verbosity:
| Level | Description | Use Case |
|---|---|---|
error | Only errors | Production (minimal logging) |
warning | Errors and warnings | Production (standard) |
info | Informational messages | Default |
debug | Detailed debug information | Development |
trace | Very detailed tracing | Troubleshooting |
Examples:
# Minimal output
nobgp agent --log-level error
# Standard production
nobgp agent --log-level warning
# Development
nobgp agent --log-level debug
# Detailed troubleshooting
nobgp agent --log-level trace
Exit Signals
The agent handles standard Unix signals on Linux and macOS:
| Signal | Behavior |
|---|---|
SIGTERM | Graceful shutdown |
SIGINT (Ctrl+C) | Graceful shutdown |
SIGHUP | Reload configuration |
SIGUSR1 | Increase log level |
SIGUSR2 | Decrease log level |
Unix signals are not supported on Windows. Use nobgp service stop or the Windows Service Manager to stop the agent. Configuration reloads require a service restart.
Examples (Linux/macOS):
# Gracefully stop the agent
sudo pkill -TERM nobgp
# Reload configuration without restarting
sudo pkill -HUP nobgp
# Temporarily increase logging
sudo pkill -USR1 nobgp
Logging
Service Logs
The simplest cross-platform way to view logs is with the built-in nobgp service logs command (see above). Platform-specific methods are also available:
Linux (systemd):
sudo journalctl -u nobgp.service -f
Linux (OpenRC / Alpine):
tail -f /var/log/nobgp.err
Linux (OpenWRT):
logread -e nobgp
macOS (launchd):
tail -f /var/log/nobgp.err.log
Windows (PowerShell):
Get-WinEvent -FilterHashtable @{LogName='Application';ProviderName='nobgp'} -MaxEvents 50
Standalone Logs
When running standalone, logs go to stdout/stderr:
# Standard output
sudo nobgp agent
# Redirect to file
sudo nobgp agent > /var/log/nobgp.log 2>&1
# Pipe to logger
sudo nobgp agent 2>&1 | logger -t nobgp
Node Targeting
Several commands (exec, shell, proxy publish) require specifying a target node. There are two ways:
By name — specify both the network and node name:
nobgp exec -c "uptime" --network production --node web-server
By UUID — use the node ID directly (useful in scripts or when node names aren't unique across networks):
nobgp exec -c "uptime" --node-id 550e8400-e29b-41d4-a716-446655440000
You can find node IDs with nobgp network list.
JSON Output
Most management commands support a --json flag for machine-readable output. This is useful for scripting or piping to tools like jq:
# List networks as JSON
nobgp network list --json
# Get service details as JSON
nobgp proxy list --json | jq '.networks[].nodes[].services[]'
# Create a network and capture the ID
nobgp network create --name staging --json | jq -r '.network_id'
Platform Support
The management commands (login, logout, network, node, exec, proxy) work on all platforms — macOS, Linux, and Windows. The one exception is nobgp shell, which is not yet supported on Windows clients.
| Command | macOS | Linux | Windows |
|---|---|---|---|
login / logout | Yes | Yes | Yes |
network list / create | Yes | Yes | Yes |
network add-node | Yes | Yes | Yes |
exec | Yes | Yes | Yes |
shell | Yes | Yes | Not yet |
file upload / download / ls / rm | Yes | Yes | Yes |
proxy list / publish / update / delete | Yes | Yes | Yes |
The shell limitation is on the client side only. You can still open shells on Windows nodes using browser terminals or from a macOS/Linux client.
Common Usage Patterns
Personal Machine Setup
# Log in once on your laptop
nobgp login
# Now manage your infrastructure from the command line
nobgp network list
nobgp exec -c "uptime" --network production --node web-server
nobgp shell --network production --node api-server
Remote Server Setup
# Generate install commands from your laptop
nobgp network add-node --network production --node new-server
# Copy the output and run it on the remote machine
# (installs agent, registers with network, starts service)
Development Workflow
# Register interactively and run with debug
sudo nobgp register --name "dev-$(whoami)"
sudo nobgp agent --debug
# Monitor logs in another terminal
nobgp service logs -f
Production Deployment
# 1. Register the agent (opens browser for OAuth login)
sudo nobgp register --name "$(hostname)"
# 2. The registration process prompts to install and start the service
# Or do it manually:
sudo nobgp service install
# 3. Verify
nobgp status
Containerized Deployment
# Use registration key (browser login not available in containers)
docker run -d --restart unless-stopped \
--name nobgp \
--cap-add NET_ADMIN \
--cap-add SYS_ADMIN \
--device /dev/net/tun \
--device /dev/fuse \
--security-opt apparmor=unconfined \
-e NOBGP_KEY="KEY" \
-e NOBGP_NAME="container-$(hostname)" \
nobgp/nobgp
Debugging Connection Issues
# Run with maximum logging
sudo nobgp agent --log-level trace --debug
# Check if router is reachable
curl https://router.nobgp.com
# Check registration status
nobgp show
Configuration Best Practices
1. Register Before Running
Good:
sudo nobgp register --name "server"
sudo nobgp service install
Avoid:
sudo nobgp agent # Running without registration
2. Set Appropriate Log Levels
- Production:
warningorerror - Development:
infoordebug - Troubleshooting:
debugortrace
3. Use Descriptive Node Names
Good:
web-server-prod-1api-server-stagingdb-primary-us-east
Avoid:
server1nodetest
4. Secure Your Configuration File
# Restrict permissions
sudo chmod 600 /etc/nobgp/default.yml
sudo chown root:root /etc/nobgp/default.yml
5. Monitor Service Health
# Add to cron or monitoring system
*/5 * * * * systemctl is-active nobgp.service || systemctl restart nobgp.service
Troubleshooting Commands
Check Configuration
# View current config
cat /etc/nobgp/default.yml
# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('/etc/nobgp/default.yml'))"
Test Connectivity
# Check router accessibility
curl -v https://router.nobgp.com
# Test WebSocket connection
websocat wss://router.nobgp.com # If websocat is installed
Diagnose Service Issues
# Check service status
sudo nobgp service status
# View service logs
sudo journalctl -u nobgp.service -n 100
# Check for errors
sudo journalctl -u nobgp.service -p err
# Restart service
sudo nobgp service restart
Resource Usage
# Check process
ps aux | grep nobgp
# Memory usage
ps -o pid,user,%mem,rss,command -C nobgp
# CPU usage
top -p $(pgrep nobgp)
Advanced Topics
Custom Router
Custom routers are available for enterprise deployments only. Contact sales@nobgp.com for more information.
For enterprise deployments with custom routers:
router: "wss://custom-router.example.com:8080"
Multiple Profiles
Connect a single machine to multiple noBGP networks using profiles. Each profile is a separate YAML file in the config directory:
# Register profiles for different networks (interactive)
sudo nobgp register production --name "server-prod"
sudo nobgp register staging --name "server-staging"
# List all profiles
nobgp list
# Show a specific profile
nobgp show production
# When running as a service, all profiles are managed automatically
sudo nobgp service install
sudo nobgp service start
Interface Selection
Force specific network interface:
interface: "eth0" # Or eth1, wlan0, etc.
Next Steps
- Agent Installation - Detailed installation guide
- Core Concepts - Understand how noBGP works
- MCP Tools Reference - API reference for AI assistants
See Also
- Configuration directory:
/etc/nobgp/(Linux),/usr/local/etc/nobgp/(macOS),C:\ProgramData\nobgp(Windows) - Binary location:
/usr/bin/nobgpor/usr/local/bin/nobgp(Linux/macOS),C:\Program Files\noBGP\nobgp.exe(Windows)