Sandboxes

Core sandbox concepts — lifecycle, isolation, resources

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