By admin 
I burned through half of my E2B sandbox budget in just two weeks by spinning up containers for AI agents that often ran for only eight seconds.
I had been integrating AI coding agents into a few automation scripts on TecMint’s backend. These agents would generate a draft, run a command, check the output, and repeat the process until the task was complete.
Since I didn’t want an AI agent running random shell commands directly on my production server, every task needed its own isolated environment. Like many people, I started with Docker and later switched to a hosted sandbox service when Docker’s startup time became a bottleneck.
Everything worked well at first, but eventually both the cost and the startup delay became hard to ignore. A sandbox that takes 400 to 900 milliseconds to start may not seem slow by itself.
However, when an AI agent creates a new sandbox for every task, retry, or small step, that delay quickly adds up. On top of that, I was paying for a full 1 GiB virtual machine even when it was only being used to run a simple two-line shell command.
That’s when I came across agentOS, an open-source project from the Rivet team.
Before going further, it’s important to understand what agentOS actually is, because its name can be misleading. It is not a command-line tool that you install with a package manager and use like eza or bat.
Instead, it is a Node.js library that lets you run an isolated Linux-like virtual machine directly inside your backend application. It includes WebAssembly-based versions of many familiar GNU utilities, such as coreutils, grep, sed, gawk, findutils, tar, gzip, and more.
That difference is important, so I’ll walk through exactly how I set it up.
What agentOS Actually Does
agentOS is an in-process operating system kernel written in Rust and distributed as an npm package. When you call AgentOs.create() in your Node.js application, it creates a virtual Linux-like environment inside your existing process. This environment includes a virtual filesystem, process table, pipes, PTYs (pseudo terminals), and a virtual network stack.
The important thing is that nothing is started on your host system. It doesn’t create a Docker container, boot a virtual machine, or download a container image.
Everything runs inside your Node.js process, which is why agentOS can start in just a few milliseconds instead of the hundreds of milliseconds that containers often take.
Inside this virtual environment, agentOS runs software packages built as WebAssembly (WASM) binaries. These packages provide Linux commands that behave much like the ones you already use every day.
The project maintains a package registry that includes familiar tools such as coreutils, grep, sed, gawk, findutils, diffutils, tar, gzip, curl, jq, ripgrep, fd, tree, file, yq, zip, and unzip.
By default, these tools run with strict security restrictions. They cannot access your host’s files, network, or processes unless you explicitly allow it. This makes the environment much safer for running AI-generated commands.
On top of the virtual machine, agentOS also includes three built-in coding agents: Pi, Claude Code, and OpenCode. These agents communicate using the Agent Communication Protocol (ACP).
Your Node.js application creates a session, sends a prompt to the agent, and the agent performs its work entirely inside the sandbox. It can read and write files, execute Linux commands using the bundled WASM utilities, and complete coding tasks without directly accessing your host system.
If you want the agent to work with files on your server, you must explicitly mount those directories into the virtual environment.
Prerequisites
Before getting started, make sure you have the following:
- A Linux server running Ubuntu 22.04 or later, Debian 12 or later, or RHEL 9/Rocky Linux 9 or later with terminal access.
- Node.js 18 or newer, along with npm.
- Basic familiarity with JavaScript, since agentOS is used as a Node.js library rather than a standalone command-line tool.
- An Anthropic API key if you plan to use the built-in Pi or Claude Code agents. You can create one from the Anthropic Console. If you only want to experiment with the sandbox and run Linux commands using vm.exec(), you don’t need an API key.
Note: I followed this entire walkthrough on a Rocky Linux 9 VPS with 2 vCPUs and 2 GB of RAM. agentOS used very little memory, which is one of its biggest advantages over running a separate container or virtual machine for every task.
Step 1: Install Node.js
agentOS requires Node.js 18 or later. First, install Node.js and npm using your distribution’s package manager.
On Ubuntu/Debian
sudo apt update sudo apt install -y nodejs npm
On RHEL/Rocky Linux
sudo dnf install -y nodejs npm
After the installation, verify the installed versions:
node -v npm -v
Example output:
v24.18.0 11.16.0
agentOS requires Node.js 18 or newer to support its APIs. If your distribution provides an older version, install a newer release from the NodeSource repository instead of using the default package.
Step 2: Create a Project and Install agentOS
Unlike Docker or other system services, agentOS runs entirely inside a Node.js project. There is no system-wide package to install and no service to start.
Create a new project directory and initialize it with npm:
mkdir ~/agentos-demo cd ~/agentos-demo npm init -y
You should see output similar to:
Wrote to /home/ravi/agentos-demo/package.json:
{
"name": "agentos-demo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs"
}
Next, install the core agentOS library along with the common software package and the Pi coding agent:
npm install @rivet-dev/agentos-core \
@agentos-software/common \
@agentos-software/pi
The installation may take a few minutes, depending on your internet connection. You may also see output similar to the following:
npm WARN deprecated @mariozechner/[email protected]: please use @earendil-works/pi-ai instead going forward npm WARN deprecated @mariozechner/[email protected]: please use @earendil-works/pi-coding-agent instead going forward added 359 packages, and audited 360 packages in 3m 69 packages are looking for funding run `npm fund` for details 8 vulnerabilities (2 low, 5 moderate, 1 high) To address issues that do not require attention, run: npm audit fix Some issues need review and may require choosing a different dependency. Run `npm audit` for details.
Don’t worry if you see deprecation or vulnerability warnings during the installation. These are related to some of the project’s dependencies and are common in many Node.js projects.
The packages are still installed successfully, so you can continue with the next step. If you plan to use agentOS in a production environment, it’s a good idea to review the npm audit report and keep your dependencies up to date.
The three packages you installed each have a different role:
@rivet-dev/agentos-coreprovides the core agentOS engine that creates the virtual filesystem, process table, network stack, and manages agent sessions.@agentos-software/commoninstalls a collection of WebAssembly-based Linux utilities, includingcoreutils,grep,sed,gawk,findutils,diffutils,tar, andgzip.@agentos-software/piinstalls Pi, one of the built-in coding agents available in agentOS, alongside Claude Code and OpenCode.
Step 3: Run Your First Agent Session
If you want to use the built-in Pi agent, you first need to provide your Anthropic API key. The easiest way is to export it as an environment variable in your current terminal session, so you don’t have to hardcode it into your script.
export ANTHROPIC_API_KEY="your-api-key-here"
Now create a file named index.mjs with the following code:
cat > index.mjs << 'EOF' import { AgentOs } from "@rivet-dev/agentos-core"; import common from "@agentos-software/common"; import pi from "@agentos-software/pi"; const vm = await AgentOs.create({ software: [common, pi] }); const { sessionId } = await vm.createSession("pi", { env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }, }); vm.onSessionEvent(sessionId, (event) => {
console.log(event);
});
await vm.prompt(sessionId, "Write a hello world script to /home/agentos/hello.js");
const content = await vm.readFile("/home/agentos/hello.js");
console.log(new TextDecoder().decode(content));
vm.closeSession(sessionId);
await vm.dispose();
EOF
This script performs the following tasks:
- Creates a new agentOS virtual machine.
- Loads the common Linux utilities and the Pi coding agent.
- Starts a new Pi agent session.
- Passes your Anthropic API key to the agent.
- Asks the agent to create a simple Hello World JavaScript program.
- Reads the generated file from the virtual filesystem and prints its contents.
- Closes the session and removes the virtual machine.
Run the script with:
node index.mjs
If everything works correctly, you’ll see output similar to this:
{ type: 'session_start', sessionId: 'sess_8f2a1c' }
{ type: 'agent_message', text: 'Writing hello.js now.' }
{ type: 'tool_call', name: 'write_file', path: '/home/agentos/hello.js' }
{ type: 'session_end', sessionId: 'sess_8f2a1c' }
console.log("Hello, World!");
The last line is the contents of the hello.js file that the agent created. The script reads the file from the virtual filesystem using vm.readFile() and prints it to your terminal.
Notice that the file exists only inside the agentOS virtual environment. It is not written to your server’s real filesystem. Once the script callsvm.dispose(), the virtual machine is destroyed along with everything stored inside it. If you want files to persist, you need to explicitly mount a directory from your host system into the virtual environment.
Tip: Pay attention to how quickly the session starts after running node index.mjs. On my Rocky Linux 9 VPS, the first session_start event appeared in less than 10 milliseconds. That’s one of the biggest advantages of agentOS, it starts almost instantly because there’s no container image to download or virtual machine to boot.
Step 4: Run Linux Commands Without an AI Agent
One of the nice things about agentOS is that you don’t have to use an AI agent. You can use it as a lightweight sandbox for running Linux commands by calling vm.exec() directly.
Create a new file named shell-test.mjs:
cat > shell-test.mjs << 'EOF'
import { AgentOs } from "@rivet-dev/agentos-core";
import common from "@agentos-software/common";
const vm = await AgentOs.create({ software: [common] });
const result = await vm.exec("echo 'tecmint rocks' | grep -i tecmint");
console.log(result);
await vm.dispose();
EOF
Now run the script:
node shell-test.mjs
If the command runs successfully, you’ll see output similar to this:
{
stdout: 'tecmint rocks\n',
stderr: '',
exitCode: 0
}
Here’s what happens behind the scenes:
echo 'tecmint rocks'prints the text inside the virtual environment.- The pipe (
|) sends that output directly to the next command, just as it would in a regular Linux shell. grep -itecmint searches for the word tecmint without considering letter case and returns the matching line.
Although the commands look like normal Linux commands, they are actually WebAssembly versions running inside the agentOS virtual environment. They don’t execute on your host system or interact with your real shell.
I also tested what happens when you try to run a command that isn’t available or forget to load the required software package. Instead of crashing, agentOS returns a structured error with a non-zero exit code. This makes it much easier to detect failures and handle them in your application, especially when the commands are being generated by an AI agent.
Tip: If you only need a secure environment to execute Linux commands, vm.exec() is often all you need. You can add an AI agent later when your application needs to generate or modify commands automatically.
Step 5: Why Fast Startup Times Matter
One of the biggest advantages of agentOS is how quickly it starts a new virtual environment.
According to the benchmarks published by the project, a typical agentOS instance starts in about 5 milliseconds, while a traditional hosted sandbox can take around 440 milliseconds to start. The difference becomes even larger under heavier workloads.
Memory usage is also much lower. A typical coding session in agentOS uses around 130 MB of memory, whereas many hosted sandbox services allocate a 1 GB virtual machine for each session because they have to boot an entire operating system.
For applications that create lots of short-lived agent sessions, these differences can have a significant impact. Faster startup times reduce waiting, and lower memory usage means you can run more agent sessions on the same server.
That said, agentOS is not designed to replace every type of sandbox. If your workload needs to launch a web browser, compile native applications, or run software that isn’t available as a WebAssembly package, you’ll still need a full virtual machine or container.
In those situations, agentOS can work alongside external sandbox providers by connecting to a real sandbox only when it’s actually needed.
Warning: By default, the agentOS virtual environment cannot access your host’s files or network unless you explicitly allow it. However, the Node.js application running agentOS still has whatever permissions you gave it, including access to environment variables such as your Anthropic API key. Always treat your Node.js application as part of your trusted environment and follow standard security practices.
Keeping agentOS Updated
Like most npm packages, agentOS is updated regularly. You can check whether a newer version is available by running:
npm outdated @rivet-dev/agentos-core
Example output:
Package Current Wanted Latest Location @rivet-dev/agentos-core 0.2.5 0.2.7 0.2.7 agentos-demo
If updates are available, install them with:
npm update @rivet-dev/agentos-core \
@agentos-software/common \
@agentos-software/pi
It’s also a good idea to keep an eye on the project’s GitHub releases. New versions of the core library and the software packages are often released independently, so you may see new WebAssembly-based Linux utilities added even when the core package hasn’t changed.
If you’re using agentOS in production, consider pinning package versions in your package.json and testing new releases before deploying them to your servers.
Conclusion
You now have a working agentOS project that creates an isolated Linux-like environment, runs familiar Linux commands using WebAssembly-based tools, and can safely hand that environment to an AI coding agent. Because agentOS runs everything inside a lightweight virtual environment, there’s no need to start a container or virtual machine for every task.
What makes agentOS different is its focus. Instead of replacing traditional sandbox providers, it offers a fast, lightweight environment for running short-lived agent tasks and Linux commands. For many automation workflows, that can mean lower startup times, reduced memory usage, and lower infrastructure costs.
Before adding an AI agent to your application, spend some time using vm.exec() on its own. Try running a few common Linux commands, build simple pipelines, and intentionally execute an invalid command to see how agentOS reports errors. This will help you understand what the built-in WebAssembly tools can do and where their limitations are.
If your application eventually needs features such as running a browser, compiling native code, or executing software outside the available WASM packages, you can always combine agentOS with a traditional sandbox solution for those specific workloads.
As the project continues to evolve, it’s worth experimenting with real-world workloads to see where it fits best in your own automation pipeline. The lightweight design makes it an interesting option for AI-powered Linux automation, especially when fast startup times and efficient resource usage are important.
If this article helped, with someone on your team.