Zero to Bot in 30 Minutes

Vibe‑Code Your
Towns Bot

Build production‑ready bots using AI assistance. No coding experience required—just follow the steps, paste the code, and deploy to the world.

Minutes to Deploy

Zero

Coding Experience

∞

Possibilities

Your Journey to Bot Mastery

Follow these 7 simple steps to build and deploy your first Towns bot

Get the Bot Starter Template

Clone the starter template with AI or manually

2 min

Easy

Prepare Your Bot

Load knowledge base files into Cursor

2 min

Easy

Create Bot Account

3 min

Easy

Push to GitHub & Deploy

Push your code to GitHub and deploy it live

8 min

Medium

Configure Webhook

Connect your deployed bot to Towns Protocol

2 min

Easy

Install & Test Bot

Install your bot in a Towns space and verify it works

3 min

Easy

Ready to Level Up?

Add powerful features with AI prompts

∞

Fun

Step 1: Get the Bot Starter Template

Choose your preferred method to get started - both work perfectly!

Option A: Pure Vibe Coding ✨

EASIEST

Let AI clone it for you - Zero effort!

Just copy this prompt and paste into Cursor/Codex AI:

Vibe Coding Prompt

Run this install command for me:
bunx towns-bot init my-towns-bot

Please:
1. if bun isn't installed, install it using instructions here: https://bun.sh/docs/installation
2. follow the instructions to install dependences
3. Confirm when it's ready

Let me know if you need any permissions or have questions!

True vibe coding: AI handles git, install, everything. You just approve when it asks!

After AI finishes installing

Open the project folder in Cursor: File → Open Folder → select my-towns-bot

After AI finishes installing

Open the project folder in Cursor: File → Open Folder → select my-towns-bot

Option B: Terminal

For developers who prefer CLI

Run these commands in your terminal:

Terminal

bunx towns-bot init my-towns-bot

Terminal

cd my-towns-bot

Terminal

bun install

Then open the folder in Cursor: File → Open Folder → select `my-towns-bot`

Step 2: Prepare Your Bot

Let's make sure your bot is ready to deploy (keep it simple!)

Good news! The bot template is already working. It responds to mentions out of the box. We'll deploy it as-is first, then add features once it's live.

Optional: Quick Verification

If you want to verify everything is ready or need help with issues:

Verification Prompt

@AGENTS.md

- README.md
- AGENTS.md
- src/index.ts
- src/commands.ts

Confirm when you've loaded them and let me know you're ready.

Please verify my bot is ready to deploy:
1. Check src/index.ts has the basic onMessage handler
2. Confirm the bot responds when mentioned
3. Make sure package.json has build and start scripts
4. Review the AGENTS.md documentation if there are any issues

Don't add any features - just verify the basic bot works!

Tip: The @AGENTS.md reference tells Cursor AI to use the comprehensive bot documentation included in your project for accurate guidance.

• AGENTS.md - AI agent patterns and architecture
• README.md - Deployment workflow and troubleshooting

Now you're ready to customize!

With all that knowledge loaded, simply ask Cursor to add features in plain English:

• "Add a response when users say 'wagmi'"
• "Create a verification system with ✅ reactions"
• "Build a points system with leaderboard command"
• "Add moderation for bad words"

Cursor will use the knowledge base to write correct, production-ready code!

Step 3: Create Bot Account

Register Your Bot

Open Towns Developer Portal

Click to register your bot and get credentials

1.Click "Create New Bot"
2.Name your bot (e.g., "VibeBot")
3.Copy and save these 3 credentials:
- • APP_PRIVATE_DATA
- • JWT_SECRET
- • MNEMONIC (wallet recovery phrase)

Save All 3 Credentials!

Critical: You'll receive 3 credentials that you must save:

• APP_PRIVATE_DATA - Your bot's private key (cannot be recovered if lost!)
• JWT_SECRET - For webhook verification
• MNEMONIC - Recovery phrase for your bot's wallet (cannot be recovered if lost!)

