Moru Python SDK

bash
1pip install moru

Quick Start

python
1from moru import Sandbox
2
3with Sandbox.create() as sbx:
4    sbx.files.write("/app/script.py", "print('Hello from Moru!')")
5    result = sbx.commands.run("python3 /app/script.py")
6    print(result.stdout)
7# Sandbox auto-killed

Quick Reference

Sandbox Lifecycle

Create

python
1from moru import Sandbox
2
3# Default template
4sbx = Sandbox.create()
5
6# Specific template
7sbx = Sandbox.create("python")
8
9# With options
10sbx = Sandbox.create(
11    template="python",
12    timeout=600,                    # seconds (default: 300)
13    metadata={"project": "myapp"},
14    envs={"API_KEY": "secret"},
15    volume_id="vol_xxx",
16    volume_mount_path="/workspace",
17    allow_internet_access=True,
18)

Context Manager (Recommended)

python
1with Sandbox.create() as sbx:
2    result = sbx.commands.run("echo hello")
3# Auto-killed on exit

Connect to Existing

python
1sbx = Sandbox.connect("sbx_abc123")
2if sbx.is_running():
3    result = sbx.commands.run("echo still alive")

Kill

python
1sbx.kill()
2# or
3Sandbox.kill("sbx_abc123")

List All

python
1for info in Sandbox.list():
2    print(f"{info.sandbox_id}: {info.state}")

Running Commands

Basic

python
1result = sbx.commands.run("echo hello")
2print(result.stdout)      # "hello\n"
3print(result.stderr)      # ""
4print(result.exit_code)   # 0

With Options

python
1result = sbx.commands.run(
2    "python3 script.py",
3    cwd="/app",                         # Working directory
4    user="root",                        # Run as root
5    envs={"DEBUG": "1"},               # Environment variables
6    timeout=120,                        # Command timeout (seconds)
7    on_stdout=lambda d: print(d, end=""),  # Stream stdout
8    on_stderr=lambda d: print(d, end=""),  # Stream stderr
9)

Background Process

python
1handle = sbx.commands.run("python3 server.py", background=True)
2
3# Get public URL
4url = sbx.get_host(8080)
5print(f"Server at: {url}")
6
7# Send input
8handle.send_stdin("quit\n")
9
10# Wait for completion
11result = handle.wait()
12
13# Or kill it
14handle.kill()

Process Management

python
1# List running processes
2for proc in sbx.commands.list():
3    print(f"PID {proc.pid}: {proc.command}")
4
5# Kill by PID
6sbx.commands.kill(1234)

Working with Files

Read/Write

python
1# Write
2sbx.files.write("/app/config.json", '{"key": "value"}')
3
4# Read
5content = sbx.files.read("/app/config.json")
6
7# Binary
8data = sbx.files.read("/app/image.png", format="bytes")
9sbx.files.write("/app/output.bin", binary_data)
10
11# Stream large files
12for chunk in sbx.files.read("/app/large.bin", format="stream"):
13    process(chunk)

Multiple Files

python
1sbx.files.write_files([
2    {"path": "/app/file1.txt", "data": "content1"},
3    {"path": "/app/file2.txt", "data": "content2"},
4])

Directory Operations

python
1# Check existence
2if sbx.files.exists("/app/config.json"):
3    config = sbx.files.read("/app/config.json")
4
5# List directory
6for entry in sbx.files.list("/app"):
7    print(f"{entry.type}: {entry.name} ({entry.size} bytes)")
8
9# Recursive list
10entries = sbx.files.list("/app", depth=5)
11
12# Get info
13info = sbx.files.get_info("/app/file.txt")
14print(f"Size: {info.size}, Modified: {info.modified_time}")
15
16# Create directory
17sbx.files.make_dir("/app/data")
18
19# Delete
20sbx.files.remove("/app/old_file.txt")
21
22# Rename/Move
23sbx.files.rename("/app/old.txt", "/app/new.txt")

Watch for Changes

python
1handle = sbx.files.watch_dir("/app")
2for event in handle.events():
3    print(f"{event.type}: {event.name}")
4handle.stop()

Volumes (Persistent Storage)

