Skip to content

PhD Sandbox Deployment ​

This guide covers building, configuring, and deploying the GhostScience PhD sandbox Docker images for scientific computing.

Architecture ​

The PhD sandbox is a hardened Docker container with a curated scientific Python stack. The backend dispatches generated code to the sandbox, collects structured JSON output, and PII-scans the results before returning them.

Prerequisites ​

  • Docker 20.10+ (or Podman)
  • 4 GB+ RAM available for the build
  • For GPU images: NVIDIA Container Toolkit + CUDA 12.2 compatible GPU

Building the Images ​

CPU Image ​

bash
cd infrastructure/docker/sandbox
docker build -f Dockerfile.phd -t ghostai-phd-sandbox:latest .

The CPU image uses python:3.11-slim with OpenBLAS, LAPACK, HDF5, and the scientific library stack from requirements-phd.txt.

GPU Image ​

bash
docker build -f Dockerfile.phd-gpu -t ghostai-phd-sandbox-gpu:latest .

The GPU image uses nvidia/cuda:12.2.0-runtime-ubuntu22.04 with Python 3.11 (via deadsnakes PPA) and replaces JAX CPU with jax[cuda12]>=0.4.30.

Verifying the Build ​

Both Dockerfiles run a sanity check during build:

bash
python -c "import sympy, numpy, scipy, plotly; print('OK')"

The GPU image additionally verifies JAX:

bash
python -c "import jax; print(jax.devices())"

Library Stack ​

Core (requirements-phd.txt) ​

DomainPackages
SymbolicSymPy
NumericalNumPy, SciPy, JAX (CPU)
OptimizationCVXPy
Controlpython-control
Statisticsstatsmodels
VisualizationPlotly, matplotlib
UnitsPint, uncertainties
Data Formatsh5py, pandas
Notebooksnbformat, latexify-py
GraphsNetworkX
MLscikit-learn

Extended (requirements-phd-full.txt) ​

Optional extended stack with additional libraries:

DomainPackages
DistributedDask, Polars
Multi-objectivepymoo
WaveletsPyWavelets
Audio/Signallibrosa
PDE/FEMFiPy, DeepXDE
ProbabilisticEquinox, PyMC, ArviZ
SensitivitySALib
Graphsigraph
Roboticsspatialmath
TensorsTensorLy
Geospatialxarray, Cartopy, GeoPandas, netCDF4
Meshingmeshio
AstronomyAstropy
3DPyVista
MATLAB compatoct2py

To use the extended stack, add requirements-phd-full.txt to the Dockerfile pip install step.

Container Hardening ​

Seccomp Profile ​

The PhD sandbox uses a custom seccomp profile (seccomp-phd.json) that:

  • Sets defaultAction to SCMP_ACT_ERRNO (deny by default)
  • Allows ~170 computation-related syscalls (file I/O, memory, timers, execve, fork, clone, signals, epoll, futex)
  • Supports both x86_64 and aarch64 architectures
  • Denies network, raw socket, mount, and ptrace syscalls

To apply the profile when running containers manually:

bash
docker run --security-opt seccomp=seccomp-phd.json ghostai-phd-sandbox:latest

The backend applies this automatically when configured.

Runtime Isolation ​

ControlValue
FilesystemRead-only (/usr, /opt); writable /workspace and /tmp
User1000:1000 (non-root sandbox user)
Networknone
Privilegesno-new-privileges:true, cap_drop=["ALL"]
OCI runtimerunsc (gVisor) recommended for production

gVisor ​

For production deployments, set SANDBOX_RUNTIME=runsc to enable gVisor. This interposes a userspace kernel between the sandbox and the host, preventing container escape via kernel CVEs.

bash
# Install gVisor runtime
# See https://gvisor.dev/docs/user_guide/install/
SANDBOX_RUNTIME=runsc

Supply Chain Security ​

  • All pip packages use pinned SHA-256 hashes in requirements files
  • Images are scanned with Trivy and Grype on every build
  • Critical/high CVEs block image publication
  • No runtime pip install is possible (network is blocked)

GPL Compliance ​

The PHD_GPL_FREE setting controls whether GPL-licensed libraries are included in the sandbox. When set to true:

  • Slycot (GPL-2.0) is excluded
  • GNU Octave / oct2py (GPL-3.0) is excluded
  • FEniCSx (LGPL/GPL) is excluded

See LICENSE_AUDIT.md in infrastructure/docker/sandbox/ for the complete licensing analysis.

Environment Variables ​

These are set inside the container image:

VariableCPU ImageGPU Image
MPLBACKENDAggAgg
JAX_PLATFORM_NAMEcpucuda
OPENBLAS_NUM_THREADS22
CUDA_VISIBLE_DEVICESn/a0

Resource Sizing ​

WorkloadMemoryCPUTimeout
Symbolic math2 GB1 core60s
Numerical ODE4 GB2 cores120s
Large optimization8 GB4 cores300s
Monte Carlo (10M paths)16 GB4 cores600s
GPU (JAX CUDA)8 GB + GPU2 cores300s

Adjust PHD_SANDBOX_MEMORY_LIMIT, PHD_SANDBOX_CPU_LIMIT, and PHD_SANDBOX_TIMEOUT based on expected workloads.

Deployment Environments ​

EnvironmentImageRuntimeNotes
Local devCPUDocker defaultdocker compose with socket mount
Docker ComposeCPUDocker defaultSocket mounted read-only
KubernetesCPU or GPUgVisor recommendedHelm chart includes PhD values
AWS ECSCPU or GPULambda or DockerGPU via p3/g4 instances
Air-gappedCPU or GPUgVisorAll libraries pre-installed; Zarf packaged

SOC 2 Type II Certified | BAA Available | HIPAA-Ready