Container2wasm

Checked: 2026-07-14

Summary

container2wasm converts an existing container image into a WebAssembly module that can run under a WASI runtime or in a web browser. It achieves broad Linux compatibility by putting a Linux kernel and CPU emulator inside the WebAssembly module, then starting the original container with runc inside that emulated Linux system.

It is a packaging and compatibility component, not a complete agent sandbox. It creates the runnable artifact; the selected WebAssembly runtime, directory mappings, network helper, and surrounding application determine the real security policy and lifecycle.

Problem it solves

• Existing software: Most Linux programs are not compiled for WebAssembly and may depend on a normal Linux system-call interface.
• Rebuild cost: Recompiling every application and dependency for WebAssembly can require substantial porting work.
• Browser execution: Normal OCI container images cannot run directly inside a browser.
• Runtime portability: One converted module can target several WASI runtimes instead of requiring a native container engine at execution time.

The tradeoff is similar to putting a small computer emulator inside a sealed box: old software fits, but every instruction passes through more layers.

How it works

• Build step: BuildKit runs the conversion recipe and extracts the selected container image.
• CPU emulation: Bochs emulates x86_64, TinyEMU emulates RISC-V, and QEMU Wasm is used for the JavaScript/Emscripten browser path.
• Guest system: A Linux kernel boots on the emulated CPU. runc starts the converted container filesystem and configured entrypoint.
• Other architectures: Non-recommended guest architectures can add another QEMU/binfmt emulation layer.
• Packaging: wasi-vfs or Emscripten packages the emulator, kernel, filesystem, and supporting assets.
• Faster startup: The WASI build uses Wizer to snapshot a pre-booted kernel state.
• Host directories: A WASI runtime can expose selected host paths; the guest receives them through virtio-9p.
• Network helper: Optional c2w-net or browser-side c2w-net-proxy provides a user-space network stack based on gvisor-tap-vsock.

Security role and boundary

• Outer boundary: The WebAssembly/WASI runtime is the main host isolation boundary. It decides which files, sockets, environment data, clocks, and other host capabilities the module can access.
• Guest boundary: Linux and runc provide familiar container behavior inside the emulated machine, but they are nested within the WebAssembly process.
• Default capability model: A module does not automatically receive arbitrary host filesystem access; the operator explicitly maps directories through the runtime.
• Optional network: Basic execution can run without networking. Enabling a host proxy or browser network path adds a new trusted bridge to external systems.
• Converter versus policy: c2w transforms an image. It does not validate that the chosen WASI runtime is securely configured or enforce a standard deny policy.
• Trusted code: The WASI runtime, emulator, Linux kernel, packaging code, network helper, and any mapped-host implementation all sit in the trusted computing chain.
• No agent guardrails: There are no agent command approvals, destination allowlists, credential mediation, source-review workflow, or session manager in the converter.

The project README calls the output “sandboxed WASM,” but safety is only as strong as the runtime permissions and bridges actually enabled.

Platforms

• WASI runtimes: Wasmtime and wazero have the broadest documented support, including mapped directories and networking through a host-side stack.
• Partial runtime support: WAMR, Wasmer, and WasmEdge have incomplete or untested features in the project’s compatibility table.
• Browsers: Browser execution is supported through WASI shims or the Emscripten/QEMU Wasm path. Some networking examples are tested only in Chrome.
• Source containers: x86_64 and RISC-V are recommended. AArch64 is supported, while other architectures may be considerably slower.
• Build host: Released c2w binaries are available; building/converting requires Docker BuildKit or a compatible builder workflow.

Setup

1. Install c2w: Download a release archive or build with Go and make.
2. Provide a builder: Docker 18.09 or newer with BuildKit is the documented baseline; Buildx 0.8 or newer is recommended.
3. Convert: Run c2w <container-image> <output.wasm> and select a target architecture if needed.
4. Choose a runtime: Run the result under a supported WASI runtime, or assemble the browser example.
5. Grant carefully: Add only required directory mappings and networking.
6. Optional network: Use c2w-net --invoke for Wasmtime or configure the browser Fetch/WebSocket path.

The generated WebAssembly includes third-party components under several licenses. Distribution requires checking the converted container and bundled emulator, kernel, bootloader, and utility licenses—not only container2wasm’s Apache-2.0 license.

Network and credentials

• No network mode: The module can run without a network helper.
• WASI network mode: c2w-net can run a gVisor-based user-space stack on the host, connect to a runtime socket, and map host ports to the guest.
• Browser Fetch mode: The browser-side proxy forwards HTTP/HTTPS through Fetch, so browser CORS and other browser rules limit reachable sites.
• Browser delegate mode: A WebSocket connection can delegate packets to c2w-net on a host, which can forward broader traffic.
• No built-in allowlist: The documented helper does not provide Clawk-style destination rules, approval prompts, or denial history.
• Credentials in images: Secrets baked into the source container remain in the converted artifact and should be treated as exposed to anyone who receives it.
• Mapped secrets: Host credentials become reachable if their directory is mapped into the runtime.
• No credential broker: The project does not issue short-lived credentials or bind them to approved destinations.

Strengths

