ioi/isolate: Linux sandbox for contest executables

Why ioi/isolate exists in contest grading

Isolate addresses a narrow but consequential problem: executing a program that the host cannot trust. The README gives programming contest competitors' submissions as its primary example. A submitted executable might read files, consume resources, send signals, make network requests, or interfere with the grading machine if it receives the same access as the judge. Isolate places that executable in a limited-access environment intended to contain such activity before it reaches the host.

The intended users are contest operators and maintainers of grading systems rather than application developers seeking a general container platform. Isolate was originally part of the Moe Contest Environment, but the project became separate and is used by different contest systems. The README names CMS as its most prominent example. That history ties the project to the security boundary around automated code execution, not to ordinary desktop application deployment.

The design assumes Linux-specific controls. The README specifically calls out namespaces and control groups. The build also links against `libcap` and `libseccomp`, while the source includes a separate `isolate-check-environment` utility and configuration files for systemd. Together, these repository elements indicate a sandbox assembled from several Linux facilities rather than a language runtime wrapper or a library linked into the submitted program.

That scope has a practical consequence. Isolate is most relevant where a service accepts binaries from many users and executes them repeatedly under defined access and resource restrictions. The project is less convincing as an off-the-shelf answer for macOS, Windows, or arbitrary workloads because its documented mechanism depends on Linux kernel features. It is a specialized grading component, not a transparent layer for every untrusted process.

The Linux isolation boundary in isolate.c and its companions

According to the README, Isolate creates a limited-access environment around each untrusted executable. Namespaces restrict which operating-system resources the program can see, while control groups provide a mechanism for controlling and measuring the execution. The repository's dependency list adds two more explicit boundaries: Linux capabilities through `libcap`, and system-call filtering through `libseccomp`.

The source layout separates concerns across several C files. `isolate.c` is the main program, `config.c` handles configuration, `rules.c` is dedicated to rules, and `cg.c` corresponds to control-group work. Utility code is in `util.c`. The Makefile also builds `isolate-check-environment`, which indicates that validating the host before using the sandbox is a distinct operational concern rather than an incidental setup detail.

A second executable, `isolate-cg-keeper`, is built alongside Isolate and has its own manual page. Its name indicates a role in keeping control groups present, although the README does not document its operational protocol or failure handling. The repository also includes `systemd/isolate.service` and `systemd/isolate.slice`, indicating an integration path for a systemd-based host. The exact rule syntax, namespace set, default filesystem view, and process-launch sequence are not included in the README, so an engineer should read `isolate.1.txt` and `rules.c` before designing a deployment around them.

Isolate executes a separate untrusted process instead of requiring the grading service to understand or compile the contestant's code. That permits arbitrary compiled submissions without making their language or libraries part of Isolate. The containment boundary remains the operating-system configuration, so its effectiveness depends on the host kernel, permissions, control groups, and rules being configured for the intended threat. Isolate should therefore be evaluated as a system component rather than as a self-contained executable that is secure after compilation.

Building isolate on a source checkout

The README's minimal build path is suitable when the goal is only to produce the `isolate` binary. Before compiling, install `pkg-config`, the `libcap` headers, the `libseccomp` headers, and, for compiling `isolate-cg-keeper`, the `libsystemd` headers. The README does not provide distribution-specific commands for those development packages, so their installation must match the host Linux distribution.

From a repository checkout, invoke the documented minimal target:

make isolate

The Makefile identifies `gcc` as the compiler and compiles in GNU C99 mode with optimization and warnings. It also enables hardening flags including `-D_FORTIFY_SOURCE=3`, `-fstack-protector-strong`, `-fstack-clash-protection`, `-fPIE`, and `-pie`. Linker hardening includes `-Wl,-z,nodlopen`, `-Wl,-z,noexecstack`, `-Wl,-z,relro`, and `-Wl,-z,now`. These are visible build policies, not proof that the resulting sandbox is correctly configured on a particular host.

If the complete project is needed, the Makefile's default `all` target also builds the manual pages, their HTML forms, and generated configuration files. Building the documentation may require `a2x`. For a first installation, the README gives the narrower command and explicitly says it is sufficient when only the `isolate` binary is wanted.

The README does not show a command for launching the built binary, creating an input directory, applying a rule, or reading the program's output. Supplying such a command would go beyond its documentation. Before running an untrusted program, use the manual and `isolate-check-environment` to establish the required host setup. The repository includes `default.cf.in` as the configuration source and `isolate.1.txt` as the manual source, which are the relevant places to continue from this abbreviated installation guide.

Installing the Debian isolate package

