Information as of March 2026 — verify with official sources

⚠️ Know the Risks Before You Proceed

Nanobot is an autonomous AI agent — it takes real actions and makes real API calls. Understand these risks first:

🤖
Rogue Agent Behaviour

Nanobot can misinterpret instructions and take unintended actions — looping searches, rewriting files, or sending unexpected messages. Always test in a supervised session before leaving it unattended.

💸
Cost Escalation

A runaway tool loop or leaked API key can exhaust your Gemini or Tavily quotas fast. Set GCP budget alerts (Section 8) before running Nanobot unattended. The maxToolIterations limit in config provides a safety cap.

🔓
Hijacking by Attackers

If your Telegram bot token or API keys are leaked — from a public repo, shared screenshot, or log file — an attacker can control your agent and rack up API costs. Treat every key like a bank password.

👁️
Data Exposure

Everything you send to the bot is transmitted to Google Gemini (for processing) and Tavily (for web search). Do not share private data, passwords, or confidential business information with the bot.

This guide is an independent community resource created by Commune.AI. It is provided "as is" without warranty of any kind. Commune.AI, its affiliates, and contributors accept no liability for any damages, costs, or losses arising from the use of this guide, including but not limited to misconfiguration, API charges, data exposure, or service disruptions. By proceeding, you acknowledge that you use this guide entirely at your own risk. Not affiliated with Google LLC, HKUDS/nanobot, Telegram, Tavily, or any third-party service mentioned herein.

Throughout this guide, ORANGE_VALUES in code blocks are placeholders you must replace. Fill in the input fields in each section — code snippets update automatically.
0

Prerequisites

↑ Setup Map

Collect the items below as you work through each section. Enter your Project ID here now — it will populate all GCP commands automatically.

ItemWhere to get itCost
Google accountaccounts.google.comFree
GCP project + billingconsole.cloud.google.comFree
Telegram accounttelegram.orgFree
Gemini API keyaistudio.google.com — Section 3Free tier
Tavily API keyapp.tavily.com — Section 4Free · No CC

Your GCP Project ID

Find it: GCP Console → project picker (top-left) → note the ID column (e.g. my-project-123456).

🏷️ Enter your Project ID — all GCP commands update automatically
Lowercase, permanent. Different from the project display name.
○ Not yet entered

1

GCP Setup — Service Account & VM

↑ Setup Map

Creates a zero-permission service account, a free-tier e2-micro VM, and automatically configures a 2 GB swap file on first boot — all in one step.

☁️
Run this in Google Cloud ShellClick the terminal icon (top-right of the GCP Console) to open Cloud Shell — a browser-based terminal pre-loaded with gcloud.

The script uses your Project ID entered above. You can also customise the VM and service account names:

Name for the Compute Engine instance.
Name for the restricted service account.

Paste the whole script into Cloud Shell and press Enter:

☁️ Google Cloud Shell bash
#!/usr/bin/env bash
# ── Edit if needed ───────────────────────────────────
PROJECT_ID="YOUR_PROJECT_ID"
ZONE="us-central1-a"        # keep for Always Free tier
# ─────────────────────────────────────────────────────

set -euo pipefail
trap 'echo "❌ Script aborted on line $LINENO. Check the gcloud error above." >&2' ERR
VM_NAME="nanobot-vm" ; SA_NAME="nanobot-sa"

echo "🔌  Enabling APIs (Compute + IAM)…"
gcloud services enable compute.googleapis.com iam.googleapis.com \
  --project="$PROJECT_ID"
echo "   ↳ APIs confirmed."

echo "🔐  Creating restricted service account (no IAM roles)…"
set +e  # Allow SA creation to fail without stopping script
gcloud iam service-accounts create "$SA_NAME" \
  --display-name="Nanobot SA — zero GCP permissions" \
  --project="$PROJECT_ID" 2>&1 | grep -q "already exists" && echo "   ↳ Service account already exists (OK)" || true
