{"slug": "boxagnts-introduction-3-webassembly-sandbox", "title": "BoxAgnts Introduction (3) — WebAssembly Sandbox", "summary": "BoxAgnts has implemented a WebAssembly (WASM) sandbox as the security foundation for its AI agent platform, using Wasmtime from the Bytecode Alliance as the runtime engine. The sandbox provides 11-dimensional control over agent permissions, including filesystem isolation through host-to-guest directory mapping, network access whitelisting with wildcard pattern matching, and IP blacklist support for blocking private network ranges. WASM's instruction-level isolation verifies every memory access during execution, offering millisecond startup times and approximately 1MB memory overhead compared to seconds and 50MB+ for Docker containers.", "body_md": "**When an AI Agent possesses file read/write, Shell execution, and network access capabilities, who guarantees it won't do harm?**\n\nThe severity of this problem should not be underestimated. In traditional architectures, AI tools run directly on the host machine with the same system permissions as the user. This means:\n\nBoxAgnts' answer is in the bottom layer — **the WASM security sandbox**. This is not an optional \"security enhancement,\" but the trust foundation of the entire system.\n\nAmong numerous sandbox technologies, BoxAgnts chose WebAssembly — a mature technology validated by billions of browsers.\n\n| Comparison | Docker Container | VM Virtual Machine | WebAssembly (Wasmtime) |\n|---|---|---|---|\n| Startup Speed | Seconds | Minutes | Milliseconds |\n| Memory Overhead | ~50MB+ | ~500MB+ | ~1MB |\n| Isolation Granularity | Process-level | Hardware-level | Instruction-level (in-sandbox verification) |\n| Cross-platform | ✅ | ❌ | ✅ |\n| Near-native Performance | ✅ | ❌ | ✅ (Cranelift JIT) |\n| Embeddability | Requires Docker Daemon | Requires Hypervisor | Library-level embedding |\n\nWASM's instruction-level isolation means every memory access instruction is verified within sandbox boundaries. This is not a post-hoc check — it's hardware-assisted bounds checking during execution. BoxAgnts chose Wasmtime (from the Bytecode Alliance) as its runtime engine, one of the most mature and performant WASM runtimes available today.\n\nBoxAgnts' sandbox configuration is not a simple \"on\" or \"off\" — it's an 11-dimensional control panel:\n\n```\npub struct RunOption {\n    pub work_dir: Option<String>,              // Host directory → Guest root directory mapping\n    pub map_dirs: Option<Vec<(String, String)>>, // Multi-directory mapping\n    pub env_vars: Option<Vec<(String, Option<String>)>>, // Environment variable injection\n    pub allowed_outbound_hosts: Option<Vec<String>>, // Outbound network whitelist\n    pub block_url: Option<String>,             // Block specific URLs\n    pub block_networks: Option<Vec<String>>,    // Block IP network ranges\n    pub wasm_timeout: Option<u32>,              // Execution timeout (seconds)\n    pub wasm_max_memory_size: Option<u32>,      // Max memory limit\n    pub wasm_max_wasm_stack: Option<u32>,       // Max stack size\n    pub wasm_fuel: Option<u32>,                  // Instruction fuel (execution budget)\n    pub wasm_cache_dir: Option<String>,          // Precompiled cache directory\n}\n```\n\n**1. work_dir + map_dirs: Filesystem Isolation**\n\nWASM components have no ability to directly access the host filesystem. All file operations must go through WASI's `preopen`\n\nmechanism — host directories are mapped to the guest's virtual filesystem root. This means:\n\n`/etc/passwd`\n\n, `C:\\Windows\\System32`\n\n) are naturally invisible**2. allowed_outbound_hosts: Network Access Whitelist**\n\nThis is one of the most critical security controls. It uses wildcard pattern matching:\n\n```\n\"https://*\"         → Allow all HTTPS connections\n\"https://*.github.com\" → Only allow *.github.com subdomains\n\"*://localhost:*\"   → Allow all protocols to localhost on any port\n```\n\nEvery time a WASM component attempts to make a network connection, `socket_addr_check()`\n\nverifies:\n\n```\npub async fn socket_addr_check(\n    addr: SocketAddr,\n    addr_use: SocketAddrUse,\n    allowed_outbound_hosts: OutboundAllowedHosts,\n    blocked_networks: BlockedNetworks,\n) -> bool\n```\n\nTCP Bind and UDP Bind are directly rejected — components can only initiate outbound connections, not listen on ports.\n\n**3. block_networks: IP Blacklist**\n\nIn addition to hostname whitelisting, IP network range blacklisting is supported:\n\n```\n--block-network 10.0.0.0/8       # Block Class A private network\n--block-network 192.168.0.0/16   # Block Class C private network\n--block-network private           # Block all private networks\n```\n\n`block_networks`\n\nuses the `ip_network`\n\ncrate for precise IP range matching, including special handling for the `private`\n\nkeyword — blocking the three RFC 1918 private network ranges: `10.0.0.0/8`\n\n, `172.16.0.0/12`\n\n, `192.168.0.0/16`\n\n.\n\n**4. wasm_timeout: Hard Execution Time Limit**\n\nIf WASM code enters an infinite loop or maliciously consumes CPU, the timeout mechanism forcibly terminates execution after the specified number of seconds. Wasmtime's epoch-based interruption mechanism ensures reliability — not \"waiting\" externally for a timeout, but periodically checking internally within the WASM execution engine.\n\n**5. wasm_max_memory_size + wasm_max_wasm_stack: Hard Memory Limits**\n\nPrevents malicious or buggy WASM components from exhausting host resources through unlimited memory growth. When a linear memory growth request exceeds the limit, the `memory.grow`\n\ninstruction returns -1, allowing the component to fail gracefully rather than causing OOM.\n\n**6. wasm_fuel: Instruction-Level Execution Budget**\n\nThis is a unique WASM security feature — \"fuel metering.\" Each WASM instruction consumes 1 unit of fuel (some control flow instructions consume 0). When fuel runs out, execution terminates immediately. This provides more precise execution control than timeouts, preventing algorithmic complexity attacks.\n\n**7. wasm_cache_dir: Balancing Performance and Security**\n\nPrecompiled `.cwasm`\n\nfile caching avoids recompiling WASM modules on every execution. This is both a performance optimization and a security enhancement — precompiled modules have already passed Wasmtime's validation and don't need re-verification.\n\n`WasmTool`\n\nin `wasm_tool.rs`\n\nis the critical bridge connecting the middle-layer `Tool`\n\ntrait with the bottom-layer WASM execution:\n\n```\npub struct WasmTool {\n    name: String,                 // Tool name (\"read\", \"write\", \"bash\"...)\n    wasm_file: String,            // .wasm filename\n    description: String,          // AI-readable tool description\n    input_schema: Value,          // JSON Schema parameter definition\n}\n\nimpl Tool for WasmTool {\n    async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult {\n        // 1. Convert JSON parameters to CLI arguments\n        let args = value_to_cli_args(input);\n\n        // 2. Locate WASM file\n        let wasm_file = ctx.get_app_extensions_dir()\n            .join(\"tools/\").join(&self.wasm_file);\n\n        // 3. Build RunOption (extract security config from ToolContext)\n        let mut options = RunOption::default();\n        options.work_dir = Some(work_dir);\n        options.allowed_outbound_hosts = Some(ctx.get_allowed_outbound_hosts());\n        options.wasm_cache_dir = Some(cache_dir);\n        options.block_url = ctx.block_url.clone();\n\n        // 4. Execute via Wasmtime\n        let result = boxagnts_wasm_sandbox::run::execute(\n            wasm_file, None, Some(args), options, None\n        ).await;\n\n        // 5. Parse stdout/stderr → ToolResult\n        // ...\n    }\n}\n```\n\nBoxAgnts' WASM components adopt a clean, practical interface pattern — **JSON stdin/stdout**:\n\n```\nWASM Component\n    stdin  ← JSON parameters (e.g., {\"file_path\":\"/src/main.rs\",\"limit\":50})\n    stdout → JSON result (e.g., {\"content\":\"...\",\"is_error\":false})\n    stderr → Error messages\n```\n\nAdvantages of this design:\n\n`echo '{}' | wasmtime run tool.wasm`\n\nWASM itself is only a computation model. For WASM code to access filesystems and networks, WASI (WebAssembly System Interface) is needed. BoxAgnts' sandbox implements controlled system access through WASI:\n\n```\nHost Filesystem                       WASM Guest View\n─────────────────                    ────────────────\n/home/user/workspace/     ──map──→   /\n/home/user/workspace/src  ──map──→   /src\n/tmp/wasm-cache/          ──map──→   /cache\n/etc/                     (not mapped)   Invisible\n/root/                    (not mapped)   Invisible\n```\n\nWASM code's `fopen(\"/etc/passwd\")`\n\ncall is intercepted by the WASI layer — because `/etc/`\n\nis not mapped to any host directory, this call fails directly.\n\nEvery time WASM code attempts to create a network connection, a security check is triggered:\n\n```\n// 1. TCP Bind → Directly rejected (components shouldn't listen on ports)\nSocketAddrUse::TcpBind => {\n    eprintln!(\"Deny TCP bind: {}\", addr);\n    return false;\n}\n\n// 2. UDP Bind → Directly rejected\nSocketAddrUse::UdpBind => { return false; }\n\n// 3. Outbound connections → Check whitelist + blacklist\nSocketAddrUse::TcpConnect | UdpConnect => {\n    // Check allowed_hosts whitelist\n    // Check blocked_networks blacklist\n    // Check private network\n}\n```\n\nWhen a connection is denied, the system outputs a clear log message:\n\n```\nA component tried to make an outbound network connection to\ndisallowed destination 'http://internal-server:8080'.\nTo allow this request, add 'http://internal-server:8080' to\nthe allowed outbound hosts config.\n```\n\nCombining the above mechanisms, BoxAgnts' sandbox forms a three-layer defense-in-depth system:\n\n```\n                        Request to Execute Tool\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        ▼                     ▼                     ▼\n   ┌─────────┐          ┌─────────┐          ┌─────────┐\n   │ Layer 1 │          │ Layer 2 │          │ Layer 3 │\n   │ Resource│  ──────→ │ WASI    │ ──────→ │ Network │\n   │ Limits  │          │ Intercept│         │ Control │\n   │         │          │         │          │         │\n   └─────────┘          └─────────┘          └─────────┘\n        │                     │                    │\n   Memory/Stack/Fuel/    Filesystem Path       Hostname Whitelist\n   Timeout Hard Limits   Virtualized Mapping   IP Blacklist\n```\n\nThe WASM runtime sets hard resource boundaries when loading the module:\n\n`wasm_max_memory_size`\n\n`wasm_max_wasm_stack`\n\n`wasm_timeout`\n\n`wasm_fuel`\n\nThese limits are guaranteed at the Wasmtime engine level — component code cannot bypass them because the limits are encoded into the WASM virtual machine's execution loop.\n\nFilesystem access is virtualized through the WASI preopen mechanism. Key protections:\n\n`../../etc/passwd`\n\n) are blocked by the WASI layerNetwork access undergoes dual filtering:\n\nThe two filters are in AND relationship — the target must simultaneously pass the whitelist check and not be blocked by the blacklist.\n\nThe `wasmtime_http/`\n\nmodule provides a restricted HTTP client for WASM components:\n\n```\n// wasmtime_http/src/handler.rs\n// Intercepts HTTP requests from WASM components\n// Checks allowed_outbound_hosts\n// Checks blocked_networks\n// Forwards legitimate requests to reqwest\n// Returns responses to WASM components\n```\n\nKey design decision: WASM components do not directly use the host OS's network stack. All HTTP requests go through BoxAgnts' proxy layer, ensuring:\n\n`block_url`\n\nparameter)Beyond the 7 WASM tool components, BoxAgnts also supports running specialized AI skills within the sandbox through the Skill system. 5 skills are pre-installed:\n\n| Skill | Function | Config File |\n|---|---|---|\ncode-review |\nCode review and analysis | `skills/code-review/SKILL.md` |\ncss-refactor-advisor |\nCSS refactoring advice | `skills/css-refactor-advisor/SKILL.md` |\ncurrent-weather |\nCurrent weather query | `skills/current-weather/SKILL.md` |\nweather-forecast |\nWeather forecast | `skills/weather-forecast/SKILL.md` |\nfront-component-generator |\nFrontend component generation | `skills/front-component-generator/SKILL.md` |\n\nThe core of a Skill is a `SKILL.md`\n\nfile — a Markdown-formatted description of the skill's specialized prompt. When the SkillTool is invoked:\n\n`SKILL.md`\n\nfileThe cost of creating a new skill is extremely low — write a Markdown description file, no code compilation needed. However, all underlying tools called by the Skill still run within the WASM sandbox, so security is not compromised.\n\nTwo practical examples:\n\n**Code Review Skill**: When the AI analyzes code in the role of \"code review expert,\" it uses the file-read tool to read source code, then provides analysis within the sandbox's permission constraints. The Skill defines the review focus (security, performance, readability), but the underlying file reading is still protected by the sandbox's path mapping.\n\n**Weather Query Skill**: When the AI works in the role of \"weather expert,\" it uses the web-fetch tool to request weather APIs. The Skill defines the query format and output style, but the underlying network requests are still restricted by the `allowed_outbound_hosts`\n\nwhitelist — if the weather API's domain is not in the whitelist, the request will be rejected.\n\nThe `app/extensions/services/`\n\ndirectory contains a pre-installed WASM static file server component. This means you can:\n\nService components share the same sandbox infrastructure as tool components — the same permission controls, network restrictions, and resource boundaries. This ensures that even long-running services cannot cross security boundaries.\n\nMany people's first reaction to sandbox technology is \"won't it be slow?\" BoxAgnts answers this with its actual architecture:\n\nWasmtime uses the Cranelift compiler to compile WASM bytecode into machine code for the target platform. While not at the highest optimization level (that's LLVM's domain), Cranelift's compilation speed is extremely fast, suitable for JIT scenarios.\n\n`compiler.rs`\n\nsupports precompiling `.wasm`\n\nfiles to `.cwasm`\n\n(Compiled WASM) and caching them:\n\n```\n// compiler.rs\n// First load .wasm → compile → cache as .cwasm\n// Subsequent loads → use .cwasm directly → skip compilation\n```\n\nThis means the first use of a tool incurs a slight compilation overhead (milliseconds), but subsequent uses are nearly equivalent to native code startup speed.\n\nData transfer through stdin/stdout between host and WASM uses zero-copy optimization wherever possible. For typical AI Agent workloads (file reads/writes, web requests, command-line output), the sandbox overhead is far lower than the I/O overhead itself — you can barely feel its presence.\n\nThe bottom-layer WASM security sandbox is the trust foundation of BoxAgnts. Through three-layer defense-in-depth (resource limits → WASI filesystem interception → network control), it allows users to confidently grant AI file read/write, command execution, and network access capabilities.\n\nThis design answers the second core question: **how to let AI do things without doing harm?**\n\nThe answer is not a simple \"sandbox\" label, but a comprehensive fine-grained control system:\n\nThis \"security depth\" is what allows BoxAgnts to put \"dangerous tools\" like Bash execution and file editing into the Agent's toolbox — because trust comes not from \"hoping the AI doesn't make mistakes,\" but from \"ensuring mistakes are isolated within the sandbox.\"\n\nThe spirit of this layer's design is worth learning for all AI Agent developers: **security is not the price of capability sacrifice, but the prerequisite for capability expansion.**", "url": "https://wpnews.pro/news/boxagnts-introduction-3-webassembly-sandbox", "canonical_source": "https://dev.to/guyoung/boxagnts-introduction-3-webassembly-sandbox-2o5e", "published_at": "2026-05-27 04:11:24+00:00", "updated_at": "2026-05-27 04:22:38.557306+00:00", "lang": "en", "topics": ["ai-agents", "ai-safety", "ai-infrastructure", "ai-tools", "ai-products"], "entities": ["BoxAgnts", "WebAssembly", "Wasmtime", "Bytecode Alliance", "Cranelift"], "alternates": {"html": "https://wpnews.pro/news/boxagnts-introduction-3-webassembly-sandbox", "markdown": "https://wpnews.pro/news/boxagnts-introduction-3-webassembly-sandbox.md", "text": "https://wpnews.pro/news/boxagnts-introduction-3-webassembly-sandbox.txt", "jsonld": "https://wpnews.pro/news/boxagnts-introduction-3-webassembly-sandbox.jsonld"}}