← Back to Slides
Information as of March 2026 — verify with official sources
Copy Paste Done

Fill in your keys below.
Install scripts are auto-generated.
You paste them.

What You're Building

Free Cloud VM

A 24/7 Linux server on Google's free tier — runs while you sleep, no electricity bill, no exposed home ports.

Nanobot Agent

An ultra-lightweight AI agent (~4K lines) that searches the web, runs commands, manages files, and responds via your favourite messaging app.

Always On, Always Ready

Runs as a background service — message it from anywhere, get instant responses, even when your laptop is off.

How does Nanobot compare? ▸

Nanobot vs OpenClaw

Both are open-source autonomous AI agents capable of web search, shell execution, file management, and multi-channel messaging. The key difference is complexity: Nanobot is ~4,000 lines of Python while OpenClaw spans ~430,000 lines of JavaScript/TypeScript. This 100× difference in codebase size translates to a smaller attack surface and easier auditing for security-conscious users. Nanobot supports 11+ LLM providers (Gemini, Claude, GPT, DeepSeek, Groq, Zhipu, and local models via Ollama/vLLM) compared to OpenClaw's model-agnostic approach. For messaging, Nanobot covers 8+ platforms (Telegram, Discord, WhatsApp, Slack, Email, DingTalk, Feishu, QQ) while OpenClaw supports 20+. Choose Nanobot for simplicity and quick deployment; choose OpenClaw for maximum platform coverage and advanced automation workflows.

Before you begin
⚠ Know the risks before you begin

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, Vertex AI, or Brave Search quotas fast. Set GCP budget alerts 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 your selected model provider (Gemini API, Vertex AI, Groq, etc.) and Brave Search when web search is enabled. 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, Brave Software, or any third-party service mentioned herein.

Configure Your Agent

Select your messaging channels, tools, and AI model. The guide adapts — only relevant sections and API key inputs appear. Your config.json is generated automatically.

Messaging Channels
Tools
AI Model Provider
About the highlighted placeholders ▸
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.

Three Simple Steps to Your AI Agent

1

Setup Google Cloud Compute Engine

Create a free-tier VM, Vertex-capable service account, and swap — ready for Nanobot

PrerequisiteWhere to get itCost
Google accountaccounts.google.comFree
GCP project + billingconsole.cloud.google.comFree

Service Account & VM Creation

Creates a dedicated service account with only Vertex AI access, a free-tier e2-micro VM, and automatically configures a 2 GB swap file on first boot — all in one step. This lets you switch to Vertex AI later without recreating the VM.

☁️
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 auto-detects your Project ID from Cloud Shell. You can optionally customise the VM and service account names:

Name for the Compute Engine instance.
Name for the dedicated Vertex-capable service account.
Key Step: Run This Script
Paste the entire script into Cloud Shell and press Enter
☁️ Google Cloud Shell bash
#!/usr/bin/env bash
# ── Step 0: Identify the Google Cloud project ──────────────────
# Cloud Shell already knows the active project selected in GCP.
# Auto-detecting it avoids copy/paste mistakes with project IDs.
PROJECT_ID="$(gcloud config get-value project 2>/dev/null)"
ZONE="us-central1-a"        # Always Free e2-micro is region-limited; keep this zone.
# ─────────────────────────────────────────────────────

set -uo pipefail  # Keep undefined variables/pipeline errors visible, but continue for readable diagnostics.
VM_NAME="nanobot-vm" ; SA_NAME="nanobot-sa"
FAILED=0

# ── Step 1: Save a Cloud Shell log ─────────────────────────────
# Cloud Shell can disconnect or be closed. This log lives in your
# Cloud Shell home directory, so you can reopen Cloud Shell later
# and inspect what happened.
LOG_DIR="${HOME}/nanobot-logs"
mkdir -p "$LOG_DIR"
LOG_FILE="${LOG_DIR}/gcp-vm-create-$(date +%Y%m%d-%H%M%S).log"
exec > >(tee -a "$LOG_FILE") 2>&1

echo "📍  Project ID: $PROJECT_ID"
echo "📍  Zone:       $ZONE"
echo "🧾  Cloud Shell setup log: $LOG_FILE"
echo "    If Cloud Shell disconnects, reopen it and run:"
echo "    ls -lt ~/nanobot-logs && tail -n 160 ~/nanobot-logs/gcp-vm-create-*.log"
echo ""

