Skip to main content

Core Concepts

Understanding these core concepts will help you get the most out of noBGP.

Networks​

A network is an isolated overlay that connects your infrastructure together. Think of it as a private virtual network that spans across all your machines, clouds, and locations.

Key Features​

  • Isolation: Each network is completely separate - nodes in one network can't see or access nodes in another
  • Secure: All communication within a network is encrypted end-to-end
  • Distributed: Networks span across clouds, data centers, and edge locations seamlessly
  • Authenticated: Access controlled by network keys and OAuth permissions

Registration​

Nodes join a network through registration. There are two ways to register:

  1. Interactive (recommended): Run nobgp register — this opens your browser for OAuth sign-in, then lets you pick which network to join. No keys needed.
  2. Key-based (for automation): Pass a registration key via nobgp register --key or the NOBGP_KEY environment variable. This is designed for Docker containers, CI/CD pipelines, and other headless environments.

Registration keys are base64-encoded tokens managed through the noBGP web dashboard. Treat them as secrets — don't commit to git.

After registration (either method), the agent receives a JWT token for ongoing authentication. The registration key is removed from the config file.

Default Network​

Every noBGP account comes with a default network automatically. When you ask your AI assistant to provision nodes or show networks, it uses your default network unless you specify otherwise.

Nodes​

A node is any machine connected to a noBGP network. Nodes can be:

  • Cloud instances (AWS, GCP, Azure, etc.)
  • Physical servers in your data center
  • Raspberry Pis and edge devices
  • Docker containers

Node Components​

Every node runs the noBGP agent - a lightweight background process that:

  • Maintains connection to the noBGP router
  • Handles encrypted communication with other nodes
  • Executes commands from your AI assistant (with your authorization)
  • Reports system status and metadata

Node Identity​

Each node has:

  • Name: Human-friendly identifier (e.g., "web-server-1", "raspberry-pi")
  • Network: Which network it belongs to
  • Status: Online, offline, or connecting
  • Metadata: OS, architecture, IP addresses, etc.

Node Discovery​

Your AI assistant can discover nodes by asking noBGP:

Show me all nodes in my production network

This returns real-time status for all connected nodes.

DNS & Hostname Resolution​

Nodes in the same network can reach each other by name. When the agent connects, it configures your system's DNS so that bare hostnames resolve automatically:

# From any node in the same network, reach others by name
ping web-server
curl http://api-server:8080/health
ssh raspberry-pi

Under the hood, the agent adds a DNS search domain (e.g., mynetwork.nobgp) to your system's resolver configuration. This means ping web-server expands to web-server.mynetwork.nobgp and resolves to the node's overlay IP address — no manual /etc/hosts entries or DNS records needed.

The agent integrates with your platform's native DNS:

  • Linux: resolvectl, systemd-resolved, NetworkManager, or /etc/resolv.conf
  • macOS: /etc/resolver/ directory
  • Windows: DNS suffix search list
tip

Hostname resolution works across clouds and locations. A node in AWS can reach a Raspberry Pi at home simply by name, as long as both are in the same network.

Services​

Services are the way you expose functionality from your nodes to the internet. noBGP supports two types of services:

1. Proxy Services​

Proxy services expose HTTP applications running on your nodes to the public internet with a unique URL.

Example use cases:

  • Expose a web app running on localhost:8080
  • Share a development server temporarily
  • Provide access to an internal dashboard

How it works:

Features:

  • Automatic HTTPS with valid certificates
  • Optional authentication (require OAuth to access)
  • Enable/disable without deleting
  • Base64-encoded target URLs for security

2. Terminal Services​

Terminal services provide browser-based terminal access to your nodes through a web interface.

Example use cases:

  • Remote shell access without SSH
  • Shared terminal sessions for collaboration
  • Emergency access when SSH is unavailable
  • Terminal access for air-gapped systems

