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 a forked child 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
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
- 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
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.2.4.tar.gz.
File metadata
- Download URL: sandtrap-0.2.4.tar.gz
- Upload date:
- Size: 100.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
814d1edf4821b2a316f37d568366553495e739ca9107f7cf4c896cfbd230c704
|
|
| MD5 |
eabef97e771aad334527d87daad8d35c
|
|
| BLAKE2b-256 |
a67ef68dc34286ef4dd68935700e0af8b29d58efb80f8a5425b9a7c46804416d
|
File details
Details for the file sandtrap-0.2.4-py3-none-any.whl.
File metadata
- Download URL: sandtrap-0.2.4-py3-none-any.whl
- Upload date:
- Size: 62.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
77bbc08f17a7419ea1b5554673189eed52d3db40e35ba192db099561bd0852e3
|
|
| MD5 |
e4bff7867d8ba4f7f5851ab755f4dfe6
|
|
| BLAKE2b-256 |
0ae78280b45ffceb9a0eca3a21d3e6c8168641d3ca1a0337bed21c9a26531d8e
|
