# 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](https://orkestr.eu/docs/sandboxes/templates).

**Python:**

```python
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](https://orkestr.eu/docs/sandboxes/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.

> **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

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.

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

```bash
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](https://orkestr.eu/docs/sandboxes/networking).