set -e  # Re-enable exit on error
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

echo "🖥️   Creating free-tier VM (with swap auto-configured on first boot)…"

# Write startup script to temp file (configures 2GB swap on first boot)
cat > /tmp/startup.sh << 'STARTUP_EOF'
#!/bin/bash
if [ ! -f /swapfile ]; then
  fallocate -l 2G /swapfile && chmod 600 /swapfile
  mkswap /swapfile && swapon /swapfile
  echo "/swapfile none swap sw 0 0" >> /etc/fstab
  sysctl -w vm.swappiness=10
  echo "vm.swappiness=10" >> /etc/sysctl.conf
fi
STARTUP_EOF

gcloud compute instances create "$VM_NAME" \
  --project="$PROJECT_ID" \
  --zone="$ZONE" \
  --machine-type=e2-micro \
  --image-project=debian-cloud \
  --image-family=debian-12 \
  --boot-disk-size=10GB \
  --boot-disk-type=pd-standard \
  --boot-disk-auto-delete \
  --service-account="$SA_EMAIL" \
  --scopes=https://www.googleapis.com/auth/logging.write,https://www.googleapis.com/auth/monitoring.write \
  --metadata=block-project-ssh-keys=true \
  --metadata-from-file=startup-script=/tmp/startup.sh

rm /tmp/startup.sh

echo ""
echo "✅  VM ready! 2 GB swap will be live by the time you SSH in."
echo ""
echo "▶  SSH into your VM:"
echo "   gcloud compute ssh $VM_NAME --zone=$ZONE --project=$PROJECT_ID"
🔒
What this enforcesThe service account has zero IAM roles — Nanobot cannot call any GCP API (Compute, Storage, IAM, etc.). The VM startup script configures 2 GB swap automatically on first boot, before you even connect.

Connect to the VM after creation

Wait ~60 seconds for the VM to boot, then open an SSH session. You can use the Cloud Shell command below, or click the SSH button next to the VM in the GCP Console.

☁️ Google Cloud Shell bash
gcloud compute ssh nanobot-vm \
  --zone=us-central1-a \
  --project="YOUR_PROJECT_ID"
💡
Verify swap is activeOnce connected to the VM, run free -h — you should see ~2.0G in the Swap row. If it shows 0, the startup script is still running; wait 30 s and check again.

1A. Create the Service Account

The fastest way is a single Cloud Shell command. No roles are granted — this is intentional.

☁️ Google Cloud Shell bash
gcloud iam service-accounts create nanobot-sa \
  --display-name="Nanobot SA — zero GCP permissions" \
  --project="YOUR_PROJECT_ID"

Or via the Console: IAM & Admin → Service Accounts → + Create Service Account — fill name nanobot-sa, skip the roles step, click Done. Do not create or download a JSON key.

1B. Create the VM

  1. Go to Compute Engine → VM instances → + Create Instance.
  2. Region: us-central1   Zone: us-central1-a
    ⚠️
    Region lockThe Always Free e2-micro only applies to us-central1 or us-west1. Any other region incurs compute charges.
  3. Machine type: Series E2 → e2-micro (2 vCPU, 1 GB memory).
  4. Boot disk → Change: Debian 12 · pd-standard · 10 GB. (Do not select pd-ssd — not free.)
  5. Identity and API access: select service account nanobot-sa.
  6. Firewall: leave both HTTP and HTTPS unchecked.
    🔒
    Nanobot dials outbound HTTPS to Telegram, Tavily, and Gemini. GCP allows all outbound TCP by default — no rules needed. These checkboxes only open inbound ports, which we do not want.
  7. Confirm cost shows $0.00/month, click Create.

1C. Add Swap Memory (VM SSH)

SSH in via the GCP Console → VM instances → SSH button next to nanobot-vm. Then run:

