Skip to content
/
Tier A A9 Sandbox substrate

Arrakis

arrakis · abshkbh/arrakis · ★ 816 · last commit 2025-06-02

Primitive shape 1 total
MCP tools 1
00

Summary

Arrakis — Summary

Arrakis is a self-hosted, fully customizable sandboxing solution for AI agent code execution and computer use, built on cloud-hypervisor microVMs. It ships a REST API server (arrakis-restserver), a Go CLI (arrakis-client), a Python SDK (py-arrakis), and an MCP server (arrakis-mcp-server). Each sandbox runs Ubuntu inside a cloud-hypervisor microVM with a pre-installed code execution service and VNC server (Chrome included for computer use). The defining feature is snapshot-and-restore: agents can checkpoint a sandbox at any state and later backtrack exactly to it, enabling Monte Carlo Tree Search-style workflows and multi-step agent explainability. Port forwarding is automatic — VNC access and any service ports are exposed from the VM to the host without extra setup. Arrakis is Linux-only (requires /dev/kvm) and self-hosted (no managed service). Like all sandbox infrastructure projects in this batch, it sits below the agent loop rather than inside it, making it fundamentally different from the 11 seed frameworks.

01

Overview

Arrakis — Overview

Origin

Arrakis (abshkbh/arrakis) was built by Abhishek (abshkbh) as a self-hosted alternative to E2B/Daytona for AI agent sandbox execution. As of May 2026: 816 stars, 2 contributors, AGPL-3.0 license. Last pushed June 2025.

Philosophy

From the README: "AI agents can generate malicious or buggy code that can attack the host system its run on. Many agents have elaborate multi-step plans to achieve their goals and benefit from the ability to backtrack to intermediate states."

Arrakis's distinctive answer: snapshot-and-restore as a first-class primitive. The README positions this for:

  • Monte Carlo Tree Search (MCTS) based agents that need to explore multiple paths
  • Explainability of elaborate multi-step agent execution flows
  • General checkpointing of agent progress

Key Technical Choices

  • cloud-hypervisor as the VMM (not libkrun/firecracker) — Linux KVM only
  • Ubuntu as the guest OS with code execution service + VNC server at boot
  • overlayfs for rootfs protection per sandbox
  • Automatic port forwarding — VNC and service ports exposed to host without manual configuration
  • REST API as primary interface — daemon running, multiple clients connect to it
  • Self-hosted only — no managed service

Demo

The README links a YouTube demo of Claude coding a live Google Docs clone using Arrakis via MCP, including snapshotting to checkpoint progress. This demonstrates the MCP + computer-use + snapshot workflow.

02

Architecture

Arrakis — Architecture

Distribution

  • Type: Self-hosted binary server + CLI + Python SDK
  • Install: curl -sSL https://raw.githubusercontent.com/abshkbh/arrakis/main/setup/setup.sh | bash (downloads prebuilt binaries to arrakis-prebuilt/)
  • Python SDK: pip install py-arrakis
  • Platform: Linux with /dev/kvm only — no macOS, no Windows

Repo Structure

arrakis/
├── cmd/
│   ├── restserver/     — arrakis-restserver binary
│   └── client/         — arrakis-client CLI (Go)
├── api/
│   ├── server-api.yaml — OpenAPI 3.0 spec for REST API
│   └── chv-api.yaml    — cloud-hypervisor API spec
├── pkg/                — Core Go packages
├── resources/
│   └── scripts/rootfs/ — Dockerfile for sandbox Ubuntu image
├── initramfs/          — Guest init / boot
├── setup/
│   └── setup.sh        — One-click setup script
│   └── gcp-instructions.md
├── docs/               — Architecture diagrams, images
└── Makefile

Components

Component Language Purpose
arrakis-restserver Go REST API daemon; manages VM lifecycle; runs as root
arrakis-client Go CLI CLI interface to restserver
py-arrakis (PyPI) Python SDK for Python applications
arrakis-mcp-server Python (separate repo) MCP server for Claude Desktop, Windsurf, Cursor

