Sandboxes

Sandboxes are the fundamental unit of execution in Runra. Each sandbox is an isolated cloud workspace where agents can safely run code, modify files, and operate.

Sandbox lifecycle

create → start → [running] → pause → [paused]
                           → resume → [running]
                           → terminate → [terminated]

States

State	Description	Consumes runtime?
creating	Sandbox is being provisioned	No
running	Active, can execute commands	Yes
paused	State preserved, not executing	No
terminated	Sandbox is destroyed	No

Resources

Each sandbox has configurable resource limits:

const sandbox = await runra.sandboxes.create({
  image: "node:22",
  resources: {
    cpu: 2,            // vCPUs (2, 4, or 8)
    memoryMb: 4096,    // Memory in MB
    diskMb: 10240,     // Disk in MB
  },
});

Isolation model

Runra Sandbox uses VM-backed isolation via CubeSandbox:

• File system: Each sandbox gets its own workspace. No cross-workspace access.
• Processes: Processes in one sandbox cannot see or interact with another.
• Network: Configurable network policies per sandbox.
• Resource limits: Hard CPU, memory, and disk limits.

Lifecycle hooks

sandbox.on("started", () => console.log("Sandbox ready"));
sandbox.on("paused", () => console.log("Sandbox paused"));
sandbox.on("terminated", () => console.log("Sandbox ended"));

Next steps

• Pause & Resume — state management
• Isolation Model — security details
• Running Code — execution guide