Agent Games

A multi-game agent simulation platform where students and teams submit code agents that compete in game simulations.

Adding a new game? See backend/games/README.md — drop 3 files in backend/games/<name>/ and 1 manifest folder in frontend/src/AgentGames/Feedback/games/<name>/. Auto-discovered on both sides.

Frontend

Backend

Containers

All Python services use lightweight two-stage Alpine builds. Dependencies are compiled in a builder stage and only the virtual environment is copied into the final image, keeping containers at ~400MB (API) compared to ~1.6GB for the full Debian-based Python image.

Setup

Prerequisites: Docker

git clone https://github.com/SanjinDedic/agent_games.git
cd agent_games
docker compose up --build

That's it. The .env file ships with safe local defaults — no configuration needed.

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

The database initializes automatically on first startup.

Running Tests

docker compose -f docker-compose.yml -f docker-compose.test.yml run --rm test-runner

Production

Production is deployed with Kamal (config/deploy.yml) and runs against a DigitalOcean managed Postgres cluster (there is no postgres accessory on the droplet). Secrets live in .kamal/secrets; the database is reached over TLS:

SECRET_KEY=<real secret>
DATABASE_URL=postgresql+psycopg://agent_games_user:<password>@<cluster-host>:25060/agent_games?sslmode=require

First-time setup against a fresh managed cluster:

1. In the DO control panel create the database (agent_games) and the app role (agent_games_user).

2. Grant that role what init_db needs (run once, as the doadmin role):

   DOADMIN_DATABASE_URL='postgresql://doadmin:<pw>@<cluster-host>:25060/agent_games?sslmode=require' \
     uv run python -m backend.scripts.grant_managed_db

3. Deploy. backend/entrypoint.sh runs init_db (builds the schema from the models + seeds) then the migrations — no dump to import.

Allow the droplet's IP under the cluster's Trusted Sources so the app and the CI/backups (which pg_dump through the web container) can connect.

Adding a New Game

Games are auto-discovered from backend/games/*/ and frontend/src/AgentGames/Feedback/games/*/. Drop the required files, restart services, and the new game lights up across the API, validator, simulator, league dropdown, homepage, demo, and feedback rendering — no edits to factories, registries, or config.

Full walkthrough: backend/games/README.md

Service Management

docker compose logs -f api     # View logs
docker compose down            # Stop all services
docker compose down -v         # Stop and delete database data