🚀 nanobot-serverless-deploy

One-Click Serverless Deployment for nanobot AI Assistant

Deploy nanobot to popular serverless platforms with zero local setup required. Access your AI assistant from Telegram anywhere, anytime.

✨ Features

🎯 One-Command Deployment - Deploy to Google Cloud Run with a single script
💰 Free Tier Support - Runs entirely on GCP Always-Free tier
🔄 24/7 Availability - No need to keep your computer running
📱 Telegram Integration - Full Telegram bot support via webhooks
💾 Persistent Storage - All data stored in Google Cloud Storage (chat history, sessions, files)
⚡ Serverless Optimized - Cold start optimization and automatic scaling

🏗️ Architecture

┌─────────────────────────────────────────┐
│   Google Cloud Run (Serverless)        │
│  ┌───────────────────────────────────┐  │
│  │  FastAPI HTTP Handler             │  │
│  │  - Telegram webhook endpoint      │  │
│  │  - Health check endpoint          │  │
│  └───────────────────────────────────┘  │
│           │                              │
│           ▼                              │
│  ┌───────────────────────────────────┐  │
│  │  nanobot Gateway Adapter          │  │
│  │  - Initialize from env vars       │  │
│  │  - Handle webhook events          │  │
│  │  - Sync files to/from GCS         │  │
│  └───────────────────────────────────┘  │
│           │                              │
└───────────┼──────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────┐
│   External Services                      │
│  - Google Cloud Storage (persistent)    │
│  - OpenRouter API (LLM)                 │
│  - Brave Search API (optional)          │
└─────────────────────────────────────────┘

🚀 Quick Start

Tip

Get API keys: OpenRouter (LLM) · Brave Search (optional, for web search) You can also change the model to minimax/minimax-m2 for lower cost.

Prerequisites

Before deploying, you'll need:

OpenRouter API Key - Get from OpenRouter.ai
Telegram Bot Token - Create a bot with @BotFather
Telegram User ID - Get from @userinfobot
Google Cloud Platform Account - Create at cloud.google.com

Deploy to Google Cloud Run

1. Clone repository

git clone elliot35/nanobot-serverless-deploy
cd serverlessbot

2. Configure environment

# Copy template
cp .env.example .env

# Edit .env file with your credentials
# Required:
# - NANOBOT_OPENROUTER_API_KEY
# - TELEGRAM_BOT_TOKEN
# - TELEGRAM_ALLOWED_USERS
# Optional:
# - GCS_BUCKET_NAME (auto-created if not set)
# - NANOBOT_MODEL (defaults to anthropic/claude-opus-4-5)
# - BRAVE_SEARCH_API_KEY

3. Set GCP project

export GCP_PROJECT_ID=your-project-id
# Or set it permanently:
gcloud config set project your-project-id

4. Load environment variables

# For bash/zsh:
set -a
source .env
set +a

5. Deploy

./gcp/deploy.sh

The script will:

✅ Enable required GCP APIs
✅ Create GCS bucket for persistent storage
✅ Build and push Docker image
✅ Deploy to Cloud Run
✅ Provide service URL and next steps

6. Set Telegram webhook

After deployment, the script will output your service URL. Then:

curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook?url=https://your-service-url.run.app/api/webhook/telegram"

7. Test

Send a message to your bot on Telegram - it should respond!

💾 Storage

All data is automatically stored in Google Cloud Storage:

Data Type	Storage Location	Format
Chat History	`sessions/{session_key}/chat_history.jsonl`	JSONL (one message per line)
Sessions	`sessions/{session_key}/session.json`	JSON
Agent Actions	`sessions/{session_key}/agent_actions.jsonl`	JSONL
Files	`sessions/{session_key}/files/`	Any file type

Automatic syncing:

Files are synced from GCS before processing (agent can access previous files)
Chat history is loaded automatically (up to 50 previous messages)
Files are synced to GCS after processing (persists across invocations)

📋 Environment Variables

Required

Variable	Description	Example
`NANOBOT_OPENROUTER_API_KEY`	OpenRouter API key for LLM access	`sk-or-v1-xxx`
`TELEGRAM_BOT_TOKEN`	Telegram bot token from @BotFather	`123456:ABC...`
`TELEGRAM_ALLOWED_USERS`	Comma-separated list of allowed user IDs	`123456789,987654321`

Optional