VM Technology

  • VMM: cloud-hypervisor (not libkrun/firecracker)
  • Guest OS: Ubuntu (custom image with code execution service + VNC + Chrome pre-installed)
  • Rootfs isolation: overlayfs per sandbox
  • Port forwarding: Automatic, managed by restserver; host ports map to guest ports
  • Networking: TAP devices per VM (tap-<vmname>)

REST API

Full OpenAPI 3.0 spec in api/server-api.yaml. Base URL: http://localhost:8080 (or configured host:port).

Endpoints:

  • GET /v1/health — health check
  • GET /v1/vms — list all VMs
  • POST /v1/vms — start a VM
  • DELETE /v1/vms — destroy all VMs
  • GET /v1/vms/{name} — get VM details
  • DELETE /v1/vms/{name} — destroy specific VM
  • VM snapshot and restore endpoints
03

Components

Arrakis — Components

CLI (arrakis-client)

Command Purpose
arrakis-client start -n <name> Start a new VM sandbox
arrakis-client stop -n <name> Stop a VM
arrakis-client destroy -n <name> Destroy a VM
arrakis-client list -n <name> List specific VM details
arrakis-client list-all List all running VMs
arrakis-client snapshot -n <name> -o <snapshot> Take VM snapshot
arrakis-client restore -n <name> --snapshot <snapshot> Restore from snapshot

Python SDK (py-arrakis)

from py_arrakis import SandboxManager

sandbox_manager = SandboxManager('http://127.0.0.1:7000')

# Start and run commands
with sandbox_manager.start_sandbox('agent-sandbox') as sb:
    sb.run_cmd('echo hello world')

# Snapshot and restore
sandbox = sandbox_manager.start_sandbox('agent-sandbox')
sandbox.run_cmd("echo 'before snapshot' > /tmp/testfile")
snapshot_id = sandbox.snapshot("initial-state")
sandbox.run_cmd("echo 'after snapshot' > /tmp/testfile")
sandbox.destroy()

# Restore to snapshot state
sandbox = sandbox_manager.restore('agent-sandbox', snapshot_id)
result = sandbox.run_cmd("cat /tmp/testfile")
# result["output"] == "before snapshot"

MCP Server (arrakis-mcp-server, separate repo)

Python MCP server for Claude Desktop App, Windsurf, Cursor. Connects to arrakis-restserver. Config:

{
    "mcpServers": {
        "arrakis": {
            "command": "/path/to/uv",
            "args": ["--directory", "/path/to/arrakis-mcp-server", 
                     "run", "arrakis_mcp_server.py"]
        }
    }
}

REST API Server (arrakis-restserver)

Daemon that exposes REST API for VM lifecycle management. Must run as root (cloud-hypervisor KVM access). Manages:

  • VM boot / stop / destroy
  • Port forwarding setup and teardown
  • Snapshot creation and restoration
  • VM metadata and status

Guest VM Features

Every Arrakis sandbox runs Ubuntu with:

  • Code execution service (allows run_cmd() from SDK/API)
  • VNC server (port 5901 forwarded to host port; description: "gui")
  • Chrome pre-installed (for computer use)
  • SSH access (default credentials in resources/scripts/rootfs/Dockerfile)
05

Prompts

Arrakis — Prompts

Arrakis ships no agent prompt files, skills, or hooks in its main repository. It is a self-hosted sandbox execution infrastructure, not an agent behavior framework.

Verbatim: Python SDK Snapshot/Restore Example (README)

# Start a sandbox and write some data to a file.
sandbox_name = 'agent-sandbox'
sandbox = sandbox_manager.start_sandbox(sandbox_name)
sandbox.run_cmd("echo 'test data before snapshot' > /tmp/testfile")
snapshot_id = sandbox.snapshot("initial-state")
sandbox.run_cmd("echo 'test data after snapshot' > /tmp/testfile")

# Destroy the sandbox.
sandbox.destroy()

# Restore the sandbox from the snapshot and verify we have the same data at the time of the snapshot.
sandbox = sandbox_manager.restore(sandbox_name, snapshot_id)
result = sandbox.run_cmd("cat /tmp/testfile")
# result["output"] should be "test data before snapshot".

