How to give AI agents a persistent cloud workspace for reading files and running commands
Imagine an AI agent that goes beyond text to explore a real file system and execute commands. This repository provides a virtual computer for agents. It stores state in SQLite within a Durable Object and offers an environment to run code in containers or workers as needed.
Three execution modes
File state is stored in the Durable Object's SQLite, supporting three backends. The container backend projects SQLite state into a real FUSE mount, providing a full Linux environment where you can run actual binaries and access the network. The Isolate shell runs just-bash inside a Dynamic Worker and accesses state directly via Workers RPC. The Isolate JavaScript executes ECMAScript modules and supports Node.js APIs like node:fs/promises. You can select one of these to run code via workspace.runtime.exec.
Runnable examples
The repository's examples/ directory contains runnable examples using the public API.
- Container and worker execution Shows how to run
computerdinside a container or execute shell commands and JavaScript modules in a Dynamic Worker without a container. - Agent integration Includes examples of agents using this computer as a tool via the MCP protocol or chat agents utilizing it as a workspace.
- Content generation and distribution Demonstrates specific workflows such as converting Markdown to PDF or generating images with Workers AI to create share links.
Performance benchmarks
The container backend's FUSE mount is faster than real disk for tasks with heavy metadata processing. However, it is slower than real disk for large sequential input/output. docs/19_performance.md summarizes fs-bench figures and comparison results with cloudflare/sandbox-sdk.
Limitations of the preview stage
This package is a preview version for feedback, with an unstable API and design that may change. It is best not to use it in production environments and is suitable for experiments or prototype development. The specifications in docs/ contain forward-looking intentions and may differ from the current code. It is released under the MIT license, and contributions are made through issues and discussions.
