Appearance
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)
| Domain | Packages |
|---|---|
| Symbolic | SymPy |
| Numerical | NumPy, SciPy, JAX (CPU) |
| Optimization | CVXPy |
| Control | python-control |
| Statistics | statsmodels |
| Visualization | Plotly, matplotlib |
| Units | Pint, uncertainties |
| Data Formats | h5py, pandas |
| Notebooks | nbformat, latexify-py |
| Graphs | NetworkX |
| ML | scikit-learn |
Extended (requirements-phd-full.txt)
Optional extended stack with additional libraries:
| Domain | Packages |
|---|---|
| Distributed | Dask, Polars |
| Multi-objective | pymoo |
| Wavelets | PyWavelets |
| Audio/Signal | librosa |
| PDE/FEM | FiPy, DeepXDE |
| Probabilistic | Equinox, PyMC, ArviZ |
| Sensitivity | SALib |
| Graphs | igraph |
| Robotics | spatialmath |
| Tensors | TensorLy |
| Geospatial | xarray, Cartopy, GeoPandas, netCDF4 |
| Meshing | meshio |
| Astronomy | Astropy |
| 3D | PyVista |
| MATLAB compat | oct2py |
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
defaultActiontoSCMP_ACT_ERRNO(deny by default) - Allows ~170 computation-related syscalls (file I/O, memory, timers,
execve,fork,clone, signals, epoll, futex) - Supports both
x86_64andaarch64architectures - 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:latestThe backend applies this automatically when configured.
Runtime Isolation
| Control | Value |
|---|---|
| Filesystem | Read-only (/usr, /opt); writable /workspace and /tmp |
| User | 1000:1000 (non-root sandbox user) |
| Network | none |
| Privileges | no-new-privileges:true, cap_drop=["ALL"] |
| OCI runtime | runsc (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=runscSupply 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 installis 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:
| Variable | CPU Image | GPU Image |
|---|---|---|
MPLBACKEND | Agg | Agg |
JAX_PLATFORM_NAME | cpu | cuda |
OPENBLAS_NUM_THREADS | 2 | 2 |
CUDA_VISIBLE_DEVICES | n/a | 0 |
Resource Sizing
| Workload | Memory | CPU | Timeout |
|---|---|---|---|
| Symbolic math | 2 GB | 1 core | 60s |
| Numerical ODE | 4 GB | 2 cores | 120s |
| Large optimization | 8 GB | 4 cores | 300s |
| Monte Carlo (10M paths) | 16 GB | 4 cores | 600s |
| GPU (JAX CUDA) | 8 GB + GPU | 2 cores | 300s |
Adjust PHD_SANDBOX_MEMORY_LIMIT, PHD_SANDBOX_CPU_LIMIT, and PHD_SANDBOX_TIMEOUT based on expected workloads.
Deployment Environments
| Environment | Image | Runtime | Notes |
|---|---|---|---|
| Local dev | CPU | Docker default | docker compose with socket mount |
| Docker Compose | CPU | Docker default | Socket mounted read-only |
| Kubernetes | CPU or GPU | gVisor recommended | Helm chart includes PhD values |
| AWS ECS | CPU or GPU | Lambda or Docker | GPU via p3/g4 instances |
| Air-gapped | CPU or GPU | gVisor | All libraries pre-installed; Zarf packaged |
Related
- GhostScience -- feature overview
- Admin Configuration -- all environment variables
- Code Interpreter -- standard sandbox (non-PhD)
- Container Security Whitepaper -- full security analysis