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 completed setup for either:

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. Generate a new network key
  3. Show you the new network details

Response Example​

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

Network Key: abc123def456... (base64)

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

Save your network keys somewhere secure! You'll need them to connect agents.

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

Step 4: Provision Your First Node (Optional)​

If your account has provisioning access, you can create compute resources through conversation.

Provisioning Access

Node provisioning requires account approval. If you don't have access yet, skip to Step 5 to learn about connecting existing infrastructure instead.

Ask your AI assistant​

Provision a new Ubuntu node with 4GB RAM in my development network

What Happens​

The AI will:

  1. Use the provision_node tool
  2. Create a cloud instance (on AWS or another provider)
  3. Automatically install the noBGP agent
  4. Configure it with your network key
  5. Wait for it to come online

Response Example​

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

Provisioning node...
- Provider: AWS
- Instance type: t3.medium (2 vCPU, 4GB RAM)
- OS: Ubuntu 22.04 LTS
- Region: us-east-1

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.

Get your network key​

Get your network key from https://app.nobgp.com:

  1. Sign in to the web dashboard
  2. Navigate to "Networks"
  3. Select your default network
  4. Copy the network key (it looks like a long base64 string)

Install the agent​

On your Linux machine, run:

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

Then configure it:

sudo nobgp config --key "YOUR_NETWORK_KEY" --name "my-server"
sudo nobgp service install
sudo nobgp service start

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. Create a session or run a command
  3. Execute df -h (or similar)
  4. Return the output to you

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 creates a persistent session and you can send multiple commands while maintaining state (environment variables, current directory, etc.).

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.com
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 service status
  • Verify network key is correct: cat /etc/nobgp/agent.yml
  • Check logs: sudo journalctl -u nobgp.service -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 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!