⚠️ Warning: If you lose APP_PRIVATE_DATA or MNEMONIC, they cannot be recovered and you'll need to create a new bot.

Never commit these keys to GitHub. We'll add them to Render as environment variables in the deployment step.

Step 4: Push to GitHub & Deploy to Render

Push your code to GitHub and deploy it live

Prerequisites

You need a GitHub account and Render account (both free). Create them if you haven't already.

First Time Using Git? Set Up Authentication First

Many beginners get stuck here. Before you can push to GitHub, you need to authenticate. If you've never used Git before, follow one of these methods:

Easiest Method: GitHub CLI

1. Install from cli.github.com
2. Run gh auth login
3. Follow the prompts - it handles everything automatically

Need other methods? Expand the section below for more options.

Part A: Push to GitHub

Use AI to help with Git!

Ask Cursor to help you push to GitHub. Copy this prompt:

AI Prompt

Help me push my Towns bot to GitHub. I need to:
1. Initialize git in this project
2. Create a new repository on GitHub
3. Push all my code to GitHub

Guide me through each step.

The AI will guide you through creating a GitHub repository and pushing your code. Follow its instructions!

Part B: Deploy on Render

1
Go to render.com
Create a Render account and connect it with your GitHub
2
Create a new Web Service
Click "New" → "Web Service" and connect your GitHub repository
3
Configure deployment settings:
Name: my-bot
Environment: Node
Build Command: bun install
Start Command: bun run start
4
Add environment variables (click "Advanced"):
APP_PRIVATE_DATA = Your saved credential
JWT_SECRET = Your saved credential
PORT = 5123
5
Click "Create Web Service" and wait for deployment

Note: After deployment, you'll get a URL like https://my-bot.onrender.com. Save this URL - you'll need it in the next step!

Free tier note: Free Render services may experience 30-60 second delays after inactivity while the service spins up.

Important: Storage on Free Tier

Render free tier services sleep after inactivity. This means:

• In-memory storage (Maps, variables) will be lost on restart
• Your bot will forget all stored data when it wakes up
• Use a database (SQLite, PostgreSQL, or Turso) for persistent storage

Solution: For production bots on free tier, always use database storage, not in-memory Maps or variables.

Add Bot Discovery Endpoint

REQUIRED

This endpoint is required for bot directories to discover and index your bot. Without it, your bot won't appear in bot marketplaces or be discoverable by users. After deploying your bot, go to the developer dashboard and click the Boost button to submit your bot for indexing.

Open src/index.ts and add this route after the /webhook route:

Code

// After your /webhook route

app.get('/.well-known/agent-metadata.json', async (c) => {
  return c.json(await bot.getIdentityMetadata())
})

Required: After adding this endpoint and deploying, visit your bot's developer dashboard and click the "Boost" button to submit your bot for indexing in bot directories.

Step 5: Configure Webhook in Towns

Connect your deployed bot to Towns Protocol

What's a webhook?

A webhook tells Towns where to send messages so your bot can respond. It's like giving Towns your bot's phone number!

1
Go to Towns Developer Portal
Find your bot and click "Edit"
2
Enter your webhook URL:
https://my-bot.onrender.com/webhook
Important: Add /webhook to the end of your Render URL!
3
Configure message forwarding preferences:
All Messages
Bot receives all messages
Mentions, Replies, Reactions, Slash Commands
Recommended. Bot only receives messages when directly mentioned or replied to.
No Messages
Bot only receives status checks (not recommended for interactive bots)
4
Click "Save Changes" to activate your bot

Step 6: Install Bot

Install your bot in a Towns space and verify it works

The moment of truth!

Time to see your bot come alive in Towns. If everything worked, your bot will respond to messages!

Install Your Bot

