agentOS

Run coding agents inside isolated VMs with full filesystem, process, and network control using RivetKit.

Getting Started

Install dependencies:

bash

pnpm install

Each example has a server and a client. Start the server in one terminal, then run the client in another.

Hello World - Write a file and read it back:

bash

pnpm hello-world:server
# In another terminal:
pnpm hello-world

Git - Clone a repository and check out a branch:

bash

pnpm git:server
# In another terminal:
pnpm git

Filesystem - Directories, stat, move, delete, and mount configuration:

bash

pnpm filesystem:server
# In another terminal:
pnpm filesystem

Processes - Run shell commands and spawn processes:

bash

pnpm processes:server
# In another terminal:
pnpm processes

Network - Start a server inside the VM, fetch from it, and create preview URLs:

bash

pnpm network:server
# In another terminal:
pnpm network

Cron - Schedule and manage recurring jobs:

bash

pnpm cron:server
# In another terminal:
pnpm cron

Tools - Define host toolkits callable from inside the VM:

bash

pnpm tools:server
# In another terminal:
pnpm tools

Agent Session - Create a PI agent session and send prompts (requires ANTHROPIC_API_KEY):

bash

pnpm agent-session:server
# In another terminal:
ANTHROPIC_API_KEY=sk-... pnpm agent-session

Sandbox Mounting - Mount a sandbox into the VM (requires Docker for demonstrating local sandbox):

bash

pnpm sandbox:server
# In another terminal:
pnpm sandbox

Features

Isolated VM execution with filesystem, process, and network APIs
Client-server architecture with type-safe RPC via RivetKit actors
In-VM networking with vmFetch and signed preview URLs for external access
Process spawning and lifecycle management through actor actions
Cron scheduling for recurring commands and agent sessions
Host toolkits that expose JavaScript functions as CLI commands inside the VM
Sandbox mounting for heavy workloads via Docker containers

Prerequisites

ANTHROPIC_API_KEY for the agent-session example
Docker for the sandbox mounting example

Implementation

Each example folder contains a server.ts that configures an agentOS actor and a client.ts that connects to it. The server boots an isolated VM on first use. The client calls actor actions over WebSocket.

src/hello-world/ - Minimal write/read file
src/git/ - Local clone and branch checkout
src/filesystem/ - Full filesystem operations with mount config
src/processes/ - Shell commands and process management
src/network/ - In-VM HTTP server with vmFetch and preview URLs
src/cron/ - Cron job scheduling
src/tools/ - Host toolkits with Zod schemas
src/agent-session/ - PI agent session with prompts
src/sandbox/ - Docker sandbox filesystem and toolkit

Resources

License

MIT