🖥️ VM SSH Terminal bash
sudo bash -c '
  fallocate -l 2G /swapfile && chmod 600 /swapfile
  mkswap /swapfile -q && swapon /swapfile
  echo "/swapfile none swap sw 0 0" >> /etc/fstab
  sysctl -w vm.swappiness=10 > /dev/null
  echo "vm.swappiness=10" >> /etc/sysctl.conf
  echo "✅  2 GB swap active"; free -h
'
💡
Why swap on a 1 GB VM?The e2-micro has only 1 GB RAM. Nanobot + Python venv + system processes can exhaust physical memory, causing the OS to kill Nanobot mid-task. Swap provides a 2 GB overflow buffer.

With GCP done, collect your API keys in Sections 2–4 before installing Nanobot.


2

Set Up Your Telegram Bot

↑ Setup Map
💻
Run this section on your phone or desktopOpen Telegram on any device — no access to the VM or Cloud Shell is needed here.

2.1 Create a bot with BotFather

  1. Open Telegram → search @BotFather → send /newbot.
  2. Enter a display name, e.g. My Nanobot.
  3. Enter a username ending in bot, e.g. mynanobot_xyz_bot.
  4. BotFather sends your Bot Token: a long string like 7012345678:AAFxxxxxxxxxxxxxxx. Copy it.
⚠️
Your bot token is a master keyAnyone who has it can send commands through your bot. Never commit it to Git, share it publicly, or paste it into a shared document.
🔑 Paste your Telegram Bot Token — updates all code snippets
From @BotFather — looks like: 7012345678:AAFxxxxx...
○ Not yet entered

2.2 Get your personal Telegram User ID

  1. Search Telegram for @userinfobot → send any message.
  2. The bot replies with Id: 123456789 — that number is your User ID.
🔒
Why a numeric ID?Nanobot checks every incoming message's sender ID. Any sender not in allowFrom is silently ignored — strangers cannot command your bot. Numeric IDs are permanent; usernames can change.
🪪 Enter your Telegram User ID — updates all code snippets
A number, not a username. From @userinfobot in Telegram.
○ Not yet entered

3

Set Up Gemini API Free Tier

↑ Setup Map
💻
Run this section in your browserVisit aistudio.google.com from any browser — no VM or Cloud Shell access required.
  1. Open aistudio.google.com → sign in with your Google account.
  2. Click Get API key (left panel) → Create API key.
  3. Select Create API key in new project (or an existing project).
  4. Copy the key — it begins with AIzaSy...
Free tier limitAllowance
Requests/day (Gemini 2.0 Flash)1,500
Tokens/minute1,000,000
GCP billing impactNone — tracked separately via AI Studio
🔑 Paste your Gemini API Key — updates all code snippets
From Google AI Studio — starts with AIzaSy...
○ Not yet entered

4

Set Up Tavily Search Free · No CC

↑ Setup Map
💻
Run this section in your browserVisit app.tavily.com — no VM or Cloud Shell needed.

Tavily is an AI-native search API — free for 1,000 queries/month with no credit card required. Nanobot uses it to answer questions about current events beyond its training data.

  1. Go to app.tavily.comSign up with email. No credit card.
  2. Confirm your email and log in.
  3. In the dashboard, click API Keys+ New API Key → name it nanobot.
  4. Copy the key — it starts with tvly-.
Free tier limitAllowance
Searches/month1,000
Credit cardNot required
Overage cost$5 per 1,000 additional searches
🔑 Paste your Tavily API Key — updates all code snippets
From app.tavily.com dashboard — starts with tvly-...
○ Not yet entered

5

Install & Configure Nanobot

↑ Setup Map
🖥️
Everything in this section runs inside the VM SSH terminalOpen it via: GCP Console → Compute Engine → VM instances → SSH button next to nanobot-vm.

5.1 Enter your Linux username

SSH into the VM first, then run whoami to find your username:

🖥️ VM SSH Terminalbash
whoami
👤 Enter your Linux username — updates the install script and config
The output of the whoami command above.
○ Not yet entered

