Module 6

Deployment & Production

Take your bot from local development to live production. Learn the complete deployment workflow: create your bot account in Towns Developer Portal, push code to GitHub, deploy on Render, and connect everything with webhooks. By the end, your bot will be live and responding in Towns!

5 steps

Intermediate

Learning Objectives

By the end of this module, you will be able to:

Create and configure a bot account in Towns Developer Portal

Set up a GitHub repository and push your bot code

Deploy your bot to Render with proper environment configuration

Connect your deployed bot to Towns Protocol using webhooks

Test and verify your bot is working in production

Towns Developer Portal

What You'll Get

Two critical credentials that connect your bot to the Towns Protocol network:APP_PRIVATE_DATAandJWT_SECRET. Keep these safe!

Step-by-Step Setup

Go to app.towns.com/developer

Connect with your Towns account (not just your wallet)

Don't have a Towns account yet?

Before creating a bot, you need an active Towns account:

1. Go to app.towns.com
2. Create an account and connect your wallet
3. Join or create a space to activate your account
4. Once active, return to app.towns.com/developer

Click "Create New Bot" and fill in details:

• Username: my_awesome_bot (lowercase, underscores allowed, no spaces)
• Display Name: My Awesome Bot (how it appears in Towns)
• Description: Brief description of what your bot does
• Bot Pricing: Select "Free"
• Bot Type: Select "Simple Bot"

Set Bot Permissions (check the boxes you need):

Essential Permissions (recommended):

• ✅ Read Messages - Allow the bot to read messages
• ✅ Send Messages - Allow the bot to send messages
• ✅ React to Messages - Allow the bot to react to messages

Optional Permissions (for moderation bots):

• Delete Messages - Allow the bot to delete messages
• Ban Members - Allow the bot to ban members
• Pin Messages - Allow the bot to pin messages
• Manage Channels - Allow the bot to create and manage channels
• Manage Roles & Permissions - Allow the bot to create and manage roles

SAVE ALL YOUR CREDENTIALS (CRITICAL):

• Copy APP_PRIVATE_DATA (base64 encoded bot authentication)
• Copy JWT_SECRET (webhook verification token)
• Copy MNEMONIC (12-word recovery phrase for bot wallet)
• Note your bot wallet addresses (bot.botId and bot.appAddress)

⚠️ CRITICAL: If you lose APP_PRIVATE_DATA or MNEMONIC, they CANNOT be recovered! You will need to create a new bot. Store them securely!

💡 Bot has two wallets: signing address (bot.botId) and execution address (bot.appAddress)

Next Step

Your bot account is created! Now let's push your code to GitHub so we can deploy it.

Push to GitHub

Create a GitHub repository and push your bot code so Render can deploy it.

Create GitHub Repository

Go to github.com/new

Fill in repository details:

• Repository name: "my-towns-bot"
• Description: "My Towns Protocol bot"
• ✅ Private (recommended for security)
• ❌ Don't add README, .gitignore, or license (your project has them)

Click "Create repository"

Copy the repository URL (e.g., https://github.com/yourusername/my-towns-bot.git)

Push Your Code

Run these commands in your terminal (in your bot project directory):

Git Commands

# Initialize git repository
git init

# Add all files
git add .

# Create first commit
git commit -m "Initial bot setup"

# Add your GitHub repository as remote
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git

# Push to GitHub
git branch -M main
git push -u origin main

Important

Replace YOUR_USERNAME and YOUR_REPO_NAME with your actual GitHub username and repository name.

Success!

Your code is now on GitHub! Next, we'll deploy it to Render.

Deploy on Render

Deploy your bot to Render's free tier and configure environment variables.

Why Render?

Render offers a free tier perfect for bots, with automatic deployments from GitHub, persistent storage, and easy environment variable management.

Deploy Your Bot

Go to render.com and sign up with GitHub

Render will automatically access your repositories through GitHub

Click "New" → "Web Service" → Connect your bot repository

Select the repository you just created on GitHub

Configure deployment settings:

• Name: "my-towns-bot"
• Build Command: bun install && bun run build
• Start Command: bun run start
• Instance Type: Free

Add Environment Variables (click "Advanced"):

• APP_PRIVATE_DATA: Paste from Developer Portal (Step 1)
• JWT_SECRET: Paste from Developer Portal (Step 1)
• MNEMONIC: Paste your 12-word recovery phrase (Step 1)
• PORT: 5123

⚠️ These are the credentials you saved from the Developer Portal!

(Optional) Add Persistent Disk for Database:

• Scroll to "Disks" section
• Click "Add Disk"
• Name: bot-database
• Mount Path: /data
• Size: 1 GB (free tier)
• Add env var: DATABASE_PATH=/data/bot.db

Add Discovery Endpoint (REQUIRED):

• Create file: public/.well-known/agent-metadata.json
• Content: {"type": "agent"}
• This is MANDATORY for bot discovery in Towns

Click "Deploy" and wait 2-5 minutes

Watch the build logs to see your bot being deployed

Deployment Complete!

After deployment, you'll get a URL like https://my-towns-bot.onrender.com. Save this URL - you'll need it for the webhook!

Connect Webhook

Link your deployed bot to Towns Protocol so it can receive and respond to messages.

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!

Configure Webhook

Go back to Towns Developer Portal

Find your bot and click "Edit"

Set Webhook URL:

https://your-bot.onrender.com/webhook

⚠️ Important: Add /webhook to the end!

Configure Message Forwarding:

• ✅ All Messages (so bot can respond to "GM")
• ✅ Mentions (when @bot is mentioned)
• ✅ Replies (when someone replies to bot)
• ✅ Reactions (emoji reactions)
• ✅ Channel Joins (user joins/leaves)

Click "Save Changes"

Your bot is now connected to Towns Protocol!

Webhook Connected!

Your bot can now receive messages from Towns. Let's test it!

Test Your Bot

Install your bot in a Towns space and verify everything works!

The Moment of Truth!

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

Install & Test

Go to Towns Developer Portal

Find your bot and click "Install Bot"

Choose your space and channels:

• Select Space: Choose the space where you want the bot
• Select Channels: Pick which channels the bot can access
• Permissions: Confirm the bot permissions

You need admin permissions in the space to install bots

Test your bot:

• Send "GM" → Bot should respond with a greeting
• Try /help → Should show available commands
• Test slash commands → Try any commands you created
• Check reactions → Add emoji reactions to messages

✓

🎉 Success! Your bot is alive and responding!

Congratulations! You've successfully deployed a production Towns bot.

Troubleshooting

Bot not responding?

• Check Render logs for errors
• Verify environment variables are set correctly
• Make sure webhook URL ends with /webhook
• Check bot permissions in Developer Portal
• Visit https://your-bot.onrender.com/health to check bot status