How denisorehovsky/docker-code-sandbox works
Project type and purpose
• This is an open-source Node.js library (“docker-python-sandbox”) whose sole responsibility is to execute untrusted Python code inside isolated Docker containers.
• It exposes a simple API (via the Sandbox class) so that any Node.js application can spin up a pool of disposable containers, send Python code to them, collect stdout/stderr, and enforce time/memory limits.
File structure
• Top‐level:
• container/ – Docker image definition and entrypoint for the “minimalistic API” running inside each sandbox container
• lib/ – core classes (Container, Job, PoolManager, Sandbox) implementing pool management, container lifecycle, code execution orchestration
• scripts/ – helper scripts to build the Docker image and run tests
• test/ – unit and integration tests, mocks for each core class
• package.json, .travis.yml, wallaby.js – build/test configuration
• Patterns:
• PoolManager maintains a fixed‐size pool of Container instances
• Each Container wraps a single Docker container (created, used once, then destroyed)
• Job objects encapsulate one code execution request/response cycle
• Deployment concerns:
• container/Dockerfile and build.sh define the sandbox runtime image
• start.sh in container/ wires up a small HTTP API inside the container
README for additional insights
• Core flow:
• initialize(): PoolManager → Docker daemon creates N containers using the pulled image
• run(): pick an idle Container → proxy the code to the container’s HTTP API → await result → destroy that container → replace it
• Security: one-time containers, CPU/memory/time limits, no inter-container comms
Diagramming recommendations
• Grey rectangle for Client Application
• Client → Sandbox (initialize/run)
• Sandbox → PoolManager → Docker Engine (create/destroy)
• Container ↔ Docker container (HTTP code execution)
• Container → PoolManager (job completion)