A Discord bot to streamline running D&D 5e.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Dice 04036e890a
Serving aliases (#1629)
6 days ago
.github build: fix sentry org name 1 month ago
aliasing Serving aliases (#1629) 6 days ago
cogs5e Merge pull request #1676 from avrae/nightly 7 days ago
cogsmisc Serving aliases (#1629) 6 days ago
ddb misc: formatting 2 weeks ago
docker Update development readme 2 months ago
docs feat(aliasing): signature() initial impl 3 weeks ago
gamedata Merge pull request #1658 from avrae/2021w44 1 month ago
migrators chore: load actions in compendium 6 months ago
notes Update workshop-tags.txt 1 year ago
res add new token borders to token command 1 year ago
scripts feat(settings): lookup settings menu 4 weeks ago
test refactor(inline-rolling): use faster regex expr matcher 1 month ago
tests Serving aliases (#1629) 6 days ago
ui feat(settings): add servsettings command 3 weeks ago
utils Merge pull request #1676 from avrae/nightly 7 days ago
.bandit some more CI skips 3 years ago
.dockerignore 🔧 Add dockerignore 2 years ago
.gitattributes [ci skip] Add gitattributes to repository (#1328) 1 year ago
.gitignore cleanup/update deps 9 months ago
.pylintrc add some linting config 3 years ago
.readthedocs.yml update doc builder to use 3.8 2 years ago
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md 3 years ago
Dockerfile misc: remove newrelic [temp] 5 months ago
Dockerfile.ci build: add docker tests back for contrib 5 months ago
LICENSE Add GNU GPLv3 license 3 years ago
README.md docs: clean up docker containers 5 months ago
SECURITY.md chore: create security policy 7 months ago
SUPPORTERS.md update SUPPORTERS 3 years ago
dbot.py chore: disnake startup clustering considerations, test guild config 1 month ago
docker-compose.ci.yml build: add docker tests back for contrib 5 months ago
docker-compose.yml Expose Mongo/Redis ports to the local system 3 years ago
requirements.txt chore(deps): -discord.py, +disnake 1 month ago


Avrae Discord Bot

Avrae Website

Build Status Codacy Badge

Avrae is a Discord bot designed to help you and your friends play D&D online.

You can join the Avrae Development Discord here, and invite Avrae to your own Discord server here!

Key Features

Advanced Dice Roller

With a custom dice parser, Avrae is one of the most advanced dice rollers on Discord, capable of supporting pretty much every type of roll needed to play D&D. Advantage, disadvantage, and crits are built in, you can keep, drop, or reroll dice as needed, dice can explode, and dice can be bounded.

Want to use the dice roller in your own code? Check out the code!

Character Sheet Integration

Avrae can read character sheets from D&D Beyond, Dicecloud, or a Google Sheet, automatically generating macros to roll attacks, ability checks, and saving throws. A player can then simply use a command to make a check, save, attack, or cast, and all necessary rolls will be resolved automatically.

Initiative Tracking

The initiative tracker is a fast way to track combat in a text channel. It supports automatic combatant sorting, HP, AC, resistance, and status effect tracking, and integration with the character sheet manager and 5e content to further streamline combat.


Have a feature in mind that isn't already in Avrae? Avrae provides a fully-featured modding API to write your own commands, and a place to share them with the community!

Check out the docs and the Alias Workshop!


How to run Avrae locally

Check out docker/readme.md.

Building Manually

OS Requirements

Avrae is built on Ubuntu, but should be fully compatible with any UNIX-based system. It is possible to run Avrae on Windows, but is not recommended.

Creating Support Files

You'll need to create a Google Drive Service Account. You can find instructions on how to do this here.

Follow steps 1-3 in the Signed Credentials portion. Rename the JSON avrae-google.json and put it in the project root.



You will need to run a Redis instance to serve as a high-performance cache. Download Redis and run a redis server locally before launching Avrae.


You will also need to run a MongoDB instance to serve as Avrae's database.


Avrae requires Python >= 3.8.0.

Install the dependencies with pip install -r requirements.txt.

Environment Variables

These are the required/recommended environment variables for local dev.

  • ENVIRONMENT - "development" for development
  • DISCORD_BOT_TOKEN - a valid Discord bot token
  • DISCORD_OWNER_USER_ID - your Discord user ID
  • MONGO_URL - a MongoDB connection string (defaults to mongodb://localhost:27017)
  • REDIS_URL - a Redis connection string (defaults to redis://redis:6379/0)
  • NO_DICECLOUD - if set, disables dicecloud connection/importing, otherwise:
    • DICECLOUD_USER - a dicecloud username
    • DICECLOUD_PASS - the password for the dicecloud user
    • DICECLOUD_TOKEN - a dicecloud API token
  • If running Avrae in unsharded mode (recommended for testing), run python dbot.py test.
  • If running Avrae in sharded mode, run python dbot.py.


To test Avrae, run these commands:

docker-compose -f docker-compose.ci.yml -p avrae up -d --build
docker logs -f avrae_tests_1

This should initialize an ephemeral database to run command unit tests in. You should set the DICECLOUD_USER, DICECLOUD_PASS, DICECLOUD_TOKEN, and GOOGLE_SERVICE_ACCOUNT env vars to their correct values.

Once tests complete, it is recommended to clean up the containers with docker-compose down.


Env vars required to deploy to production - not required for local dev:

  • NUM_CLUSTERS - equal to the number of ECS tasks running Avrae
  • DDB_AUTH_SECRET - JWT signing secret for DDB auth request
  • DDB_AUTH_WATERDEEP_SECRET - JWT signing secret for DDB auth response
  • DDB_AUTH_AUDIENCE - JWT audience (default "avrae.io")
  • DDB_AUTH_ISSUER - JWT issuer (default "dndbeyond.com")
  • DDB_AUTH_EXPIRY_SECONDS - JWT expiry (default 5m)
  • DDB_AUTH_SERVICE_URL - DDB Auth Service base URL
  • DYNAMO_REGION - AWS region for Entitlements DB
  • DYNAMO_USER_TABLE - Table name for Entitlements user table
  • DYNAMO_ENTITY_TABLE - Table name for Entitlements entity table
  • AWS_ACCESS_KEY_ID - AWS Access Key to access Dynamo
  • AWS_SECRET_ACCESS_KEY - AWS Secret Access Key
  • CHARACTER_COMPUTATION_ENDPOINT - HTTP endpoint for DDB character computation call

Other env vars:

  • NUM_SHARDS - explicitly set the number of shards to run
  • GIT_COMMIT_SHA - should be set in Travis (required for prod)