Variable	Description	Default
`GCS_BUCKET_NAME`	GCS bucket name for storage	`{PROJECT_ID}-nanobot-files`
`GCP_PROJECT_ID`	GCP project ID	Auto-detected from gcloud
`NANOBOT_MODEL`	LLM model identifier	`anthropic/claude-opus-4-5`
`BRAVE_SEARCH_API_KEY`	Brave Search API key	-
`LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)	`INFO`

See .env.example for a complete example.

🧪 Testing

Health Check

curl https://your-service-url.run.app/api/health

Expected response:

{
  "status": "healthy",
  "checks": {
    "bus": true,
    "agent_loop": true,
    "session_manager": true,
    "config": true,
    "workspace": true,
    "storage_manager": true,
    "gcs": true
  }
}

View Logs

gcloud run services logs read nanobot-gateway \
  --region us-central1 \
  --project your-project-id \
  --limit 50

🗑️ Cleanup

To remove all deployed resources:

export GCP_PROJECT_ID=your-project-id
./gcp/destroy.sh

This will delete:

✅ Telegram webhook
✅ Cloud Run service
✅ Container images
⚠️ GCS bucket (optional, with confirmation)

Note: GCS data (sessions, chat history, files) will be preserved unless you choose to delete the bucket.

💰 Free Tier Limits

Google Cloud Run (Always-Free)

✅ 2 million requests/month
✅ 360,000 GB-seconds compute/month
✅ 180,000 vCPU-seconds/month
✅ 1 GB egress/month
⚠️ Requires billing account (but stays within free tier for small usage)

Google Cloud Storage (Always-Free)

✅ 5GB storage/month
✅ 1GB egress/month
✅ Automatic scaling
⚠️ Requires billing account (but stays within free tier for small usage)

🐛 Troubleshooting

Health check returns "unhealthy"

Check logs for detailed error messages:

gcloud run services logs read nanobot-gateway --region us-central1 --project your-project-id --limit 50

Common issues:
- Missing environment variables (especially GCS_BUCKET_NAME)
- Invalid API keys or tokens
- GCS bucket permissions issues
- Import errors (check that nanobot is installed correctly)

Bot not responding

Check webhook is set correctly:

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Verify webhook URL matches your deployment URL exactly

Check logs for errors:

gcloud run services logs read nanobot-gateway --region us-central1

Verify environment variables are set correctly in Cloud Run
Check user ID is in TELEGRAM_ALLOWED_USERS (comma-separated, no spaces)

GCS storage errors

Verify bucket exists:
```
gsutil ls gs://your-bucket-name
```

Check bucket permissions - Cloud Run service account needs storage.objectAdmin role:

gsutil iam ch serviceAccount:PROJECT_ID@appspot.gserviceaccount.com:roles/storage.objectAdmin gs://your-bucket-name

Verify GCS_BUCKET_NAME environment variable is set correctly

Check GCS API is enabled:

gcloud services enable storage-api.googleapis.com --project your-project-id

Cold start delays

First request may take 5-10 seconds (cold start)
Subsequent requests are faster (warm instances)

Consider increasing min instances for production:

gcloud run services update nanobot-gateway \
  --min-instances 1 \
  --region us-central1

📁 Project Structure

serverlessbot/
├── README.md                    # This file
├── .env.example                 # Environment variables template
├── gcp/
│   ├── main.py                 # Cloud Run FastAPI app
│   ├── requirements.txt        # Python dependencies
│   ├── Dockerfile              # Docker image for Cloud Run
│   ├── cloudbuild.yaml         # Cloud Build configuration
│   ├── deploy.sh               # One-command deployment script
│   └── destroy.sh              # Cleanup script
├── src/
│   ├── adapter.py              # nanobot gateway adapter
│   ├── config.py               # Environment-based config loader
│   ├── storage.py              # GCS persistent storage
│   └── handlers.py             # HTTP request handlers
└── scripts/
    └── setup_mongodb.py        # (Deprecated - no longer needed)

🔧 Local Development

# Clone repository
git clone <YOUR_REPO_URL>
cd serverlessbot

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r gcp/requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env file with your credentials

# Load environment variables
set -a
source .env
set +a

# Run locally
python -m uvicorn gcp.main:app --host 0.0.0.0 --port 8080

# Test health endpoint
curl http://localhost:8080/api/health

📚 Additional Resources

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built for nanobot by HKUDS
Inspired by the need for easy serverless deployment

Made with ❤️ for the nanobot community

Get Started • Troubleshooting • Cleanup

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🚀 nanobot-serverless-deploy

✨ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Deploy to Google Cloud Run

💾 Storage

📋 Environment Variables

Required

Optional

🧪 Testing

Health Check

View Logs

🗑️ Cleanup

💰 Free Tier Limits

Google Cloud Run (Always-Free)

Google Cloud Storage (Always-Free)

🐛 Troubleshooting

📁 Project Structure

🔧 Local Development

📚 Additional Resources

🤝 Contributing

📝 License

🙏 Acknowledgments

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🚀 nanobot-serverless-deploy

✨ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Deploy to Google Cloud Run

💾 Storage

📋 Environment Variables

Required

Optional

🧪 Testing

Health Check

View Logs

🗑️ Cleanup

💰 Free Tier Limits

Google Cloud Run (Always-Free)

Google Cloud Storage (Always-Free)

🐛 Troubleshooting

📁 Project Structure

🔧 Local Development

📚 Additional Resources

🤝 Contributing

📝 License

🙏 Acknowledgments