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

Network Keys​

Every network has a network key - a base64-encoded token that looks like:

VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ=

Network keys:

  • Authenticate nodes joining the network
  • Can be regenerated without destroying the network
  • Are managed through the noBGP web dashboard
  • Should be treated as secrets (don't commit to git!)

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.

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.

Sessions​

A session represents an active, interactive shell connection to a node. Unlike one-shot commands, sessions maintain state across multiple interactions.

Session Lifecycle​

  1. Start: Your AI assistant creates a session on a specific node
  2. Interact: You send commands, the session returns output
  3. Maintain: Session stays alive between commands
  4. End: Session closes when you're done or after timeout

Session Features​

  • Stateful: Environment variables, current directory, and history persist
  • Interactive: Full support for programs like vim, less, top
  • Control characters: Send Ctrl+C, Ctrl+D, arrow keys, etc.
  • Concurrent: Multiple sessions per node supported

When to Use Sessions​

Use sessions for:

  • Editing files interactively
  • Running long-running commands with progress output
  • Navigating filesystem and running related commands
  • Debugging with interactive tools

Use one-shot commands for:

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

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

Network Keys​

Nodes authenticate to networks using network keys:

  • Unique per network
  • Can be rotated without downtime
  • Never sent over the wire (used for cryptographic derivation)

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 virtual nobgp mounted volume at /mnt/nobgp
  • Accessible from any node connected to the network
  • Files stored here are accessible to all nodes in the same network

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

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 using network keys (separate from user auth)
  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 (requires multiple agent configurations)

Q: What happens if I regenerate my network key? A: Existing nodes will reconnect automatically with the new key. Old key immediately stops 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 timeout after 30 minutes of inactivity, but you can configure this.