Local Development Setup

This guide explains how to develop and test bots locally using VSCode and the Ugly Bot CLI, instead of using the web editor.

Prerequisites

  • Python 3.10 or later

  • VSCode (optional, for the extension)

Set Up Project

Create a directory for your bot and set up a virtual environment:

mkdir my-bot && cd my-bot
python -m venv venv
source venv/bin/activate      # macOS/Linux
venv\Scripts\activate          # Windows

Install the Ugly Bot CLI and SDK into the virtual environment:

pip install ugly-bot

Verify the installation:

ugly-bot --help

To upgrade to the latest version:

pip install --upgrade ugly-bot

Note

Always activate your virtual environment before running ugly-bot commands. The CLI, dev tunnel, and your bot code all run from the same venv.

Login

Authenticate the CLI with your Ugly Bot account:

ugly-bot login

This opens your browser to log in. After logging in, the CLI stores a token locally at ~/.ugly-bot/auth.json.

Sync Bot Code

Download an existing bot’s code to your local machine:

ugly-bot sync <botId>

This creates the bot’s files in the current directory and generates an ugly-bot.json config file.

To find your botId, open the bot’s Settings tab and look under the Local Development section — click Copy Bot ID to copy it to your clipboard.

To re-sync later (e.g., after someone edits via the web editor):

ugly-bot sync

This uses the botId from ugly-bot.json.

If your bot has additional dependencies, install them:

pip install -r requirements.txt

Start Dev Tunnel

Run the dev tunnel to route your bot’s traffic to your local machine:

ugly-bot dev

This:

  1. Connects to the Ugly Bot server via WebSocket

  2. Registers a tunnel for your bot

  3. Watches for .py file changes and hot-reloads automatically

  4. Routes only your messages to the local bot — other users’ traffic is unaffected

While the tunnel is active, open a conversation with your bot on the website. Your messages will trigger the local code instead of the production code.

Make Changes

Edit your bot’s Python files in any editor. When you save a .py file, the dev tunnel automatically kills the running bot process. The next message triggers a fresh process with your updated code.

Publish

When you’re ready to deploy your changes to production:

ugly-bot publish

This uploads all local files (respecting .gitignore) to the server’s bot code database. Other users will immediately see the updated bot.

VSCode Extension

For a streamlined experience, install the Ugly Bot VSCode extension.

Installing the Extension

  1. Download ugly-bot.vsix from the bot’s Settings tab (under “Local Development”)

  2. In VSCode, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

  3. Run Extensions: Install from VSIX…

  4. Select the downloaded .vsix file

Using the Extension

The extension activates when your workspace contains an ugly-bot.json file.

Status Bar: Shows tunnel status in the bottom bar. Click to start the dev tunnel.

Commands (via Command Palette):

  • Ugly Bot: Start Dev Tunnel — starts ugly-bot dev in the integrated terminal

  • Ugly Bot: Stop Dev Tunnel — stops the tunnel

  • Ugly Bot: Sync Bot Code — runs ugly-bot sync

  • Ugly Bot: Publish Bot Code — runs ugly-bot publish

  • Ugly Bot: Open Preview — opens an embedded browser panel showing the Ugly Bot website

Typical Workflow

  1. Create project directory and virtual environment

  2. pip install ugly-bot — install CLI and SDK

  3. ugly-bot login — authenticate

  4. ugly-bot sync <botId> — download bot code

  5. pip install -r requirements.txt — install bot dependencies

  6. ugly-bot dev — start the dev tunnel

  7. Edit code, test in browser, iterate

  8. ugly-bot publish — deploy to production