Sandboxes

Base images

Every sandbox boots from a base image - a prebuilt root filesystem with a language runtime and a common set of tools. Choose one with the template argument when you create a sandbox. The default is python-3.12. You can also build your own image on top of any base with custom templates.

pick-a-base
from orkestr import Sandbox

# Pick a base with the template argument (default: python-3.12)
sbx = Sandbox.create(template="debian-12", network="restricted")
print(sbx.exec("apt-get --version").stdout)

Available bases

python-3.12 - the default. Python 3.12 with pip, development headers and a C/C++ toolchain, plus the common CLIs (git, curl, wget, openssl). A good general starting point for Python work and for pip install of wheels that need to compile.

python-3.12-bare - just the Python 3.12 interpreter and a shell, nothing else. Deliberately minimal: fastest to boot, smallest footprint. Reach for it when you control exactly what runs and want no surprises on the path.

node-22 - Node.js 22 with npm, a bundled Python and the build toolchain (so node-gyp native addons compile), plus the common CLIs.

debian-12 - a real Debian bookworm slim base where apt-get works. Ships apt, TLS roots, build-essential, Python 3 with pip and venv, and the common CLIs. This is the general-purpose base - use it when you want a familiar Debian userland or need apt packages (install them in a custom template recipe, see below).

ubuntu-24.04 (retired) - kept only as a bootable alias for existing callers. Despite the name it never had a working apt-get. Use debian-12 instead - it is a strict superset and apt actually works. New code should not target this identifier.

glibc, so wheels and native addons just work
The Python and Node bases are glibc-based, not musl. manylinux Python wheels and glibc-built Node native modules install and run without falling back to slow source builds - pip install and npm install behave the way they do on a normal Linux box.

Installing packages

The base filesystem is mounted read-only at run time - a sandbox uses what is baked into its image. Two ways to add more:

  • Language packages, at run time. The writable workspace is the package home, so pip install and npm install work inside a running sandbox with no extra flags. They cost memory and vanish when the sandbox is terminated.
  • System packages, baked into a template. Because the root filesystem is read-only at run time, apt-get install / apk add belong in a custom template recipe, which runs in a writable build VM and captures the result into a new reusable image.
run-time installs
# pip / npm work at run time - HOME is on the writable workspace
sbx.exec("pip install httpx")
sbx.exec("npm install zod")
bake apt packages into a template
curl -X POST https://api.orkestr.eu/v1/templates \
  -H "Authorization: Bearer $ORKESTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "debian-with-ripgrep",
    "base_template": "debian-12",
    "recipe": ["apt-get update && apt-get install -y ripgrep"],
    "network": "restricted"
  }'

Pulling packages needs egress. A new sandbox has no network by default; turn on a curated allowlist (or your own) with the restricted network mode - see Networking & egress.