Technique: Imperative SDK code demonstrating state management. The snapshot/restore pattern is the distinguishing interaction design — not a prompt, but a sandbox control primitive for backtracking.

Verbatim: MCP Server Config (README)

{
    "mcpServers": {
        "arrakis": {
            "command": "/Users/username/.local/bin/uv",
            "args": [
                "--directory",
                "/Users/username/Documents/projects/arrakis-mcp-server",
                "run",
                "arrakis_mcp_server.py"
            ]
        }
    }
}

Technique: MCP server configuration for Claude Desktop / Windsurf / Cursor. The MCP server exposes sandbox operations as tool calls to the connected agent. This is the closest Arrakis gets to agent-layer integration — but the MCP server is in a separate repo (arrakis-mcp-server).

Assessment

Arrakis has zero agent-facing prompt files in the main repo. Its agent integration happens via an external MCP server (separate repo) that exposes sandbox lifecycle as MCP tools. The framework provides execution substrate only.

09

Uniqueness

Arrakis — Uniqueness & Positioning

differs_from_seeds

Arrakis is architecturally orthogonal to all 11 seed frameworks. Seeds operate within the agent loop via skills, hooks, personas, MCP tools, or spec files. Arrakis is a self-hosted microVM sandbox server — it provides isolated execution environments where agent code runs safely, with the distinctive addition of VM-level snapshot-and-restore for state backtracking. The isolation_mechanism field captures the clearest architectural delta: seeds use none/git-worktree; Arrakis uses microvm (cloud-hypervisor/KVM). No seed framework provides VM-level snapshot/restore as a backtracking primitive — the closest conceptual analog is agent-os's TASKS.md update pattern for tracking agent decisions, but that is file-based metadata tracking rather than VM state capture.

Positioning Within This Batch

Arrakis uniquely combines:

  1. MicroVM isolation (cloud-hypervisor, like brood-box/microsandbox but via different VMM)
  2. Snapshot-and-restore (VM-level backtracking — unique in this batch among local options)
  3. Computer use (VNC + Chrome pre-installed — shared with Daytona)
  4. MCP integration (separate arrakis-mcp-server — shared pattern with microsandbox)
  5. Self-hosted REST API (daemon model — unlike the embedded SDK approach of microsandbox)

vs brood-box: Arrakis has snapshot/restore + VNC but no COW workspace diff/review workflow; brood-box has review workflow + MCP proxy but no VM-level snapshot backtracking.

Distinctive Opinion

AI agents executing multi-step plans need a "save state and backtrack" primitive at the VM level — not just at the git/file level — to enable MCTS-style exploration and to safely recover from failed attempts.

Explicit Antipatterns

  • Running agent code without VM isolation (risk to host system)
  • No backtracking support for multi-step agent workflows

Observable Failure Modes

  1. Linux-only: Requires /dev/kvm; no macOS, no Windows
  2. Root required: arrakis-restserver must run as root
  3. AGPL-3.0 license: Copyleft implications for commercial use
  4. Single maintainer: Only 2 contributors; maintenance risk
  5. Last pushed June 2025: Less recent than other projects in this batch
  6. Restore IP constraint: "restore the VM to use the same IP as the original VM" — must stop/destroy original before restoring

Cross-References in This Batch

  • abshkbh/arrakis-mcp-server is the companion MCP server (separate repo)
  • py-arrakis is the companion Python SDK (PyPI)
  • Uses cloud-hypervisor (different VMM than libkrun used by brood-box/microsandbox)
04

Workflow

Arrakis — Workflow

Setup Workflow

# 1. Verify KVM available
stat /dev/kvm

# 2. Download prebuilt binaries
curl -sSL https://raw.githubusercontent.com/abshkbh/arrakis/main/setup/setup.sh | bash
ls arrakis-prebuilt

# 3. Start server (runs as root)
cd arrakis-prebuilt
sudo ./arrakis-restserver

# 4. Use CLI or SDK in separate shell

Basic Sandbox Workflow

# Start VM
./out/arrakis-client start -n foo
# Output: {"codeServerPort":"","ip":"10.20.1.2/24","status":"RUNNING",...}

# SSH into VM
ssh elara@10.20.1.2  # password: elara0000

