Sandboxes

Isolated environments for AI agents — run code, manage files, execute commands

Overview

Sandboxes are isolated microVM environments for AI agents. They provide a full Linux environment with file system access, shell execution, and network connectivity. Three modes cover different use cases, and all three are available today.

Sandbox Types

Ephemeral sandboxes are disposable: they stop at their idle or hard timeout and nothing on the rootfs persists past stop. Compute is billed per vCPU-hour and GB-hour of allocation while running.

Persistent sandboxes live at /v1/persistent and survive restarts. They add pause, resume, snapshot and touch, plus schedule for wake-ups by cron, time or event — a paused sandbox is resumed automatically by the wake-up worker when its schedule fires.

Persistent sandbox or Computer?

Both keep state. Pick on how you interact with it:

• Persistent sandbox — a machine your code drives, programmatically, at scale: pause it, snapshot it, wake it on a schedule.
• Computer — a machine you inhabit: root, real ssh, a reserved address, and your editor over Remote-SSH.

Quick Start

Create an Ephemeral Sandbox

curl -X POST https://api.scalix.world/v1/sandboxes \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "node22",
    "timeout_ms": 300000
  }'

Available runtime today: node22 (more are rolling out). timeout_ms ranges from 60000 (1 min) to 86400000 (24 h).

Execute Commands

curl -X POST https://api.scalix.world/v1/sandboxes/{id}/commands \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "node", "args": ["-e", "console.log(1+1)"]}'

Upload Files

Files are sent as a JSON array of {path, content} objects. Writable paths are under /app (your workspace), /scalix, and /build:

curl -X POST https://api.scalix.world/v1/sandboxes/{id}/files \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"path": "/app/script.js", "content": "console.log(1+1)"}]}'

Download Files

The file path goes directly in the URL after /files/:

curl https://api.scalix.world/v1/sandboxes/{id}/files/app/output.json \
  -H "Authorization: Bearer $SCALIX_API_KEY"

For AI Agents

Sandboxes are designed for AI agents to:

• Write and execute code safely
• Install packages and dependencies
• Read and write files
• Run tests and builds
• Interact with databases and APIs

The MCP server exposes sandbox tools:

scalix_sandbox_run — create and execute code in a sandbox

Resource Limits