All six values from Sections 0–5.1 are pre-filled below if you entered them. Verify the top six lines, then paste the entire script into the VM terminal:

🖥️ VM SSH Terminalbash — auto-install
#!/usr/bin/env bash
# ── Your values (pre-filled from the form above) ──────────────────────────────
LINUX_USER="YOUR_LINUX_USERNAME"
TELEGRAM_TOKEN="YOUR_TELEGRAM_BOT_TOKEN"
TELEGRAM_USER_ID=YOUR_TELEGRAM_USER_ID
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
TAVILY_API_KEY="YOUR_TAVILY_API_KEY"
# ──────────────────────────────────────────────────────────────────────────────

set -euo pipefail
NANOBOT_DIR="/home/${LINUX_USER}/.nanobot"

echo "📦  Updating system…"
sudo apt-get update -qq && sudo apt-get upgrade -y -qq

echo "🐍  Installing Python…"
sudo apt-get install -y -qq python3-venv python3-pip

echo "📁  Creating directories…"
mkdir -p "${NANOBOT_DIR}/workspace"

echo "🔧  Creating virtual environment…"
python3 -m venv "${NANOBOT_DIR}/venv"

echo "📥  Installing nanobot-ai…"
"${NANOBOT_DIR}/venv/bin/pip" install --upgrade pip -q
"${NANOBOT_DIR}/venv/bin/pip" install nanobot-ai -q

echo "📝  Writing config.json…"
cat > "${NANOBOT_DIR}/config.json" << EOF
{
  "agents": {
    "defaults": {
      "workspace": "/home/${LINUX_USER}/.nanobot/workspace",
      "model": "google/gemini-2.0-flash",
      "maxToolIterations": 20
    }
  },
  "providers": {
    "google": { "apiKey": "${GEMINI_API_KEY}" }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_TOKEN}",
      "allowFrom": [${TELEGRAM_USER_ID}]
    }
  },
  "tools": {
    "web": {
      "search": {
        "type": "tavily",
        "apiKey": "${TAVILY_API_KEY}",
        "maxResults": 5
      }
    },
    "exec": { "enabled": false }
  }
}
EOF

chmod 600 "${NANOBOT_DIR}/config.json"

echo ""
echo "════════════════════════════════════════════"
echo "✅  Nanobot installed successfully!"
echo "════════════════════════════════════════════"
echo ""
echo "▶  Test (foreground):  ~/.nanobot/venv/bin/nanobot gateway"
echo "▶  Background:         nohup ~/.nanobot/venv/bin/nanobot gateway > ~/.nanobot/nanobot.log 2>&1 &"
  1. Update system and install Python:
    🖥️ VM SSH Terminal
    sudo apt-get update && sudo apt-get upgrade -y
    sudo apt-get install -y python3-venv python3-pip
  2. Create virtual environment:
    🖥️ VM SSH Terminal
    mkdir -p ~/.nanobot/workspace
    python3 -m venv ~/.nanobot/venv
  3. Install nanobot-ai:
    🖥️ VM SSH Terminal
    ~/.nanobot/venv/bin/pip install --upgrade pip
    ~/.nanobot/venv/bin/pip install nanobot-ai
  4. Verify:
    🖥️ VM SSH Terminal
    ~/.nanobot/venv/bin/nanobot --version
  5. Create config file:
    🖥️ VM SSH Terminal
    nano ~/.nanobot/config.json
    Paste the config below (values auto-filled from Sections 0–5.1 if entered):
    🖥️ VM SSH Terminaljson — ~/.nanobot/config.json
    {
      "agents": {
        "defaults": {
          "workspace": "/home/YOUR_LINUX_USERNAME/.nanobot/workspace",
          "model": "google/gemini-2.0-flash",
          "maxToolIterations": 20
        }
      },
      "providers": {
        "google": { "apiKey": "YOUR_GEMINI_API_KEY" }
      },
      "channels": {
        "telegram": {
          "enabled": true,
          "token": "YOUR_TELEGRAM_BOT_TOKEN",
          "allowFrom": [YOUR_TELEGRAM_USER_ID]
        }
      },
      "tools": {
        "web": {
          "search": {
            "type": "tavily",
            "apiKey": "YOUR_TAVILY_API_KEY",
            "maxResults": 5
          }
        },
        "exec": { "enabled": false }
      }
    }
    Save: Ctrl+XYEnter
  6. Lock down permissions:
    🖥️ VM SSH Terminal
    chmod 600 ~/.nanobot/config.json

