Skip to main content

Your First Steps with noBGP

This guide walks you through your first conversation with noBGP. You'll learn how to discover your network, check node status, run commands, and understand the AI-driven workflow.

Prerequisites

Before starting, make sure you've:

Step 1: Discover Your Network​

Every noBGP account comes with a default network. Let's see what's in yours.

Start a new conversation​

Open your AI assistant (Claude or ChatGPT) and try this prompt:

Show me my noBGP networks

What to Expect​

Your AI assistant will use the network_directory tool to query your networks. You'll see a response like:

I'll check your noBGP networks for you.

You have 1 network:

Network: "default"
- Created: 3 days ago
- Nodes: 0 online, 0 offline
- Services: None published
tip

If this is your first time using noBGP, you likely have zero nodes. That's normal! We'll add some in the next steps.

Step 2: Create Your First Network (Optional)​

While you can use your default network for everything, you might want to create separate networks for different purposes (e.g., "production", "development", "testing").

Ask your AI assistant​

Create a new network called "development"

What Happens​

The AI will:

  1. Use the network_create tool
  2. Create the network
  3. Show you the new network details

Response Example​

I've created a new network called "development".

You can now connect agents to this network. Would you like me to
explain how to install an agent?

Step 3: Understanding the Workflow​

Let's pause and understand what just happened:

The key insight: You're talking to the AI in natural language, but the AI is using structured MCP tools (or ChatGPT Actions) to interact with noBGP on your behalf.

This means:

  • You don't need to remember API endpoints or commands
  • The AI understands context and can do multi-step operations
  • You can ask follow-up questions naturally
  • The AI formats responses in human-readable ways
info

To follow the remaining steps, you'll need at least one connected node. Either provision a cloud node or install an agent on your own machine.

Step 4: Provision Your First Node (Optional)​

You can create compute resources through conversation. Every account may provision, from router 0.4.110 — there is no approval step and no waiting list, on any plan including Free.

What bounds a provision is your plan's compute allowance

Each plan includes an amount of compute each month — $1 on Free, which is 50 hours of a small machine — and a provision is refused once it is spent, naming how much was used against how much is included. See Provisioned compute. If you would rather use a machine you already have, skip to Step 5.

Ask your AI assistant​

Provision a new medium node in my development network

What Happens​

The AI will:

  1. Use the provision_node tool with the class you asked for — one of small (0.25 vCPU / 0.5 GiB), medium (1 vCPU / 2 GiB), large (2 vCPU / 4 GiB) or xlarge (4 vCPU / 8 GiB), defaulting to small
  2. Create a container instance on a cloud provider (AWS)
  3. Automatically install and register the noBGP agent
  4. Wait for it to come online

The machine stops on its own after 24 hours unless you ask for longer — say how long you need it and the assistant will tell you the exact time it will stop. See How long it runs.

Response Example​

I'll provision a new node for you in the development network.

Provisioning node...
- Provider: AWS
- Class: medium (1 vCPU / 2 GiB)

The node is starting up. This usually takes 1-2 minutes...

✓ Node "ubuntu-node-1" is now online in your development network!

Would you like me to run any setup commands on it?

Step 5: Install an Agent on Existing Infrastructure​

If you have your own servers, VMs, or Raspberry Pis, you can connect them to noBGP. The install script handles everything — installation, registration, and service setup — in a single command.

Linux / macOS:

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

macOS (Homebrew):

brew install nobgp/tap/nobgp

Windows — one command, works in Command Prompt and PowerShell alike:

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

The script will open your browser to sign in with your noBGP account, let you choose which network to join, and start the agent as a service. No keys needed.

tip

For Docker containers and automated environments where browser login isn't possible, use a registration key instead. See the Docker and Automation section in the Agent Installation guide.

Verify it's connected​

Go back to your AI assistant and ask:

Show me all nodes in my default network

You should see your newly connected node listed as "online"!

Step 6: Run Your First Command​

Now that you have a node connected, let's run a command on it.

Ask your AI assistant​

Check disk space on my-server

What Happens​

The AI will:

  1. Identify which node you're referring to ("my-server")
  2. Use the command tool to run df -h as a one-shot command
  3. Return the output — the session closes automatically when the command finishes