• Runs unmodified Linux software: Existing container filesystems and native binaries can work without a WebAssembly port.
• Browser capability: Full Linux tools, including Python, Node, Vim, and newer LLM examples, can run in browser demonstrations.
• Runtime choice: The WASI output targets several independent WebAssembly runtimes.
• Explicit host paths: Files are shared through runtime mappings rather than inheriting the whole host filesystem.
• Offline option: Workloads can run with no network bridge.
• Open implementation: Conversion, emulators, network helpers, examples, and tests are public under an LF Projects home.
• Active project: Development and releases continued through 2026.

Limits

• Experimental: The README explicitly calls it experimental software.
• Performance cost: Native instructions run through CPU emulation. This is slower and heavier than compiling the application directly to WebAssembly.
• Large artifacts: The output can include a kernel, emulator, container filesystem, and utilities rather than a small application module.
• Layer complexity: Debugging spans the WASI runtime, emulator, kernel, runc, guest program, and optional network proxy.
• Partial compatibility: Several WASI/runtime combinations lack networking or working stdin.
• No lifecycle manager: It does not create named sessions, enforce quotas, idle-stop work, reset state, or export reviewed changes.
• No policy product: Runtime permissions, filesystem scope, networking, and secrets are left to the integrator.
• Browser restrictions: Fetch networking is constrained by browser behavior; delegated WebSocket networking needs an external trusted service.
• Architecture penalty: Architectures outside x86_64 and RISC-V can require an additional emulation layer.

Activity and maturity

As of 2026-07-14:

• Repository: Created 2023-02-15; 2,730 stars and 146 forks when checked.
• Latest release: v0.8.4, published 2026-03-16.
• Recent push: 2026-07-10.
• Latest release focus: Added an in-browser container example using an LLM and reduced a JavaScript runtime dependency.
• Governance: The project states it is a series of LF Projects, LLC.
• Release integrity aid: v0.8.4 publishes binaries and a checksum file, with the checksum file’s SHA-256 stated in the release notes.
• Status: Clearly active and widely noticed, but still pre-1.0 and explicitly experimental.

Best fit

• Good fit: A browser or WASI application must run an existing Linux tool that is impractical to port.
• Good fit: A demonstration, education tool, or offline utility benefits from a full Linux userland inside WebAssembly.
• Possible agent fit: An integrator supplies a hardened WASI runtime, no or narrowly proxied networking, carefully scoped files, fresh state, and safe credential handling.
• Poor fit: A developer wants fast native builds, a lightweight module, or a ready-made secure coding-agent workflow.

Comparison with Clawk

Area	container2wasm	Clawk
Primary role	Convert an OCI container into a WASM-hosted emulated Linux artifact	Run and manage coding agents in isolated VMs
Main boundary	Chosen WASI/WebAssembly runtime	Hardware-backed VM
Compatibility method	CPU-emulated Linux inside WASM	Native guest architecture and Linux tools
Network	Optional proxy; integrator controls exposure	Default-deny destination policy
Credentials	No broker; avoid embedding or mapping secrets	Agent-oriented credential controls
Files	WASI mapdir through virtio-9p	Controlled VM workspace workflow
Lifecycle	Not provided	Session creation, status, stop, and cleanup
Best advantage	Run existing Linux containers in WASI or a browser	Practical full-speed local coding-agent isolation

Practical difference: container2wasm can be one engine inside a sandbox product. It is not the surrounding guardrail system.

Hacker News context

• Indirect reference: In the Clawk thread, comment 48893850 linked HN comment 46825119 and labeled it as container2wasm, a VS Code container-WASM example, and building WASM containers with Dockerfiles.
• Earlier thread: Comment 46825119 discussed container2wasm alongside AgentVM, vscode-container-wasm-gcc-example, Cloudflare workerd, and a linux-wasm alternative.
• Performance comparison: The linked container2wasm issue quoted the argument that compiling an entire Linux userland to WebAssembly can avoid container2wasm’s instruction-set emulation and may be much faster, at the cost of porting and different bugs.
• Meaning for Clawk: The mention was a related-technology pointer, not evidence that container2wasm supplies Clawk-equivalent agent lifecycle, network policy, or credential controls.

Direct sources

• container2wasm repository
• container2wasm v0.8.4
• Networking examples
• Issue 550: linux-wasm comparison
• HN comment discussing container2wasm
• Clawk-thread reference
• Clawk HN discussion

Unknowns

• Independent audit: No independent end-to-end security audit of the converter, bundled guest stack, and network helpers was found.
• Runtime hardening: No maintained secure configuration baseline covering every supported WASI runtime was found.
• Isolation tests: Public material does not establish systematic escape testing across Wasmtime, wazero, browsers, emulators, and mapped filesystems.
• Resource controls: Memory, CPU, output, and process limits depend on the runtime and integrator; one portable policy was not documented.
• Network policy: Fine-grained host or destination filtering would need another component.
• Agent production use: No named production deployment of container2wasm as a hostile coding-agent sandbox was verified.
• Artifact size and speed: Current representative benchmarks against native containers, microVMs, and direct WebAssembly compilation were not found in the main documentation.

Sources

• • imported AI research note for Container2wasm.