Skip to main content

Run untrusted code in secure Docker based sandboxes

Project description


Build Status

A Python library to run untrusted code in secure, isolated Docker based sandboxes. It is used to automatically grade programming assignments on

It allows to spawn a process inside one-time Docker container, send data to stdin, and obtain its exit code and stdout/stderr output. It's very similar to what the subprocess module does but additionally you can specify a custom environment for the process (a Docker image) and limit the CPU, memory, disk, and network usage for the running process.


Run a simple Python script in a one-time Docker container using the python:3.6.5-alpine image:

import epicbox

        epicbox.Profile('python', 'python:3.6.5-alpine')
files = [{'name': '', 'content': b'print(42)'}]
limits = {'cputime': 1, 'memory': 64}
result ='python', 'python3', files=files, limits=limits)

The result value is:

{'exit_code': 0,
 'stdout': b'42\n',
 'stderr': b'',
 'duration': 0.143358,
 'timeout': False,
 'oom_killed': False}

Available Limit Options

The available limit options and default values:

    # CPU time in seconds, None for unlimited
    'cputime': 1,
    # Real time in seconds, None for unlimited
    'realtime': 5,
    # Memory in megabytes, None for unlimited
    'memory': 64,

    # limit the max processes the sandbox can have
    # -1 or None for unlimited(default)
    'processes': -1,

Advanced usage

A more advanced usage example of epicbox is to compile a C++ program and then run it multiple times on different input data. In this example epicbox will run containers on a dedicated Docker Swarm cluster instead of locally installed Docker engine:

import epicbox

    'gcc_compile': {
        'docker_image': 'stepik/epicbox-gcc:6.3.0',
        'user': 'root',
    'gcc_run': {
        'docker_image': 'stepik/epicbox-gcc:6.3.0',
        # It's safer to run untrusted code as a non-root user (even in a container)
        'user': 'sandbox',
        'read_only': True,
        'network_disabled': False,
epicbox.configure(profiles=PROFILES, docker_url='tcp://')

untrusted_code = b"""
// C++ program
#include <iostream>

int main() {
    int a, b;
    std::cin >> a >> b;
    std::cout << a + b << std::endl;
# A working directory allows to preserve files created in a one-time container
# and access them from another one. Internally it is a temporary Docker volume.
with epicbox.working_directory() as workdir:'gcc_compile', 'g++ -pipe -O2 -static -o main main.cpp',
                files=[{'name': 'main.cpp', 'content': untrusted_code}],
                workdir=workdir)'gcc_run', './main', stdin='2 2',
                limits={'cputime': 1, 'memory': 64},
    # {'exit_code': 0, 'stdout': b'4\n', 'stderr': b'', 'duration': 0.095318, 'timeout': False, 'oom_killed': False}'gcc_run', './main', stdin='14 5',
                limits={'cputime': 1, 'memory': 64},
    # {'exit_code': 0, 'stdout': b'19\n', 'stderr': b'', 'duration': 0.10285, 'timeout': False, 'oom_killed': False}


epicbox can be installed by running pip install epicbox. It's tested on Python 3.4+ and Docker 1.12+.

You can also check the epicbox-images repository that contains Docker images used to automatically grade programming assignments on


Contributions are welcome, and they are greatly appreciated! More details can be found in CONTRIBUTING.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

epicbox-1.1.0.tar.gz (12.8 kB view hashes)

Uploaded source

Built Distribution

epicbox-1.1.0-py3-none-any.whl (12.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page