Skip to main content
Create a new sandbox with Sandbox.create(). The sandbox starts immediately and is ready for operations once the method returns.

​
Basic Usage

from moru import Sandbox

# Create with default 'base' template
sandbox = Sandbox.create()

# Create with a specific template
sandbox = Sandbox.create("python")

# Create with options
sandbox = Sandbox.create(
    template="python",
    timeout=600,  # 10 minutes in seconds
    metadata={"project": "my-agent"}
)

​
Options Reference

OptionTypeDefaultDescription
templatestring"base"Template ID or name
timeout / timeoutMsnumber300s / 300000msAuto-termination timeout
metadataobject{}Custom key-value pairs
envsobject{}Environment variables
allow_internet_access / allowInternetAccessbooleantrueEnable outbound network
networkobjectnullFine-grained network control
mcpobjectnullMCP server configuration
securebooleantrueEnable security features

​
Template Selection

Templates define the base image and pre-installed packages: 
from moru import Sandbox

# Built-in templates
sandbox = Sandbox.create("base")      # Minimal Ubuntu
sandbox = Sandbox.create("python")    # Python with common packages
sandbox = Sandbox.create("node")      # Node.js LTS

# Custom template (by ID or name)
sandbox = Sandbox.create("my-custom-template")
sandbox = Sandbox.create("tpl_abc123")

​
Network Configuration

Control outbound network access: 
from moru import Sandbox

# Completely isolated - no network access
sandbox = Sandbox.create(allow_internet_access=False)

# Allow specific destinations only
sandbox = Sandbox.create(
    network={
        "allow_out": ["api.openai.com", "8.8.8.8/32"],
        "deny_out": [],
        "allow_public_traffic": True,  # Allow inbound to exposed ports
    }
)

# Block specific destinations
sandbox = Sandbox.create(
    network={
        "deny_out": ["internal.company.com"],
    }
)

​
Environment Variables

Set environment variables available to all processes: 
from moru import Sandbox

sandbox = Sandbox.create(
    envs={
        "OPENAI_API_KEY": "sk-...",
        "DATABASE_URL": "postgres://...",
        "NODE_ENV": "production",
    }
)

# Access in commands
result = sandbox.commands.run("echo $OPENAI_API_KEY")

​
Metadata

Attach metadata for organization and filtering: 
from moru import Sandbox

sandbox = Sandbox.create(
    metadata={
        "user_id": "user_123",
        "session_id": "sess_abc",
        "agent_type": "code-assistant",
    }
)

# Later, list sandboxes by metadata
# (using API or dashboard)

​
MCP Mode

Enable Model Context Protocol for tool execution: 
from moru import Sandbox

# Enable MCP mode
sandbox = Sandbox.create(mcp=True)

# Get MCP URL for connecting tools
mcp_url = sandbox.get_mcp_url()
mcp_token = sandbox.get_mcp_token()

​
Async Creation (Python)

For async Python applications: 
import asyncio
from moru import AsyncSandbox

async def main():
    sandbox = await AsyncSandbox.create(
        template="python",
        timeout=600,
        metadata={"project": "async-agent"}
    )

    result = await sandbox.commands.run("python3 --version")
    print(result.stdout)

    await sandbox.kill()

asyncio.run(main())

​
Beta: Auto-Pause

Create sandboxes that automatically pause when idle (beta feature): 
from moru import Sandbox

# Create with auto-pause enabled
sandbox = Sandbox.beta_create(
    template="python",
    auto_pause=True,
    auto_pause_timeout=300  # Pause after 5 minutes of inactivity
)

​
Error Handling

Handle common creation errors: 
from moru import Sandbox
from moru.exceptions import (
    AuthenticationException,
    NotFoundException,
    TimeoutException,
)

try:
    sandbox = Sandbox.create("my-template")
except AuthenticationException:
    print("Invalid API key")
except NotFoundException:
    print("Template not found")
except TimeoutException:
    print("Sandbox creation timed out")

​
Next Steps

Connect to Sandbox

Reconnect to existing sandboxes.

Run Commands

Execute commands in your sandbox.

File Operations

Read and write files.

Custom Templates

Create templates with your dependencies.