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 invisible2. 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 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.