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 compose both. agentOS can mount a full sandbox into the VM through trusted host functions and mounts.
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 | Host functions keep credentials on the host. | Must be injected into the sandbox environment. |
| Permissions | Granular, deny-by-default. | Coarse-grained (container-level). |
| Infrastructure | An npm package in your backend, or hosted VMs. | 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 isolated command and language workloads:
- Coding and file editing
- Running scripts and CLI tools
- Calling APIs and services via host functions
- Durable command workflows
- Tasks where backend integration matters (permissions and tool access)
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 when a workflow needs both:
- Guest code runs in the agentOS VM with access to configured bindings and permissions
- Sandbox spins up on demand for heavy tasks
- Sandbox filesystem is mounted into the VM as a native directory
- Guest code reads and writes sandbox files the same way it reads local files