https://github.com/a14a-org/llama-index-tools-omnirun
LlamaIndex tools for OmniRun sandboxes
https://github.com/a14a-org/llama-index-tools-omnirun
ai-agents code-execution firecracker llamaindex microvm python sandbox
Last synced: 10 days ago
JSON representation
LlamaIndex tools for OmniRun sandboxes
- Host: GitHub
- URL: https://github.com/a14a-org/llama-index-tools-omnirun
- Owner: a14a-org
- License: mit
- Created: 2026-04-07T17:52:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-15T02:03:38.000Z (13 days ago)
- Last Synced: 2026-06-15T04:06:06.120Z (13 days ago)
- Topics: ai-agents, code-execution, firecracker, llamaindex, microvm, python, sandbox
- Language: Python
- Size: 18.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# llama-index-tools-omnirun
LlamaIndex tools for [OmniRun](https://omnirun.dev) sandboxes. Execute code in isolated Firecracker microVMs from your LlamaIndex agents.
Each sandbox runs its own Linux kernel with hardware-level isolation, making it safe to execute untrusted code generated by LLMs.
## Installation
```bash
pip install llama-index-tools-omnirun
```
## Quick start
```python
from llama_index_tools_omnirun import OmniRunToolSpec
spec = OmniRunToolSpec()
tools = spec.to_tool_list()
# Execute Python code
result = spec.execute_code("print(sum(range(100)))")
print(result) # 4950
spec.cleanup()
```
## Available tools
The `OmniRunToolSpec` provides four tools that share a single sandbox instance:
| Tool | Name | Description |
|------|------|-------------|
| `execute_code` | `omnirun_execute` | Execute Python code in an isolated Firecracker microVM |
| `run_shell` | `omnirun_shell` | Run shell commands (install packages, list files, etc.) |
| `write_file` | `omnirun_write_file` | Write a file to the sandbox filesystem |
| `read_file` | `omnirun_read_file` | Read a file from the sandbox filesystem |
## Using with a LlamaIndex agent
```python
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from llama_index_tools_omnirun import OmniRunToolSpec
spec = OmniRunToolSpec()
tools = spec.to_tool_list()
llm = OpenAI(model="gpt-4o")
agent = ReActAgent.from_tools(tools, llm=llm, verbose=True)
response = agent.chat(
"Write a Python script that calculates the first 20 Fibonacci numbers, "
"save it to /tmp/fib.py, then run it."
)
print(response)
spec.cleanup()
```
## Direct tool usage
```python
from llama_index_tools_omnirun import OmniRunToolSpec
spec = OmniRunToolSpec()
tools = spec.to_tool_list()
print("Available tools:")
for t in tools:
print(f" - {t.metadata.name}: {t.metadata.description}")
# Execute code
result = spec.execute_code("print('Hello from Firecracker!')")
print(result)
# Write and read files
spec.write_file("/tmp/data.txt", "sample data")
content = spec.read_file("/tmp/data.txt")
print(content)
# Run shell commands
result = spec.run_shell("pip install requests && python3 -c 'import requests; print(requests.__version__)'")
print(result)
spec.cleanup()
```
## Configuration
```python
# Custom template and timeout
spec = OmniRunToolSpec(
template="python-3.11", # Sandbox template
timeout=60, # Per-execution timeout in seconds
)
```
## Environment variables
- `OMNIRUN_API_KEY` - Your OmniRun API key (required)
## Documentation
- [OmniRun docs](https://docs.omnirun.dev)
- [LlamaIndex docs](https://docs.llamaindex.ai)
## License
MIT