Linux sandboxes from S3. 93-99% cheaper than always on for AI Agents. The open-source Python library exec-sandbox runs untrusted Python, JavaScript or shell code — including code written by AI agents — in QEMU microVMs on a user's own Linux or macOS hosts, with no cloud account or API key required. Its author claims sessions start in under 1 ms from a warm pool and about 50-60 ms from an L1 memory snapshot, and that saved instances written encrypted to S3 make the setup 93-99% cheaper than always-on sandboxes for AI agents. The library requires Python 3.12-3.14, QEMU 11.0+ for L1 memory snapshots and saved instances (8.0+ for the rest), and KVM on Linux or HVF on macOS for roughly 5-8x faster execution. exec-sandbox runs untrusted Python, JavaScript or shell code in QEMU microVMs on your own Linux or macOS hosts, for example code that an AI agent wrote. It is a Python asyncio library with a command line sbx . It needs no cloud account and no API key. python import asyncio from exec sandbox import Language, Scheduler, VmSpec async def main - None: async with Scheduler as scheduler: Language.PYTHON, Language.JAVASCRIPT or Language.RAW async with await scheduler.new VmSpec language=Language.PYTHON as session: result = await session.exec "print 'Hello from a secure VM ' " print result.stdout Hello from a secure VM print result.exit code 0 asyncio.run main The other Python examples use async with and await at the top level: run them in an async def function, as main above. - Start: Features features · Install install · Quick start quick-start · Key terms key-terms - Use: Sessions sessions · Files files · Packages packages · Network network · Saved instances saved-instances · Configuration configuration · Errors and recovery errors-and-recovery - Operate: Performance performance · Caches and disk use caches-and-disk-use · VM images and offline use vm-images-and-offline-use · Linux host setup linux-host-setup · Instance store operations instance-store-operations - Reference: CLI reference cli-reference · API reference api-reference · Limits limits · Guest environment guest-environment - Internals: How it works how-it-works · Security security · Contributing contributing · License license - Hardware isolation. Each session runs in its own QEMU VM, not in a container, with KVM or HVF acceleration. Up to 8 layers of isolation Security security . - Fast start. Under 1 ms from the warm pool, about 50-60 ms from an L1 memory snapshot. L2 disk snapshots keep the installed packages, and L3 shares them in S3 with all hosts Performance performance . - Self-hosted. The first use downloads the VM images from GitHub Releases. For hosts with no internet access, use sbx prefetch . - Python API and CLI. Run code once or in several steps, stream stdout and stderr, and read and write files. - Saved instances. save writes the RAM, the processes and /home/user of a VM, encrypted, to S3 or a local folder. reuse continues it later on any worker of the same host kind. - Network control. No network access by default. Per spec, an allow-list of domains, checked by DNS filtering and TLS SNI inspection. - Memory density. zram in the guest. On Linux, KSM page merging and memory reclaim of idle warm-pool VMs. - Python: 3.12, 3.13, 3.14 including free-threaded . - OS: Linux or macOS, x64 or arm64. On Windows, use WSL2 on native Windows, import exec sandbox raises ConfigError PLATFORM UNSUPPORTED . - QEMU: 11.0+ for L1 memory snapshots and saved instances; 8.0+ for the rest. ARM64 without KVM or HVF needs 9.0.4+. - Hardware acceleration: KVM Linux or HVF macOS , recommended ~5-8x faster . - x86 CPU with KVM or HVF: x86-64-v3 Intel Haswell, AMD Zen 1 or newer . On a CPU without it, the Scheduler start raises ConfigError HOST DEPENDENCY with the missing features. TCG runs on any x86 CPU. uv add exec-sandbox Core library uv add "exec-sandbox cli " + the sbx command line and the local instance store uv add "exec-sandbox s3 " + the L3 snapshot cache and the s3 instance store and the local store With pip, use pip install with the same names. For sbx with the s3 store, install exec-sandbox cli,s3 . brew install qemu macOS apt install qemu-system qemu-utils Ubuntu/Debian test -r /dev/kvm -a -w /dev/kvm && echo ok Linux: ok means your user can use KVM sysctl kern.hv support macOS: kern.hv support: 1 means HVF is available exec-sandbox uses qemu-system-x86 64 or qemu-system-aarch64 from /usr/bin/ , else from PATH EXEC SANDBOX QEMU BIN X86 and EXEC SANDBOX QEMU BIN ARM set another file , and qemu-img and qemu-storage-daemon from PATH . A missing QEMU binary, or one whose version or machine types this user cannot read, raises ConfigError HOST DEPENDENCY when the Scheduler starts; a missing qemu-img raises it at its first use. Check the version with /usr/bin/qemu-system-x86 64 --version or qemu-system-aarch64 : Ubuntu 24.04 ships 8.2.2. Saved instances and L1 snapshots need QEMU 11.0 or later: where the distribution ships an older one, build QEMU from its source release qemu.org/download https://www.qemu.org/download/ source and set EXEC SANDBOX QEMU BIN X86 or EXEC SANDBOX QEMU BIN ARM to the binary. On Linux, give your user access to KVM with sudo usermod -aG kvm $USER , then log in again. Without this access, exec-sandbox logs a warning and uses TCG. To run QEMU as its own user, with cgroup limits and namespaces, see Linux host setup linux-host-setup . The first run downloads the VM images How images download how-images-download . For Python, see the example at the top and Sessions sessions . sbx comes with the cli extra; all its options are in the CLI reference cli-reference . sbx run 'print "Hello from sandbox" ' Python sbx run -l javascript 'console.log "Hello from sandbox" ' JavaScript sbx run script.py A file: the extension gives the language sbx run -p pandas==3.0.1 'import pandas; print pandas. version ' With packages sbx run --network --allow-domain api.example.com fetch data.py Network, with an allow-list sbx run --instance my-vm -c 'x = 41' Keep the VM state Saved instances sbx run --instance my-vm -c 'print x + 1 ' 42 | Term | Meaning | |---|---| | Spec | A VmSpec : what a VM is made of VmSpec vmspec | | REPL | The interpreter in the VM that runs your code | | Session | One VM that runs your code: new or reuse gives it, close ends the VM Sessions sessions | | Saved instance | The state of a session that save stored RAM, processes, files in /home/user : reuse continues it on any worker of its host kind Saved instances saved-instances | | Warm pool | VMs started before the request Warm pool warm-pool | | L1, L2, L3 | The snapshot cache: memory snapshots, disk snapshots with the packages installed, and a copy of L2 in S3 Snapshot cache snapshot-cache . It makes new VMs start faster; it holds no saved instance | | Instance store | Where saved instances live: your S3 bucket s3 or a folder on this host local Choose a store choose-a-store | | Generation | The save number of an instance: 1, then +1 for each save | | Head | The object in the store that names the current state of an instance | | VM images | The kernel, the initramfs and the base disk image of each language VM images and offline use vm-images-and-offline-use | | Assets | The VM images and the gvproxy-wrapper binary: what sbx prefetch downloads | | Guest images | The disk images of one VM: the base image and, with packages, the L2 package image | | Worker | A process that runs a Scheduler , on its host a machine or a container | | Host kind | What a saved instance must match to load Rules for save and reuse rules-for-save-and-reuse | | Admission | The wait until the host has the memory, CPU and disk for a VM Limits limits | | KVM, HVF, TCG | Hardware acceleration on Linux KVM and macOS HVF . TCG is QEMU's software emulation | scheduler.new spec starts a new VM and returns its session. The session keeps variables, imports, files and background processes between exec calls Limits limits , until close destroys the VM. Some errors close a session What closes a session what-closes-a-session . async with Scheduler as scheduler: async with await scheduler.new VmSpec language=Language.PYTHON as session: await session.exec "import math" await session.exec "x = math.pi 2" result = await session.exec "print f'{x:.4f}' " print result.stdout 6.2832 print session.exec count 3 JavaScript sessions also TypeScript keep variables and functions. Shell sessions raw , Bash keep environment variables, the working folder and functions. A session closes after session idle timeout seconds default 300 with no call. For one session, pass idle timeout seconds 10-3600 to new or reuse ; a value out of range raises InvalidInputError ARGUMENT INVALID . To get the output while the code runs, pass on stdout and on stderr to exec : await session.exec code, on stdout=lambda chunk: print chunk, end="" . To get the boot output of the kernel, tiny-init and the guest agent, pass on boot log to new ; the VM then always cold boots no warm pool, no L1 . Keep each callback short: a slow callback blocks the event loop. Paths are relative to /home/user , the folder where your code runs. await session.write file "input.csv", b"name,score\nAlice,95" From bytes, a local Path or an IO bytes stream await session.write file "run.sh", Path "./run.sh" , make executable=True Mode 0755 default 0644 await session.exec "open 'output.csv', 'w' .write open 'input.csv' .read .upper " await session.read file "output.csv", destination=Path "./output.csv" To a local Path or an IO bytes stream for f in await session.list files "" : "" is /home/user print f.name, f.is dir, f.size sbx run --upload ./local.csv:input.csv --download output.csv:./result.csv -c "open 'output.csv','w' .write open 'input.csv' .read .upper " Set packages in the spec. The first VM of a spec installs the packages and caches the result; later VMs of that spec start from the cache Snapshot cache snapshot-cache . Count and size limits: Limits limits . Runtimes and tools: Guest environment guest-environment . - Give each package a version: VmSpec language=Language.PYTHON, packages= "pandas==3.0.1", , VmSpec language=Language.JAVASCRIPT, packages= "lodash@4.17.21", . Other operators = , ~= pass too; == gives a stable cache entry. - A package without a version, a bad name, or packages for raw raise InvalidInputError ARGUMENT INVALID . Scoped npm names @scope/name are refused. - A package outside the allow-list the top 10,000 of PyPI or npm raises InvalidInputError PACKAGE NOT ALLOWED . To skip this check, set enable package validation=False sbx run --no-validation . - Python packages install into Python 3.14 on musl with no build step: use packages with pure-Python or musllinux wheels. - The install reaches PyPI or npm, whatever the network settings of the spec. allow network=True turns on outbound access. allowed domains then sets what the guest can reach: - None default : the package registries of the language python: pypi.org , files.pythonhosted.org ; javascript: registry.npmjs.org . raw reaches every host. - empty : every host. - A list of domains, such as "httpbin.org", : these domains and their subdomains example.com also allows api.example.com . python from exec sandbox import Language, PortMapping Guest port 8080 on host port 3000 spec = VmSpec language=Language.PYTHON, expose ports= PortMapping internal=8080, external=3000 , async with await scheduler.new spec as session: print session.exposed ports 0 .url http://127.0.0.1:3000 - A fixed host port must be 1024-65535. An int in place of a PortMapping expose ports= 8080, is the guest port: the OS picks the host port. protocol is "tcp" default or "udp" . - Ports bind to 127.0.0.1. For access from other machines, put a reverse proxy on the host. - Port forwarding works without allow network ; all outbound TCP and UDP then stays blocked. - After reuse , the ports open again: a fixed host port must be free on this host, and a dynamic one can change read exposed ports again . save writes the state of a VM RAM, processes, files in /home/user , compressed and encrypted, to the instance store. reuse continues it later, on any worker of the same host kind. Every worker needs QEMU 11.0 or later else the Scheduler start fails with ConfigError MIGRATION UNSUPPORTED and a keyring: set EXEC SANDBOX INSTANCE KEYRING , or pass instance keyring= in code Keys keys . python import os from exec sandbox import Language, Scheduler, SchedulerConfig, VmSpec KEYRING = os.environ "MY KEYRING" from your secret store: see Keys config = SchedulerConfig instance store="local", instance keyring=KEYRING "s3" for several workers async with Scheduler config as scheduler: async with await scheduler.new VmSpec language=Language.PYTHON as session: await session.exec "x = 41" ref = await session.save InstanceRef instance id=..., generation=1 async with await scheduler.reuse ref.instance id as session: Later, with the same keyring result = await session.exec "x += 1; print x " print result.stdout 42 await session.save generation 2 save keeps the VM running: the session goes on after the save. Make a key with python3 -c "import base64, secrets; print base64.b64encode secrets.token bytes 32 .decode " . The keyring is a comma-separated list of keys, newest first: the first key encrypts new saves, the others only open older instances. Keep the keyring in your secret store, and give every worker the same keyring. Keep every key that saved an instance: without it, reuse raises ConfigError INSTANCE KEY MISSING . To change keys: Key rotation key-rotation . To choose the id, pass it to new : scheduler.new spec, instance id="user-42" . An id has 1 to 64 lowercase letters, digits, . , or - , and starts with a letter or digit. If the id exists, the first save fails with INSTANCE CONFLICT . Without an id, the first save makes a random one ref.instance id . session.save instance id="run-17" saves the VM as generation 1 of a new instance, then the session saves to that instance session.instance . The instance the session had stays as its last save left it. An id that exists raises INSTANCE CONFLICT , and nothing is overwritten. The session's own id gives a plain save. To start many sessions from one save, call reuse of the same instance in each, and give each session its own id at its first save: children = await scheduler.reuse checkpoint.instance id for in range 3 for n, child in enumerate children : await child.exec f"attempt {n} " await child.save instance id=f"attempt-{n}" the checkpoint stays as it was Each VM that starts from the same save gets new values from its first exec : the kernel random source os.urandom , /dev/urandom , Python ssl and the module functions of random , the random functions of the JavaScript crypto and node:crypto , Math.random also in the node:vm contexts that the code makes , the keys of the Sync functions of node:crypto such as generateKeyPairSync , and bash $RANDOM . Python random gets a new seed at each reuse : to repeat a seeded run, call random.seed after the load. These keep the state of the save in each copy: values made before the save, programs that run since before the save, random.Random objects and NumPy generators. In Bun, these can give the same values in each copy: the keys, primes and signatures of the functions that take a callback or return a promise such as generateKeyPair , generatePrime and crypto.subtle , TLS and fetch , and Workers. To get other values in each copy, make keys with the Sync functions, and seed the other generators in the copy. The local store instance store="local" is a folder on this host, for one host. For the s3 store, set up the bucket Set up the S3 bucket set-up-the-s3-bucket , then give every worker the same keyring and the same config: SchedulerConfig instance store="s3", s3 bucket="my-bucket" . At start, the Scheduler checks the bucket and logs "Instance store ready" with its key ids. sbx run --instance ID continues the instance ID , or makes it when it does not exist: sbx run --instance my-vm -c 'x = 41' Created instance my-vm, generation 1 sbx run --instance my-vm -c 'x += 1; print x ' 42, then: Saved instance my-vm, generation 2 sbx instance list One id on each line --json for an array sbx instance list --long One JSON object for each instance: as describe, or its error sbx instance describe my-vm JSON: generation, recent commits, key id, access, writer release; spec, host with the device layout , guest and egress domains when access is full sbx instance keys The id of each key of the keyring, newest first sbx instance check my-vm "my-vm ok", or why this worker cannot continue it sbx worker describe JSON: this worker's facts WorkerFacts , for a broker sbx instance rm my-vm other-vm In order, stops at the first error; exit code 0 when they are gone - Store. sbx reads the environment variables of SchedulerConfig schedulerconfig . By default, it uses the local store in instance store dir EXEC SANDBOX INSTANCE STORE DIR . For S3, set EXEC SANDBOX INSTANCE STORE=s3 , EXEC SANDBOX S3 BUCKET and EXEC SANDBOX INSTANCE KEYRING , and the other EXEC SANDBOX S3 variables as needed. Only --instance and sbx instance open the store. - Key. sbx reads EXEC SANDBOX INSTANCE KEYRING ; set it on a host with no OS keyring, such as a server or a container. Else, for the local store, sbx makes one key at the first use and keeps it in the OS keyring macOS Keychain; Secret Service or KWallet on Linux; no other keyring backend , entry exec-sandbox / instance-keyring . Back it up with keyring get exec-sandbox instance-keyring , restore it with keyring set exec-sandbox instance-keyring the keyring command of the cli extra, in the same Python environment . To open these instances from code, pass instance keyring=keyring.get password "exec-sandbox", "instance-keyring" . - Save. A run saves after the uploads, the code and the downloads, also when the code exits with an error or a download fails. It saves nothing after a timeout, a VM that stopped, or a failed upload or run; stderr tells why. -q hides the "Created/Saved" line. - VM settings. -l , -p , -m , --network , --allow-domain and --expose are fixed when the instance is made. Leave them out or give the same value; another value exits with code 2. With --allow-domain , also give --network . --instance takes one source -c , a file or - . - Exit codes. A bad id exits with code 2. If two runs save at the same time, the second save fails with INSTANCE CONFLICT and exit code 125; its output stays, its state does not. Others: Exit codes exit-codes . info = await scheduler.describe instance instance id Generation, recent commits, key id; spec and host when this keyring opens it deleted = await scheduler.delete instance instance id True if it existed async for instance id in scheduler.list instances : ... To do this without a Scheduler no VM, no guest image, no QEMU: a cleanup job on any host , open the store with instance admin : python from exec sandbox import SchedulerConfig, instance admin async with instance admin SchedulerConfig instance store="s3", s3 bucket="my-bucket" as admin: async for instance id in admin.list ids : info = await admin.describe instance id - One writer. save fails with INSTANCE CONFLICT if another save of the instance was stored since this session loaded or last saved it. The session stays open: save it under a new id to keep its work, or close it. If two requests can reach one instance at the same time, use your own lock. - Network. A reused instance reaches the domains its last save allowed describe instance id .egress domains ; empty: all , also after a release that changes the default list of allowed domains=None . - close never saves. After an exec or write file with no later save, close warns with InstanceNotSavedWarning not after another save of the instance won: no plain save of that session can store its work . The idle timeout closes the session with no save it logs a warning in the cases where close warns : save before a long pause. - Host kind. An instance loads only on a worker with the same CPU architecture, accelerator kvm , hvf or tcg , guest CPU model, host CPU ARM with KVM or HVF and guest clock rate any rate on x86 KVM with TSC scaling , and a QEMU that has the saved machine type for example virt-11.1 and accepts the saved state. The release of the worker must run the saved devices describe instance id .host.device layout . Other workers raise RouteError ; its required field gives the values empty for the devices: load it on a worker of another release . - After reuse . The network connections that were open at the save are closed. | action class | Codes | Do this | |---|---|---| | RETRY TransientError | INSTANCE STORE UNAVAILABLE , LOCAL DISK | Call again later. A failed save stored nothing. | | ROUTE RouteError | INSTANCE HOST MISMATCH | Use a worker that satisfies required Upgrades upgrades . Keep the instance. | | RECREATE InstanceGoneError | INSTANCE NOT FOUND , INSTANCE EXPIRED , INSTANCE INTEGRITY | Start a new instance. To use the same id again, call delete instance id first. A save that raises INSTANCE NOT FOUND keeps its session open: save it under a new id to keep its work. | | VERIFY OutcomeUnknownError | INSTANCE SAVE OUTCOME UNKNOWN | The session stays open. The save was stored if describe instance id .recent commits has error.context "commit id" : check before you do the work again. A retry of the same save the same instance id never stores a second copy. | | VERIFY OutcomeUnknownError | INSTANCE CONFLICT | This save was not stored, and the session stays open. If an earlier save of the session had an unknown outcome, look for its commit id in describe instance id .recent commits first: it may be the save that is stored. Else another save holds the instance: save this session under a new id to keep its work, or reuse the instance it has the other save and do the work again. For a new id, or the first save of new instance id=... , the id is taken: use another id. | | FIX CONFIG ConfigError | INSTANCE CONFIG , INSTANCE KEY MISSING , MIGRATION UNSUPPORTED , IMAGE DAMAGED | INSTANCE CONFIG : fix the bucket, store folder, permissions or keyring, or use a store with conditional writes. INSTANCE KEY MISSING : add the named key; keep the instance. MIGRATION UNSUPPORTED : upgrade QEMU to 11.0+. IMAGE DAMAGED : download or rebuild the images. | | FIX INPUT InvalidInputError | INSTANCE INVALID ID | Fix the id Instance ids instance-ids . | save and reuse can also raise the other codes of ErrorCode : Error codes error-codes . VmSpec says what a VM is made of. It is frozen and hashable: keep one spec per workload. | Field | Default | Description | |---|---|---| | language | required | "python" , "javascript" or "raw" shell | | memory mb | 192 | VM memory, 128 MB minimum. See Memory and file systems memory-and-file-systems | | cpu cores | 1 | Guest vCPUs | | disk mb | 1024 | Home disk size /home/user , ext4 , 128 MB minimum. Only written blocks use host disk | | packages | | Packages, each with a version "pandas==3.0.1" , "lodash@4.17.21" . See Packages packages | | allow network | False | Outbound network access | | allowed domains | None | With allow network : the domains the guest can reach. See Outbound access outbound-access | | expose ports | | Guest ports to expose on the host PortMapping or an int , at most 10. See Port forwarding port-forwarding | Settings for all VMs of a Scheduler : Scheduler SchedulerConfig warm pool size=1 . A field that you do not set in code reads its environment variable. An invalid value fails the Scheduler start with ConfigError SETTING INVALID . | Field | Default | Env var | Description | |---|---|---|---| | Sessions and warm pool | | | | | warm pool size | 0 | — | Warm-pool VMs per language, for VmSpec language=... with no other field. 0: no warm pool | | default timeout seconds | 30 | — | Execution timeout 1-300 s | | session idle timeout seconds | 300 | — | Close a session after this long without a call 10-3600 s | | Admission | | | | | memory overcommit ratio | 5.0 | EXEC SANDBOX MEMORY OVERCOMMIT RATIO | 1.0-10.0. Budget = host memory × 1 - reserve × ratio | | cpu overcommit ratio | 2.0 | EXEC SANDBOX CPU OVERCOMMIT RATIO | 1.0-20.0. Budget = host CPUs - reserve × ratio | | disk overcommit ratio | 4.0 | EXEC SANDBOX DISK OVERCOMMIT RATIO | 1.0-64.0. Each VM reserves the unwritten part of its disk mb / ratio | | host memory reserve ratio | 0.08 | EXEC SANDBOX HOST MEMORY RESERVE RATIO | Fraction of host memory kept for the OS 0.01-0.5 | | host cpu reserve cores | 0.5 | EXEC SANDBOX HOST CPU RESERVE CORES | CPU cores kept for host processes 0.0-16.0 | | Packages | | | | | enable package validation | True | — | Check packages against the allow-list top 10,000 of PyPI and of npm | | Images and caches | | | | | images dir | None | EXEC SANDBOX IMAGES DIR | Folder of the VM images. None: found automatically How images download how-images-download | | auto download assets | True | — | Download missing VM images from GitHub Releases | | disk snapshot cache dir |