sandtrap ⛳
A local Python sandbox using AST rewriting and compiled bytecode execution. Whitelist-based policies control attribute access, imports, and resource usage. Designed as a walled garden for cooperative code (e.g. agent-generated scripts), not for adversarial inputs.
Three isolation levels via the sandbox() factory:
"none"(default) -- in-process, lightweight, shares the host's memory space"process"-- subprocess-backed, crash protection, no kernel restrictions"kernel"-- subprocess + kernel-level isolation (seccomp, Landlock, Seatbelt)
Install
pip install sandtrap
For subprocess isolation with kernel-level sandboxing on Linux:
pip install sandtrap[process]
Quick start
In-process (default)
from sandtrap import Policy, sandbox
policy = Policy(timeout=5.0, tick_limit=100_000)
with sandbox(policy) as sb:
result = sb.exec("""
total = sum(range(10))
print(f"total = {total}")
""")
print(result.stdout) # "total = 45\n"
print(result.namespace) # {"total": 45}
print(result.error) # None
print(result.ticks) # 2 (fn calls: sum + print)
Subprocess
from sandtrap import Policy, IsolatedFS, sandbox
policy = Policy(timeout=5.0, tick_limit=100_000)
with sandbox(policy, isolation="kernel", filesystem=IsolatedFS("/tmp/sandbox")) as sb:
result = sb.exec("""
total = sum(range(10))
print(f"total = {total}")
""")
print(result.stdout) # "total = 45\n"
print(result.namespace) # {"total": 45}
isolation="kernel" runs code in an isolated worker process with:
- Filesystem restricted to the
IsolatedFSroot via Landlock (Linux) or Seatbelt (macOS) - Syscall filtering via seccomp (Linux) or Seatbelt (macOS)
- Network blocked at the kernel level (unless the policy enables it)
- Worker crash doesn't take down the host process
- The worker does not inherit the host's memory or threads — it is forked from a dedicated broker, so a multi-threaded host can't deadlock it (see process docs)
Kernel mode is defense-in-depth — a second layer that contains accidental or casual escape (a buggy agent's stray network call, a walk outside the root) under the cooperative-code Python sandbox. It is not a boundary against code actively trying to escape: the inner Python layer isn't adversarial-safe, and the worker→host IPC uses pickle. See the security model for the full picture and the roadmap for hardening plans.
If the platform can't apply the requested kernel restrictions (missing sandtrap[process] packages, Landlock-less kernel, unsupported OS), isolation="kernel" fails closed — it raises IsolationUnavailable rather than silently running with no protection. Pass allow_degraded=True to proceed anyway; inspect result.isolation to see exactly what took effect.
Part of the agex stack
sandtrap powers sandboxed code execution in agex, where AI agents write and execute Python directly against host libraries. Filesystem interception is provided by monkeyfs.
Documentation
- Policy & Registration -- configuring what sandboxed code can access
- Sandbox Execution -- running code, results, error handling, REPL-style expression echo
- Process Sandbox -- subprocess isolation with kernel-level restrictions
- Filesystem & Network -- VFS interception, network denial, VFS imports
- Serialization -- pickling functions, classes, and state across turns
- Security Model -- how the sandbox works, what it blocks, threat model
- Roadmap -- planned isolation hardening (restricted deserialization, kernel-mode boundary)
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sandtrap-0.3.1.tar.gz.
File metadata
- Download URL: sandtrap-0.3.1.tar.gz
- Upload date:
- Size: 161.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bd8b35833af75b49efb535bc7e2c285f88ae0204f9e78eadc06dddff674ec291
|
|
| MD5 |
eb6e7b00ba001659bd7da65daf531d3c
|
|
| BLAKE2b-256 |
fd38d4e509a19003d1c9c34bf99f868f089b21f2f73a1a39bec1b3fa3a5fc130
|
File details
Details for the file sandtrap-0.3.1-py3-none-any.whl.
File metadata
- Download URL: sandtrap-0.3.1-py3-none-any.whl
- Upload date:
- Size: 92.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e5155d7b3ac3751a39af87431e948ce67442a90826bd817cdf3e7f9f055f1319
|
|
| MD5 |
5f64b5b83b91e000a86496e191d4db3d
|
|
| BLAKE2b-256 |
c59e5de51f1a682d7c28560517f182a299bbfc31d9522cd83ef2ac91bcd79c37
|
