Choose a runtime image (managed or custom) for a Vercel Sandbox, install system packages, and run privileged workloads (Docker, VPN clients, FUSE) inside it using sudo.

Documented steps

1. For a managed image, pass `image` to `Sandbox.create()`: options include `vercel/sandbox/universal` (default; Node.js LTS 24, Python 3.14, coding agents, utilities), `vercel/sandbox/node:22|24|26`, `vercel/sandbox/python:3.14`, `vercel/sandbox/arch:latest`, `vercel/sandbox/ubuntu:latest`. Docs: https://vercel.com/docs/sandbox/concepts/images
2. Pin to a specific version or digest for reproducibility: `image: 'vercel/sandbox/universal@sha256:...'`.
3. For a custom image, build a Dockerfile and push it to Vercel Container Registry: `vercel vcr build docker . my-repository:latest --push`, then create the sandbox with `image: 'my-repository:latest'`. Custom images must be an optimized `linux/amd64` VCR build; `Sandbox.create()` returns `image_not_ready` if VCR is still preparing it.
4. Install packages or run privileged workloads at runtime with `sudo: true`, e.g. `await sandbox.runCommand({ cmd: 'apt-get', args: ['install', '-y', 'ffmpeg'], sudo: true })` (Python: `sandbox.run_command('apt-get', ['install', '-y', 'ffmpeg'], sudo=True)`). Via the CLI: `sandbox exec --sudo <name> -- apt-get install -y ffmpeg`, or `sandbox connect --sudo <name>` for an interactive privileged shell.
5. Know the sudo identity: each sandbox runs in its own Firecracker microVM with a dedicated kernel, so `sudo`-level workloads (Docker, VPN clients, FUSE filesystems) are isolated to that sandbox; `sudo` commands run as user `vercel-sandbox` with root home directory set to `/root`.
6. If running containers (e.g. Docker) inside the sandbox, their outbound traffic still passes through the sandbox's `networkPolicy` firewall, and containers do not automatically inherit the sandbox's proxy CA trust — mount and trust it explicitly if the firewall terminates TLS for transformation rules, e.g. `docker run -v /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem:/usr/local/share/ca-certificates/vercel-proxy-ca.crt:ro my-image sh -c "update-ca-certificates && my-command"`.