README
¶
goru
Run untrusted Python and JavaScript safely. No Docker, no VMs, just WebAssembly.
The Problem
You need to execute user-submitted or AI-generated code. Your options:
- Docker: Requires daemon, orchestration, Linux features. Overkill for running a Python snippet.
- Firecracker/gVisor: Linux-only, complex setup, operational overhead.
- Native execution: Dangerous. One
os.system('rm -rf /')and you're done.
Who It's For
- Code execution platforms - LeetCode clones, coding interviews, online judges
- LLM tool execution - Run AI-generated code without risking your infrastructure
- Plugin systems - Let users extend your app with custom scripts
- Educational platforms - Safe code playgrounds for students
Who It's NOT For
- High-performance computing - WASM adds overhead; use native execution if you trust the code
- NumPy/Pandas workloads - C extensions don't work in WASI; pure Python only
- Long-running processes - Designed for short scripts, not daemons or servers
- Multi-threaded code - WASI doesn't support threads
Limitations
Performance: WASM interpretation adds ~2-10x overhead vs native. Cold starts are slow (~500ms Python, ~100ms JS). We mitigate with disk caching and session reuse.
WASI constraints: No threads, no raw sockets, no FFI. Python's multiprocessing, threading, socket, ssl modules are blocked. C extensions (numpy, pandas) won't load.
Abstraction layer: http, fs, kv modules are wrappers over host functions, not real stdlib. They're injected into the runtime and call back to Go. This means:
- No
requestslibrary (use built-inhttpmodule instead) - No direct filesystem access (only mounted paths via
fs) - Behavior may differ slightly from native equivalents
Features
- Bidirectional host-guest protocol - Sandboxed code calls Go functions via
call(), Go receives structured responses (docs) - Extensible - Register custom Go functions callable from sandbox via
Registry.Register()(docs) - Async batching - Concurrent host calls with
asyncio.gather()/Promise.all()batched into single round-trip (docs) - Capability-based security - Zero permissions by default, opt-in HTTP/filesystem/KV per-session (docs)
- Session state - Variables persist across executions, define functions once and reuse (docs)
- Built-in modules -
http,fs,kvavailable in sandbox without imports when enabled (docs) - Python packages - Pre-install via CLI or allow runtime
install_pkg()from sandboxed code (docs)
Security Model
By default, sandboxed code has zero capabilities:
| Capability | Default | Enable With |
|---|---|---|
| Filesystem | Blocked | WithMount() |
| HTTP | Blocked | WithAllowedHosts() |
| KV Store | Blocked | WithKV() |
| Host Functions | Blocked | Registry.Register() |
Install
# CLI
curl -fsSL https://raw.githubusercontent.com/caffeineduck/goru/main/install.sh | bash
# Go library
go get github.com/caffeineduck/goru
CLI Quick Start
goru script.py # Run file
goru --lang python -c 'print(1+1)' # Inline code
echo 'print(1+1)' | goru -l python # Pipe code via stdin
echo 'console.log(1+1)' | goru -l js # Works with JavaScript too
goru repl --lang python # Interactive REPL
goru --help # Full options
Go API
exec, _ := executor.New(hostfunc.NewRegistry())
defer exec.Close()
session, _ := exec.NewSession(python.New(),
executor.WithSessionAllowedHosts([]string{"api.example.com"}),
executor.WithSessionMount("/data", "./input", hostfunc.MountReadOnly),
executor.WithSessionKV(),
)
defer session.Close()
session.Run(ctx, `x = 42`)
session.Run(ctx, `resp = http.get("https://api.example.com/data")`)
result := session.Run(ctx, `print(x, resp["status"])`)
Full API: pkg.go.dev/github.com/caffeineduck/goru
Documentation
- Sandbox API - APIs for Python/JavaScript code running in the sandbox
- Go API - Go embedding documentation on pkg.go.dev
License
MIT
Documentation
¶
Overview ¶
Package goru provides a WebAssembly-based sandbox for executing untrusted Python and JavaScript code safely.
Overview ¶
goru runs code in isolated WASM modules with zero default capabilities. Filesystem, network, and other system access must be explicitly enabled.
Basic Usage ¶
exec, _ := executor.New(hostfunc.NewRegistry())
defer exec.Close()
// Stateless execution
result := exec.Run(ctx, python.New(), `print("hello")`)
fmt.Println(result.Output)
// Session with persistent state
session, _ := exec.NewSession(python.New())
session.Run(ctx, `x = 42`)
session.Run(ctx, `print(x)`) // 42
Enabling Capabilities ¶
// HTTP access
result := exec.Run(ctx, python.New(), code,
executor.WithAllowedHosts([]string{"api.example.com"}))
// Filesystem access
result := exec.Run(ctx, python.New(), code,
executor.WithMount("/data", "./input", hostfunc.MountReadOnly))
// Key-value store
result := exec.Run(ctx, python.New(), code,
executor.WithKV())
See the [executor], [hostfunc], language/python, and language/javascript packages for detailed API documentation.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
goru
command
|
|
|
Package executor provides a WebAssembly-based code execution engine for running untrusted Python and JavaScript code in a secure sandbox.
|
Package executor provides a WebAssembly-based code execution engine for running untrusted Python and JavaScript code in a secure sandbox. |
|
Package hostfunc provides host function implementations for sandboxed WASM code.
|
Package hostfunc provides host function implementations for sandboxed WASM code. |
|
internal
|
|
|
tools/download
command
|
|
|
language
|
|
|
python
Package python provides the Python language adapter for goru.
|
Package python provides the Python language adapter for goru. |