Configuration

A Runner is configured entirely by environment variables. There is no configuration file and no command line.

Every variable is prefixed AJ_, with __ between sections — the same convention the Server reads, so one Compose file does not have to spell the two services differently.

The Server

The prefix is checked at start: a base URL with no /api/ is refused by name rather than discovered as a wall of 404s. The Server's path guard answers those with an empty body, so there would be nothing to read.

Identity and capabilities

AJ_Runner__ProblemTypes is how a Runner that should also take output-only@1 work is told to: standard-io@1,output-only@1. Which types a Runner advertises is configuration, not code.

The default in that table is the binary's, for a process started with the variable unset. AlgoJudge-Ops ships RUNNER_PROBLEM_TYPES=standard-io@1,output-only@1, so an installation's Runners declare both — which is why a queue that looks stuck is diagnosed against the value the service actually has and not against this column.

Polling and the lease

AJ_Poll__WaitSeconds makes the two below matter only after a failure. On an empty queue the Server holds the request rather than answering it, so the wait is the interval, and a submission starts being judged as soon as it exists instead of at the next poll. See Claiming for what the Server does with it.

What bounds it in practice is not this product but whatever sits between the Runner and the Server — an Azure Application Gateway ends a silent request at 20 s, a stock nginx or an AWS ALB at 60 s, Cloudflare at 125 s. Twenty-five clears all but the first. Raise it on a path you own; lower it, or set 0, behind a proxy you do not control.

Three hundred is a ceiling, and above it the Runner refuses to start. That is the longest a Server will hold a claim, and asking for more is worse than being ignored: the Runner tells a held claim from an immediate answer by how long it took, so one asking for nine hundred would read the Server's three hundred as no wait at all and sleep the interval below after every claim — the deafness the held claim exists to remove, restored by a setting and visible in no log.

AJ_Lease__RequestSeconds is a request. The Server clamps it to [60, 3600] and answers with the deadline it actually granted, which is the authoritative one. The lease is renewed automatically while work is in progress, on a timer at a quarter of the granted lease — three renewals fit inside every lease, so two may fail in a row with the deadline still ahead.

The heartbeat is sent only when the Runner has nothing to do. A Runner holding a job is renewing its lease instead, which says the same thing more precisely.

Storage

The package cache is the only state a Runner keeps besides its key. Losing it costs a re-download, nothing more.

The pipes pair is not about space: a judged run's output travels on a named pipe, which holds no bytes at all, so what it needs is a filesystem that can make one. A bind mount of a Windows or macOS directory cannot — a developer's checkout, not a deployment. A tmpfs: entry on the Runner's own service will not do either: that is private to the Runner's mount namespace, and the daemon would make an empty directory instead, which is the failure the callout below describes.

The sandbox and the language images

Each image is independent: anything left unset keeps its compiled-in default, so an operator republishing one image says so in one line. The defaults are what a development stack builds locally, so a deployment names all four explicitly.

AJ_Sandbox__Image__Gcc=ghcr.io/algojudge/lang-gcc:0.1.0
AJ_Sandbox__Image__Clang=ghcr.io/algojudge/lang-clang:0.1.0
AJ_Sandbox__Image__Python=ghcr.io/algojudge/lang-python:0.1.0
AJ_Sandbox__Image__Pypy=ghcr.io/algojudge/lang-pypy:0.1.0

Pin the same version as the Runner unless there is a reason not to: that pairing is what the release was tested as. Languages says why the compiler version is a thing to pin rather than a thing that moves.

The variables that are not ours

These are read by the libraries the Runner is built on rather than by its own configuration. They carry no AJ_ prefix, and the Runner never validates them.

Three ways a configuration fails

A malformed number panics at start. Every numeric variable above is parsed strictly, and AJ_Poll__MaxSeconds=3O — a letter O for a zero — stops the process with a message naming the key and the value. There is deliberately no fallback to the default: an operator whose setting did nothing would otherwise never learn it.

A wrong AJ_Work__HostPath does not fail at all. It is the opposite case and the reason the callout above exists.

And two settings are accepted and then quietly do the wrong thing. The poll interval is advisory rather than checked, so an AJ_Poll__MaxSeconds below AJ_Poll__MinSeconds is silently raised to meet it instead of being refused. And a typo in AJ_Runner__ProblemTypes is accepted at start-up — the Runner declares the misspelt type, is handed nothing that matches it, and looks exactly like a Runner nobody has any work for.

A value naming no type at all is a different case and is refused by name: a lone comma, or a trailing one from a paste, leaves the list empty, and an empty list matches no problem in the installation. That Runner would register, be approved, heartbeat, show as connected and be handed nothing for as long as it ran.

An empty AJ_Sandbox__CgroupRoot is not one of them: it is treated as unset, and a relative value is refused by name.

Everything else that can be wrong shows up as a queue that never drains. When that happens, read Tags and routing first.