| description | CodeAct via Hyperlight. Use when looping over many files (8+), cross-referencing
results from multiple sources, aggregating data across directories, or
chaining 5+ dependent tool calls. Collapses N round-trips into one sandboxed
Python run via scripts/codeact.py. NOT beneficial for <5 files or simple
grep-then-view — direct tool calls have less overhead at small scale.
ESPECIALLY valuable when MCP servers are loaded — fewer turns means the
MCP tool catalog context is replayed fewer times.
Run `scripts/codeact.py --discover` to see available sandbox tools.
Trigger: "codeact", "chain tools", "sandbox", "batch", "for each",
"hyperlight sandbox", "collapse tool calls", "run in sandbox",
"sandbox execution".
|
| name | hyperlight-codeact |
Hyperlight CodeAct
Collapse multi-step tool chains into a single sandboxed Python execution
inside an isolated Hyperlight micro-VM (WebAssembly).
Syntax
Use call_tool(name, **kwargs) — built-in global, no import needed:
content = call_tool('view', path='src/main.py')
files = call_tool('glob', pattern='**/*.py')
hits = call_tool('grep', pattern='TODO', paths='src')
result = call_tool('bash', command='git log --oneline -5')
call_tool('edit', path='config.json', old_str='"debug": false', new_str='"debug": true')
Return types (critical — wrong assumptions cause retries)
call_tool('glob', ...) → list of strings like ["src/app.py", ...]call_tool('view', ...) → string (file content)call_tool('bash', ...) → dict with stdout, stderr, returncodecall_tool('mcp_call', ...) → string
Pattern
for f in call_tool('glob', pattern='src/**/*.py'):
try:
content = call_tool('view', path=f)
except Exception:
continue
print(f"{f}: {result}")
Rules
- One bash call, one program. Do not scout with separate tool calls first.
- Wrap file reads in try/except.
glob() returns workspace-relative paths — pass directly to view().- Brace expansion works:
call_tool('glob', pattern='src/{db,services}/**/*.py')
Discover tools
python3 scripts/codeact.py --discover
python3 scripts/codeact.py --instructions
Tools are auto-detected based on what's installed on the host.
Execute
uv run --python 3.13 --with 'hyperlight-sandbox[wasm,python_guest]>=0.3.0' \
python3 scripts/codeact.py --auto --workspace . --code '...'
Output: {"stdout": "...", "stderr": "...", "exit_code": 0, "success": true}
Trust model
Sandboxed code can only reach the outside world through call_tool() bridges.
Tools run on the host with full process access. Use --workspace to restrict
file tools to a directory tree.
Prerequisites
- Python 3.10–3.13 (Wasm backend has no wheels for 3.14+)
uv (recommended) or pip install 'hyperlight-sandbox[wasm,python_guest]>=0.3.0'
References