For an amd64 system, the README provides a package repository for stable Debian and the last two Ubuntu LTS releases. It instructs administrators to create `/etc/apt/sources.list.d/isolate.sources` with the following repository metadata:

Types: deb
URIs: http://www.ucw.cz/isolate/debian/
Suites: trixie-isolate
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/isolate.asc

The README also requires the repository's public key. Its documented command writes that key to the path referenced by the source definition:

curl https://www.ucw.cz/isolate/debian/signing-key.asc >/etc/apt/keyrings/isolate.asc

With the source file and key in place, update package metadata and install the project:

apt update && apt install isolate

This route is for administrators choosing to use the documented third-party package repository. It downloads metadata over `http://www.ucw.cz/isolate/debian/`, so repository authenticity depends on package signatures and the integrity of the downloaded key rather than HTTPS alone. The README calls the arm64 packages experimental, which is a narrower support statement than the amd64 package path.

Installation alone does not establish an acceptable execution environment. The README refers readers to the manual's INSTALLATION and REPRODUCIBILITY sections for the recommended system setup. Those sections should determine which kernel facilities, control-group configuration, permissions, and reproducibility controls are required before the package is used by a grading service. An operator should also verify that the package repository architecture matches the host, especially because the README's standard package instructions specify amd64.

Systemd integration and environment verification

The repository includes `systemd/isolate.service` and `systemd/isolate.slice`, and its Makefile installs a generated unit under `/usr/local/lib/systemd/system`. This indicates that Isolate can fit into a systemd-managed host rather than requiring every execution-related setting to be reconstructed separately. However, the README does not document how to enable the service, how the slice relates to individual invocations, or whether the unit is mandatory. Those details require the project manual.

The separate `isolate-check-environment` executable is a more direct adoption signal. Its dedicated manual page indicates that checking the environment is a supported operation, not merely a repository convenience script. A grading operator should not infer readiness because `apt install isolate` succeeded or `make isolate` returned successfully. Kernel facilities and host configuration can still be absent, disabled, or incompatible with the intended sandbox policy.

This separation affects upgrades. Changes to the host kernel, systemd unit, control-group hierarchy, or configuration template can affect sandbox operation without changing the Isolate executable alone. The Makefile generates configuration files, while source builds include version, build-date, and commit information. A grading platform may need to record which package or source revision is deployed, but the README does not provide a rollback procedure or a host compatibility matrix.

The last repository push was on 2026-08-23, so the project had recent repository activity before this review. There are no GitHub releases, which makes the repository history and the documented package repository more relevant entry points than GitHub release notes. Repository activity does not establish that every kernel or service-manager configuration is supported, and it does not replace checking the custom license before redistribution.

License and operating boundaries for adopters

The repository identifies its license as a custom license that GitHub cannot classify and points readers to the `LICENSE` file. The README does not reproduce its terms, so it is not possible to state whether modification, redistribution, packaging, or embedded use carries specific conditions. Anyone considering Isolate for a hosted grading service must inspect `LICENSE` before redistributing source or binaries. That is a license-compatibility review, not legal advice.

The operational boundary is equally important. Isolate targets Linux and depends on kernel mechanisms rather than a portable process API. Namespaces and control groups can behave differently across kernels, distributions, and service managers. The README's package path covers amd64 systems, while it describes arm64 packages as experimental. It does not claim support for Windows, macOS, distributed execution, or arbitrary remote workloads.

A direct alternative is running an executable as an unprivileged contest user without an Isolate-created sandbox. That approach has a different security boundary: it relies on host user permissions and existing discretionary access controls. Isolate adds namespace, control-group, capability, and seccomp-oriented controls around the process. The trade-off is that Isolate requires a compatible Linux environment and careful policy configuration, while direct execution avoids Isolate-specific setup but does not provide the isolation layer described in its README.

Isolate is the wrong choice where portable execution, a simple documented first run, or support outside Linux is mandatory. It is also unsuitable as the only operational control if the host administrator cannot verify kernel settings and configuration. Its usefulness depends on a correctly prepared host and explicit access restrictions. The decision is therefore between a specialized Linux security boundary and a simpler host-permission model, not between two interchangeable sandbox libraries.

Editorial conclusion

Contest operators with a compatible Linux environment should consider Isolate after reviewing the manual's installation and reproducibility guidance and checking the custom LICENSE. Organizations seeking a documented cross-platform workflow, or users expecting an executable sandbox example in the README, should choose elsewhere. The first project-specific check is whether the target kernel and configuration satisfy the requirements of `isolate-check-environment` and the grading policy.

Frequently asked questions

Official sources

1. ioi/isolate on GitHub
2. Issues
3. README