General
agentOS vs Sandbox
Choose between lightweight agentOS VMs, full external sandboxes, or a combined architecture based on isolation, compatibility, and workload needs.
- agentOS is a lightweight VM that runs inside your process. Near-zero cold start, low memory, and direct backend integration via host functions.
- Sandboxes are full Linux environments with root access, system packages, and native binary support.
- You can use both. agentOS works with sandboxes through the external sandbox extension. Agents run in the lightweight VM by default and spin up a full sandbox on demand.
Comparison
| agentOS VM | Full Sandbox | |
|---|---|---|
| Cost | Very low. Runs in your process. | Pay per second of uptime. |
| Startup | Near-zero cold start (~6 ms). | Seconds to spin up. |
| Backend integration | Direct. Host functions call your functions with zero latency. | Indirect. Requires network calls back to your backend. |
| Credentials | Stay on the host. Host functions run your functions server-side; agents see only inputs and outputs. | Must be injected into the sandbox environment. |
| Permissions | Granular, deny-by-default. | Coarse-grained (container-level). |
| Infrastructure | npm install | Vendor account + API keys. |
| Best for | Coding, file manipulation, scripting, API calls, orchestration. | Browsers, desktop automation, native compilation, dev servers. |
When to use each
agentOS VM
Use the lightweight VM for most agent workloads:
- Coding and file editing
- Running scripts and CLI tools
- Calling APIs and services via host functions
- Multi-agent orchestration and workflows
- Tasks where backend integration matters (permissions, tool access, LLM routing)
Full sandbox
Spin up a sandbox when the workload needs a real Linux kernel:
- Browsers and desktop automation (Playwright, Puppeteer, Selenium)
- Heavy compilation and native toolchains
- Dev servers with hot reload, databases, and system ports
- GUI applications and VNC sessions
Both together
Use agentOS with external sandboxes for workflows that need both:
- Agent runs in the agentOS VM with full access to host functions and permissions
- Sandbox spins up on demand for heavy tasks
- Sandbox filesystem is mounted into the VM as a native directory
- Agent reads and writes sandbox files the same way it reads local files