Getting started

This page tells you how to run Platform on your machine, and on one RunPod pod without Docker.

ToolsCopy Anchor Link

Run it on your machineCopy Anchor Link

1. Clone the repo and install the Python dependencies:

   Copy Text

   uv sync
   uv run pre-commit install

2. Copy .env.template to .env. Set the values in the table below.

3. Start the containers with make dev. The API is at http://localhost:8000 and the dashboard at http://localhost:5000.

4. Create an org:

   Copy Text

   flask --app main org create --name "Robotics Club" --prefix robotics --guild-id <server id> --officer-role-id <role id>

make dev adds docker-compose.dev.yml. It runs python3 main.py with the Flask reloader and mounts the source, so a Python change does not need a rebuild. The bot runs in the bot container.

To run the API with no container, run uv run alembic upgrade head, then uv run python main.py. In this mode the API also starts the bot in a thread. Set RUN_BOT_IN_API=false to stop that.

SettingsCopy Anchor Link

core/config.py reads .env. .env.template lists every setting with a comment. A module page lists the settings of its module.

Discord appsCopy Anchor Link

Platform uses one Discord app: BOT_TOKEN, CLIENT_ID and CLIENT_SECRET all come from it. An agent bot that runs as a RunPod app (see RunPod apps) gets its own token from an org secret, such as app_<app>_discord_token, not from these settings.

Platform can share the app of an agent bot. Then set RUN_BOT=false, so that only one process connects to Discord with the token.

flask --app main config check shows the bot name and app of BOT_TOKEN. It fails if CLIENT_ID is from a different app. deploy/runpod/start.sh runs it at each start, so the pod log shows the app.

CommandsCopy Anchor Link

make dev       # start with logs and the reloader
make up        # start in the background
make down      # stop
make logs      # last 50 log lines
make status    # container status
make health    # container health
make shell     # shell in the API container
make check     # fix lint and format, then type check, tests, migrations
make ci        # the same checks with no changes to files; CI runs this

To run one test file: uv run pytest tests/contract/test_compute.py -v. The tests use an in-process app and a temporary database. They need no running server.

Run it on one RunPod podCopy Anchor Link

deploy/runpod/start.sh runs Platform on one CPU pod with no Docker. It starts the API on port 8000, the dashboard on 5000 and the MCP server on 8001. If BOT_TOKEN is set, it also starts the bot. Set RUN_BOT=false to use the token of a bot that runs elsewhere, such as an agent bot: the API then uses the token only for Discord's REST API, and the bot commands, LeetCode posts and games do not run. Do not run two bot processes with one token. Jobs run in threads of the API, on SQLite.

At each start the script gets the head of PLATFORM_BRANCH. A pod restart thus deploys the branch.

Caution: keep /workspace/data/keys.env. It holds SECRET_KEY and SECRETS_KEY. If you lose it, the stored org secrets cannot be read.

1. Create a network volume and mount it at /workspace.

2. Create a pod from the image nikolaik/python-nodejs:python3.12-nodejs20 with the ports 8000/http, 5000/http and 8001/http.

3. Set the start command:

   Copy Text

   bash -c "curl -fsSL https://raw.githubusercontent.com/theaisocietyasu/bedrock/$PLATFORM_BRANCH/deploy/runpod/start.sh | bash"

4. Set the pod environment from the table below.

5. Add <API_URL>/api/auth/callback as a redirect in the Discord app. For compute CLI sign-in, also add <API_URL>/api/compute/cli/callback.

Agents connect to the MCP server at https://<pod id>-8001.proxy.runpod.net/mcp with a machine token.