Quick Start

Install

pip install cordless

uv add cordless

Scaffold

mkdir my-bot && cd my-bot
cordless init my-bot

This asks how Discord should reach your bot: a direct Lambda Function URL (recommended, lower latency) or an API Gateway HTTP API (only needed if you want a custom domain later). Pick 1 unless you already know you want a custom domain.

This creates lambda_function.py, cordless.toml, and .env.example.

lambda_function.py

import os

from cordless import Cordless

bot = Cordless(public_key=os.environ.get("DISCORD_PUBLIC_KEY"))

@bot.command("hello", description="Say hello")
async def hello(ctx, name: str = "world"):
    await ctx.send(f"Hello, {name}!")

handler = bot.handler()

Typed parameters become Discord options automatically: name: str = "world" registers an optional string option.

Configure

Fill in your credentials. Create a .env file in your project root (cordless loads it automatically for all commands and merges it into your Lambda’s environment on deploy):

.env

DISCORD_PUBLIC_KEY=your_public_key
DISCORD_BOT_TOKEN=your_bot_token

cordless.toml

[deploy]
function = "my-bot"
region = "us-east-1"

Test locally

cordless dev

Runs your bot on localhost with hot reload. With cloudflared installed it also opens a public tunnel, paste that URL into your app’s Interactions Endpoint URL and test in Discord without deploying anything. Deferred handlers run in-process, so the whole flow works.

Install cloudflared

brew install cloudflared

winget install Cloudflare.cloudflared

curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install cloudflared

paru -S cloudflared

Or download a binary directly from the Cloudflare releases page.

Deploy

cordless deploy --register

One command: cordless creates the Lambda, its endpoint (a Function URL by default), and the IAM role, registers your slash commands with Discord, and prints your bot’s URL. Paste it into your Discord app’s Interactions Endpoint URL and run /hello.

You can also register separately with cordless register, add --guild-id during development for instant propagation.