# ── Step 2: Enable required GCP APIs ───────────────────────────
# Compute Engine API creates the VM. IAM API creates the service
# account that the VM will run as. Vertex AI API lets the VM use
# Application Default Credentials for Vertex models later.
echo "🔌  Enabling APIs (Compute + IAM + Vertex AI)…"
if ! gcloud services enable compute.googleapis.com iam.googleapis.com aiplatform.googleapis.com --project="$PROJECT_ID" 2>&1; then
  echo "❌ Failed to enable APIs. Check your project ID and billing status." >&2
  FAILED=1
else
  echo "   ↳ APIs confirmed."
fi

# ── Step 3: Create a least-privilege service account ───────────
# The VM uses this identity for Application Default Credentials.
# It receives Vertex AI User only: enough to call Vertex models,
# but not enough to administer Compute, IAM, Storage, or Secrets.
echo "🔐  Creating dedicated service account…"
if gcloud iam service-accounts create "$SA_NAME" \
  --display-name="Nanobot SA — Vertex AI only" \
  --project="$PROJECT_ID" 2>&1; then
  echo "   ↳ Service account created."
else
  echo "   ↳ Service account may already exist; continuing."
fi
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

if [ $FAILED -eq 0 ]; then
  echo "🎯  Granting Vertex AI User to $SA_EMAIL…"
  if ! gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="roles/aiplatform.user" \
    --condition=None >/dev/null 2>&1; then
    echo "❌ Failed to grant Vertex AI User role." >&2
    FAILED=1
  else
    echo "   ↳ Vertex AI permission confirmed."
  fi
fi

if [ $FAILED -eq 0 ]; then
  # ── Step 4: Prepare first-boot startup script ────────────────
  # The free-tier e2-micro has limited RAM. This script runs once
  # on first boot and adds a 2 GB swap file so installs and small
  # agent workloads are less likely to be killed by low memory.
  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
# Persist startup diagnostics on the VM boot disk. This can be read
# later with: sudo tail -n 160 /var/log/nanobot-startup.log
exec > >(tee -a /var/log/nanobot-startup.log) 2>&1
echo "[$(date -Is)] Nanobot VM startup script started"
if [ ! -f /swapfile ]; then
  echo "Creating 2 GB swap file..."
  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
else
  echo "Swap file already exists; leaving it unchanged."
fi
free -h || true
echo "[$(date -Is)] Nanobot VM startup script finished"
STARTUP_EOF

  # ── Step 5: Create the VM ────────────────────────────────────
  # e2-micro + Debian + standard 10 GB boot disk are chosen for
  # Google Cloud's free-tier constraints. cloud-platform scope lets
  # Google client libraries request tokens; IAM still restricts the
  # service account to Vertex AI User only. block-project-ssh-keys
  # keeps SSH access scoped to this instance rather than inheriting
  # every project-level SSH key.
  if ! 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/cloud-platform \
    --metadata=block-project-ssh-keys=true \
    --metadata-from-file=startup-script=/tmp/startup.sh 2>&1; then
    echo "❌ VM creation failed. See error above." >&2
    FAILED=1
  fi

  rm -f /tmp/startup.sh
fi

echo ""
echo "════════════════════════════════════════════"
if [ $FAILED -eq 0 ]; then
  echo "✅  VM ready! 2 GB swap will be live by the time you SSH in."
  echo "════════════════════════════════════════════"
  echo ""
  echo "▶  SSH into your VM:"
  echo "   gcloud compute ssh $VM_NAME --zone=$ZONE --project=$PROJECT_ID"
  echo ""
  echo "▶  VM startup/swap log from Cloud Shell:"
  echo "   gcloud compute instances get-serial-port-output $VM_NAME --zone=$ZONE --project=$PROJECT_ID --port=1 | tail -n 200"
else
  echo "❌  Setup incomplete — review errors above"
  echo "════════════════════════════════════════════"
  echo ""
  echo "Common fixes:"
  echo "  • Wrong PROJECT_ID → verify in GCP Console"
  echo "  • Billing not enabled → console.cloud.google.com/billing"
  echo "  • VM already exists → delete it first or use a different name"
  echo ""
  echo "Cloud Shell will stay open so you can review the errors."
