Sandboxes

Sandboxes are the core primitive of Akira - isolated execution environments where untrusted code can run safely.

What is a Sandbox?

A sandbox is a lightweight, hardware-isolated micro-VM that provides:

• Full Linux environment - Standard shell, filesystem, networking
• Complete isolation - No access to host system or other sandboxes
• Fast startup - Boot in under a second
• Resource controls - CPU and memory limits

Think of sandboxes as disposable computers. Create them, use them, delete them. Perfect for running untrusted AI-generated code.

Architecture

┌────────────────────────────────────────────────┐
│                  Host System                    │
│  ┌──────────────────────────────────────────┐  │
│  │            Hardware Isolation             │  │
│  │  ┌────────┐ ┌────────┐ ┌────────┐       │  │
│  │  │Sandbox │ │Sandbox │ │Sandbox │  ...  │  │
│  │  │  VM    │ │  VM    │ │  VM    │       │  │
│  │  │        │ │        │ │        │       │  │
│  │  │ Linux  │ │ Linux  │ │ Linux  │       │  │
│  │  │ + Code │ │ + Code │ │ + Code │       │  │
│  │  └────────┘ └────────┘ └────────┘       │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘

Each sandbox runs in its own micro-VM with hardware-level isolation. A compromised sandbox cannot affect:

• The host system
• Other sandboxes
• Your infrastructure

Isolation Model

Hardware Isolation

Sandboxes use hardware virtualization (not containers) for strong isolation:

Network Isolation

By default, sandboxes have:

• Outbound internet access - Can reach external services
• No inbound access - Cannot be reached from outside
• No inter-sandbox access - Sandboxes cannot communicate

Filesystem Isolation

Each sandbox has its own filesystem:

• Root filesystem from the selected image
• Writable overlay for modifications

Sandbox Lifecycle

Create → Running → Execute → Delete
           ↑          ↓
           ├── Snapshot (save state)
           └── Clone (duplicate)

1. Create - Provision VM with image and configuration
2. Running - Sandbox is ready for commands
3. Execute - Run commands, upload/download files
4. Snapshot - (Optional) Save state for later
5. Clone - (Optional) Create an identical copy
6. Delete - Terminate and release resources

Images

Sandboxes boot from images - pre-built filesystem snapshots:

Resource Management

CPU

Sandboxes are allocated CPU cores:

const sandbox = await client.sandboxes.create({
  image: 'akiralabs/akira-default-sandbox',
  resources: {
    cpus: 2,  // 2 CPU cores
  },
});

Memory

Memory is allocated in MB:

const sandbox = await client.sandboxes.create({
  image: 'akiralabs/akira-default-sandbox',
  resources: {
    cpus: 2,
    memory: 4096,
    storage: 20,  // 20 GB storage
  },
});

Best Practices

1. Right-size resources - Don't over-provision CPU/memory
2. Set timeouts - Prevent runaway sandboxes
3. Use snapshots - Save state before important changes
4. Delete promptly - Clean up when work is complete
5. Snapshot important states - Backup before risky operations

Use Cases

• AI Code Execution - Run LLM-generated code safely
• Build Pipelines - Isolated CI/CD environments
• Development - Throwaway dev environments
• Testing - Parallel test execution
• Exploration - Safe environment for experiments

Next Steps

• Create your first sandbox
• Learn about snapshots for persistence
• Understand the security model