Volumes Overview

​

When to Use Volumes

• Agent workspaces - Git repositories, project files that persist between sessions
• Large datasets - Data that shouldn’t be re-downloaded on every sandbox start
• Shared state - Files accessed by multiple sandboxes over time
• Cold access - Browsing or downloading files without spinning up a sandbox

​

How It Works

Volume (Persistent)           Sandbox (Ephemeral)
┌────────────────────┐       ┌────────────────────┐
│ JuiceFS Mount      │──────►│ /workspace/data    │
│ ─────────────      │       │                    │
│ Redis (metadata)   │       │ Full POSIX access  │
│ GCS (data chunks)  │       │ Lazy loading       │
│                    │       │ Crash-safe writes  │
└────────────────────┘       └────────────────────┘
         │
         ▼
    ┌────────────────────┐
    │ API File Access    │
    │ (No sandbox needed)│
    └────────────────────┘

• POSIX compatibility - Supports all standard file operations
• Lazy loading - Files load on-demand, not at startup
• Crash durability - Writes are persisted immediately
• Cold access - List, upload, and download files via API

​

Quick Start

from moru import Sandbox, Volume

# Create a volume
vol = Volume.create(name="my-workspace")

# Attach to sandbox
sbx = Sandbox.create(
    template="base",
    volume_id=vol.volume_id,
    volume_mount_path="/workspace"
)

# Work with files in the mounted volume
sbx.commands.run("git clone https://github.com/user/repo /workspace")

# Kill sandbox - data persists in volume
sbx.kill()

# Later: access files without sandbox
files = vol.list_files("/")
content = vol.download("/README.md")

​

Volume vs Sandbox Filesystem

​

Limits

​

Next Steps