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.

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.

code-interpreter - everything python-3.12 has, plus a persistent interpreter runtime with pandas, NumPy and matplotlib preinstalled. On this base, run_code becomes a stateful notebook-style session: variables persist between calls and results come back rich (tables, charts, chart data). See Code interpreter. The base for data analysis and agent workloads that think in Python.

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.

Installing packages

Every sandbox gets a writable overlay on its base image, so run-time installs just work - and evaporate with the sandbox. Two ways to add packages:

• At run time. pip install, npm install (including -g), and on debian-12 a full apt-get install all work inside a running sandbox with no extra flags. Everything installed this way is per-sandbox and gone on terminate.
• Baked into a template. If every run installs the same packages, pay the install cost once: a custom template recipe captures the result into a reusable image, and sandboxes boot from it in ~300 ms with everything already in place.

# pip / npm work at run time - HOME is on the writable workspace
sbx.exec("pip install httpx")
sbx.exec("npm install zod")

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.