BoxAgnts Tool System (1) — Design Motivation & Architecture Overview

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:

1. Send message history and system Prompt to the AI model
2. Parse SSE stream events, detect ToolUse requests
3. Look up the corresponding tool instance in the tool table, perform permission checks
4. Call tool.execute(), capture the result
5. Inject the result into message history, return to step 1
6. 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.

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:

1. 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."

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

3. 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/