Response Example​

I'll check the disk space on my-server.

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        50G   12G   36G  25% /
tmpfs           2.0G  4.0M  2.0G   1% /dev/shm
/dev/sdb1       100G   45G   51G  47% /data

Your server has plenty of space available. The root filesystem is at 25%
capacity and the data volume is at 47%.
tip

Notice how the AI not only shows you the raw command output but also interprets it for you. This is the power of AI-native infrastructure management!

Step 7: Try an Interactive Session​

For more complex tasks, you can start an interactive shell session.

Ask your AI assistant​

Start an interactive shell session on my-server

What Happens​

The AI starts a bash session using the command tool, then sends your subsequent commands as inputs to that shell. This maintains state (current directory, environment variables, etc.) across multiple exchanges.

Example Interaction​

You: Start an interactive shell session on my-server

AI: I've started a shell session on my-server. What would you like to do?

You: Navigate to /var/log and show me the newest files

AI: [Changes directory and runs ls -lt]
    total 1024
    -rw-r--r-- 1 root root  45234 Nov  4 14:32 syslog
    -rw-r--r-- 1 root root  12856 Nov  4 14:30 auth.log
    ...

You: Show me the last 10 lines of syslog

AI: [Executes tail -n 10 syslog]
    [Log output here...]

You: Exit the session

AI: Session closed. Is there anything else you'd like to do?

Step 8: Publish a Service​

Let's make something accessible from the internet.

Scenario: Browser Terminal​

Want to access your server's terminal through a web browser? Ask your AI:

Create a browser terminal for my-server with authentication required

What Happens​

The AI will:

  1. Use the service_publish tool
  2. Create a terminal service
  3. Generate a public URL
  4. Configure OAuth authentication

Response Example​

I've created a browser-based terminal for my-server.

URL: https://xyz789.nobgp.link
Authentication: Required (OAuth)

Anyone who visits this URL will need to sign in before accessing the terminal.
The service is now active!

Open that URL in your browser, sign in, and you'll have a full terminal interface!

Common Patterns​

As you use noBGP more, you'll discover common patterns:

Discovery Pattern​

You: What's running?
AI: [Checks networks, nodes, services, and summarizes status]

Chain Pattern​

You: Provision a node, install Docker, and run nginx
AI: [Provisions node, waits for online, installs Docker, runs nginx container]

Monitoring Pattern​

You: Check the health of all my production nodes
AI: [Runs health checks on each node, summarizes results]

Troubleshooting Pattern​

You: My web-server-1 is slow. Help me diagnose it.
AI: [Checks CPU, memory, disk, network, running processes, identifies issues]

Best Practices​

1. Be Specific with Node Names​

Instead of "my server", use "web-server-1". The AI can usually figure it out, but being specific helps.

2. Ask for Explanations​

Don't understand the output? Ask the AI to explain it. That's what it's there for!

You: What does that error mean?
AI: [Explains the error in plain English and suggests fixes]

3. Use Networks for Isolation​

Create separate networks for different environments:

  • production - Your live infrastructure
  • staging - Testing before production
  • development - Experimental work

4. Leverage Session State​

For related tasks, use sessions instead of one-off commands. The AI can navigate directories, set environment variables, and maintain context.

5. Secure Your Services​

When publishing services, use authentication unless you specifically need them to be public.

What's Next?​

Now that you've taken your first steps:

Learn More​

Explore Features​

Reference​

Troubleshooting​

AI Says "I don't have access to that network"​

  • Verify you're authenticated (check your OAuth session)
  • Make sure the network name is correct
  • Try: "Show me all my networks" to see what's available

Node Won't Come Online​

  • Check the agent is running: sudo nobgp status
  • Verify the agent is registered: sudo nobgp show
  • Check logs: sudo nobgp service logs -f

Commands Time Out​

  • Long-running commands may exceed timeout limits
  • Use interactive sessions for complex operations
  • Break up large tasks into smaller steps

Service URL Returns 404​

  • Wait 30-60 seconds after creation (DNS propagation)
  • Verify service is enabled: "Show me my published services"
  • Check the target URL is correct

Get Help​

If you're stuck:

Remember: The AI is there to help you. If something doesn't work, describe the problem and ask for help!