Berry Wiki

AgentVM

Properties2
tagsai, sandboxing
aliasesAgentvm

6 min read

AgentVM

Summary

AgentVM is an experimental Node.js library that runs an Alpine Linux virtual machine compiled to WebAssembly. AI applications can use it to execute shell commands without installing a native hypervisor or container service.

Problem

AI agents need a place to run untrusted commands. Native execution exposes the host, while Docker and hardware virtual machines may be unavailable or too heavy for some applications. AgentVM packages a Linux environment as a WebAssembly file that a Node.js application can start in a worker thread.

How It Works

  • Linux in WebAssembly: An Alpine Linux image with Python is converted using container2wasm and shipped as an approximately 173 MB WebAssembly file.

  • Node host: The library starts the emulator in a worker thread, sends shell commands through shared memory, and returns standard output, standard error, and an exit code.

  • Custom network stack: Guest network packets pass through a JavaScript TCP/IP stack. The Node main thread opens the real TCP and UDP sockets.

  • Optional file sharing: Callers map chosen guest paths to host directories. The guest can read and write those mounted directories.

Security Boundary

  • WebAssembly boundary: Guest Linux code runs through WebAssembly and WASI, the system interface connecting WebAssembly programs to host services. It does not run directly as a normal host process.

  • Not hardware isolation: This is an emulated Linux machine inside the Node process, not a separate hardware-backed microVM. Its safety depends on Node, WebAssembly, the custom WASI code, and the emulator.

  • Explicit warning: The maintainers say Node’s WASI implementation has quirks and possible security flaws. They advise against production use.

  • Mounted folders are exposed: Any mapped host directory is readable and writable from the guest. A hostile command can change or remove those files.

  • Host-mediated networking: The guest asks the Node main thread to create real sockets. There is no documented destination allowlist, proxy policy, or content filter.

  • Resource controls unclear: The public API does not document CPU, memory, process, disk, or execution-time limits. A worker thread keeps the main event loop responsive but is not itself a security boundary.

Platforms and Agents

  • Runtime: Node.js 20 or newer. The project does not list operating-system restrictions, so it should work where its Node and WebAssembly requirements work, but the supported platform matrix is undocumented.

  • Guest: Alpine Linux with Python.

  • Agents: AgentVM is a general command-execution library rather than a packaged coding-agent launcher. The repository includes a Vercel AI SDK example and OpenClaw integration material.

  • No built-in agent catalog: Claude Code, Codex, and similar coding agents are not documented as bundled integrations.

Setup

  • Install: npm install deepclause-agentvm.

  • Use: Create an AgentVM, call start(), run commands with exec(), and call stop().

  • Custom image: Build a Linux container image, convert it with container2wasm, and pass the resulting WebAssembly path to AgentVM.

  • Host requirement: Node.js 20 or newer. Rebuilding the image also requires Docker, Go, and container2wasm.

Network and Credentials

  • Network on by default: The network option defaults to true and provides TCP and UDP internet access through network address translation.

  • Broad access: The documented API offers on or off control, not host, port, or protocol rules.

  • DNS: The custom stack provides DHCP and sends DNS through the host-side UDP bridge.

  • Credentials: No secret broker, scoped token forwarding, redaction, or credential policy is documented.

  • Caller responsibility: Applications must decide which environment values, configuration files, or keys enter the guest. Mounting a credential directory gives guest commands access to it.

Strengths

  • Simple embedding: A Node application can start Linux and run commands through a small API.

  • No native daemon: It does not require a running Docker service or platform-specific hypervisor manager.

  • Full Linux behavior: Emulating Linux supports features that are difficult to reproduce with a small WASI-only command environment, including normal Linux programs and process behavior.

  • Useful basics: Python, writable host mounts, captured command results, and TCP/UDP networking cover common agent-tool needs.

  • Open source: The project uses the MIT license.

Limits

  • Experimental: The maintainers explicitly advise against production use and warn that the API may change without notice.

  • Known foundation risk: The README calls out possible security flaws in the underlying Node WASI implementation.

  • Large package: The npm package is about 181 MB unpacked, mostly because it contains the Linux WebAssembly image.

  • No network policy: Internet access is enabled by default and lacks a documented destination allowlist.

  • No documented quotas: Resource and time limits are not part of the public API.

  • Early API: The latest npm version is 0.0.5, with no GitHub releases or tags.

Activity and Maturity

Checked 2026-07-14.

  • Repository age: Created on 2026-01-19.

  • Latest commit: 44ed7efc7b9e6eb19fad4f3e564316889a9402df on 2026-02-05, updating OpenClaw documentation.

  • Package: npm lists deepclause-agentvm version 0.0.5.

  • Community: GitHub showed 74 stars, 3 forks, 29 commits, no open issues, and one open pull request.

  • Release status: No GitHub releases or tags were published. The repository is young and had no commits for roughly five months at the check date.

Best Fit

  • Good fit: Prototypes and experiments that need Linux command execution embedded in a Node application without a native container service.

  • Good fit: Research into WebAssembly-hosted agent tools or environments where containers are unavailable.

  • Poor fit: Production systems, hostile multi-tenant workloads, sensitive repositories, strict network controls, or workloads requiring guaranteed resource limits.

Comparison

  • Versus Clawk: AgentVM is an embeddable command sandbox, while Clawk is a complete local coding-agent workflow. Clawk uses hardware-backed microVMs and filtered networking; AgentVM uses WebAssembly emulation with unrestricted networking by default.

  • Versus SandBoxy: SandBoxy uses Apple’s virtualization stack and a separate guest kernel on Apple silicon. AgentVM is easier to embed across Node environments but has a weaker and explicitly experimental isolation foundation.

  • Versus WASI-only sandboxes: AgentVM carries a full emulated Linux system, giving broader compatibility at the cost of an approximately 173 MB image and more moving parts.

  • Versus Docker: AgentVM needs no daemon and can work where native containers cannot. Docker has a much more mature ecosystem, resource controls, image tooling, and documented security model.

Hacker News Context

In the discussion linked from the Clawk thread, user westurner pointed to AgentVM as a WebAssembly-based Linux option. The author of another WebAssembly sandbox described AgentVM’s full Linux emulation as technically impressive but contrasted its roughly 173 MB image with their roughly 11 MB binary. AgentVM’s author explained that full Linux emulation was chosen after finding that recreating features such as fork directly in WASI would take unreasonable effort.

Direct Sources

Unknowns

  • Security review: No independent audit or formal threat model was found.

  • Platform support: The exact tested combinations of macOS, Linux, Windows, and processor architecture are not documented.

  • Escape resistance: The practical strength of the custom WASI and filesystem-mount protections has not been established.

  • Resource safety: CPU, memory, disk, process, and execution-time enforcement are undocumented.

  • Network isolation: Host access, private-address access, port restrictions, and policy hooks are not explained.

  • Image maintenance: The process and schedule for rebuilding Alpine and Python with security updates are unclear.

  • Agent compatibility: Coding-agent integrations beyond the example material have not been demonstrated in the official documentation.

Sources

    • imported AI research note for Agentvm.

Graph View