1
Go to Towns Developer Dashboard
Find your bot in the list
2
Click Install on your bot
Select which space and channels to install it in. Your bot will appear in that space immediately.

Test Your Bot

Go to a channel where your bot is installed and type:

/

You'll see your bot's available commands in the dropdown. Select one to test it!

Try these commands:

• /help - Shows all available commands
• /ping - Bot responds with "Pong!"
• Or mention the bot: @yourbot hello

Congratulations!

You've successfully deployed your first Towns Protocol bot!

Your bot is now live and responding in Towns. Ready to make it more powerful?

Ready to Level Up?

Now that your bot is live, add powerful features with AI

How to use: Copy any prompt below and paste it into Cursor AI. The AI will write the code for you. After adding features, push to GitHub and your bot will auto-update!

Important: Start each prompt with @AGENTS.md to reference the bot documentation for accurate implementation guidance.

Tip Bot

Complete tipping system with leaderboard

Tip to Unlock

Gate features behind tips

Voting Polls

Interactive button polls

User Onboarding

Welcome forms for new users

Points & XP

Gamification with levels

User Lookup

Find users & wallets

Auto-Mod

Auto-delete & warnings

Fun Reactions

Auto-reactions & vibes

Mini Apps

Launch web apps

Pro Tips for Customization

• Test locally with bun dev before pushing changes
• Add multiple features at once to save deployment time
• Check AGENTS.md in your project for advanced patterns
• Remember: bots are stateless - use Maps or databases for storage
• For payment features, fund your bot wallets after deployment

Troubleshooting

Bot not responding?

• Check webhook URL ends with /webhook - This is the most common mistake
• Check Render logs for errors in the dashboard
• Verify environment variables are set correctly (APP_PRIVATE_DATA and JWT_SECRET)
• Check bot permissions in Developer Portal
• If on free tier, wait 30-60 seconds for service to wake up

Deployment failed?

• "Command not found: bun" - Add npm install -g bun to build command
• Check build logs in Render dashboard for specific errors
• Verify package.json has correct scripts
• Make sure all files are committed to GitHub
• Try manual deploy from Render dashboard

"Insufficient funds" errors?

• For payment features: You need to fund your bot's wallets
• Gas Wallet (bot.viem.account): Pays for transaction fees - needs Base ETH
• Bot Treasury (bot.appAddress): Holds bot's funds for sending tips
• Go to developer portal and click your bot to see wallet addresses
• Fund both wallets with Base ETH from any wallet

Need help?

Join the Towns Developer Town for support, or check the complete documentation in your template's README.md file.

Learn More

Level up your bot building skills with comprehensive courses and tutorials

Now that you've built your first bot, explore the Towns Academy to dive deeper into advanced bot development, learn best practices, and discover new ways to leverage the Towns Protocol.

Explore Towns Academy

Vibe‑Code YourTowns Bot

Your Journey to Bot Mastery

Get the Bot Starter Template

Prepare Your Bot

Create Bot Account

Push to GitHub & Deploy

Configure Webhook

Install & Test Bot

Ready to Level Up?

Step 1: Get the Bot Starter Template

Option A: Pure Vibe Coding ✨

First time? Install Cursor first (click to expand)

Option B: Terminal

Step 2: Prepare Your Bot

Step 3: Create Bot Account

Register Your Bot

Step 4: Push to GitHub & Deploy to Render

First Time Using Git? Set Up Authentication First

Easiest Method: GitHub CLI

More Git Authentication Methods

First Time? Setup Git & GitHub Authentication

Part A: Push to GitHub

Part B: Deploy on Render

Important: Storage on Free Tier

Add Bot Discovery Endpoint

Step 5: Configure Webhook in Towns

Step 6: Install Bot

Install Your Bot

Test Your Bot

Ready to Level Up?

Troubleshooting

Bot not responding?

Deployment failed?

"Insufficient funds" errors?

Need help?

Learn More

Vibe‑Code Your
Towns Bot