BoxAgnts adopts local-first Rust runtime with Wasmtime sandboxing for AI tools

WASM sandboxing provides BoxAgnts with instruction-level security isolation, while the tool registration chain enables zero-configuration auto-discovery. On top of these two foundations, developers only need to focus on one thing: writing programs that follow standard CLI conventions. This article jumps straight into hands-on practice — from a complete base64 encoding tool development process, through compilation, deployment, and testing, to some common pitfalls. Why Base64 as the Example Base64 encoding/decoding is an ideal example tool: the logic is simple enough (won't distract), yet it covers the typical characteristics of an AI Agent tool — multiple input parameters (mode, input source, output target), error handling (invalid base64 strings), file I/O, and strict output format requirements. Understanding base64 tool development means understanding all WASM tool development. The complete example code is located in the BoxAgnts repository at examples/tool-sample-base64-component/. Cargo.toml Configuration [package] name = "tool-sample-base64-component" version = "1.0.0" edition = "2021" [[bin]] name = "base64" path = "src/main.rs" [dependencies] clap = { version = "4", features = ["derive", "string"] } base64 = "0.22" serde_json = "1" The dependencies are minimal: clap handles CLI argument parsing, base64 handles encoding/decoding logic, and serde_json handles structured output. There are no WASM-specific dependencies — Wasmtime provides the runtime environment on the host side; the WASM tool itself doesn't need to know it's running in a sandbox. The WASM compilation target needs to be specified in .cargo/config.toml (or via the command-line --target flag): [build] target = "wasm32-wasip2" Core Code The main function structure (see the repository for the full code): use clap::{Parser, ValueEnum}; use base64::{engine::general_purpose, Engine as _}; use serde_json::json; #[derive(Copy, Clone, Debug, PartialEq, ValueEnum)] enum Mode { Encode, Decode } #[derive(Copy, Clone, Debug, PartialEq, ValueEnum)] enum Alphabet { Standard, UrlSafe } #[derive(Parser, Debug)] #[command(name = "base64")] #[command(version)] #[command(about = "Strict Base64 encode/decode tool")] struct Args { #[arg(long, value_enum, required = true)] mode: Mode, #[arg(long, conflicts_with = "file_path")] input: Option<String>, #[arg(long, conflicts_with = "input")] file_path: Option<String>, #[arg(long)] output_file: Option<String>, #[arg(long, value_enum, default_value = "standard")] alphabet: Alphabet, #[arg(long, default_value_t = false)] no_padding: bool, } fn main() { let args = Args::parse(); if let Err(e) = validate_args(&args) { eprintln!(r#"{{"error":true,"content":"{}"}}"#, e); std::process::exit(1); } let input_bytes = match read_input(&args) { Ok(b) => b, Err(e) => { eprintln!(r#"{{"error":true,"content":"{}"}}"#, e); std::process::exit(1); } }; let engine: &dyn Engine = match (&args.alphabet, args.no_padding) { (Alphabet::Standard, false) => &general_purpose::STANDARD, (Alphabet::Standard, true) => &general_purpose::STANDARD_NO_PAD, (Alphabet::UrlSafe, false) => &general_purpose::URL_SAFE, (Alphabet::UrlSafe, true) => &general_purpose::URL_SAFE_NO_PAD, }; let result = match args.mode { Mode::Encode => engine.encode(&input_bytes), Mode::Decode => { let input_str = std::str::from_utf8(&input_bytes) .unwrap_or_else(|_| ""); match engine.decode(input_str.trim()) { Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(), Err(e) => { eprintln!(r#"{{"error":true,"content":"Invalid base64: {}"}}"#, e); std::process::exit(1); } } } }; if let Some(output_file) = &args.output_file { std::fs::write(output_file, &result).unwrap_or_else(|e| { eprintln!(r#"{{"error":true,"content":"Write failed: {}"}}"#, e); std::process::exit(1); }); println!(r#"{{"error":false,"content":"Written to {}"}}"#, output_file); } else { println!(r#"{{"error":false,"content":"{}"}}"#, result); } } Several implementation details worth noting: JSON output format. WASM tools return JSON objects via stdout, with the convention {"error": bool, "content": "..."}. BoxAgnts' WasmTool::execute() automatically parses this JSON and maps it to ToolResult. If stdout is not valid JSON, the entire text is treated as the content of a successful result. Parameter conflict handling. input and file_path are mutually exclusive — conflicts_with lets clap reject both appearing simultaneously at parse time, rather than deferring the check to business logic. Error output to stderr. When WASM safety failures occur, output should go to stderr, not stdout. BoxAgnts captures both streams separately — stderr content is used for error reporting, stdout for tool results. Compilation and Deployment # Compile cargo build --target wasm32-wasip2 --release # Artifact location ls target/wasm32-wasip2/release/base64.wasm After compilation, copy directly to the extensions directory: cp target/wasm32-wasip2/release/base64.wasm \ app/extensions/tools/base64-component.wasm The filesystem change is captured by the notify event watcher, triggering the hot-reload flow: sandbox execution of --help, output parsing, ToolSpec generation, and global tool table registration. The total latency from file copy to tool availability is typically within 100 milliseconds, with the primary time spent on Wasmtime compiling WASM to .cwasm cache. Cross-Language Development Although the example uses Rust, WASM tools can be written in any language that supports wasm32-wasi. Here's a comparison using Go to write a simple file-read tool: // Go version file-read (compiled with TinyGo) package main import ( "fmt" "os" ) func main() { if len(os.Args) < 2 { fmt.Fprintf(os.Stderr, `{"error":true,"content":"Missing file path"}`) os.Exit(1) } data, err := os.ReadFile(os.Args[1]) if err != nil { fmt.Fprintf(os.Stderr, `{"error":true,"content":"%s"}`, err) os.Exit(1) } fmt.Printf(`{"error":false,"content":"%s"}`, string(data)) } # Compile tinygo build -target wasm-wasi -o file-read.wasm main.go The Go and Rust versions of file-read behave identically — they output the same JSON format, run under the same sandbox constraints, and are called by the same WasmTool::execute(). This is the core value of WASM as a tool distribution format: define a simple output convention, and different language implementations are automatically compatible. Common Issues File I/O Paths The filesystem seen by WASM tools is not the host's complete filesystem. If RunOption.work_dir is set to /home/user/project, then ./src/main.rs inside the WASM tool accesses the host's /home/user/project/src/main.rs. Attempting to access /etc/passwd will fail because it falls outside the mapped directory scope. stdout Buffering Whether WASM stdout is line-buffered or fully buffered depends on the WASI implementation. If a tool writes JSON and exits without explicitly flushing, the final chunk of output may be lost. For single-shot outputs of small JSON this is typically not a problem, but if a tool produces large output (e.g., file-read reading a 100MB file), consider segmenting the output or using a streaming protocol. Encoding Issues println! in the WASI environment outputs UTF-8 by default. If a tool needs to output non-UTF-8 encoded text (e.g., reading a GBK-encoded file), encoding must be handled manually, and the result should be Base64-wrapped in the content field. Testing Tools During development, you can test WASM tools directly using BoxAgnts' CLI, without going through an AI conversation: # Simulate tool registration — view the ToolSpec parsed by the system boxagnts tool:validate path/to/tool.wasm # Simulate tool execution — pass JSON parameters boxagnts tool:execute path/to/tool.wasm '{"mode":"encode","input":"hello"}' This is far faster than testing through AI conversations and lets you directly see Wasmtime-level error messages (if sandbox startup fails). Tools vs. Skills WASM tools are suitable for deterministic computational tasks: encoding/decoding, file operations, database queries, regex matching. But if a task's core isn't "computation" but "guiding the AI's thought process" — such as code reviews, architecture suggestions, writing guidance — it's not a good fit for a WASM tool. These scenarios should use Skills, which are pure Markdown prompt templates loaded by the system and injected into the AI's context; the AI then makes autonomous decisions and executes actions accordingly. Summary BoxAgnts' WASM tool development workflow subtracts complexity — developers don't need to learn any BoxAgnts-specific APIs or configuration formats; they only need to follow two conventions: --help output must contain standard CLI help blocks (Usage:, Options:, Arguments:, or Commands:) for the system to auto-extract the Schema. stdout outputs JSON format {"error": bool, "content": "..."}, with an optional metadata field for passing structured rendering information to the frontend. Beyond these, the tool code is entirely an ordinary CLI program. This is a watershed in developer experience — traditional Agent frameworks require developers to understand the framework's Tool base class, Schema declaration format, and callback registration patterns. BoxAgnts replaces all of these with "just write proper --help output." Cross-language support is another unique advantage. Rust, Go, Python, C — any language that can compile to wasm32-wasi can be used to develop BoxAgnts tools. The compiled .wasm file is placed in the extensions directory, and the hot-reload mechanism automatically handles the remaining registration and caching steps. References BoxAgnts source code: https://github.com/guyoung/boxagnts Base64 tool example: https://github.com/guyoung/boxagnts/tree/main/examples/tool-sample-base64-component Cargo WASM compilation guide: https://rustwasm.github.io/docs/book/ TinyGo WASM compilation: https://tinygo.org/docs/guides/webassembly/ WASI Preview2 component model: https://component-model.bytecodealliance.org/

Tool registration sounds like a lightweight module — scan directories, read files, fill a hash table. But doing it right and doing it reliably requires handling encoding detection, text parsing, race conditions, and startup performance — problems that aren't obvious at first glance. This article traces the complete chain from a .wasm file to an AI-callable tool, breaking down each step. The Problems Registration Must Solve Let's be clear about what this module needs to accomplish. Once a .wasm file is placed in the extensions directory, the system needs to know: What its name is What parameters it has, their types, and whether each is required What permission level it belongs to What its functional description is (for AI model call decisions) What its keywords are (for AI model search) The traditional approach is to have the developer provide a JSON Schema file alongside the .wasm. This approach has synchronization problems: the Schema says a parameter is string but the code treats it as number; the Schema wasn't updated but the tool already gained new parameters; the Schema has errors but the tool registers successfully and then fails forever on execution. Plus, to prepare this Schema, the developer has to additionally understand BoxAgnts' Schema format. BoxAgnts' approach changes the Schema source from "manually written" to "tool self-described" — directly execute the WASM tool, pass --help, and parse the help text it prints. This means tool developers only need to follow standard CLI program conventions, using any language's CLI argument parsing library (Rust's clap, Go's cobra, Python's argparse) to define parameters, and BoxAgnts extracts everything automatically. Encoding Detection The first technical detail comes after reading stdout. A WASM tool's --help output is a byte stream, not a string — you need to detect the encoding before decoding. If you assume UTF-8 blindly, tools encoded in GBK or Shift-JIS will fail to parse. BoxAgnts uses chardetng for encoding detection: // wasm-tools/src/decode.rs pub fn decode_bytes(bytes: Bytes) -> (String, &'static str, bool) { let mut detector = chardetng::EncodingDetector::new( chardetng::Iso2022JpDetection::Allow ); detector.feed(&bytes, true); let encoding = detector.guess(None, chardetng::Utf8Detection::Allow); let (cow, _, had_errors) = encoding.decode(&bytes); (cow.into_owned(), encoding.name(), had_errors) } chardetng is an encoding detection library developed by Mozilla, used by Firefox for automatic webpage encoding detection. It has very high accuracy for short texts (--help output is typically no more than a few KB). Iso2022JpDetection::Allow enables ISO-2022-JP detection for WASM tools from Japanese environments; Utf8Detection::Allow validates UTF-8 integrity to avoid misclassifying random binary data as valid text. After decoding, three items are returned: the string, the encoding name, and whether there were decoding errors. The subsequent parser receives clean UTF-8 text. The Help Text Parser Parsing --help output is not straightforward. Different CLI libraries produce output in different formats: clap's --help and -h differ in detail level (the former includes long_about, the latter only about); some libraries have inconsistent indentation between Options: and Arguments: blocks; subcommands may appear under either Commands: or Subcommands: headings. BoxAgnts' parser, located in wasm-tools/src/registry/parser.rs, follows this flow: 1. Fetch Two Help Texts pub async fn fetch_help_texts(program: &str) -> Result<HelpTextPair> { let short_candidates = vec![vec!["-h"], vec!["--help"]]; let long_candidates = vec![vec!["--help"], vec!["-h"]]; let short_help = run_first_help_candidate(program, &short_candidates).await?; let long_help = run_first_help_candidate(program, &long_candidates).await?; Ok(HelpTextPair { short_help, long_help }) } Why two copies? Because many CLI programs produce different output for -h (short help) and --help (long help). -h may only list parameter names with one-line descriptions, while --help includes more detailed long descriptions (long_about). BoxAgnts merges both: Tool name and version extracted from short help (most compact and reliable format) Long description (long_about), keywords (Keywords:), and permission level (PermissionLevel:) taken preferentially from long help Parameter list (properties) and required items (required) merged from both — long help as primary, short help as supplementary 2. Validate Output Legitimacy Not every WASM program qualifies as a tool. run_first_help_candidate performs legitimacy checks after receiving output: pub fn looks_like_help_output(text: &str) -> bool { let has_usage = text.lines().any(|l| l.trim_start().starts_with("Usage:")); let has_options = text.lines().any(|l| l.trim() == "Options:"); let has_arguments = text.lines().any(|l| l.trim() == "Arguments:"); let has_commands = text.lines().any(|l| { let t = l.trim(); t == "Commands:" || t == "Subcommands:" }); has_usage || has_options || has_arguments || has_commands } The output must contain at least one of Usage:, Options:, Arguments:, or Commands: block headers. If a WASM program's --help output doesn't include these — for example, if it's an HTTP server rather than a CLI tool — the parser rejects registration and logs an error. 3. Field-by-Field Extraction fn parse_help_text(help: &str) -> Result<ParsedHelp> { let lines: Vec<&str> = help.lines().collect(); let (name, version) = parse_name_version(lines[0])?; // First line format: "base64 1.0.0" → name="base64", version="1.0.0" let about = lines.iter().skip(1) .find(|l| !l.trim().is_empty()) .ok_or("missing about line")? .trim().to_string(); let keywords = extract_single_line_field(help, "Keywords:"); let permission_level = extract_single_line_field(help, "PermissionLevel:"); let properties = parse_options_section(&lines)?; // Options: block let (arg_props, arg_required) = parse_arguments_section(&lines)?; // Arguments: block let commands = parse_commands_section(&lines)?; // Commands: block // ... } The core of parameter parsing lies in two functions: parse_options_section: Locate the Options: line; each subsequent line is an option definition (in --mode <MODE> or -m, --mode <MODE> format). Extract parameter name, type (from <TYPE>), and description (free text at end of line). parse_arguments_section: Locate the Arguments: line; positional parameters in <NAME> format, with square brackets indicating optional. Both functions use regex matching. The former's pattern is --([a-zA-Z][a-zA-Z0-9_-]*) with optional <TYPE> angle brackets; the latter matches <([a-zA-Z][a-zA-Z0-9_-]*)> and determines optionality from the presence of [ around it. 4. Merge and Deduplicate merge_required combines the required parameter lists extracted from -h and --help: fn merge_required(short: &[String], long: &[String]) -> Vec<String> { let mut merged = Vec::new(); for item in short.iter().chain(long.iter()) { if !merged.contains(item) { merged.push(item.clone()); } } merged } Similarly, properties from both sources are merged — long help's entries override short help's same-named entries (since long help descriptions are more detailed). The final product is ToolSpec: pub struct ToolSpec { pub name: String, pub wasm_file: String, pub about: String, pub long_about: String, pub keywords: String, pub permission_level: String, pub version: String, pub input_schema: InputSchema, // type: "object" + properties + required pub commands: Vec<CommandSpec>, } Hot Reloading and Concurrency Safety Tool registration isn't a one-time thing. Users may add, overwrite, or delete .wasm files in the extensions directory at any time. BoxAgnts uses the notify crate for filesystem monitoring: let _ = start_watcher(workspace_extensions_dir.join("tools")).await; let _ = start_watcher(app_extensions_dir.join("tools")).await; start_watcher internally creates a tokio task that loops, receiving filesystem events. The handling logic for arriving events looks like this: notify::Event::Create(path) | Event::Modify(path) │ path ends with .wasm? ├── Yes → execute wasm-sandbox::run::execute(path, ["--help"]) → parse → update HashMap └── No → ignore notify::Event::Remove(path) │ path ends with .wasm? ├── Yes → HashMap.remove(tool_name) └── No → ignore The HashMap itself is protected by tokio::sync::RwLock: static WASM_TOOLS: Lazy<RwLock<HashMap<String, ToolSpec>>> = Lazy::new(|| RwLock::new(HashMap::new())); RwLock allows multiple concurrent reads (tool invocations) and one exclusive write (hot-reload updates). Since tool list update frequency is very low (writes are almost exclusively triggered by manual user operations), read-write lock contention costs are negligible. An edge case: what happens if, while the file watcher is parsing a new tool, an AI conversation happens to request the tool list? The answer is that no special handling is needed — all_tools() holds an RwLock read lock, the parser needs a write lock, and the write lock waits for the read lock to release. From the user's perspective, the delay is imperceptible — all_tools()'s read lock hold time is merely the duration of one HashMap traversal (microsecond scale), causing no noticeable blocking. Compilation Caching There's an implicit performance optimization during registration. The first time a .wasm file is encountered, parse_wasm_tool() not only executes it in the sandbox to capture --help output, but also triggers Wasmtime precompilation: // compiler.rs pub fn process(wasm_file: &str, cache_dir: &str) -> Result<PathBuf> { let cache_file = dir.join(cache_file_name); if cache_file.exists() { return Ok(cache_file); // cache hit } // Wasmtime CodeBuilder compilation, outputs .cwasm let output_bytes = code.compile_component_serialized()?; std::fs::write(&cache_file, output_bytes)?; Ok(cache_file) } .cwasm is Wasmtime's precompiled format (compiled WebAssembly). Subsequent actual tool invocations load it directly, skipping the parsing and compilation phases. For larger WASM tools (e.g., sqlite-component.wasm, which includes a SQLite engine and can produce .cwasm files several MB in size), this cache can compress the first tool invocation latency from hundreds of milliseconds down to a few milliseconds. The cache key is based on a hash of the WASM file's content, not the filename. This means updating .wasm file content automatically triggers recompilation — no stale cache issues. Tool Search As the registry grows, the AI model needs a way to discover the tools it needs — you can't shove every tool's Schema into the system Prompt (token costs are too high). ToolSearchTool provides keyword-based retrieval: struct ToolEntry { name: String, description: String, keywords: Vec<String>, } Search supports exact lookup ("select:ToolName") and fuzzy matching (relevance scoring by name and keywords). The scoring algorithm is straightforward: exact name match has the highest weight, keyword inclusion next, description inclusion lowest. This is sufficient for scenarios with dozens to hundreds of tools. If larger-scale support is needed (thousands of tools), vector search can be substituted — the interface remains unchanged, only the scoring implementation changes. Differences from Peer Approaches Many Agent frameworks require pre-registering all tools (in Python code: tool = Tool(name=..., func=..., description=...)). BoxAgnts' model eliminates this step. An additional benefit is that the deployment workflow is simplified to the extreme: developer writes and compiles the tool → scp to the server's extensions directory → done. No configuration file modifications, no service restarts, no API registration calls. This design is especially friendly for CI/CD scenarios — you can put the tool compilation step in GitHub Actions, with build artifacts automatically deployed to the server running BoxAgnts. The moment deployment completes, the AI can call the new tool. Summary BoxAgnts' tool registration mechanism solves the core problem of Schema-code inconsistency inherent in traditional approaches through three components: Encoding detection (chardetng) eliminates the parser's hardcoded UTF-8 assumption, enabling correct registration of WASM tools produced in any language environment. Dual help text merging (-h and --help) compensates for differences in output detail across CLI libraries. -h provides reliable name/version, --help provides detailed long_about and parameter descriptions; merging both yields the complete ToolSpec. Content-based compilation caching precompiles WASM tools to .cwasm at registration time; subsequent calls skip the compilation phase, reducing latency from hundreds of milliseconds to single-digit milliseconds. The cache key is a content hash, not the filename, so updating tool content automatically triggers recompilation. The hot-reload RwLock design finds an appropriate balance between concurrency safety (many reads, single write) and implementation complexity. The complete chain of notify event monitoring → HashMap update → compilation caching forms the technical foundation of BoxAgnts' "zero-configuration deployment" — after a developer copies a .wasm file to the extensions directory, the system automatically completes all steps from registration to availability. References BoxAgnts source code: https://github.com/guyoung/boxagnts chardetng encoding detection library: https://github.com/hsivonen/chardetng notify (Rust filesystem watcher): https://github.com/notify-rs/notify Wasmtime precompilation cache documentation: https://docs.wasmtime.dev/cli-cache.html clap (Rust CLI argument parser): https://github.com/clap-rs/clap cobra (Go CLI argument parser): https://github.com/spf13/cobra

The core rationale behind BoxAgnts choosing WebAssembly sandboxing: "capability-based injection" rather than "permission reduction." What exactly does the Wasmtime sandbox isolate? Where are the boundaries of each layer of defense? And why are typical attack vectors ineffective against this model? Why Traditional Sandboxes Are Patchwork Take Docker as an example. Its security model relies on Linux namespaces (UTS, PID, mount, network, IPC, user, cgroup) combined with seccomp profiles. This combination works reasonably well at the application level, but for AI Agent tool scenarios, several problems emerge. The first problem is the inherent flaw of syscall blacklists. seccomp's default behavior is "allow all syscalls, only block the specified list." Docker disables approximately 44 syscalls by default (reboot, kexec_load, add_key, etc.). If a newly discovered dangerous call isn't on the list, the protection is non-existent. More critically, AI model-driven tool invocation behavior is unpredictable — a human developer wouldn't write code that calls ptrace on other processes, but a bash command generated on the fly by an AI might accidentally trigger an unblocked syscall. The second problem is the shared kernel attack surface. Namespaces provide view isolation (PID 1 inside the container is not the host's PID 1), but all containers share the same kernel instance. If a WASM tool triggers a kernel vulnerability through some path (e.g., an eBPF-related CVE), the escape risk propagates to the host level. The WASM sandbox differs here structurally. A WASM program doesn't run on the host CPU — it runs on a virtual instruction set layer generated by Wasmtime's interpreter/JIT. It doesn't know what the x86 syscall instruction is, and it can't access the host's memory pages. Its "operating system" is the WASI interface — a function table explicitly injected by the host program. // wasm-sandbox/src/run.rs - WASI capability injection run_common.common.wasi.cli = Some(true); // allow command-line arguments run_common.common.wasi.http = Some(true); // allow HTTP outbound run_common.common.wasi.inherit_network = Some(true); run_common.common.wasi.allow_ip_name_lookup = Some(true); run_common.common.wasi.tcp = Some(true); run_common.common.wasi.udp = Some(true); Every Some(true) is an explicit authorization decision. Unauthorized WASI interfaces are completely invisible to the Guest — not "can't call," but "calling target doesn't exist." This is the core of the capability-based injection model. Filesystem Isolation: Preopen Directory Handles Traditional path-based whitelist approaches face symbolic link attacks and TOCTOU (time-of-check-time-of-use) problems. WASM's filesystem isolation takes a different path: preopen directory handles. // wasm-sandbox/src/run.rs let mut dirs: Vec<(String, String)> = Vec::new(); if let Some(dir) = option.work_dir { dirs.push((dir, "/".to_string())); // host directory → Guest root } if let Some(map_dirs) = option.map_dirs { for (k, v) in map_dirs { dirs.push((k, v)); // custom mapping } } The principle works like this: during component initialization, Wasmtime passes the host directory into WASI through the preopen_dir interface. What's passed is a file descriptor (fd), not a path string. The Guest's / is the virtual root of this fd. Regardless of how the Guest internally performs cd, open, readdir, it always uses the fd provided by Wasmtime, and this fd's visibility scope was fixed at creation time by openat + O_NOFOLLOW. This means symbolic link attacks are ineffective within the Guest — the WASM Guest never even received the directory fd containing the symlink target, and the kernel's path resolution is cut off on the host side. TOCTOU is handled similarly. Preopen occurs at WASM component initialization; once the fd is created, subsequent directory permission changes don't affect the already-opened fd. Attackers cannot expand the Guest's visible scope at runtime by replacing directory contents. Network ACL: Dual-Channel Validation BoxAgnts adopted its network control design from the Spin Framework, implementing a whitelist + blacklist dual-channel validation system. The whitelist (OutboundAllowedHosts) defines which domains WASM tools can connect to: // Format examples "https://api.github.com" // exact match "https://*.example.com" // subdomain wildcard "http://localhost:*" // any port "*://*.github.net" // any protocol + subdomain The blacklist (BlockedNetworks) blocks specific IP ranges and internal network access: // block 1.1.1.1/32 (single IP) // "private" keyword blocks all RFC 1918 addresses + loopback Every time a WASM program initiates a connection through the network interface, a two-step check is triggered: wasmtime_wasi::socket_addr_check(addr, addr_use, hosts, networks) │ ├── Step 1: BlockedNetworks::is_blocked(ip) │ - Hit IP blacklist? (IpNetworkTable longest-prefix match) │ - block_private mode: reject all non-global-routing addresses │ - Special handling: IPv4-mapped IPv6 addresses (::ffff:x.x.x.x) reduced to IPv4 before check │ └── Step 2: OutboundAllowedHosts::check_url(url, scheme) - Parse URL host portion - Match against whitelist entries (supports * wildcards and template variables) There's a noteworthy implementation detail here. The IPv6 protocol defines the IPv4-mapped address format (::ffff:10.0.0.1). If the blacklist only checks the IPv4 format, an attacker could use http://[::ffff:10.0.0.1] to bypass a 10.0.0.0/8 blacklist rule. BoxAgnts' BlockedNetworks::is_blocked() explicitly handles this case: // blocked_networks.rs if let IpAddr::V6(ipv6) = ip_addr { if let Some(ipv4_compat) = ipv6.to_ipv4() { return self.is_blocked(&IpAddr::V4(ipv4_compat)); } } Similarly, SocketAddrUse::TcpBind and UdpBind are directly rejected — WASM tools cannot listen on ports or run as servers. Instruction-Level Resource Control: wasm_fuel CPU time limits are typically implemented using timeouts. But timeouts have a granularity problem: if a WASM program executes 1 billion instructions in 1 second, pegs a CPU core, and then blocks before being killed by the timeout — that 1 second of CPU consumption is already a fait accompli. In dense multi-tool concurrency scenarios, this is enough to impact host responsiveness. Wasmtime provides a finer-grained solution: Fuel Metering. // run.rs pub wasm_fuel: Option<u32>, // initial fuel allocation Each WASM instruction consumes 1 unit of fuel when executed (nop, drop, block, loop, and other control flow instructions consume 0). When fuel is exhausted, Wasmtime generates a trap; the host catches it, terminates the component, and reclaims all resources. This mechanism relies on Wasmtime's Store::set_fuel() and Store::consume_fuel() APIs under the hood. Wasmtime checks remaining fuel at the entry of each basic block rather than per-instruction — a performance compromise (per-instruction checking is too expensive), but for WASM programs with substantial code, each basic block typically contains at most a few dozen instructions, so the precision loss is acceptable. Combined with wasm_timeout, wasm_max_memory_size, and wasm_max_wasm_stack, BoxAgnts forms a complete two-dimensional (time + space) resource constraint matrix for WASM tools: Constraint Dimension Parameter Violation Behavior CPU Time wasm_timeout Timeout → kill component CPU Instructions wasm_fuel Fuel exhausted → trap Heap Memory wasm_max_memory_size memory.grow failure → OOM trap Stack Memory wasm_max_wasm_stack Stack overflow → trap These constraints take effect at the Wasmtime Engine level. WASM programs cannot bypass them through any code path — this isn't the sandbox "intercepting," it's the sandbox's core semantics making over-limit operations impossible in the first place. The PermissionLevel Classification System Sandboxing ensures security isolation, but another problem remains: users need to set different trust levels for different tools. Giving a web search tool the same permissions as Bash is unreasonable. BoxAgnts defines a four-level permission classification: pub enum PermissionLevel { None, // pure information query, no side effects ReadOnly, // read-only operations Write, // write operations Execute, // command execution } Permission enforcement happens before tool execution. After run_query_loop() detects a ToolUse request and before calling tool.execute(), it performs a permission cross-check: // Pseudocode; actual implementation in gateway/api/tool.rs match (tool.permission_level(), ctx.permission_mode) { (_, PermissionMode::Full) => Ok(()), // full permission mode, no restrictions (None | ReadOnly, PermissionMode::ReadOnly) => Ok(()), (Write | Execute, PermissionMode::ReadOnly) => Err("insufficient permission"), } Users can configure different PermissionMode settings for different Agents through the Dashboard. For example, create a code-review-only Agent set to ReadOnly — even if it calls the Bash tool, the system will reject it before execution. Why This Model Beats AppArmor/seccomp for AI Agents Let's review the overall structure. The security sequence for traditional approaches is: Tool code loaded → Execute → Syscall → seccomp check → Allow/Deny ↑ Risk has already occurred before this point BoxAgnts' security sequence is: WASM component loaded → Capability injection (file fd, network whitelist, resource limits) → Execute ↑ All permissions determined before execution, non-extensible The difference lies in the "timing of security boundary establishment." In traditional approaches, there's a natural time gap between execution and permission checking — this gap is the attack surface. In the WASM approach, the execution environment is fully constrained before code ever gains control; the Guest has no means to extend its own permission boundary. This isn't to say the WASM sandbox is naturally immune to all security issues. Wasmtime itself may have security vulnerabilities (see wasmtime-related entries in the RustSec advisory database), and compiler infrastructure errors could lead to Guest escape. But for AI Agent tool use cases — primarily file operations, network access, database queries — the WASM sandbox's security boundary far exceeds the necessary level. This also explains why BoxAgnts' built-in bash tool doesn't need an additional WASM sandbox layer. The bash tool itself is WASM-compiled — it doesn't invoke the host shell; it's a complete shell implementation compiled to wasm32-wasi, running inside the sandbox. All the isolation mechanisms described above apply to it equally. Summary Wasmtime sandboxing provides BoxAgnts with three capabilities that traditional approaches cannot simultaneously satisfy: Instruction-level isolation. WASM programs run on a virtual instruction set, with no direct access to host CPU, memory, or syscall interfaces. The security boundary isn't "filtered syscalls" — it's "no syscall invocation path exists." Capability-based resource control. Filesystem (preopen fd), network (whitelist + blacklist dual-channel), CPU (wasm_fuel + timeout), memory (max_memory_size + max_wasm_stack) — all resources are precisely constrained before component launch and cannot be extended at runtime. Microsecond-level sandbox startup. Unlike Docker's second-level cold starts and hundreds-of-millisecond warm starts, WASM component loading and initialization overhead is in the microsecond range. This speed difference is critical for high-frequency tool invocation in Agent conversations — when the AI repeatedly calls tools in a loop for parameter exploration, sandbox startup latency directly determines user experience. The IPv4-mapped IPv6 anti-bypass handling and four-level PermissionLevel classification further harden the security boundary: the former closes IP whitelist/blacklist vulnerabilities, and the latter lets users authorize different tool sets to different Agents based on trust levels. References BoxAgnts source code: https://github.com/guyoung/boxagnts Wasmtime documentation: https://docs.wasmtime.dev/ WASI Preview2 specification: https://github.com/WebAssembly/wasi-cli Spin Framework network ACL: https://github.com/fermyon/spin Claude Code sandbox design: https://claude.com/blog/beyond-permission-prompts-making-claude-code-more-secure-and-autonomous Docker seccomp security configuration: https://docs.docker.com/engine/security/seccomp/ RustSec Advisory Database: https://rustsec.org/

The AI Agent framework landscape has reached a state one could fairly describe as oversaturated. The Python ecosystem has LangChain, CrewAI, and AutoGen; TypeScript offers the Vercel AI SDK; Go has langchaingo. Yet every one of these frameworks shares the same predicament: they define tools as trusted code running in an untrusted environment, then patch the gaps with sandboxes after the fact. BoxAgnts takes the opposite approach. It chooses a harder path: building the isolation boundary at the runtime level from the start, using a WebAssembly sandbox to enforce security constraints before tool execution begins, rather than intercepting syscalls after the fact. The entire system is implemented in Rust from the ground up — 12 crates, a zero-external-dependency Agent runtime, and a streaming query engine that directly interfaces with 12 AI model providers. The "Impossible Triangle" of Tool Systems LangChain-style tool systems rest on a deep-seated assumption: tool code and the Agent runtime run in the same process. Python's exec(), subprocess.run(), Node's child_process.spawn() — all share the characteristic of performing permission checks at the moment of tool execution, and doing so in a "retrospective" fashion (intercepting known-dangerous syscalls, blocking specific file paths, etc.). This model has a structural problem. Every time a new "dangerous operation" category emerges, another rule must be added to the security interceptor — an arms race with no end. rm -rf / gets blocked, so the attacker tries dd if=/dev/zero of=/dev/sda. That gets blocked too, so they try a fork bomb. You can block every known dangerous pattern, but the attack surface remains the operating system's entire syscall table. A more subtle problem is tool composition. file-read is read-only in isolation; web-fetch is also read-only. But if the AI first uses file-read to exfiltrate ~/.ssh/id_rsa, then uses web-fetch to POST it to an external server, no single-point check catches this cross-tool data leak. BoxAgnts' response to this problem: don't let tools see the host operating system. This is the fundamental difference between a WASM sandbox and a traditional sandbox. Traditional sandboxes (seccomp, AppArmor, Docker seccomp profiles) "shrink permissions" at the OS level. The WASM sandbox operates at the runtime level where permissions don't exist in the first place. A WASM program doesn't even know what open() is by default — it can only access directory handles explicitly injected by the host through WASI interfaces. I call this design "Capability-based" vs "Permission-reduction". The latter's security boundary is: everything you can do, minus what I forbid. The former's security boundary is: only what I explicitly allow — everything else does not exist. This means we can achieve strong security guarantees at a relatively low engineering cost. Now let's examine the architecture. Layered Design of 12 Crates BoxAgnts' Rust side consists of 12 crates organized into five layers from bottom to top: Layer 1: Runtime (wasm-sandbox + wasm-tools) wasm-sandbox wraps Wasmtime's component runtime and exposes a unified execute() interface upward. WASM tools are compiled to the wasm32-wasip2 target and loaded as WASI components. On each invocation, the host maps a working directory as the Guest's root filesystem, injects the allowed outbound domain list into the network layer, sets execution time limits and memory caps — and only then launches the component. wasm-tools handles tool metadata extraction. It doesn't take the "configuration file" route — instead, it directly executes the WASM tool, captures its --help output, and uses regex to parse the parameter list, types, and descriptions. This self-describing parsing mechanism is the foundation of BoxAgnts' "zero-configuration" registration, covered in detail in the tool registration documentation. Layer 2: Core Abstractions (tools + tools-manager + core) core defines the shared data types used across the entire system: Message, ContentBlock, ToolDefinition, UsageInfo. It's thin — just a few hundred lines — but its correctness directly affects all upper-layer modules. tools defines the Tool trait — the "universal language" of the entire tool system. All tools, regardless of whether they originate as Rust built-ins or WASM extensions, must implement the following methods: pub trait Tool: Send + Sync { fn name(&self) -> &'static str; fn description(&self) -> &'static str; fn source(&self) -> ToolSource; fn permission_level(&self) -> PermissionLevel; fn input_schema(&self) -> Value; async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult; } tools-manager is the tool registration and discovery center. It maintains a global tool table, watches for file changes in extension directories, and supports hot-reloading. Layer 3: API Gateway (api + gateway) api encapsulates the integration logic for all major AI models. A single LlmProvider trait unifies 12 interfaces including Anthropic Messages API, OpenAI Chat Completions, Google Gemini, Cohere, and MiniMax, using the Transformer pattern for bidirectional message format conversion. gateway provides business orchestration: session management, tool list construction, model selection, permission filtering, Cron job scheduling, and static site deployment. Layer 4: Agent Loop (query) query is the Agent's "heartbeat" — the run_query_loop() function implements the complete tool invocation cycle: Send message history and system Prompt to the AI model Parse SSE stream events, detect ToolUse requests Look up the corresponding tool instance in the tool table, perform permission checks Call tool.execute(), capture the result Inject the result into message history, return to step 1 Continue until the model returns end_turn, context is exhausted, the user cancels, or the cost limit is exceeded Layer 5: Web Service (server) The top layer is an Axum-based HTTP/WebSocket server providing REST APIs and real-time WebSocket chat channels. The frontend is a Vue 3 + Vuetify 3 Dashboard, with Pinia for state management and CodeMirror 6 for the code editor. A key characteristic of this architecture: every layer has clear responsibility boundaries with no implicit cross-layer dependencies. query doesn't know whether a tool is a Rust built-in or a WASM sandbox; gateway doesn't know whether the AI model is from Anthropic or OpenAI; tools-manager doesn't know in what kind of AI conversation a tool will be invoked. Three Key Design Decisions 1. WASM Instead of Containers Many ask why not just use Docker. The answer lies in startup cost and isolation granularity. Launching a WASM component takes microseconds — it's essentially a precompiled binary loaded into memory and executed by Wasmtime. Launching a Docker container takes seconds; even a warm start takes hundreds of milliseconds. Tool invocations in an Agent conversation can happen multiple times per turn with fast returns; Docker's startup overhead is unacceptable in this scenario. In terms of isolation granularity, WASM provides finer-grained control than containers. A container's security boundary is Linux namespaces and cgroups — filesystem, network, processes. WASM's security boundary can be per-function invocation and per-memory-access. Resource control at the "instruction burning" level, like wasm_fuel, is something containers cannot achieve. 2. Rust Instead of Python/TypeScript Rust's ecosystem richness doesn't match Python's, but given that BoxAgnts needs deep integration between a "high-performance WASM runtime" and a "secure Agent runtime," Rust's zero-cost abstractions, ownership system, and native Wasmtime support are decisive factors. A concrete example is cross-task ToolContext passing. In Python/TypeScript, you typically need locks or deep copies to protect shared state, and all of this protection is runtime-based. In Rust, Arc<AtomicUsize>, Arc<CostTracker> — the safety of these shared states is verified at compile time. The &ToolContext in the execute() method signature guarantees that a tool cannot modify shared context — this guarantee comes from the borrow checker, not from runtime checks. 3. Self-Describing Registration Instead of Explicit Configuration Most tool systems require developers to declare tool schemas in code or configuration files. This leads to two problems: first, declarations may be inconsistent with actual behavior (the schema says a parameter type is string but the code treats it as number); second, the development flow is interrupted — after writing the code, you have to write another schema. BoxAgnts' approach is to directly execute the tool's --help, parse its output, and automatically generate the schema. As long as the tool follows standard CLI conventions (using libraries like clap, cobra, argparse, etc.), no additional work is needed. The schema and code behavior can never diverge because they come from the same source. Comparison with Peer Agent Tool Systems This section selects four representative Agent tool systems for horizontal comparison: LangChain (the earliest AI Agent framework, representing the "framework" approach), Claude Code (Anthropic's terminal Agent, representing the "vendor-locked + local-first" approach), Codex CLI (OpenAI's open-source terminal Agent, representing the "cloud sandbox" approach), and OpenClaw (open-source autonomous agent gateway, representing the "heartbeat-driven" approach). The following table provides an overview, with detailed analysis for each system below. Dimension BoxAgnts Claude Code Codex CLI OpenClaw LangChain Language Rust TypeScript/Node Rust (97.6%) TypeScript Python Sandbox Wasmtime (WASM) bubblewrap/Seatbelt (OS-level) Seatbelt/Landlock (OS-level) Docker containers None (external) Sandbox Granularity Instruction-level (wasm_fuel) Process-level (syscall) Process-level (syscall) Container-level (namespace) None Tool Registration --help auto-parse MCP service declaration + built-in tools Shell commands + apply_patch MCP service declaration Explicit code declaration Language Neutrality Any → wasm32-wasi Node/Shell only Shell commands (cross-language) JavaScript/TypeScript Python only Agent Loop Single loop + sub-agents Single loop (nO) + sub-agents Single loop (ReAct) Heartbeat loop + gateway routing Custom Chain/Graph License Undisclosed Closed-source CLI Apache 2.0 MIT MIT Provider Ecosystem 12+ (multi-vendor) Claude only OpenAI only Multi-vendor Multi-vendor Claude Code Anthropic's Claude Code is the benchmark for terminal Agents — it runs locally on the developer's machine with full shell permissions, using a single-threaded main loop (internally codenamed "nO") to iteratively execute tool calls. Claude Code added bubblewrap (Linux) and Seatbelt (macOS) for OS-level sandboxing in October 2025, supporting both filesystem and network isolation. Strengths: The CLAUDE.md project context system gives the Agent deep understanding of project conventions; SKILL.md and MCP servers provide strong extensibility; sub-agents (Explore, Plan, General-Purpose) can split complex tasks with isolated contexts. Limitations: The sandbox operates at process-level syscall interception — the OS attack surface still exists. bubblewrap's seccomp filter is fundamentally a blacklist model. Claude Code is locked to Claude models with no cross-vendor switching; the closed-source CLI prevents low-level customization. Tool execution depends on the real state of the host shell environment; environmental differences can cause unstable Agent behavior. Core difference from BoxAgnts: Claude Code's security model is "allow everything, intercept dangerous operations" — even with bubblewrap, boundaries are defined by configuring which directories and domains can be accessed. BoxAgnts' security model is "default-deny, only explicitly injected capabilities" — from the moment a WASM component starts, it doesn't even know what open() is. Codex CLI OpenAI's Codex CLI is an Apache 2.0 open-source project released in April 2025, with over 95% of its codebase rewritten in Rust. It shares several interesting similarities with BoxAgnts: both use Rust for startup speed and memory efficiency; both implement sandbox isolation. But they differ fundamentally in sandbox strategy. Strengths: Codex CLI's sandbox uses OS-level primitives (macOS Seatbelt, Linux Landlock + seccomp), providing strong control over local process file access and network calls. Codex Cloud executes in remote containers, completely isolating from the local filesystem. The Rust rewrite delivers a single binary with no runtime dependencies. codex exec and GitHub Action support CI/CD embedding. Limitations: Codex CLI's tool model is essentially "one shell command executor" — there is no independent tool abstraction layer. All operations go through cat, grep, find, apply_patch and similar shell commands, meaning even read-only code searches incur shell process startup overhead. The sandbox granularity is process-level — a tool permitted to run bash can execute arbitrary scripts within the sandbox. Tool registration cannot achieve zero configuration — the apply_patch diff format must be taught to the model in the system prompt. Core difference from BoxAgnts: Codex CLI's tools are "one universal shell + a few specialized subcommands"; BoxAgnts' tools are "independently isolated WASM components per tool." The former saves tool registration overhead at the cost of inter-tool isolation; the latter constructs a separate sandbox environment per tool — even if prompt injection tricks the AI into making a malicious tool call, that tool can only operate within its own WASM boundary. OpenClaw OpenClaw is a unique contender — it's not a developer-facing coding assistance tool, but rather a "self-hosted autonomous AI agent gateway." Its design philosophy uses a "Heartbeat" to periodically wake the Agent, enabling proactive planning and task execution even without user input. Strengths: The Heartbeat mechanism gives the Agent temporal autonomy — for example, automatically checking email every morning and generating a summary; SOUL.md provides persistent agent identity and values for consistent behavior across sessions; the SQLite + embedding memory system enables long-term memory; multi-channel support (WhatsApp, Telegram, Discord, Slack) broadens use cases. Limitations: The sandbox relies on Docker containers, with high startup costs (seconds vs WASM's microseconds), making it unsuitable for high-frequency tool invocation scenarios. OpenClaw has exposed serious security vulnerabilities — researchers discovered the "ClawJacked" attack could brute-force the agent's local port via WebSocket to gain full agent control, and malicious Skill packages could execute arbitrary code in the agent's context. Microsoft's security advisory explicitly states that "OpenClaw should be treated as untrusted code execution with persistent credentials." Core difference from BoxAgnts: OpenClaw's heartbeat loop addresses the question of "when" an Agent acts; BoxAgnts' WASM sandbox addresses "what" an Agent can do. These are not contradictory — an ideal Agent system should possess both temporal autonomy and spatial constraint. But the foundation of security lies in the spatial dimension: if the sandbox is unreliable, higher heartbeat frequency means a larger blast radius. LangChain LangChain has the most mature ecosystem among AI Agent frameworks. Its tool abstractions (BaseTool, StructuredTool) and Agent executor (AgentExecutor) are the blueprint many later frameworks reference. Strengths: The tool ecosystem is vast — virtually any third-party API you can think of has a corresponding LangChain integration; mature documentation and community support; flexible Chain/Graph/Agent composition. Limitations: No built-in sandbox — tools run directly in the Python process; security depends entirely on the deployer's external solutions. Registering a tool requires maintaining both code implementation and schema declaration, with no compile-time guarantee of consistency. The Python GIL limits multi-tool concurrency. The language binding between tools and framework means Go/Rust ecosystem tools cannot be used. Five-System Summary Placing these five systems into the "capability-based vs permission-reduction" framework makes the classification clear: Permission-reduction type: Claude Code (bubblewrap/seccomp filtering syscalls), Codex CLI (Landlock/seccomp restricting files/network), OpenClaw (Docker namespace isolation), LangChain (no built-in sandbox at all) Capability-based type: BoxAgnts (Wasmtime WASI explicitly injecting directory handles and network permissions) The common weakness of permission-reduction approaches is that "attack surface = the operating system's entire syscall set minus filter rules." seccomp-bpf filter programs have length limits; bubblewrap's default seccomp filter covers about 300 dangerous syscalls, but threats like /proc filesystem vulnerabilities, kernel privilege escalation, and side-channel attacks — which fall outside syscall interception scope — remain effective. Capability-based approaches don't rely on syscall filtering — WASM components don't directly invoke the host system's syscalls; they call WASI interfaces, which are translated into restricted system calls inside Wasmtime. Even if a WASM tool "wants" to read /etc/passwd, it fundamentally doesn't know how to issue that openat() call. This explains why BoxAgnts chose WebAssembly over containers: security isn't about blocking — it's about not being there in the first place. Summary BoxAgnts' tool system has chosen a technical path different from mainstream Agent frameworks. Its core decisions can be distilled into three points: Replace permission-reduction with capability-based injection. Don't tell WASM tools which syscalls are disabled — don't give them a syscall invocation path at all. The security boundary shifts from "everything you can do minus what's forbidden" to "only what I explicitly allow." Replace runtime checks with Rust compile-time safety. &ToolContext's immutable borrow, Arc<AtomicUsize>'s lock-free sharing, and the two-layer Arc zero-copy reference — these concurrency safety guarantees come from the borrow checker, not from runtime locks or deep copies. Replace explicit configuration with self-describing registration. Tool developers don't need to write separate schema files for BoxAgnts — the CLI program's --help output is the schema. This eliminates the possibility of schema-code behavior inconsistency. In horizontal comparison with other Agent systems, BoxAgnts is the only solution offering instruction-level sandbox granularity. Claude Code and Codex CLI's OS-level sandboxes remain syscall blacklist models, OpenClaw's Docker sandbox has second-level startup latency, and LangChain has no built-in security isolation. WASM sandbox microsecond-level startup enables high-frequency tool invocation scenarios, while instruction-level fuel metering provides resource control precision that container-based solutions cannot achieve. References BoxAgnts source code: https://github.com/guyoung/boxagnts Wasmtime project: https://github.com/bytecodealliance/wasmtime WASI Preview2 specification: https://github.com/WebAssembly/wasi-cli Claude Code architecture analysis: https://blog.promptlayer.com/claude-code-behind-the-scenes-of-the-master-agent-loop/ Codex CLI Agent Loop design: https://openai.com/index/unrolling-the-codex-agent-loop/ OpenClaw security analysis: https://arxiv.org/abs/2603.27517 LangChain tool system documentation: https://python.langchain.com/docs/how_to/custom_tools/

The AI industry is moving fast. Every week brings a new agent framework, coding assistant, autonomous workflow engine, or multi-agent platform. Most discussions focus on model capabilities—reasoning performance, planning ability, context window size, tool selection accuracy. Yet a more fundamental problem receives far less attention: Most AI agents lack a trustworthy execution environment. Current agent systems are becoming increasingly capable of interacting with the real world—executing code, modifying repositories, browsing websites, accessing databases, operating cloud infrastructure. As they gain operational authority, execution safety—not model intelligence—is becoming the decisive challenge. The Industry Is Optimizing Intelligence, Not Execution Most AI infrastructure investment goes toward making models smarter—larger models, better reasoning, longer context, more sophisticated planning. These technologies answer the question: "How can agents make better decisions?" But production systems must answer a different question: "What happens when those decisions are wrong?" Traditional software engineering has long assumed that failures will occur, designing fault isolation, permission boundaries, process containment, resource governance, and recovery mechanisms accordingly. Many AI systems still lack these properties—they rely on the fragile assumption that the model will behave correctly. BoxAgnts rejects this assumption outright. In boxagnts/query/src/query.rs, the query loop has multiple defense layers built in: // Protection mechanisms in the query loop const MAX_TOKENS_RECOVERY_LIMIT: u32 = 3; // Recovery attempt cap const MAX_TOKENS_RECOVERY_MSG: &str = "..."; // Recovery message // Inside the loop: // - turn counter (prevents infinite loops) // - max_tokens recovery mechanism (prevents token-exhaustion deadlock) // - budget checking (prevents cost runaway) // - cancel_token signal (interruptible at any time) These aren't prompt-level "suggestions"—they are runtime-level hard constraints. AI Agents Are Execution Systems, Not Chatbots Viewing agents as advanced chat interfaces is an outdated and dangerous perspective. Modern agents can create files, run commands, call APIs, update databases, and deploy infrastructure—once an agent produces actions rather than text, the consequences of mistakes grow exponentially. BoxAgnts' core execution loop clearly demonstrates the execution-system nature of agents: User Request → LLM Planning → Tool Selection → Tool Execution → Environment Modification The critical step isn't planning—it's execution. And every step of execution operates under runtime constraints. Why Current Architectures Are Fragile Most agent architectures boil down to: LLM → Tool Call → Python Runtime → Shell Command → Host System It's not a Python problem—it's a trust boundary problem. The model decides what to execute, what to access, and when to stop, but the model itself is exposed to prompt injection, adversarial documents, and untrusted content. This creates the architectural paradox: "untrusted planner → trusted execution." BoxAgnts solves this by inserting runtime boundaries between Planner and Executor: LLM (Planner) ↓ Query Loop (run_query_loop — execution governance) ↓ Tool Interface (permission_level check) ↓ WASM Sandbox (hard constraints) ↓ Host Resources (protected) Each layer is an independent governance point. No implicit trust exists between layers. Sandbox as a First-Class Runtime Primitive BoxAgnts elevates sandboxed execution from "optional feature" to "architectural foundation." All WASM tools run inside sandboxes by default. The sandbox is the lowest infrastructure component (boxagnts/wasm-sandbox/), sitting beneath tools and gateway. This design ensures security isn't a bolt-on—no matter how upper layers change, execution constraints remain in effect. Tool Runtime and Workflow Engine Are Different Layers A common confusion in the AI ecosystem is the relationship between workflow engines and runtime engines. Workflow engines (chains, graphs, planners) determine "what should happen." Runtime engines determine "what is allowed to happen." BoxAgnts has three explicit orchestration layers: Query Layer (boxagnts/query/): Workflow orchestration—manages conversation loops, auto-compaction, context management Tool Layer (boxagnts/tools/ + boxagnts/wasm-tools/): Tool interface—permission checks, parameter validation Sandbox Layer (boxagnts/wasm-sandbox/): Execution constraints—memory limits, network allowlists, timeout control Workflow coordinates. Runtime governs. Both are necessary. Only the runtime provides security guarantees. Multi-Agent Systems Make Isolation More Important BoxAgnts' Managed Agent mode supports parallel Executors, each running in independent sandboxes. This improves specialization and scalability, but also amplifies risk. Without proper isolation, malicious outputs propagate, context contamination spreads, capability escalation becomes possible, and debugging becomes nearly impossible. BoxAgnts' response is process-level thinking—each Executor has independent capabilities, isolated resources, independent context, and optional Git worktree isolation. This directly mirrors the process isolation model in modern operating systems. Resource Governance BoxAgnts enforces system-level resource control across all Executors through the WASM runtime: Governance Dimension Implementation CPU Usage wasm_fuel (instruction-level fuel) + wasm_timeout Memory Usage wasm_max_memory_size + wasm_max_wasm_stack Network Access allowed_outbound_hosts + block_networks + block_url File Access work_dir + map_dirs (precise directory mounts) Token Budget total_budget_usd (Managed Agent mode) Concurrency Control max_concurrent_executors Without this governance, the more autonomous an agent becomes, the greater its destructive potential. AI Agents Need Runtime Engineering The AI industry has spent years on prompt engineering, model engineering, and workflow engineering. A new discipline is emerging: runtime engineering—focusing on execution boundaries, capability systems, resource governance, fault containment, sandboxed tooling, and orchestration safety. As agents gain authority over real environments, runtime engineering is no longer optional—it's infrastructure necessity. The Future Looks More Like an Operating System Many current AI products are designed as applications. Future AI infrastructure will more closely resemble operating systems—providing scheduling, isolation, permissions, process management, and resource governance. BoxAgnts' module architecture already shows this embryonic form: Operating System BoxAgnts ────────────── ───────── Process Scheduling ←→ Query Loop (run_query_loop) Process Isolation ←→ WASM Sandbox File Permissions ←→ PermissionLevel + RunOption Network Filtering ←→ allowed_outbound_hosts + block_networks Memory Management ←→ wasm_max_memory_size Timeout Control ←→ wasm_timeout + wasm_fuel Task Scheduling ←→ Cron Scheduler (gateway/cron/) State Management ←→ Workspace Persistence (workspace/) This isn't coincidence—when AI agents become autonomous execution units, managing them requires operating-system-level thinking. Prompt engineering is a user-space tool; true security guarantees come from the kernel-space runtime. Conclusion The next generation of AI systems will not be defined by model intelligence alone—they will be defined by execution reliability. The "model-is-correct, therefore system-is-correct" assumption that current architectures depend on does not hold in production. BoxAgnts' engineering practice points to the right direction: sandboxed execution, capability isolation, resource governance, deterministic boundaries, secure orchestration. These are runtime problems, and solving them will be the most important engineering challenge in AI infrastructure over the coming decade. The future of AI agents isn't about making models smarter—it's about making execution trustworthy. Resources BoxAgnts: https://github.com/guyoung/boxagnts

Over the past decade, software infrastructure has moved decisively toward cloud-native architectures. AI agents followed the same path—cloud-hosted models, remote APIs, centralized orchestration. But as privacy demands grow, infrastructure costs climb, and offline scenarios emerge, a question once considered settled is being re-examined: Should AI agents always run in the cloud? The answer is becoming less obvious. Local-first AI systems demonstrate irreplaceable value in healthcare, finance, government, and enterprise compliance scenarios. BoxAgnts chose this path from the very beginning. The Limitations of Cloud-Centric Agents Privacy: Many agent workflows need access to source code, internal documentation, databases, and proprietary business processes—sending these to external infrastructure means compliance risks and security concerns. Latency: Agent systems frequently perform file operations, code analysis, and repository navigation—routing every action through remote APIs introduces unnecessary latency. Offline: Cloud-first systems assume reliable network connectivity—real-world environments frequently violate this assumption. Developers need offline coding assistants, edge-computing agents, and private infrastructure automation. BoxAgnts' solution is direct: put the runtime on the user's machine; choose local or cloud models as needed. Open a browser to http://127.0.0.1:30001—all agent interaction happens locally. Why Rust Fits Agent Runtime Development Most AI tooling uses Python—fast iteration, rich libraries, research-friendly. But runtime infrastructure has different priorities: predictable performance, memory safety, efficient concurrency, low resource overhead, portable deployment. Rust excels in all these areas. BoxAgnts chose Rust for several engineering reasons: Memory safety: Agent runtimes maintain execution state, tool registries, context stores, and orchestration graphs—as complexity grows, memory safety is no longer optional. Rust provides strong guarantees without GC pauses. Concurrency: Modern agents execute parallel tool calls, concurrent retrieval, multi-agent coordination, and async orchestration—Rust's async/await + Tokio ecosystem naturally matches these workloads. Deployment simplicity: Python environments need dependency resolution, package management, runtime configuration—Rust compiles to a single binary: # No pip install, no conda, no Docker boxagnts --workspace-dir /path/to/workspace --port 30001 BoxAgnts' entire Cargo.toml workspace compiles all modules into a statically-linked executable—download, extract, run. Three steps. WebAssembly Changes the Tool Model Tool execution is one of the hardest security challenges in AI agents. The traditional path—Agent → Python → Shell → Host System—carries enormous risk. BoxAgnts replaces the entire execution chain with WebAssembly: Agent Decision ↓ Tool Trait Interface (unified abstraction) ↓ WasmTool Wrapper ↓ Wasmtime Sandbox (RunOption constraints) ↓ WASM Module Execution (isolated environment) Look at how all tools are registered in boxagnts/tools-manager/src/lib.rs: pub fn all_tools() -> Vec<Box<dyn Tool>> { vec![ // Built-in tools Box::new(AskUserQuestionTool), Box::new(BriefTool), Box::new(EnterPlanModeTool), Box::new(ExitPlanModeTool), Box::new(SleepTool), Box::new(SkillTool), Box::new(ToolSearchTool), // WASM tools (all wrapped via WasmTool) Box::new(WasmTool::new("read", "file-read-component.wasm", ...)), Box::new(WasmTool::new("write", "file-write-component.wasm", ...)), Box::new(WasmTool::new("edit", "file-edit-component.wasm", ...)), Box::new(WasmTool::new("glob", "file-glob-component.wasm", ...)), Box::new(WasmTool::new("bash", "bash-component.wasm", ...)), Box::new(WasmTool::new("web_fetch", "web-fetch-component.wasm", ...)), // ... ] } Each WASM tool compiles once, runs cross-platform—macOS, Linux, Windows—with identical behavior. This portability is enormously important for AI ecosystems—agent tools shouldn't be fragile "works on my machine" artifacts. Unified Tool Interface Design BoxAgnts' most important runtime abstraction is the Tool trait—every tool looks identical from the agent's perspective: pub trait Tool: Send + Sync { fn name(&self) -> &str; fn description(&self) -> &str; fn permission_level(&self) -> PermissionLevel; fn input_schema(&self) -> Value; async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult; } The runtime doesn't care whether a tool is native Rust, WebAssembly, MCP-compatible, or a remote service—a unified interface means unified governance. All tools' permission_level is checked by the same permission system; all WASM tools' execute goes through the same sandbox pipeline. Context Lifecycle Management Context management is one of the hidden pain points of agent systems. Most discussions focus on "context window size," but the runtime needs to think about more: context creation, persistence, compaction, expiration, sharing. BoxAgnts manages these through the boxagnts/workspace/ module. Sessions are stored as JSON files in the local workspace: // boxagnts/gateway/src/api/chat_session.rs pub async fn get_sessions() -> Result<Vec<Session>> { let sessions_dir = saved_dir.join("sessions"); // Read all JSON session files // Sort by creation time, newest first } Session history is entirely local—not uploaded to the cloud, not controlled by third-party services. Privacy and latency benefit simultaneously. Multi-Agent Orchestration BoxAgnts' Managed Agent mode implements the Manager-Executor architecture: Planner Agent (Manager) ↓ ┌──────────┬──────────┬──────────┐ │Executor 1│Executor 2│Executor 3│ │WASM Sandbox│WASM Sandbox│WASM Sandbox│ │Independent │Independent │Independent │ │capabilities │capabilities │capabilities │ └──────────┴──────────┴──────────┘ In boxagnts/query/src/managed_orchestrator.rs, the system prompt defines the Manager's workflow: Analyze the user request and decompose into well-defined sub-tasks Launch an Executor for each sub-task using the Agent tool Review Executor results; if insufficient, re-dispatch with clarified instructions Synthesize all results into a coherent response Each Executor has independent max_turns, independent tool sets, and optional Git worktree isolation—runtime-level fault isolation, not prompt-level suggestions. Resource Governance BoxAgnts enforces multi-layer resource control through the WASM sandbox: Dimension Mechanism Purpose Time wasm_timeout Prevents long-running execution Memory wasm_max_memory_size Prevents memory bloat Stack wasm_max_wasm_stack Prevents stack overflow Compute wasm_fuel Instruction count limit Network allowed_outbound_hosts Outbound allowlist Network block_networks IP range blocklist Files work_dir / map_dirs Directory access control Without this governance, highly autonomous agents eventually become operational liabilities. Skill System: Composable Agent Capabilities BoxAgnts' skill system is a lightweight capability extension mechanism. Skills are defined as Markdown files in app/extensions/skills/: skills/ ├── code-review/SKILL.md ← Code review ├── css-refactor-advisor/SKILL.md ← CSS refactoring advice ├── current-weather/SKILL.md ← Weather query ├── front-component-generator/SKILL.md ← Frontend component generation └── weather-forecast/SKILL.md ← Weather forecast Each SKILL.md uses YAML frontmatter to declare name, description, trigger conditions, required tools, and parameters. SkillTool loads and expands these templates, injecting results into the LLM context. Skills can be shared, composed, and reused across workspaces—capability security manifested at the application layer. Conclusion AI agents are evolving from conversational apps into infrastructure systems. Local-first architecture provides privacy, low latency, and offline capability. Rust provides performance, safety, and portability. WebAssembly provides sandboxing, capability isolation, and portable execution—together, they form a powerful foundation for next-generation agent runtimes. BoxAgnts proves one thing: the future of AI agents need not be entirely cloud-native—in many scenarios, it should be local-first, capability-driven, and sandboxed by default. Resources BoxAgnts: https://github.com/guyoung/boxagnts