fi
echo ""
echo "▶  Cloud Shell setup log saved at: $LOG_FILE"
echo ""
🔒
What this enforcesThe service account is dedicated to this VM and only has roles/aiplatform.user. That allows Vertex AI model calls through Application Default Credentials, but does not grant Compute, IAM, Storage, Secret Manager, or project-admin access. The VM startup script configures 2 GB swap automatically on first boot, before you even connect.
⚠️
Security tradeoffThis is more permissive than a zero-role VM because Nanobot can spend Vertex AI quota or billing credits if misused. Keep budget alerts enabled and do not grant extra roles to nanobot-sa.
Diagnostic logs for VM creation ▸

If Cloud Shell disconnects, reopen Cloud Shell and inspect the persisted setup log in your Cloud Shell home directory. VM startup output is also available through serial-port output, which does not require SSH into the VM.

☁️ Google Cloud Shellbash — setup log
ls -lt ~/nanobot-logs
tail -n 160 ~/nanobot-logs/gcp-vm-create-*.log
☁️ Google Cloud Shellbash — VM startup log
gcloud compute instances get-serial-port-output nanobot-vm --zone=us-central1-a --port=1 | tail -n 200
🖥️ VM SSH Terminalbash — on-disk startup log
sudo tail -n 160 /var/log/nanobot-startup.log

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
💡
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. The service account receives only Vertex AI User so the VM can call Vertex AI later without storing a JSON key.

☁️ Google Cloud Shell bash
PROJECT_ID="$(gcloud config get-value project 2>/dev/null)"
gcloud services enable compute.googleapis.com iam.googleapis.com aiplatform.googleapis.com --project="$PROJECT_ID"
gcloud iam service-accounts create nanobot-sa \
  --display-name="Nanobot SA — Vertex AI only" \
  --project="$PROJECT_ID" || true
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:nanobot-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user" \
  --condition=None

Or via the Console: IAM & Admin → Service Accounts → + Create Service Account — fill name nanobot-sa, grant Vertex AI User, 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; under Access scopes, choose Allow full access to all Cloud APIs. IAM still limits this service account to Vertex AI only.
  6. Firewall: leave both HTTP and HTTPS unchecked.
    🔒
    Nanobot dials outbound HTTPS to messaging services, Brave Search, and your selected model provider. 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, proceed to API keys.
2

Obtain API Keys

Set up the channels and model provider you selected above

Telegram Bot Setup

💻
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
  • Telegram Bot Token
  • Telegram User ID

Gemini API Key Free Tier

💻
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 may begin with AIzaSy... or AQ.
Gemma 4 26B free tierWhat to check
Default model in this guidegemma-4-26b-a4b-it
Where the free limit is shownGoogle AI Studio → Usage & billingRate limits for your project/model
How limits are enforcedPer project, across RPM, input TPM, and RPD; hitting any one limit can return a 429 rate-limit error.
Daily resetRequests/day quotas reset at midnight Pacific time.
GCP billing impactAI Studio usage remains separate from the VM free tier; enabling a paid tier is optional and changes API quotas.
💡
Why no fixed number here?Google documents that active Gemini API limits vary by model, project, tier, and account status. For Gemma 4 26B, use the live AI Studio rate-limit page as the source of truth before scheduling recurring jobs.
🔑 Paste your Gemini API Key — updates all code snippets
From Google AI Studio — commonly starts with AIzaSy... or AQ.
○ Not yet entered
  • Gemini API Key

Brave Search API Key ~US$1 one-time

💻
Run this section in your browserVisit api.search.brave.com — no VM or Cloud Shell needed.

Brave Search is the web search backend hardcoded in Nanobot. It gives your agent real-time access to current information. The Search plan includes US$5 of free API calls per month (~1,000 queries). Subscribing may incur a small one-time charge of approximately US$1 that's usually reversed; you can set a usage limit to stay within the free US$5 monthly credits.

  1. Go to api.search.brave.comSign Up or log in.
  2. Subscribe to the Search plan. A credit card is required — a small one-time authorization charge of ~US$1 may appear (refunded or credited).
  3. Once subscribed, go to API Keys+ Add API Key → name it nanobot.
  4. Copy the key — it starts with BSA.
  5. Set a usage limit (recommended): In your Brave account → Subscriptions → set a monthly cap at or below US$5 to avoid unexpected charges.