# Stop and destroy
./out/arrakis-client stop -n foo
./out/arrakis-client destroy -n foo

Snapshot/Restore Workflow (Key Feature)

# Create checkpoint
./out/arrakis-client snapshot -n foo-original -o foo-snapshot

# Destroy original
./out/arrakis-client destroy -n foo-original

# Restore to exact prior state
./out/arrakis-client restore -n foo-original --snapshot foo-snapshot

Python SDK Workflow

sandbox_manager = SandboxManager('http://127.0.0.1:7000')
sandbox = sandbox_manager.start_sandbox('agent-sandbox')

# Do work
sandbox.run_cmd("pip install requests")
snapshot_id = sandbox.snapshot("after-install")

# Try something risky
sandbox.run_cmd("rm -rf /tmp/important")

# Backtrack
sandbox.destroy()
sandbox = sandbox_manager.restore('agent-sandbox', snapshot_id)
# Sandbox is exactly at "after-install" state

Phases

Phase What Happens Artifact
1. Server Start sudo arrakis-restserver starts daemon REST API on :8080
2. VM Start POST /v1/vms or CLI start Running VM with IP + port forwards
3. Agent Work Code execution via SDK, CLI, or direct SSH Command results
4. Snapshot snapshot -n <name> -o <id> Snapshot artifact
5. (Optional) Restore restore backracks to exact snapshot state VM at snapshot state
6. Cleanup destroy VM + resources freed

Approval Gates

None. Fully programmatic; no human-in-the-loop gate.

Constraint on Restore

"Currently, we restore the VM to use the same IP as the original VM. If you plan to restore the VM on the same host then either stop or destroy the original VM before restoring."

06

Memory Context

Arrakis — Memory & Context

State Model

Arrakis's most distinctive memory primitive is snapshot-and-restore at the VM level. Unlike filesystem-level snapshots (git worktrees, COW copies), VM snapshots capture the complete machine state:

  • All filesystem contents (overlayfs)
  • All running processes and their state
  • Network configuration
  • Memory state (processes mid-execution)

Snapshot Mechanics

sandbox.snapshot("checkpoint-id")  →  Serialized VM state on disk
sandbox_manager.restore("sandbox-name", "checkpoint-id")  →  Exact prior state

Any processes running at snapshot time, any files modified, any network connections — all restored to the exact moment of the snapshot.

Filesystem Isolation

Overlayfs protects the base rootfs. Each VM gets its own overlay layer so changes don't affect the base image. Multiple VMs can share the same base image with independent write layers.

VM Lifetime and Daemon

The arrakis-restserver daemon manages all VM lifetimes. All VMs are tied to the lifetime of this daemon — if the server stops, VMs stop. There is no cross-session persistence beyond explicit snapshots.

No LLM Context Management

Arrakis has no mechanism for:

  • LLM prompt/context injection
  • Memory compaction
  • Vector storage
  • Cross-session agent context handoff at the framework level

The LLM's context is entirely the responsibility of the agent application. Arrakis provides execution substrate (including state checkpointing) but not agent context management.

Snapshot Use Cases

  1. Backtracking: Agent tried a risky action → restore to checkpoint
  2. MCTS workflows: Explore multiple branches from the same state → snapshot before each branch, restore between explorations
  3. Long-running agent checkpoints: Periodically snapshot progress so the session can be resumed
  4. Explainability: Replay agent actions from a known checkpoint for debugging
07

Orchestration

Arrakis — Orchestration

Multi-Agent Support

Yes — multiple VMs can be created and managed concurrently via the arrakis-restserver. Each VM is independent. The list-all command shows all running VMs.

Isolation Mechanism

MicroVM (cloud-hypervisor / KVM) — hardware-level isolation. Linux /dev/kvm required. Overlayfs protects the rootfs. Each sandbox is a full Ubuntu VM isolated from the host and from other VMs.

Execution Mode

Background daemon + on-demand VM lifecycle: arrakis-restserver runs persistently; clients connect to it to create/manage VMs. Not a "one shot per invocation" tool — the server is always running.

Orchestration Pattern

None built-in for multi-agent coordination. The application using the SDK or MCP determines how agents collaborate. Arrakis provides isolation primitives.