How it works:

  • Your AI assistant publishes a terminal service
  • noBGP generates a unique URL (e.g., https://xyz789.nobgp.com)
  • Opening the URL shows a full-featured web terminal
  • WebSocket connection provides real-time interaction

Features:

  • Full terminal emulation (colors, control characters, etc.)
  • Support for interactive programs (vim, nano, htop, etc.)
  • Command history and tab completion
  • Resize support
  • Optional authentication

Service Authentication​

Both service types support optional authentication:

  • Auth required: Users must sign in with OAuth before accessing
  • Public: Anyone with the URL can access (useful for demos, temporary shares)
Security Tip

Always use authentication for production services or those containing sensitive data.

Sharing Services with Specific People​

When a service has authentication enabled, you control exactly who gets in. Visitors who aren't on your approved list see an "Access Required" page where they can request access with one click. You receive an email notification and can approve or deny from a built-in permissions dashboard — no configuration required.

You can also add people proactively by email before they visit, including whole domains with a wildcard (*@yourcompany.com).

See Access Control in the Publishing Services guide for the full details.

Sessions​

A session is a running command on a node, managed by the AI assistant via the command MCP tool. Each session runs one specific command and closes automatically when that command exits.

Session Lifecycle​

  1. Start: Your AI assistant calls the command tool with a session object specifying the node and command to run
  2. Interact: The AI reads output using the returned command_id; for interactive programs, it sends additional input
  3. End: The session closes automatically when the command exits

Session Patterns​

One-shot commands — run a non-interactive command and read its output:

  • df -h, systemctl status nginx, cat /var/log/app.log
  • Session closes as soon as the command finishes; no explicit cleanup needed

Interactive shell sessions — start bash (or another shell) and send multiple commands while maintaining state:

  • cd and exported environment variables persist across inputs within the session
  • The AI sends each command as stdin input to the running shell
  • Close by sending exit or a SIGTERM signal

When to Use Each Pattern​

Use one-shot commands for:

  • Quick status checks (uptime, df -h)
  • Non-interactive operations
  • Scripted automation

Use interactive shell sessions for:

  • Multi-step procedures that share state (navigate directories, set env vars, run related commands)
  • Interactive programs like vim, less, top, psql
  • Debugging with tools that require back-and-forth input

Authentication & Security​

noBGP uses multiple layers of security:

OAuth 2.0​

All AI assistant access is protected by OAuth:

  • Sign in with Google, GitHub, or other providers
  • Token-based access control
  • Automatic token refresh
  • Per-session permissions

Agent Registration​

Nodes authenticate through a two-phase process:

  • Registration: Either via OAuth browser login (nobgp register) or with a registration key (nobgp register --key) for automation
  • Ongoing auth: After enrollment, the agent receives a JWT token signed with per-network Ed25519 keys — no key or login needed for subsequent connections
  • Registration keys are unique per network and can be rotated without downtime

Encryption​

All communication is encrypted:

  • TLS for web traffic
  • End-to-end encryption within the overlay
  • Certificate pinning for agent connections

Authorization​

Not all users can do everything:

  • Node provisioning requires account approval
  • Network management requires network ownership
  • Command execution requires network membership

File Sharing​

noBGP provides a shared virtual drive scoped to each network. This allows you to share files across all nodes and manage them through a web interface.

How It Works​

Virtual Mount Point:

  • Each network gets a shared drive mounted on every connected node
  • All mounts are backed by S3 storage
  • Files written on one node are visible on all other nodes in the same network
  • Default mount points: /mnt/nobgp (Linux), /Volumes/nobgp (macOS), drive letter (Windows)

Mount Technology:

  • Linux: Uses FUSE for native filesystem access with on-disk caching. Files are cached locally for fast reads and uploaded asynchronously on writes. Falls back to WebDAV if FUSE is unavailable.
  • macOS: Uses the native WebDAV client (mount_webdav)
  • Windows: Uses WebDAV via net use drive mapping

Multi-Profile Mount Points: When running multiple profiles (see Multi-Profile Support), each profile gets its own mount point with a -{profile} suffix (e.g., /mnt/nobgp-work, /mnt/nobgp-staging). The default profile always keeps the bare name (/mnt/nobgp). On Windows, each profile gets a separate drive letter.

Web Panel:

  • Each network has a dedicated web panel at https://files.nobgp.com/NETWORK_NAME
  • OAuth-protected and authenticated access only
  • Upload and download files through your browser
  • Manage directories and organize your shared files

Using File Sharing with Your AI Assistant​

Your AI assistant can:

  • Provide links to the file panel for your network
  • List files and directories currently stored
  • Guide you on uploading or downloading files
  • Help you organize and manage your shared files
Current Limitation

The AI assistant can provide you with links to upload/download files, but cannot upload files directly yet. You'll use the web panel at https://files.nobgp.com/NETWORK_NAME for file transfers.

Use Cases​

  • Share configuration files across nodes - Upload once, access from all nodes
  • Distribute deployment artifacts - Share builds or packages with your infrastructure
  • Collect logs from multiple machines - Centralized storage for log files
  • Transfer files between disconnected systems - Bridge air-gapped environments

Example Workflow​

You: I need to share a config file with all my production servers

AI: I can help you with that. You can upload your config file to the shared drive
    for your production network.

    Visit: https://files.nobgp.com/production

    Once uploaded, the file will be available at /mnt/nobgp/ on all nodes in your
    production network.

You: How do I access it from my servers?

AI: On any node in the production network, the file will be at:
    /mnt/nobgp/your-config-file.conf

    You can copy it to the appropriate location, for example:
    cp /mnt/nobgp/your-config-file.conf /etc/app/config.conf

Web Dashboard​

The noBGP web dashboard provides a graphical interface for managing your account:

  • Network management: Create and configure networks
  • Node overview: See all connected nodes and their status
  • Registration keys: Generate and manage keys for automated agent enrollment
  • Service management: View and configure published services
  • File sharing: Upload and download files via the web panel at https://files.nobgp.com/NETWORK_NAME

The web dashboard complements your AI assistant — use it for account management tasks and visual overviews, while using the AI assistant for operational tasks like running commands and troubleshooting.

Putting It Together​

Here's how these concepts work together in a typical workflow:

The flow:

  1. You authenticate to noBGP via your AI assistant (OAuth)
  2. Your request is authorized based on your account permissions
  3. Operations execute within your networks (isolated from other users)
  4. Nodes authenticate via registration (OAuth or key) and then JWT tokens
  5. All communication is encrypted and secured
  6. Results stream back to your AI assistant in real-time

Next Steps​

Now that you understand the core concepts:

  1. Try Your First Steps - Hands-on walkthrough of common tasks
  2. Install an Agent - Connect your first machine
  3. Provisioning Guide - Create nodes on-demand
  4. Service Publishing Guide - Expose your applications

Questions?​

Q: How many networks can I have? A: No limit. Create as many networks as you need for different environments (dev, staging, prod, etc.)

Q: Can nodes be in multiple networks? A: Yes! A node can join multiple networks simultaneously using multiple agent profiles (see Multi-Profile Support)

Q: What happens if I regenerate my registration key? A: Already-registered nodes are unaffected — they use JWT tokens. Only new registrations using the old key will stop working.

Q: Are services publicly accessible? A: Only if you make them public. By default, all services require OAuth authentication.

Q: How long do sessions stay alive? A: Sessions have a 1-hour idle timeout. After the command exits, there is a 30-second grace period to retrieve the final exit code.