Skip to content

Installation

Philippe edited this page Nov 13, 2026 · 1 revision

Installation

You need a machine that is always on, for example a VPS, a home server or a Raspberry Pi. It must be able to reach your Crafty Controller and the internet (for Discord).

1. Create a Crafty user and API token

A separate Crafty user for the bot is recommended.

  1. Open your Crafty Controller and click on the gear icon in the top right corner.
  2. Click on add user and enter a name, for example crafty_bot. Crafty only accepts 3 to 20 lowercase letters, digits or underscores (no spaces).
  3. Fill in the required fields and click on Save.
  4. Give the user a role that has access to the servers the bot should control (create one with add role if needed). Without it Crafty returns no servers and list stays empty.
  5. Click on the pencil icon next to the user, then on API Key, and select these permissions:
    • COMMANDS (start, stop, restart)
    • TERMINAL
    • PLAYERS
    • BACKUP (only needed for the backup command)
  6. Enter a name for the token, click on Create and save the token. This is your CRAFTY_TOKEN.

Note

Logging in with CRAFTY_USERNAME and CRAFTY_PASSWORD instead of a token works too, but not for users with two-factor authentication. A token is recommended.

2. Create the Discord bot

  1. Open the Discord Developer Portal and click on New Application.
  2. Enter a name (for example "Crafty Bot"), accept the terms and click on Create.
  3. Open Bot in the left-hand menu:
    • Disable Public Bot.
    • Enable Message Content Intent under Privileged Gateway Intents. The bot needs it for the > commands and doesn't start without it.
    • Click on Reset Token, confirm and copy the token. This is your DISCORD_TOKEN.
  4. Open OAuth2 → URL Generator:
    • Scopes: bot and applications.commands
    • Bot permissions: View Channels, Send Messages, Read Message History and Use Application Commands
  5. Open the generated URL, select your Discord server and click on Authorize.

The person who owns the Discord application is the bot owner. Only the owner can use backup, sync and the other admin commands.

3a. Run with Docker (recommended)

docker run -d --name crafty-bot --restart unless-stopped \
  -e DISCORD_TOKEN=YOUR_DISCORD_TOKEN \
  -e CRAFTY_TOKEN=YOUR_CRAFTY_TOKEN \
  -e SERVER_URL=https://YOUR-CRAFTY-HOST:8443 \
  -v crafty-bot-data:/usr/src/app/data \
  twoplay/craftybot:latest

Or with Docker Compose:

services:
  crafty-bot:
    image: twoplay/craftybot:latest
    container_name: crafty-bot
    environment:
      - DISCORD_TOKEN=YOUR_DISCORD_TOKEN
      - CRAFTY_TOKEN=YOUR_CRAFTY_TOKEN
      - SERVER_URL=https://YOUR-CRAFTY-HOST:8443
      # Optional web dashboard, see the "Web Dashboard" page
      # - WEB_ENABLED=true
      # - WEB_PASSWORD=YOUR_DASHBOARD_PASSWORD
    # ports:
    #   - "8080:8080"
    volumes:
      # Keeps the feature flags changed in the dashboard
      - crafty-bot-data:/usr/src/app/data
    restart: unless-stopped

volumes:
  crafty-bot-data:

All settings are described on the Configuration page. Update with docker compose pull && docker compose up -d.

3b. Run with Python

Python 3.10 or newer is required.

git clone https://github.com/Two-Play/Crafty-Discord-bot.git
cd Crafty-Discord-bot
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # then fill in SERVER_URL, DISCORD_TOKEN and CRAFTY_TOKEN
python -m core

To update, run git pull and pip install -r requirements.txt in the project directory and restart the bot.

4. Enable the slash commands

The > commands work right away. Slash commands only appear after the bot owner runs >sync once, see Commands.

Clone this wiki locally