Multi-Model

No. Model-agnostic.

Consensus Mechanism

None.

Snapshot/Restore as Orchestration Primitive

The most distinctive orchestration capability: snapshot-and-restore enables:

  • MCTS exploration: Create snapshot, explore path A, restore, explore path B
  • Safe parallel exploration: Multiple restores from same snapshot for parallel branches
  • Long-running checkpointing: Periodic snapshots for resumption after failures

MCP Integration

External arrakis-mcp-server (separate repo) exposes sandbox operations as MCP tools to Claude Desktop, Windsurf, Cursor. The server connects to arrakis-restserver and translates MCP tool calls to REST API calls.

Computer Use / VNC

Every Arrakis sandbox boots with a VNC server (port 5901 guest → auto-forwarded to host port). Chrome is pre-installed. This enables computer-use agents (browser control, GUI interaction) without additional setup.

Git Automation

No. Agents inside sandboxes can run git commands; Arrakis itself performs no git operations.

Port Forwarding

Arrakis automatically sets up and manages port forwarding from host to guest VMs. Each sandbox has a port_forwards field in its metadata showing host_port → guest_port mappings with descriptions (e.g., gui for VNC).

08

Ui Cli Surface

Arrakis — UI & CLI Surface

CLI Binary (arrakis-client)

  • Binary name: arrakis-client
  • Language: Go
  • Is thin wrapper: Yes — thin REST API client wrapping arrakis-restserver
  • Subcommands: start, stop, destroy, list, list-all, snapshot, restore

Server Binary (arrakis-restserver)

  • Binary name: arrakis-restserver
  • Must run as: root (requires /dev/kvm access)
  • Port: 8080 (default) or configurable
  • Function: Long-running daemon; all CLI and SDK operations call this REST API

Python SDK (py-arrakis)

  • pip install py-arrakis
  • Context manager support: with sandbox_manager.start_sandbox(...) as sb:
  • Methods: start_sandbox(), run_cmd(), snapshot(), restore(), destroy(), info()

VNC Access (Computer Use)

Each sandbox exposes VNC at guest port 5901. Arrakis auto-forwards to a host port. Access via any VNC client or noVNC:

# Get host port from sandbox info
sandbox.info()
# → port_forwards: [{'host_port': '3000', 'guest_port': '5901', 'description': 'gui'}]

# Use noVNC
./utils/novnc_proxy --vnc <server-ip>:3000

The README includes a screenshot of the Arrakis GUI (VNC view showing Ubuntu desktop with Chrome).

REST API

Full OpenAPI 3.0 spec in api/server-api.yaml. Endpoints for VM lifecycle, snapshot, and restore operations. Base URL: http://localhost:8080.

No Web Dashboard

No web dashboard. Management is via CLI, Python SDK, REST API directly, or MCP server (external repo).

Observability

  • arrakis-client list -n <name>: VM status (IP, status, tap device)
  • arrakis-client list-all: All VMs
  • REST API: /v1/vms/{name} returns full VM metadata
  • SSH into VM for direct inspection

Related frameworks

same archetype · same primary tool · same memory type

Daytona ★ 72k
A9 Sandbox substrate

Provide secure, elastic, sub-90ms sandbox compute infrastructure for running AI-generated code, accessible via multi-language…

CUA ★ 17k
A9 Sandbox substrate

Unified SDK for building, benchmarking, and deploying agents that interact with full OS GUIs via isolated VMs.

E2B ★ 12k
A9 Sandbox substrate

Run AI-generated code safely in cloud-hosted isolated sandboxes via a 3-line SDK integration.

OpenSandbox ★ 11k
A9 Sandbox substrate

Protocol-first general-purpose sandbox platform for AI applications with multi-language SDKs and pluggable isolation backends.

Microsandbox ★ 6.3k
A9 Sandbox substrate

Spawn hardware-isolated microVMs as child processes directly from application code, with no server setup, in under 100ms.

CubeSandbox ★ 5.9k
A9 Sandbox substrate

Sub-60ms KVM microVM sandboxes for AI agents with E2B drop-in compatibility and <5MB memory overhead.