python
1from moru import Sandbox, Volume
2
3# Create volume (idempotent)
4vol = Volume.create(name="my-workspace")
5
6# Attach to sandbox
7sbx = Sandbox.create(
8    volume_id=vol.volume_id,
9    volume_mount_path="/workspace"  # Must be /workspace, /data, /mnt, or /volumes
10)
11
12# Data in /workspace persists after kill
13sbx.commands.run("echo 'persistent' > /workspace/data.txt")
14sbx.kill()
15
16# Later - data still there
17sbx2 = Sandbox.create(volume_id=vol.volume_id, volume_mount_path="/workspace")
18result = sbx2.commands.run("cat /workspace/data.txt")
19print(result.stdout)  # "persistent"

Volume Operations (No Sandbox Needed)

python
1vol = Volume.get("my-workspace")
2
3# List files
4for f in vol.list_files("/"):
5    print(f"{f.type}: {f.name}")
6
7# Download/Upload
8content = vol.download("/data.txt")
9vol.upload("/config.json", b'{"key": "value"}')
10
11# Delete
12vol.delete("/old_file.txt")
13
14# Delete volume (WARNING: permanent)
15vol.delete()

Templates

python
1from moru import Template
2from moru.template import wait_for_port
3
4# Define template
5template = (
6    Template()
7    .from_python_image("3.11")
8    .apt_install(["curl", "git"])
9    .pip_install(["flask", "pandas", "requests"])
10    .copy("./app", "/app")
11    .set_workdir("/app")
12    .set_envs({"FLASK_ENV": "production"})
13    .set_start_cmd("python app.py", wait_for_port(5000))
14)
15
16# Build
17info = Template.build(template, alias="my-flask-app")
18
19# Use
20sbx = Sandbox.create("my-flask-app")

From Dockerfile

python
1template = Template().from_dockerfile("./Dockerfile")
2Template.build(template, alias="my-app")

Build Options

python
1Template.build(
2    template,
3    alias="my-app",
4    cpu_count=4,
5    memory_mb=2048,
6    on_build_logs=lambda entry: print(entry.message),
7)
8
9# Background build
10info = Template.build_in_background(template, alias="my-app")
11status = Template.get_build_status(info)  # building, success, failed

Async Support

python
1import asyncio
2from moru import AsyncSandbox
3
4async def main():
5    async with await AsyncSandbox.create() as sbx:
6        result = await sbx.commands.run("echo hello")
7        print(result.stdout)
8
9        await sbx.files.write("/tmp/test.txt", "content")
10        content = await sbx.files.read("/tmp/test.txt")
11
12asyncio.run(main())

Error Handling

python
1from moru import Sandbox
2from moru.exceptions import (
3    SandboxException,           # Base
4    TimeoutException,           # Operation timed out
5    NotFoundException,          # Resource not found
6    AuthenticationException,    # Invalid API key
7    NotEnoughSpaceException,    # Disk full
8    CommandExitException,       # Non-zero exit (has exit_code, stdout, stderr)
9)
10
11try:
12    with Sandbox.create() as sbx:
13        result = sbx.commands.run("python3 script.py", timeout=30)
14except TimeoutException:
15    print("Command timed out")
16except CommandExitException as e:
17    print(f"Failed with exit code {e.exit_code}: {e.stderr}")
18except AuthenticationException:
19    print("Invalid API key - check MORU_API_KEY")

Common Pitfalls

Always cleanup sandboxes

python
1# ❌ WRONG
2sbx = Sandbox.create()
3sbx.commands.run("echo hello")
4# Forgot to kill - sandbox keeps running!
5
6# ✅ CORRECT
7with Sandbox.create() as sbx:
8    sbx.commands.run("echo hello")

Don't assume packages exist

python
1# ❌ WRONG
2sbx.commands.run("python3 -c 'import pandas'")  # ImportError!
3
4# ✅ CORRECT
5sbx.commands.run("pip install pandas", timeout=120)
6sbx.commands.run("python3 -c 'import pandas'")

Write to volume path for persistence

python
1# ❌ WRONG - lost on kill
2sbx.files.write("/home/user/data.txt", "important")
3
4# ✅ CORRECT - persisted
5sbx.files.write("/workspace/data.txt", "important")

Handle command failures

python
1result = sbx.commands.run("python3 script.py")
2if result.exit_code != 0:
3    print(f"Error: {result.stderr}")