BoxAgnts Introduction (3) — WebAssembly Sandbox

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.

When an AI Agent possesses file read/write, Shell execution, and network access capabilities, who guarantees it won't do harm? The 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: BoxAgnts' 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. Among numerous sandbox technologies, BoxAgnts chose WebAssembly — a mature technology validated by billions of browsers. | Comparison | Docker Container | VM Virtual Machine | WebAssembly Wasmtime | |---|---|---|---| | Startup Speed | Seconds | Minutes | Milliseconds | | Memory Overhead | ~50MB+ | ~500MB+ | ~1MB | | Isolation Granularity | Process-level | Hardware-level | Instruction-level in-sandbox verification | | Cross-platform | ✅ | ❌ | ✅ | | Near-native Performance | ✅ | ❌ | ✅ Cranelift JIT | | Embeddability | Requires Docker Daemon | Requires Hypervisor | Library-level embedding | WASM'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. BoxAgnts' sandbox configuration is not a simple "on" or "off" — it's an 11-dimensional control panel: pub struct RunOption { pub work dir: Option<String , // Host directory → Guest root directory mapping pub map dirs: Option<Vec< String, String , // Multi-directory mapping pub env vars: Option<Vec< String, Option<String , // Environment variable injection pub allowed outbound hosts: Option<Vec<String , // Outbound network whitelist pub block url: Option<String , // Block specific URLs pub block networks: Option<Vec<String , // Block IP network ranges pub wasm timeout: Option<u32 , // Execution timeout seconds pub wasm max memory size: Option<u32 , // Max memory limit pub wasm max wasm stack: Option<u32 , // Max stack size pub wasm fuel: Option<u32 , // Instruction fuel execution budget pub wasm cache dir: Option<String , // Precompiled cache directory } 1. work dir + map dirs: Filesystem Isolation WASM components have no ability to directly access the host filesystem. All file operations must go through WASI's preopen mechanism — host directories are mapped to the guest's virtual filesystem root. This means: /etc/passwd , C:\Windows\System32 are naturally invisible 2. allowed outbound hosts: Network Access Whitelist This is one of the most critical security controls. It uses wildcard pattern matching: "https:// " → Allow all HTTPS connections "https:// .github.com" → Only allow .github.com subdomains " ://localhost: " → Allow all protocols to localhost on any port Every time a WASM component attempts to make a network connection, socket addr check verifies: pub async fn socket addr check addr: SocketAddr, addr use: SocketAddrUse, allowed outbound hosts: OutboundAllowedHosts, blocked networks: BlockedNetworks, - bool TCP Bind and UDP Bind are directly rejected — components can only initiate outbound connections, not listen on ports. 3. block networks: IP Blacklist In addition to hostname whitelisting, IP network range blacklisting is supported: --block-network 10.0.0.0/8 Block Class A private network --block-network 192.168.0.0/16 Block Class C private network --block-network private Block all private networks block networks uses the ip network crate for precise IP range matching, including special handling for the private keyword — blocking the three RFC 1918 private network ranges: 10.0.0.0/8 , 172.16.0.0/12 , 192.168.0.0/16 . 4. wasm timeout: Hard Execution Time Limit If 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. 5. wasm max memory size + wasm max wasm stack: Hard Memory Limits Prevents 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 instruction returns -1, allowing the component to fail gracefully rather than causing OOM. 6. wasm fuel: Instruction-Level Execution Budget This 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. 7. wasm cache dir: Balancing Performance and Security Precompiled .cwasm file 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. WasmTool in wasm tool.rs is the critical bridge connecting the middle-layer Tool trait with the bottom-layer WASM execution: pub struct WasmTool { name: String, // Tool name "read", "write", "bash"... wasm file: String, // .wasm filename description: String, // AI-readable tool description input schema: Value, // JSON Schema parameter definition } impl Tool for WasmTool { async fn execute &self, input: Value, ctx: &ToolContext - ToolResult { // 1. Convert JSON parameters to CLI arguments let args = value to cli args input ; // 2. Locate WASM file let wasm file = ctx.get app extensions dir .join "tools/" .join &self.wasm file ; // 3. Build RunOption extract security config from ToolContext let mut options = RunOption::default ; options.work dir = Some work dir ; options.allowed outbound hosts = Some ctx.get allowed outbound hosts ; options.wasm cache dir = Some cache dir ; options.block url = ctx.block url.clone ; // 4. Execute via Wasmtime let result = boxagnts wasm sandbox::run::execute wasm file, None, Some args , options, None .await; // 5. Parse stdout/stderr → ToolResult // ... } } BoxAgnts' WASM components adopt a clean, practical interface pattern — JSON stdin/stdout : WASM Component stdin ← JSON parameters e.g., {"file path":"/src/main.rs","limit":50} stdout → JSON result e.g., {"content":"...","is error":false} stderr → Error messages Advantages of this design: echo '{}' | wasmtime run tool.wasm WASM 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: Host Filesystem WASM Guest View ───────────────── ──────────────── /home/user/workspace/ ──map──→ / /home/user/workspace/src ──map──→ /src /tmp/wasm-cache/ ──map──→ /cache /etc/ not mapped Invisible /root/ not mapped Invisible WASM code's fopen "/etc/passwd" call is intercepted by the WASI layer — because /etc/ is not mapped to any host directory, this call fails directly. Every time WASM code attempts to create a network connection, a security check is triggered: // 1. TCP Bind → Directly rejected components shouldn't listen on ports SocketAddrUse::TcpBind = { eprintln "Deny TCP bind: {}", addr ; return false; } // 2. UDP Bind → Directly rejected SocketAddrUse::UdpBind = { return false; } // 3. Outbound connections → Check whitelist + blacklist SocketAddrUse::TcpConnect | UdpConnect = { // Check allowed hosts whitelist // Check blocked networks blacklist // Check private network } When a connection is denied, the system outputs a clear log message: A component tried to make an outbound network connection to disallowed destination 'http://internal-server:8080'. To allow this request, add 'http://internal-server:8080' to the allowed outbound hosts config. Combining the above mechanisms, BoxAgnts' sandbox forms a three-layer defense-in-depth system: Request to Execute Tool │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Layer 1 │ │ Layer 2 │ │ Layer 3 │ │ Resource│ ──────→ │ WASI │ ──────→ │ Network │ │ Limits │ │ Intercept│ │ Control │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ Memory/Stack/Fuel/ Filesystem Path Hostname Whitelist Timeout Hard Limits Virtualized Mapping IP Blacklist The WASM runtime sets hard resource boundaries when loading the module: wasm max memory size wasm max wasm stack wasm timeout wasm fuel These 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. Filesystem access is virtualized through the WASI preopen mechanism. Key protections: ../../etc/passwd are blocked by the WASI layerNetwork access undergoes dual filtering: The two filters are in AND relationship — the target must simultaneously pass the whitelist check and not be blocked by the blacklist. The wasmtime http/ module provides a restricted HTTP client for WASM components: // wasmtime http/src/handler.rs // Intercepts HTTP requests from WASM components // Checks allowed outbound hosts // Checks blocked networks // Forwards legitimate requests to reqwest // Returns responses to WASM components Key design decision: WASM components do not directly use the host OS's network stack. All HTTP requests go through BoxAgnts' proxy layer, ensuring: block url parameter 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: | Skill | Function | Config File | |---|---|---| code-review | Code review and analysis | skills/code-review/SKILL.md | css-refactor-advisor | CSS refactoring advice | skills/css-refactor-advisor/SKILL.md | current-weather | Current weather query | skills/current-weather/SKILL.md | weather-forecast | Weather forecast | skills/weather-forecast/SKILL.md | front-component-generator | Frontend component generation | skills/front-component-generator/SKILL.md | The core of a Skill is a SKILL.md file — a Markdown-formatted description of the skill's specialized prompt. When the SkillTool is invoked: SKILL.md fileThe 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. Two practical examples: 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. 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 whitelist — if the weather API's domain is not in the whitelist, the request will be rejected. The app/extensions/services/ directory contains a pre-installed WASM static file server component. This means you can: Service 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. Many people's first reaction to sandbox technology is "won't it be slow?" BoxAgnts answers this with its actual architecture: Wasmtime 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. compiler.rs supports precompiling .wasm files to .cwasm Compiled WASM and caching them: // compiler.rs // First load .wasm → compile → cache as .cwasm // Subsequent loads → use .cwasm directly → skip compilation This means the first use of a tool incurs a slight compilation overhead milliseconds , but subsequent uses are nearly equivalent to native code startup speed. Data 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. The 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. This design answers the second core question: how to let AI do things without doing harm? The answer is not a simple "sandbox" label, but a comprehensive fine-grained control system: This "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." The 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.