Config settings explained

KeyPurpose & security note
channels.telegram.allowFromSecurity control. Only this numeric User ID can send commands. All others silently ignored. Must be a number — not a quoted string.
tools.exec.enabled: falseContainment. Prevents Nanobot from running shell commands — it cannot modify the OS, install software, or attempt to escape the VM.
tools.web.search.type: "tavily"Selects Tavily as the web search backend (added in nanobot PR #93, Feb 2026).
maxToolIterations: 20Caps tool calls per response — prevents runaway loops from exhausting API quotas.

6

Run Nanobot

↑ Setup Map
🖥️
Run these commands in the VM SSH terminalGCP Console → Compute Engine → VM instances → SSH.

Running as a system service (auto-start on boot, auto-restart on crash) is in Appendix A. For most learners, start here:

Method 1 — Foreground (recommended for first run)

Watch all output in real time. Press Ctrl+C to stop.

🖥️ VM SSH Terminalbash
~/.nanobot/venv/bin/nanobot gateway

Method 2 — Background with nohup (survives SSH disconnect)

🖥️ VM SSH Terminalbash
nohup ~/.nanobot/venv/bin/nanobot gateway \
  > ~/.nanobot/nanobot.log 2>&1 &
echo "Started. PID: $!"
TaskCommand
Check runningpgrep -a nanobot
Watch live logstail -f ~/.nanobot/nanobot.log
Stop itpkill -f "nanobot gateway"

7

Verify the Installation

↑ Setup Map
💻
Run this test from your Telegram appNo VM access needed — open Telegram on your phone or desktop.
  1. Open Telegram → find your bot by @username → send /start. Nanobot should reply.
  2. Send: What is the latest Python version? — Nanobot should search the web and reply with a current, accurate answer.
  3. Security test: If you have a second Telegram account, message the bot from it. Nanobot should produce no reply.
🔒
No reply from the second account = security filter is working.If it does reply, recheck the allowFrom value in config.json — ensure it is a number, not a quoted string.

8

Cost Monitoring & Alerts

↑ Setup Map
💻
Run this section in your browserGCP Console — no VM access needed.

8.1 Create a GCP budget alert

  1. GCP Console → hamburger menu → Billing → select your billing account.
  2. Left sidebar → Budgets & alerts → + Create Budget.
  3. Name: Nanobot Budget · Projects: your project · Type: Monthly · Amount: $5 (safety net — normal spend is $0).
  4. Add thresholds:
    %At $5 budget triggers atSuggested action
    50%$2.50Investigate — something may be running outside the free tier.
    90%$4.50Stop non-essential resources immediately.
    100%$5.00Review all active GCP resources now.
  5. Confirm your email in Manage notificationsFinish.

8.2 Free tier at a glance

ResourceFree allowance/monthThis guide's usage
e2-micro VM (us-central1)1 instance1 ✅
pd-standard disk30 GB10 GB ✅
Network egress (Americas/EMEA)1 GBLow ✅
Gemini 2.0 Flash (AI Studio)1,500 req/dayLow ✅
Tavily Search1,000 queries/moLow ✅
Ephemeral external IP (running VM)FreeFree ✅

A

Appendix A: System Service Optional

↑ Setup Map
🖥️
All commands in this appendix run in the VM SSH terminal.
Featurenohup (Section 6)systemd (this appendix)
Survives SSH disconnect
Auto-restarts on crash
Starts on VM reboot
OS-level filesystem sandbox

A.1 Stop any running background process

🖥️ VM SSH Terminal
pkill -f "nanobot gateway" 2>/dev/null || true

A.2 Create the unit file

🖥️ VM SSH Terminal
sudo nano /etc/systemd/system/nanobot.service

Paste — replace the four occurrences of YOUR_LINUX_USERNAME:

🖥️ VM SSH Terminalsystemd unit
[Unit]
Description=Nanobot AI Agent
After=network-online.target
Wants=network-online.target

[Service]
User=YOUR_LINUX_USERNAME
WorkingDirectory=/home/YOUR_LINUX_USERNAME
Environment=HOME=/home/YOUR_LINUX_USERNAME
ExecStart=/home/YOUR_LINUX_USERNAME/.nanobot/venv/bin/nanobot gateway
Restart=always
RestartSec=10
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/YOUR_LINUX_USERNAME/.nanobot
PrivateTmp=true

[Install]
WantedBy=multi-user.target

A.3 Enable and start

🖥️ VM SSH Terminal
sudo systemctl daemon-reload
sudo systemctl enable nanobot
sudo systemctl start nanobot
sudo systemctl status nanobot --no-pager

A.4 Common commands

CommandWhen to use
sudo systemctl restart nanobotAfter editing config.json.
sudo systemctl stop nanobotTo pause Nanobot.
sudo systemctl disable nanobotPrevent auto-start on boot.
sudo systemctl daemon-reloadRequired after editing the .service file.

B

Appendix B: Troubleshooting

↑ Setup Map
🖥️
All diagnostic commands run in the VM SSH terminal.

B.1 View logs

nohup mode

🖥️ VM SSH Terminal
tail -f ~/.nanobot/nanobot.log

systemd mode — follow live

🖥️ VM SSH Terminal
sudo journalctl -u nanobot -f

Last 100 lines

🖥️ VM SSH Terminal
sudo journalctl -u nanobot -n 100 --no-pager
💡
What to look forSearch output for ERROR or Traceback. Common culprits: wrong API key, invalid bot token, JSON syntax error in config.

B.2 Validate config syntax

🖥️ VM SSH Terminal
python3 -m json.tool ~/.nanobot/config.json

Valid = formatted JSON prints. Error = line number where parsing failed.

B.3 Common fixes

Telegram 401 Unauthorized — Bot token wrong or regenerated.

@BotFather → /mybots → select bot → API Token → update config.json → restart Nanobot.

Google API 403 / not valid — Gemini key wrong.

Visit aistudio.google.com, verify or regenerate the key, update config.json, restart.

Nanobot runs but no Telegram reply
  1. Confirm allowFrom is a number, not a string: [123456789] not ["123456789"].
  2. Confirm you are messaging from the account whose ID is in the config.
  3. Watch logs while sending — no log entry = Telegram isn't delivering (check bot token).
Tavily 401 / web search errors
  1. Log in to app.tavily.com — verify key is active and quota not exceeded.
  2. Confirm "type": "tavily" is present in the search config block.

C

Appendix C: Brave Search (Alternative) Alternative to Tavily

↑ Setup Map

Use Brave Search if Tavily is unavailable in your region. New accounts require a credit card and receive $5/month in credits (~1,000 queries).

  1. Go to api.search.brave.com → Sign Up → subscribe to the Data for AI plan.
  2. Click API Keys → Add key → name it nanobot → copy the key (starts with BSA...).
  3. In ~/.nanobot/config.json, replace the search block:
    🖥️ VM SSH Terminaljson — replace search block
    "search": {
      "type": "brave",
      "apiKey": "YOUR_BRAVE_API_KEY",
      "maxResults": 5
    }
  4. Restart Nanobot.
Setup Progress 0/6
GCP Project ID
Telegram Bot Token
Telegram User ID
Gemini API Key
Tavily API Key
Linux Username