littrs 0.4.1

A minimal, secure Python sandbox for AI agents

Littrs

A minimal, secure Python sandbox written in Rust for use by AI agents.

---

A minimal, secure Python sandbox written in Rust for use by AI agents.

Littrs avoids the cost, latency, and complexity of using full container-based sandboxes for running LLM-generated code. Instead, it lets you safely run Python code written by an LLM embedded directly in your agent, with startup times measured in milliseconds and zero external dependencies.

The core idea is simple: LLMs work faster, cheaper, and more reliably when they write Python code instead of relying on traditional structured tool calling. Littrs makes that possible without spinning up containers or risking arbitrary code execution on the host. You register Python functions as callable tools, hand the sandbox some LLM-generated code, and get back a result — safely.

Installation

pip install littrs

Quick Start

from littrs import Sandbox

sandbox = Sandbox()

# Execute Python code
result = sandbox.execute("2 + 2")
assert result == 4

# Variables persist across calls
sandbox.execute("x = 10")
sandbox.execute("y = 20")
result = sandbox.execute("x + y")
assert result == 30

Registering Tools

Register Python functions that LLM-generated code can call. The sandbox code calls them like normal Python functions, and you handle them on the host side.

from littrs import Sandbox

def fetch_data(args):
    id = args[0] if args else 0
    return {"id": id, "name": "Example"}

sandbox = Sandbox()
sandbox.register_function("fetch_data", fetch_data)

result = sandbox.execute("""
data = fetch_data(42)
data["name"]
""")
assert result == "Example"

Resource Limits

Prevent runaway code from consuming unbounded resources:

sandbox = Sandbox()
sandbox.set_limits(max_instructions=10_000, max_recursion_depth=50)

# This will raise an error, not hang forever
try:
    sandbox.execute("while True: pass")
except RuntimeError as e:
    print(e)  # "Instruction limit exceeded (limit: 10000)"

Resource limit errors are uncatchable — try/except in the sandbox code cannot suppress them. This is by design: the host must always be able to regain control.

Capturing Print Output

result, printed = sandbox.execute_with_output("""
for i in range(5):
    print(i)
"done"
""")
# printed == ["0", "1", "2", "3", "4"]
# result == "done"

Setting Variables

Inject values into the sandbox from the host:

sandbox = Sandbox()
sandbox.set_variable("config", {"model": "claude", "temperature": 0.7})

result = sandbox.execute('config["model"]')
assert result == "claude"

WASM Sandbox (Stronger Isolation)

For use cases requiring stronger isolation guarantees, Littrs includes a WASM-based sandbox that runs the interpreter inside a WebAssembly guest module. This provides memory isolation and fuel-based computation limits at the WASM level:

from littrs import WasmSandbox, WasmSandboxConfig

config = WasmSandboxConfig() \
    .with_fuel(1_000_000) \
    .with_max_memory(32 * 1024 * 1024)  # 32MB

sandbox = WasmSandbox(config)

result = sandbox.execute("sum(range(100))")
assert result == 4950

What Littrs Can Do

• Run a reasonable subset of Python — variables, control flow, functions (with defaults, *args, **kwargs), list comprehensions, f-strings, try/except, and all the built-in types an LLM needs
• Completely block access to the host environment — no filesystem, no network, no environment variables, no import, no standard library. The sandbox has zero ambient capabilities
• Call functions on the host — only functions you explicitly register as tools. The LLM code calls them like normal Python functions, and you handle them in Python
• Control resource usage — set instruction limits and recursion depth limits per execution call. Resource limit violations are uncatchable (they bypass try/except)
• Capture stdout — print() output is collected and returned to the caller
• Start up fast — no interpreter boot, no WASM runtime to load (unless you want it). Create a Sandbox, register tools, execute code

What Littrs Cannot Do

• Use the standard library — there is no import. No os, sys, json, re, or anything else
• Use third-party libraries — no pip install, no numpy, no requests
• Define classes — class definitions are not supported
• Use async/await — no coroutines, no asyncio
• Use finally blocks — only try/except/else
• Use match statements
• Snapshot/resume execution state — execution runs to completion in a single call

Supported Python Features

Types

None, bool, int, float, str, list, dict (string keys)

Operators

Category	Operators
Arithmetic	+, -, *, /, //, %, **
Comparison	==, !=, <, <=, >, >=, in, not in, is, is not
Boolean	and, or, not
Bitwise	|, ^, &, <<, >>, ~
Assignment	=, +=, -=, *=, /=, //=, %=, **=

Control Flow

• if/elif/else
• for loops over lists, strings, ranges, dict.items(), etc. — with break/continue
• while loops with break/continue
• Ternary expressions: x if condition else y
• List comprehensions with filters: [x*2 for x in items if x > 0]

Functions

• def with positional parameters, default values, *args, **kwargs
• Keyword arguments at call sites: f(x=1, y=2)
• Recursive and nested function definitions
• Implicit return None for functions without a return statement

Error Handling

• try/except with typed handlers: except ValueError as e:
• Bare except: to catch all exceptions
• else clause on try blocks
• raise ValueError("message") and bare raise to re-raise

F-strings

name = "world"
f"hello {name}!"  # "hello world!"

String Methods

.upper(), .lower(), .strip(), .split(), .join(), .replace(), .startswith(), .endswith(), .find(), .count(), .format()

List/Dict Methods

.append(), .pop(), .extend(), .insert(), .remove(), .keys(), .values(), .items(), .get(), .update(), .clear()

Slicing

items = [1, 2, 3, 4, 5]
items[1:3]    # [2, 3]
items[::2]    # [1, 3, 5]
items[::-1]   # [5, 4, 3, 2, 1]

Built-in Functions

len(), str(), int(), float(), bool(), list(), range(), abs(), min(), max(), sum(), print(), type(), isinstance(), enumerate(), zip(), sorted(), reversed(), dict(), tuple(), set(), round(), map(), filter(), any(), all(), chr(), ord()

Citation

If you use Littrs in your research, please cite it as:

@software{littrs,
  title = {Littrs: A Minimal, Secure Python Sandbox for AI Agents},
  author = {Chonkie Inc.},
  url = {https://github.com/chonkie-inc/littrs},
  license = {Apache-2.0},
  year = {2025}
}