Plan detailValue
Plan nameSearch
Free credits/monthUS$5 (~1,000 queries)
One-time signup charge~US$1 (authorization hold)
Credit card requiredYes
🔑 Paste your Brave Search API Key — updates all code snippets
From api.search.brave.com → API Keys — starts with BSA...
○ Not yet entered
  • Brave Search API Key
3

Install Nanobot in Compute Engine

Deploy, configure, run, and verify your AI agent on the VM

🖥️
Everything in this section runs inside the VM SSH terminalOpen it via: GCP Console → Compute Engine → VM instances → SSH button next to nanobot-vm.
Username auto-detected! The install script below automatically runs whoami to detect your Linux username — no manual entry needed.
🤖 Advanced: Custom Model ID (Click to expand)
⚠️
Advanced setting — only change if you know the exact model name! Incorrect model names will cause Nanobot to fail at startup. Leave blank to use the selected provider's recommended default.
🤖 Override Selected Provider Model ID
💡 Use the exact model ID for the selected provider. For Gemini, do not add gemini/. For Groq GPT-OSS, use a Groq model ID such as openai/gpt-oss-20b or openai/gpt-oss-120b while keeping provider groq. Examples: gemma-4-26b-a4b-it, claude-sonnet-4-6, openrouter/auto, openai/gpt-oss-20b.
○ Using default model
Key Step: Auto-Install Nanobot
Your values and selected channels/model are pre-filled. Verify, then paste the entire script into the VM terminal
🤖
Selected AI provider/modelLoading…
⚠️
Do not run a full OS upgrade during this installThe script updates the package index only. A full apt-get upgrade can restart services on the tiny free-tier VM and cut off your SSH session before Nanobot, config.json, or the systemd service are created.
🖥️ VM SSH Terminalbash — auto-install
Loading…
SSH disconnected during install? ▸
💡
Reconnect and rerun the auto-install script from the startIt is safe to rerun: it reuses ~/.nanobot, reinstalls missing Python packages, rewrites config.json, and recreates the systemd unit.
🖥️ VM SSH Terminaldiagnostic
ls -lt ~/.nanobot/install-logs
tail -n 200 ~/.nanobot/install-logs/nanobot-install-*.log
ls -l ~/.nanobot/venv/bin/nanobot ~/.nanobot/config.json /etc/systemd/system/nanobot.service
ls -l ~/.litellm-vertex/config.yaml /etc/systemd/system/litellm-vertex.service 2>/dev/null || true
  1. Update system and install Python:
    🖥️ VM SSH Terminal
    sudo apt-get update
    sudo apt-get install -y python3-venv python3-pip curl openssl
  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/python -m pip install --upgrade pip
    ~/.nanobot/venv/bin/python -m pip install nanobot-ai
  4. Verify:
    🖥️ VM SSH Terminal
    test -x ~/.nanobot/venv/bin/nanobot
    ~/.nanobot/venv/bin/nanobot --version
  5. Create config file:
    🖥️ VM SSH Terminal
    nano ~/.nanobot/config.json
    Paste the config below (dynamically generated from your selections and values):
    🖥️ VM SSH Terminaljson — ~/.nanobot/config.json
    Loading…
    Save: Ctrl+XYEnter
  6. Lock down permissions:
    🖥️ VM SSH Terminal
    chmod 600 ~/.nanobot/config.json
  7. Start Nanobot:

    Choose how to run Nanobot from your VM terminal.

    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"
Service control commands ▸

The auto-install script runs Nanobot as a system service so it starts after reboot and restarts after crashes.

🖥️ VM SSH Terminalbash
sudo systemctl status nanobot --no-pager
sudo journalctl -u nanobot -f
sudo systemctl restart nanobot
Manual run alternatives for debugging
🖥️ VM SSH Terminalbash
sudo systemctl stop nanobot
~/.nanobot/venv/bin/nanobot gateway
What do these config settings mean? ▸
KeyPurpose & security note
channels.telegram.allowFromSecurity control. Only this specific Telegram User ID (stored as a quoted string) can send commands. Add more entries if sharing access.
tools.web.search.providerSet to brave; Nanobot's web search tool uses Brave Search.
tools.web.search.apiKeyBrave Search API key. The Search plan gives US$5/month in free credits.
tools.exec.timeoutLimits shell command execution to 60 seconds. Prevents runaway processes.
tools.restrictToWorkspaceWhen true, limits file access to the workspace directory only. Set to false if Nanobot needs broader file access.
providers.custom.apiBaseWhen Vertex AI is selected, points Nanobot to local LiteLLM at http://127.0.0.1:4000/v1; LiteLLM then calls Vertex AI using the VM service account.
agents.defaults.modelFor Vertex AI mode this stays vertexaimodel. The real Vertex model ID is configured in LiteLLM, so changing Vertex models does not require changing Nanobot's alias.
maxToolIterations: 40Caps tool calls per response — prevents runaway loops from exhausting API quotas.

