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.
python-3.15 - the same base as python-3.12 on Python 3.15: pip, development headers, a C/C++ toolchain and the common CLIs.
node-22 - Node.js 22 with npm, a bundled Python and the build toolchain (so node-gyp native addons compile), plus the common CLIs.
node-26 - the same base on Node.js 26, the current LTS line.
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). It is also the base for running Docker inside a sandbox - see Docker in sandboxes.
debian-13 - the same base on Debian 13 (trixie), the current Debian stable, with Python 3.13 and newer toolchains. Same package set as debian-12. Pick it for new work; debian-12 stays available for anything pinned to bookworm.
ubuntu-26.04 - a real Ubuntu 26.04 LTS where apt-get works, with the universe component enabled. Same package set as the Debian bases. Pick it when your tooling expects Ubuntu.
alpine - real Alpine Linux (musl) where apk add works, with Python 3, pip, git and curl. The smallest general-purpose base. Being musl, it runs musllinux wheels and musl-built binaries, not glibc ones - use a Debian or Ubuntu base if a dependency ships glibc-only builds.
ubuntu-24.04 - a real Ubuntu 24.04 LTS, the same base as ubuntu-26.04 on the previous LTS release. Pick it when your tooling is pinned to 24.04.
What each base runs right now (OS and runtime versions, build date, digest) and what changed in every rebuild is listed on Base image versions.
pip install and npm install behave the way they do on a normal Linux box.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 ondebian-12a fullapt-get installall 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.