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 # set the secret for JWT token. 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.

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.