AutoJudge

AutoJudge is a platform for hosting programming contests, where users can submit their solutions to problems and have them automatically evaluated. The platform supports multiple programming languages and provides a web interface for running the autojudge.

• You can use this project as a CLI code runner. For this, check the runner-cli branch.

• Check Autojudge online version at autojudge.io.

Features

• Supports multiple programming languages, including C, C++, JavaScript, Java, PHP, Python.
• Automatically detects the language based on the script's file extension.
• Fully automated evaluation of the solutions.
• Provides a web interface for contest management, problem submission.
• For teams, the platform supports team registration, solution submission, and ranking.

Requirements

• Docker

Setup

To run the AutoJudge platform, you can either run the setup script or follow the manual setup instructions.

1. Setup script (recommended)

• Run the setup script:

./setup.sh

2. Manual setup

If you prefer to set up the platform manually, follow the instructions below.

• Rename the .env.example file to .env and set the environment variables inside it. It is important that you set the following variables:

NODE_ENV=production # if you are running the platform in production (like in a contest)
MYSQL_ROOT_PASSWORD=your_password # set the root password for the MySQL database
JWT_SECRET=your_secret # required: signs team session tokens ({team, sid}, no expiry). A random string is recommended
BACKGROUND_TOKEN=your_secret # set the secret for background tasks. A random string is recommended
LOCAL_SERVER=your_ip # set the IP address of the server if you are running a local contest. Otherwise, keep false

• Pull the images for the languages the judge will support:

docker pull gcc:15
docker pull node:24-alpine
docker pull php:8.4-cli-alpine
docker pull python:3.12-slim
docker pull openjdk:26-slim

• Build the Docker images and start the containers:

If you are running the as a local contest, use the compose.local.yaml file:

docker compose -f compose.local.yaml up -d

Otherwise, use the docker-compose.yaml file:

docker compose up -d

Usage

After the containers are up and running, you can access the platform at http://localhost:3000 (or the IP address you set in the .env file) if you are running a local contest. Otherwise, you can access the platform at https://localtest.me.

Database

database.sql is the fresh-install schema. It is loaded automatically into an empty MySQL volume (/docker-entrypoint-initdb.d/init.sql in both Compose files), so a first docker compose up creates everything.

• New columns: public_id (unique, on contests, problems and teams), teams.login_code (unique), teams.session_id, teams.session_started_at, teams.sign_in_count.
• Breaking change: there is no migration from the old numeric-id/hash schema. For an existing install, drop the MySQL volume and start fresh.

Team login (code + PIN)

Teams log in with their login code and 6-digit PIN:

POST /teams/login
{ "code": "<6-character login code>", "pin": "<6-digit PIN>" }

• The code is case-insensitive; spaces and dashes are ignored. The PIN is numeric and 6 digits.
• Contest admins get both values from POST /contests/:id/teams (team creation) and PUT /teams/:id/reset (new PIN). The PIN is shown once, so write it down.
• One session per team. A second login while a session is active answers 409 TEAM_ALREADY_LOGGED_IN. Sign out with POST /teams/session/logout (ends the session on every client) and log in again.
• Login answers: 401 INVALID_PASSWORD for a wrong or unknown code/PIN pair (generic on purpose), 429 when throttled, 403 CONTEST_NOT_STARTED before the contest starts, 403 CONTEST_ENDED after the session window closes.
• Team requests use Authorization: Bearer <token>. The token carries { team, sid } with no expiry of its own: every request checks the session is still the team's current one and the contest window (contest end + 24h) is still open, otherwise 401 SESSION_ENDED. A PIN reset, sign-out, or contest start/reset also ends the session.
• Browser handoff (used by the VS Code extension): a signed-in team creates POST /teams/session/handoff -> { code } (single use, valid 60 seconds, one pending code per team, 403 CONTEST_NOT_STARTED before the start). The other client exchanges it with POST /teams/session/redeem { "code": "..." } (no auth) -> { token }; unknown, used or expired codes answer 400 HANDOFF_INVALID, an ended session answers 401 SESSION_ENDED.

Identifiers and extension compatibility

• External ids are publicId only (13 lowercase base36 characters) for contests, problems and teams, in URLs and responses. Numeric ids and hash fragments are no longer accepted; unknown values answer 404.
• Error responses carry a machine-readable code next to the HTTP status (for example SESSION_ENDED, CONTEST_NOT_STARTED).
• The VS Code extension aj-contest >= 0.2.0 requires this server version (publicId-only requests, browser handoff login). Older servers and older extensions are not supported.

Judge Runtime Tuning

The judge service can be tuned through .env values:

• RUNNER_TIMEOUT caps the API-to-judge request lifetime in milliseconds.
• JUDGE_TIME_LIMIT sets the default per-test execution limit in seconds.
• JUDGE_TIME_LANGUAGE_C, JUDGE_TIME_LANGUAGE_CPP, JUDGE_TIME_LANGUAGE_JAVASCRIPT, JUDGE_TIME_LANGUAGE_PHP, JUDGE_TIME_LANGUAGE_PYTHON, and JUDGE_TIME_LANGUAGE_JAVA add per-language execution slack in seconds.
• JUDGE_CONCURRENCY controls how many test cases the judge evaluates at once.
• CPU_LIMIT and MEMORY_LIMIT are forwarded to the per-language compiler containers.

AI Agent Guidance

This repository now includes workspace-local AI customization files for future maintenance work:

• AGENTS.md gives repository-wide architecture notes, command shortcuts, validation rules, and environment pitfalls.
• .github/instructions/ contains file-scoped guidance for API and web work.
• .github/agents/autojudge-maintainer.agent.md defines a repository-focused custom agent for scoped AutoJudge tasks.
• .github/skills/ contains reusable skills for API changes, web changes, and validation workflows.

When project conventions change, update these files alongside the code so future AI-assisted work stays aligned with the implementation.