Verify the Installation

💻
Run this test from your messaging appNo VM access needed — open the messaging app you configured and test your bot.
  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.

Set up cost alerts (recommended) ▸
💻
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 ✅
Gemma 4 26B (AI Studio)Check live AI Studio rate limitsLow ✅
Vertex AI modelsUses GCP billing/trial credits; not part of the AI Studio free tierKeep budget alerts on ✅
Brave Search (Search plan)US$5 free credits/moLow ✅
Ephemeral external IP (running VM)FreeFree ✅
Installation Complete: Open Next Steps →

Reference & Troubleshooting Appendices System service, logs, search notes, and WhatsApp bridge setup
A

Appendix A: System Service Optional

🖥️
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

🖥️
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 contains your Telegram User ID as a quoted string: ["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).
Brave Search 401 / web search errors
  1. Log in to api.search.brave.com — verify key is active and monthly credits not exceeded.
  2. Confirm "apiKey" in the tools.web.search block matches your Brave key (starts with BSA).

C

Appendix C: Search Backend Notes

Nanobot's web search tool is hardcoded to use the Brave Search API. Alternative search providers (e.g. Tavily) are not supported at this time.

Managing Brave Search costs

  1. Log in to api.search.brave.com → go to your Subscriptions page.
  2. Set a monthly usage cap at or below US$5 to stay within the free credit allocation.
  3. Monitor usage under Dashboard → Usage. Each query costs ~US$0.005.
  4. If you exceed the free credits, Brave will charge your card on file. The usage cap prevents this.
💡
TipThe maxToolIterations: 40 setting in config.json also indirectly limits search calls per conversation — a runaway agent cannot issue unlimited queries.

D

Appendix D: WhatsApp Bridge as systemd Service

🖥️
All commands in this appendix run in the VM SSH terminal.

The WhatsApp bridge requires a persistent process to maintain the connection. This appendix shows how to run it as a systemd service that survives terminal close and system restarts.

Prerequisites

Create WhatsApp Bridge Service

Create a systemd service file for the WhatsApp bridge:

🖥️ VM SSH Terminal bash
sudo tee /etc/systemd/system/nanobot-whatsapp-bridge.service > /dev/null << 'EOF'
[Unit]
Description=Nanobot WhatsApp Bridge
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_LINUX_USERNAME
WorkingDirectory=/home/YOUR_LINUX_USERNAME
ExecStart=/home/YOUR_LINUX_USERNAME/.nanobot/venv/bin/nanobot channels login
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

Enable and Start the Bridge Service

🖥️ VM SSH Terminal bash
sudo systemctl daemon-reload
sudo systemctl enable nanobot-whatsapp-bridge.service
sudo systemctl start nanobot-whatsapp-bridge.service

Verify Bridge Status

🖥️ VM SSH Terminal bash
sudo systemctl status nanobot-whatsapp-bridge.service

You should see Active: active (running). To view logs:

🖥️ VM SSH Terminal bash
sudo journalctl -u nanobot-whatsapp-bridge.service -f

Update Nanobot Gateway Service

If you're using the systemd service from Appendix A, ensure the gateway service starts after the bridge:

🖥️ VM SSH Terminal bash
sudo sed -i '/^After=/s/$/\nAfter=nanobot-whatsapp-bridge.service/' /etc/systemd/system/nanobot.service
sudo systemctl daemon-reload
sudo systemctl restart nanobot.service
💡
Service ManagementStop: sudo systemctl stop nanobot-whatsapp-bridge · Restart: sudo systemctl restart nanobot-whatsapp-bridge · Disable auto-start: sudo systemctl disable nanobot-whatsapp-bridge
⚠️
Session PersistenceThe bridge session is stored in ~/.nanobot/bridge/. If you delete this directory, you'll need to re-scan the QR code. Back it up before major system changes.
Steps Navigation 0/6