Forem: Guyoung Studio

BoxAgnts Introduction (2) — AI Agent Toolbox

Guyoung Studio — Tue, 26 May 2026 02:55:24 +0000

BoxAgnts' middle layer — the Agent Toolbox — is the brain and hands of the system. It consists of six core modules responsible for three things: understanding your intent, dispatching the right tools, and feeding back execution results. This article takes a deep dive into the architectural design and key implementations of each module.

Architecture Overview: A Seven-Module Collaboration Network

What happens when you type "Help me analyze the code structure of this Rust project" in the Dashboard and hit send?

User Message
  │
  ▼
┌─────────────────────────────────────────────────────────────┐
│  boxagnts-api            Unified API Abstraction Layer      │
│  LlmProvider trait → 20+ Providers → Message Normalization  │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-query          Agent Query Loop                   │
│  run_query_loop() → Multi-turn Conversation → Tool Dispatch → Auto Recovery │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-tools + tools-manager + wasm-tools                │
│  Tool trait → Built-in Tools + WASM Tools → Execution       │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-gateway        Gateway & Scheduling               │
│  Cron Scheduler + Site Hosting                              │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-workspace      Memory & Configuration             │
│  SQLite + JSON Config + Conversation History                │
└─────────────────────────────────────────────────────────────┘

Let's break down each one.

boxagnts-api: Unified Multi-Model Abstraction Layer

This is the interface layer between the middle layer and the external AI world. It solves the most painful problem in AI tool development: every model provider's API is different, but your code should not pay the price for that.

`LlmProvider` Trait: The Foundation of Polymorphism

The core interface that all provider adapters must implement:

#[async_trait]
pub trait LlmProvider: Send + Sync {
    fn id(&self) -> &ProviderId;       // Unique identifier "anthropic", "openai"
    fn name(&self) -> &str;            // Human-readable name

    // Non-streaming request
    async fn create_message(&self, request: ProviderRequest)
        -> Result<ProviderResponse, ProviderError>;

    // Streaming request (returns Pin<Box<dyn Stream>>)
    async fn create_message_stream(&self, request: ProviderRequest)
        -> Result<Pin<Box<dyn Stream<Item = Result<StreamEvent, ProviderError>> + Send>>, ProviderError>;

    // List available models
    async fn list_models(&self) -> Result<Vec<ModelInfo>, ProviderError>;
}

This trait design has three elegant aspects:

Async trait: Uses the async_trait macro, compatible with the Tokio async runtime
Returns Pin>: Uses dynamic dispatch to abstract away different providers' stream type differences
Unified error typing: All provider errors are normalized to ProviderError

Unified Access for 20+ Providers

BoxAgnts supports an extremely wide range of model providers:

Category	Providers	Independent Implementation File
International Mainstream	OpenAI, Anthropic, Google, Azure, Bedrock	Individual files
Open-Source Compatible	Deepseek, Mistral, Groq, TogetherAI, Fireworks	openai_compat.rs
Enterprise Services	Copilot, CodeX, Cohere, Perplexity	Individual files
Domestic Platforms	MiniMax, Alibaba Cloud (Qwen), Zhipu, Moonshot, SiliconFlow	Individual files
Others	Venus, Nebius, Novita, OVHCloud	Individual files

Key design pattern — Provider + Transformer dual-layer architecture:

Raw User Message
    │
    ▼
┌────────────────┐
│  Transformer   │  ← Converts internal message format to provider-specific format
│  (per-provider)│
└───────┬────────┘
        ▼
┌────────────────┐
│   Provider     │  ← Handles authentication, HTTP requests, stream parsing
│  (per-provider)│
└───────┬────────┘
        ▼
    AI Response
        │
        ▼
┌────────────────┐
│  Transformer   │  ← Converts provider response back to internal unified format
└────────────────┘

ProviderRegistry: Runtime Model Switching

QueryConfig contains a provider_registry field that allows dynamic provider selection at runtime. This means you can:

Configure different models for different tasks in Agent config (cheap model for summarization, strong model for reasoning)
Use fallback_model to automatically switch to a backup model when the primary model is overloaded
Manage API keys and endpoints for multiple models via ModelRegistry

API Key Management: Balancing Security and Convenience

BoxAgnts predefines environment variable mappings for each provider:

pub fn api_key_env_vars_for_provider(provider_id: &str) -> &'static [&'static str] {
    match provider_id {
        "anthropic" => &["ANTHROPIC_API_KEY"],
        "openai"    => &["OPENAI_API_KEY"],
        "deepseek"  => &["DEEPSEEK_API_KEY"],
        "zhipu"     => &["ZHIPU_API_KEY"],
        "minimax"   => &["MINIMAX_API_KEY"],
        // ... 30+ providers
    }
}

This means you can inject API keys through three methods — environment variables, configuration files, or the Dashboard UI — maximizing flexibility while maintaining security boundaries.

boxagnts-query: The Core Engine of the Agent

This layer is the absolute soul of BoxAgnts. The run_query_loop() function implements the complete Agent reasoning loop, about 300 lines of code, yet handles an amazing number of edge cases.

Main Loop Skeleton

loop {
    turn += 1;

    // 0. Check cancellation signal
    if cancel_token.is_cancelled() { return Cancelled; }

    // 1. Check max turns limit
    if turn > effective_max_turns { return EndTurn; }

    // 2. Inject pending user messages (multimodal interaction)
    if let Some(queue) = pending_messages.as_deref_mut() {
        for text in queue.drain(..) { /* append as user message */ }
    }

    // 3. Auto context compaction
    compact_state.maybe_compact(messages, config);

    // 4. Build API request
    let request = build_request(messages, tools, config);

    // 5. Send to AI model (supports streaming)
    let response = client.create_message_stream(request).await;

    // 6. Parse ContentBlocks from response
    for block in response.content {
        match block {
            ContentBlock::Text { text } => { /* accumulate text response */ }
            ContentBlock::ToolUse { name, input, .. } => {
                // Match and execute tool
                let tool = find_tool(name);
                let result = tool.execute(input, tool_ctx).await;
                messages.push(tool_result);  // Inject result into conversation
            }
            ContentBlock::Thinking { thinking, .. } => {
                // Handle deep thinking content (not shown to user)
            }
        }
    }

    // 7. If model ends → return final message
    if stop_reason == "end_turn" { return EndTurn; }
}

Key Mechanism Analysis

Token Exhaustion Recovery

When the model runs out of token quota in a single response, the query loop does not simply return a truncated result. Instead, it automatically sends a carefully designed recovery message:

"Output token limit hit. Resume directly — no apology, no recap of what
 you were doing. Pick up mid-thought if that is where the cut happened.
 Break remaining work into smaller pieces."

This message is remarkably restrained in design: "no apology, no recap, pick up from the cut, break down tasks" — conveying maximum instruction with minimum tokens. Retries up to 3 times (MAX_TOKENS_RECOVERY_LIMIT = 3) to avoid infinite loops.

Auto Context Compaction

compact.rs implements an intelligent compression strategy. When conversation history approaches the model's context window limit, it summarizes early messages — preserving key information (file paths, error messages, important decisions) while discarding redundant intermediate steps. This strategy ensures that even extremely complex multi-turn tasks (such as refactoring an entire codebase) won't cause the Agent to "lose its memory" due to context overflow.

Fallback Model Mechanism

// query.rs — Auto switch to backup model on overload errors
if is_overloaded_error(&err) && fallback_model.is_some() && !used_fallback {
    effective_model = fallback_model;
    used_fallback = true;
    continue; // Retry with backup model
}

When the primary model (e.g., Claude Sonnet) returns an overload error during high-load periods, the system automatically switches to a backup model (e.g., Deepseek), ensuring tasks are not interrupted. This mechanism is completely transparent to the user.

Budget Control

pub enum QueryOutcome {
    BudgetExceeded { cost_usd: f64, limit_usd: f64 },
    // ...
}

After each turn, the query loop checks whether the accumulated cost exceeds the budget cap. Every API call is tracked via CostTracker recording model and token consumption, ensuring costs are controllable. Budget overruns return clear error messages rather than silently overspending.

Multimodal Content Blocks

The ContentBlock enum defines 14 content types, covering the full spectrum of interactions from plain text to deep thinking:

pub enum ContentBlock {
    Text { text: String },                          // Plain text
    Image { source: ImageSource },                  // Image
    ToolUse { id, name, input },                    // Tool call
    ToolResult { tool_use_id, content, is_error },  // Tool result
    Thinking { thinking, signature },               // Deep thinking
    Document { source, title, context },            // Document reference
    UserLocalCommandOutput { command, output },     // Shell command output
    UserCommand { name, args },                     // User command
    UserMemoryInput { key, value },                 // User memory
    SystemAPIError { message, retry_secs },         // API error
    CollapsedReadSearch { tool_name, paths },       // Collapsed search results
    TaskAssignment { id, subject, description },    // Sub-task assignment
    // ...
}

This fine-grained content typing allows the frontend to render each type with specialized treatment — error blocks show red borders, task assignment blocks show cyan borders, collapsed search results displayed as single-line summaries.

Managed Agent Mode (Manager-Executor)

This is one of the most stunning middle-layer designs in BoxAgnts. managed_orchestrator.rs implements a hierarchical Agent architecture:

                    User
                      │
                      ▼
         ┌───────────────────────┐
         │  Manager Agent        │  ← Uses strong model (e.g., Claude Opus)
         │  Analyze tasks → Break down → Assign │
         └───────┬───────────────┘
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
   ┌────────┐┌────────┐┌────────┐
   │Executor││Executor││Executor│  ← Uses economical model (e.g., Claude Sonnet/Deepseek)
   │Subtask1││Subtask2││Subtask3│
   └────┬───┘└────┬───┘└────┬───┘
        │         │         │
        └────────┼─────────┘
                 ▼
          Manager aggregates results
                 │
                 ▼
              Final Output

Key Configuration

pub struct ManagedAgentConfig {
    pub enabled: bool,
    pub manager_model: String,           // Manager model (e.g., "claude-opus-4-6")
    pub executor_model: String,          // Executor model (e.g., "claude-sonnet-4-6")
    pub executor_max_turns: u32,         // Max turns per executor
    pub max_concurrent_executors: u32,   // Max parallel executors
    pub total_budget_usd: Option<f64>,   // Total budget cap
    pub executor_isolation: bool,        // Whether to isolate Git worktrees
}

System Prompt Injection

The Manager Agent's system prompt precisely defines its role:

You are the MANAGER, the planning and reasoning layer.
You coordinate work but do NOT execute tasks using file/bash tools directly.
All implementation work is delegated to executor agents (via the Agent tool).
Each executor uses {executor_model}, with a maximum of {max_turns} turns.
You may run up to {max_concurrent} executors in parallel.

The Executor's prompt requires "complete self-containment" — executors cannot see the Manager's conversation history and must include all context in their prompt. This avoids context leakage and reduces token consumption.

boxagnts-tools + tools-manager: Unified Tool Abstraction

Tool Trait: The Cornerstone of the Architecture

This is the most critical interface definition in all of BoxAgnts. Every new tool only needs to implement this trait:

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn input_schema(&self) -> Value;    // JSON Schema defining parameters
    async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult;
}

ToolContext: The Tool's Execution Environment

pub struct ToolContext {
    pub cost_tracker: Arc<CostTracker>,         // Cost tracker
    pub session_id: Option<String>,             // Session ID
    pub current_turn: Arc<AtomicUsize>,         // Current turn
    pub non_interactive: bool,                  // Non-interactive mode
    pub config: Config,                         // Global configuration
    pub managed_agent_config: Option<ManagedAgentConfig>,
    pub allowed_outbound_hosts: Vec<String>,    // Outbound network whitelist
    pub block_url: Option<String>,              // Blocked URLs
}

ToolContext is the tool's "passport" — carrying various contextual information such as permissions, sessions, costs, and networking. Every tool can access the required system state through it during execution.

Central Tool Registry

// tools-manager/src/lib.rs
pub fn all_tools() -> Vec<Box<dyn Tool>> {
    vec![
        // Rust native tools
        Box::new(AskUserQuestionTool),
        Box::new(BriefTool),
        Box::new(EnterPlanModeTool),
        Box::new(ExitPlanModeTool),
        Box::new(SleepTool),
        Box::new(SkillTool),
        Box::new(ToolSearchTool),

        // WASM sandbox tools — same interface, different implementation
        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", ...)),
        Box::new(WasmTool::new("js_exec", "boxedjs-execute-component.wasm", ...)),
    ]
}

Notice that Rust native tools and WASM tools are placed in the same Vec<Box<dyn Tool>> — to the AI model, they are completely equivalent. This is the power of interface-oriented programming.

boxagnts-gateway: Extending Time and Space Dimensions

Cron Scheduled Task Engine

cron/scheduler.rs builds a complete scheduled task system based on tokio_cron_scheduler:

// Core scheduling logic
let cron_job = Job::new_async(cron_expr, move |_uuid, _lock| {
    Box::pin(async move {
        let handle = job::execute(prompt, model).await;
        // Execution with timeout + result logging
        let result = timeout(Duration::from_secs(timeout), fut).await;
        append_execution_log(job_id, job_name, success, message).await;
    })
});

Key features:

Timeout protection: Each task has an independent timeout setting (default 180 seconds), wrapped by tokio::time::timeout
Cancel propagation: On timeout, cancels the executing Agent query via CancellationToken
Execution logs: Each execution records time, success/failure status, and result summary
Dynamic management: Tasks can be added, removed, enabled/disabled at any time

Site Hosting System

Site data managed by site/store.rs is persisted via SQLite, supporting CRUD operations. Combined with the frontend SitesPage, users can:

Create sites in the Dashboard (enter name and path)
Let the AI Agent generate web content
Access via the /sites/{name}/ path

boxagnts-workspace: The Agent's Memory System

The workspace module handles all persistence and configuration management:

Function	Storage	Key Implementation
Conversation History	SQLite (rusqlite)	Organized by session, supports CRUD
User Authentication	Password hash storage	Verified for remote access
Global Configuration	JSON file	`Settings::load()` to load
API Keys	Environment variables / JSON	Three-tier priority: ENV > Config > Default
AGENTS.md	Filesystem	Injected into system prompt each conversation
Cron Tasks	SQLite	Persisted storage + loaded at startup
Site Config	SQLite	Persisted storage + loaded at startup

Design highlight: configuration and state are separated. Configuration is JSON files (human-readable and editable), state is SQLite (efficient queries and transactions). This distinction avoids the common pitfall of "configuration file bloat."

QueryConfig: Full-Dimensional Query Control

QueryConfig is a massive configuration struct with 20 fields, covering every dimension of an Agent query:

pub struct QueryConfig {
    pub model: String,                           // Model name
    pub max_tokens: u32,                         // Max output tokens
    pub max_turns: u32,                          // Max reasoning turns
    pub system_prompt: Option<String>,           // System prompt
    pub thinking_budget: Option<u32>,            // Thinking budget (deep reasoning)
    pub temperature: Option<f32>,                // Temperature parameter
    pub tool_result_budget: usize,               // Total char cap for tool results (50000)
    pub effort_level: Option<EffortLevel>,       // Effort level (affects thinking_budget)
    pub max_budget_usd: Option<f64>,             // USD budget cap
    pub fallback_model: Option<String>,          // Backup model
    pub agent_definition: Option<AgentDefinition>, // Agent definition
    pub managed_agents: Option<ManagedAgentConfig>, // Managed mode
    pub output_style: OutputStyle,               // Output style
    // ... and more
}

This struct demonstrates a core design philosophy of BoxAgnts: give control to the user, but provide reasonable defaults. Every field can be overridden, but none are required — defaults cover 90% of use cases.

Summary

The middle-layer Agent Toolbox is the capability core of BoxAgnts:

Module	Responsibility	Key Highlight
boxagnts-api	Multi-model unified access	LlmProvider trait, 20+ Providers, Transformer conversion
boxagnts-query	Agent reasoning loop	Token recovery, context compaction, Fallback switching, budget control
managed_orchestrator	Managed Agent architecture	Manager-Executor layering, parallel execution, budget management
boxagnts-tools	Unified tool abstraction	Tool trait, ToolContext
tools-manager	Central tool registry	Rust native + WASM unified as Vec>
boxagnts-gateway	Time and space extension	Cron scheduler, Site hosting
boxagnts-workspace	Memory system	SQLite + JSON dual-layer storage

Related Resources

Boxagnts: https://github.com/guyoung/boxagnts

BoxAgnts Introduction (1) — Out of the Box

Guyoung Studio — Mon, 25 May 2026 04:42:32 +0000

In an era where AI tools are everywhere, a harsh reality persists: most developer tools die at the installation step. Complex dependencies, tedious configurations, incomprehensible error messages — every barrier drives away potential users.

BoxAgnts' design philosophy was clear from day one: make the path from download to usage as short as possible. This is the core problem that the outermost layer of the three-tier architecture — the "out-of-the-box experience" — aims to solve.

What Does True "Out of the Box" Mean?

AI tools on the market today can be broadly categorized into two types:

Type	Representative Products	Experience
Cloud Services	ChatGPT, Claude.ai	Sign up and go, but data is not local
Local Tools	LangChain, AutoGPT	Data is secure, but configuration hell

BoxAgnts attempts to take a third path: the security of local execution + the convenience of a cloud service.

Its "out-of-the-box" experience is reflected in four dimensions:

Zero-config startup: Download the executable, type boxagnts in the terminal, and the service starts
Web-based visual interface: Built-in Dashboard, all functionality managed through the browser
Pre-installed tools and skills: File operations, Shell execution, Web scraping, Code review — available right out of the box
Smart defaults: Every parameter has a reasonable default; it works well even without configuration

CLI Entry: Simple yet Powerful

BoxAgnts' entry point is a single executable compiled in Rust. It provides a clean and intuitive command-line interface built on the clap framework:

# Simplest startup — no parameters needed
boxagnts

# Custom workspace (recommended: isolate different projects)
boxagnts --workspace-dir ~/my-ai-workspace

# Custom port + remote access
boxagnts --host 0.0.0.0 --port 30002 --admin-user admin --admin-pass mypass

Only 6 command-line parameters, all with reasonable defaults:

Parameter	Purpose	Default	Design Intent
`--port`	Web service port	30001	Avoids common ports, reduces conflicts
`--host`	Bind address	127.0.0.1	Default local-only access, security first
`--workspace-dir`	Workspace directory	Current directory	Supports multi-project isolation
`--app-dir`	Application resource directory	Same directory as executable	Portable deployment
`--admin-user`	Admin username	None	Required for remote access
`--admin-pass`	Admin password	None	Required for remote access

No nightmare of YAML configuration files, no maze of environment variables. This design embodies an important product philosophy: users should not have to learn a configuration syntax just to get started.

Workspace Design Philosophy

BoxAgnts supports multiple workspaces — each workspace has its own configuration files, conversation history, and data directories. The official documentation explicitly recommends "do not run in the default directory; instead, specify a workspace directory." This means you can create independent workspaces for different projects without interference. Each workspace's data is persisted via SQLite and will not be lost after a restart.

Dashboard: Your AI Control Center

After starting the service, visit http://127.0.0.1:30001/dashboard in your browser, and a complete AI management platform appears before you.

Full Page Matrix

The Dashboard includes 10 functional pages, covering the core management needs of an AI Agent platform:

Page	Function	Technical Highlight
ChatPage	AI chat interface	Streaming responses, Markdown rendering, code highlighting, session management
AgentsPage	Custom AI Agent management	Model selection, system prompt, temperature parameter
ToolsPage	Tool list and management	16+ tool overview, parameter descriptions
SkillsPage	Skill management	5 pre-installed skills, supports custom extensions
CronsPage	Scheduled task management	Standard Cron expressions, status tracking, execution logs
SitesPage	Website hosting	Static site deployment, file serving
FilePage	File browser	Workspace directory browsing, file content viewing
SettingsPage	Global settings	Permission mode, theme, workspace path
SettingsModelPage	Models and API Keys	20+ providers, multi-model configuration
SettingsAgentsMdPage	AGENTS.md editing	Customize Agent behavior descriptions

Frontend Tech Stack Analysis

The BoxAgnts Dashboard is built with Vue 3 + TypeScript + Vuetify 3, one of the most mature Vue enterprise-level tech stacks currently available:

Vue 3 (Composition API)     → Reactive UI framework
Pinia                        → State management
Vue Router                   → Route management
Vuetify 3                    → Material Design component library
CodeMirror 6                 → Code editor (Markdown/JSON syntax highlighting)
marked + DOMPurify           → Markdown rendering + XSS protection
@vueuse/core                 → Composable utility functions

Elegant Design of Composables

The frontend encapsulates core interaction logic through 4 composables:

Composable	Responsibility
`useChatSession`	Session lifecycle management: load history, switch sessions, model selection, cancel execution
`useChatMessages`	Message state management: message list, streaming append, history display
`useChatScroll`	Smart scrolling: auto-follow new messages, detect manual scroll-back by user
`useMarkdownRender`	Markdown rendering pipeline: marked parsing + DOMPurify sanitization + syntax highlighting

Take useChatSession as an example — it cleverly handles race conditions during session switching:

watch(() => sessionStore.currentSessionId, (newId) => {
  if (newId === sessionId.value) return      // Prevent duplicate loading
  cleanupActiveStream()                       // Clean up old WebSocket connection
  uiState.isRunning = false                   // Reset running state
  messages.value = []                         // Clear message list
  if (newId) {
    sessionId.value = newId
    loadAndSetHistory(newId)                  // Load history asynchronously
  }
}, { immediate: true })

Two Key Interaction Details

1. End-to-End Streaming Response Pipeline

When a user sends a message, the frontend establishes a long connection with the server via WebSocket. Every token produced by the server-side Agent query loop is pushed to the WebSocket layer through an mpsc channel and then rendered in real-time in the chat interface. This pipeline design ensures a "what you see is what you get" real-time experience.

2. Deep Integration of the Code Editor

The SettingsAgentsMdPage integrates CodeMirror 6, supporting syntax highlighting for both Markdown and JSON. AGENTS.md is one of BoxAgnts' core configuration files — you can define the Agent's behavior guidelines, project conventions, and interaction style here. This editor uses the @codemirror/theme-one-dark dark theme, consistent with Vuetify's overall visual style.

REST API Gateway: The Hidden Backbone

Behind the Dashboard is a complete REST API system. All endpoints are defined in gateway/src/api/, built with the Axum framework:

POST   /api/chat/execute       → Send message, get streaming response via WebSocket
GET    /api/chat/sessions      → Get all session list
GET    /api/chat/session/:id   → Load specified session's message history
DELETE /api/chat/session/:id   → Delete session and its messages
PUT    /api/chat/session/:id   → Update session title
DELETE /api/chat/messages/:id  → Delete specified message in a session
POST   /api/file/read          → Read file content
POST   /api/file/write         → Write file
POST   /api/file/edit          → Edit file (precise string replacement)
POST   /api/tool/list          → List all available tools
POST   /api/skill/list         → List all available skills
POST   /api/cron/*             → Scheduled task CRUD
POST   /api/site/*             → Site management CRUD
POST   /api/config/*           → Configuration management
POST   /api/provider/*         → AI provider management

This API uses a unified JSON response format:

{
  "success": true,
  "data": { ... },
  "error": null
}

This means that beyond the built-in Dashboard, you can fully use the API to build your own client — desktop apps (Tauri), mobile apps (Flutter/React Native), CLI tools, or even another AI Agent.

Site Hosting: More Than Just a Management Backend

BoxAgnts also includes a built-in site hosting feature. Under the /sites/{site}/{*path} route, you can deploy static websites. Even more interestingly, the AI Agent can generate web content for you and then deploy and access it with one click through the Site module — the Dashboard itself and the site system share the same HTTP server, but you can also deploy completely independent sites.

Site navigation is dynamically fetched via the get_site_nav_items API, meaning you can add or remove sites at any time, and the navigation bar will automatically update.

Security Defense: Layered Protection

BoxAgnts embeds security considerations right at the entry point:

// server/src/main.rs
fn is_local_host(host: &str) -> bool {
    matches!(host, "127.0.0.1" | "localhost" | "::1")
}

if !is_local_host(&args.host) && (args.admin_user.is_none() || args.admin_pass.is_none()) {
    eprintln!("❌ When host is not local, --admin-user and --admin-pass are required.");
    std::process::exit(1);
}

The logic is crystal clear: if accessing locally (127.0.0.1 / localhost / ::1), no authentication is required; once exposed to the network, username and password are mandatory.

This reflects a pragmatic engineering judgment:

For local access, the user has already passed the OS identity verification; an additional password layer is redundant
For remote access, the network is untrusted and authentication must be enforced — denying service is better than risking exposure
This "scenario-based layered protection" approach runs through every layer of BoxAgnts' design

The outer layer's CORS policy is also noteworthy — using CorsLayer::permissive(), allowing cross-origin requests from any source. The reason for such leniency:

Default binding to 127.0.0.1, immune to external network attacks
Dashboard and API are same-origin deployed, no complex CORS strategy needed
Mandatory authentication serves as a backstop for remote access

Pre-installed Resources: Capabilities Right Out of the Box

BoxAgnts' pre-installed extension resources fall into three categories, all located under the app/extensions/ directory:

WASM Tool Components (7)

tools/
├── file-read-component.wasm      # File reading
├── file-write-component.wasm     # File writing
├── file-edit-component.wasm      # File editing (precise string replacement)
├── file-glob-component.wasm      # File glob matching
├── web-fetch-component.wasm      # Web content fetching
├── bash-component.wasm           # Shell command execution
└── boxedjs-execute-component.wasm # JavaScript code execution

Pre-installed Skills (5)

skills/
├── code-review/SKILL.md                # Code review expert
├── css-refactor-advisor/SKILL.md       # CSS refactoring advisor
├── current-weather/SKILL.md            # Weather query
├── weather-forecast/SKILL.md           # Weather forecast
└── front-component-generator/SKILL.md  # Frontend component generator

Service Components

services/
└── boxed_static_server_component.wasm  # Static file server

This means after downloading and extracting, without installing anything extra, the user already has the full suite of capabilities: file operations, Shell execution, Web scraping, code review, weather queries, and more.

AGENTS.md: Define Your AI Assistant

BoxAgnts introduces the AGENTS.md file — the "AI constitution" of the project. Similar to .gitignore for Git, AGENTS.md defines the Agent's behavioral guidelines for the current project.

You can edit this file in SettingsAgentsMdPage, using Markdown format to describe:

Project background and tech stack
Coding standards the Agent should follow
Disallowed operations and restrictions
Preferred tools and skill combinations
Interaction style (concise or detailed)

The content of this file is injected into the system prompt, ensuring the Agent follows your defined rules in every conversation. This is a "configuration as constraint" design — no code changes needed, just write a paragraph of Markdown.

Summary

The outer layer design answers BoxAgnts' first core question: how to let users get started effortlessly?

The answer is the synergy of six dimensions:

Minimal startup: 6 parameters, defaults covering most scenarios, single executable
Full-featured Web UI: 10 pages, Vue 3 + Vuetify 3 modern tech stack
Real-time streaming experience: WebSocket + mpsc channel, end-to-end millisecond-level push
Complete REST API: Supports secondary development and custom clients
Scenario-based security: Local authentication-free, remote strong authentication, flexible CORS
Pre-installed resources: 7 tool components + 5 skills + AGENTS.md configuration

Related Resources

Boxagnts: https://github.com/guyoung/boxagnts

Rebuilding the Security Model of AI Agents with WASM Sandbox

Guyoung Studio — Sun, 24 May 2026 08:41:38 +0000

The AI Agent ecosystem is moving fast.

Every week we see new frameworks for:

autonomous coding
browser automation
workflow orchestration
multi-agent collaboration
tool calling

But there’s one uncomfortable truth most people are ignoring:

Most AI Agents today are fundamentally unsafe.

An LLM can generate shell commands.
An Agent can execute tools.
A prompt injection can become a system compromise.

And in many systems, the execution layer still looks like this:

exec(generated_code)

or:

bash -c "$LLM_OUTPUT"

That is not an AI architecture problem.

It is a runtime security problem.

This is exactly why I started paying attention to BoxAgnts GitHub Repository — a Rust-based AI Agent runtime that uses WebAssembly sandboxing as its core security model. (DEV Community)

The Problem: AI Agents Have Too Much Power

Modern AI Agents are no longer just chatbots.

They can:

read files
execute shell commands
scrape websites
generate code
call APIs
schedule background tasks
deploy services

This creates a dangerous architecture pattern:

LLM
  ↓
Tool Selection
  ↓
Host System Access

The problem is not theoretical anymore.

Prompt injection attacks already demonstrate that AI systems can be manipulated into:

leaking secrets
executing malicious commands
accessing unintended resources
escalating privileges

The industry response so far has mostly been:

Docker containers
permission prompts
regex filtering
isolated VMs

These help, but they are still relatively coarse-grained.

What AI Agents actually need is:

capability-based execution.

Why WASM Changes Everything

This is where WebAssembly becomes interesting.

Most developers associate WASM with browsers.

But WASM is quietly becoming something much bigger:

A secure universal runtime layer.

The BoxAgnts architecture is built around this idea. (DEV Community)

Instead of allowing tools to run directly on the host machine, tools execute inside a WebAssembly sandbox powered by Wasmtime. (DEV Community)

That changes the execution model entirely.

Instead of:

Agent
  ↓
Shell Access

You get:

Agent
  ↓
WASM Runtime
  ↓
Capability-Controlled Execution

This is a fundamentally different security philosophy.

Capability-Based AI Agents

Traditional Agent frameworks often assume tools have broad access to the environment.

But capability-based systems work differently.

A tool only receives the permissions explicitly granted to it.

For example:

tool:
  name: web-fetch
  permissions:
    - network:https://api.example.com

Or:

tool:
  name: file-reader
  permissions:
    - fs.read:/workspace

No global filesystem access.
No unrestricted shell execution.
No unrestricted networking.

This model is much closer to:

browser sandboxing
mobile app permissions
serverless isolates
microVM security
wasmCloud capability systems

And that matters because AI Agents are increasingly acting like autonomous software operators.

What BoxAgnts Actually Implements

BoxAgnts is not just a chatbot UI.

The project already includes:

multi-model AI support
tool execution
scheduled automation
workspaces
Web dashboard
WebSocket streaming
skill systems
WebAssembly sandbox runtime

according to the project documentation and architecture overview. (DEV Community)

Its Rust workspace structure includes components such as:

gateway/
tools/
wasm-sandbox/
workspace/
server/

with a dedicated wasm-sandbox module built on Wasmtime. (DEV Community)

The runtime also supports:

isolated execution
permission management
network access control
workspace isolation

which are all critical primitives for secure Agent systems. (DEV Community)

AI Infrastructure Is Shifting

Most AI Agent discussions today focus on:

prompts
workflows
memory
multi-agent orchestration

But over time, the infrastructure layer will matter more.

Because eventually every serious Agent system must answer questions like:

How do we safely execute untrusted tools?
How do we isolate generated code?
How do we audit permissions?
How do we run autonomous agents locally?
How do we support edge deployment securely?

This is why I think the next generation of AI infrastructure will increasingly resemble:

serverless runtimes
capability systems
sandboxed execution environments

instead of traditional scripting frameworks.

Why Rust Is a Strong Fit

Rust is particularly well-suited for this kind of runtime architecture.

Not because “Rust is fast” — that’s the least interesting reason.

The real advantages are:

memory safety
predictable concurrency
strong type systems
systems-level control
excellent WASM ecosystem

Projects like:

Wasmtime
wasmCloud
Deno
Fermyon Spin

have already demonstrated that Rust and WASM form a powerful foundation for secure runtime systems.

BoxAgnts is applying that same philosophy to AI Agents.

AI Agents Need a Runtime Layer

Today, most AI frameworks focus on orchestration.

But orchestration is not enough.

The future AI stack will likely look more like this:

LLM Layer
   ↓
Planning Layer
   ↓
Agent Runtime
   ↓
Sandboxed Tool Execution

And the runtime layer will become increasingly important.

Because eventually:

the biggest problem in AI Agents is not intelligence.

It is trust.

Beyond Docker

Some people will ask:

Why not just use Docker?

Docker is useful, but it operates at a different abstraction level.

Containers are relatively heavyweight and coarse-grained.

WASM runtimes enable:

lightweight isolation
fast startup
portable execution
fine-grained capabilities
embedded deployment

This makes them especially attractive for:

local AI assistants
edge AI
browser-hosted agents
embedded devices
self-hosted automation
secure plugin ecosystems

The Most Interesting Direction: WASM-Native Tools

The most exciting possibility is not just sandboxing existing tools.

It is building an entire ecosystem where:

Tool = WASM Module

That would enable:

portable tools
auditable permissions
safe execution
cross-platform compatibility
secure marketplaces

Imagine an “npm for AI Agent tools” — but capability-safe by default.

That could fundamentally reshape how Agent ecosystems evolve.

Final Thoughts

Most AI Agent projects today are competing on:

better prompts
better workflows
more automation
more autonomy

But the real long-term challenge is:

secure execution.

That is why I think projects like BoxAgnts are interesting. They are not just building “another Agent framework.”

They are exploring a much deeper idea:

Rebuilding the runtime security model of AI Agents using WebAssembly sandboxing. (DEV Community)

BoxAgnts is an Out-Of-The-Box Secure AI Agent ToolBox in a WASM SandBox

Guyoung Studio — Sat, 23 May 2026 03:49:57 +0000

BoxAgnts is an open-source AI Agent ToolBox built with Rust, dedicated to delivering an ultimate out-of-the-box experience. Leveraging WebAssembly sandbox, it provides a runtime environment that balances security and flexibility, helping users effortlessly tackle a wide range of complex tasks and thus becoming an efficient and trustworthy personal AI assistant.

Core Architecture

🎯 AI Agent ToolBox

BoxAgnts is a fully-featured AI Agent toolkit providing:

Multi-model support: Compatible with major AI model providers including OpenAI, Anthropic, CodeX, Google, Deepseek, MiniMax, OpenCode
Tool system: Built-in file operations, web access, code execution, and many other tools
Skill system: Create specialized AI skills through simple configuration

🛡️ WebAssembly SandBox

Build a secure runtime environment using WebAssembly technology:

Isolated execution: All custom tools and skills run in a WASM sandbox
Security control: Fine-grained permission management and network access control
Cross-platform: Compile once, run everywhere
High performance: Based on Wasmtime runtime, near-native performance

✨ Out of the Box

Out-of-the-box experience:

Zero-configuration startup: Download and run, no complex configuration
Web interface: Built-in beautiful Dashboard for visual management of all features
Built-in extensions: Pre-configured with commonly used tools and skills, ready to use
Quick start: Simple API and intuitive workflow

Key Features

🤖 AI Chat and Agents

Chat with multiple AI models
Create and manage custom Agents
Save and manage chat history
Support for streaming responses

🔧 Tool Execution

File read/write and editing
Shell command execution
Web content scraping
Code review and analysis

📦 Skill System

Quickly create specialized skills
Skill combination and reuse
Built-in skills including code review, weather query, front-end component generation, etc.

⏰ Automatic Tasks Cron

Create and manage scheduled tasks
Support for standard Cron expressions
Task execution logs and status tracking
Flexible task configuration and triggering methods

🌐 Web Service

Custom website deployment
Static file serving
API endpoint management

Quick Start

Download Executable

Download the latest compressed package from the Releases page, extract and run.

Start Service

# Start service
boxagnts

# Specify workspace directory
boxagnts --workspace-dir /path/to/workspace

# Specify port
boxagnts --workspace-dir /path/to/workspace --port 30002

Suggestion: BoxAgnts supports multiple workspaces, each with its own configuration file and data directory. It is recommended not to run in the default directory, but to specify a workspace directory or workspace-dir.

Command line arguments:

BoxAgnts is an open-source AI Agent ToolBox built with Rust.

Usage: boxagnts [OPTIONS]

Options:
      --port <PORT>          Port to run the web server on [default: 30001]
      --host <HOST>          Host to bind to (0.0.0.0 for all interfaces) [default: 127.0.0.1]
      --workspace-dir <DIR>  Set workspace dir, default current dir
      --app-dir <DIR>        Set app dir, default Boxagnts executable file dir
      --admin-user <USERNAME>  Set admin username
      --admin-pass <PASSWORD>  Set admin password
  -h, --help                 Print help
  -V, --version              Print version

Access Dashboard

Open your browser and visit http://127.0.0.1:30001

Configure Model

Add AI models and API Keys in the settings page

Project Structure and Source Code Compilation

This project is developed based on claurst project code

Directory Structure

boxagnts/
├── boxagnts/                 # Rust backend core code
│   ├── api/                 # AI model API (multi-provider support)
│   ├── core/                # Core types, constants, and basic functions
│   ├── gateway/             # API gateway (includes Cron task scheduling)
│   ├── mcp/                 # MCP protocol implementation (optional)
│   ├── server/              # Web server and Dashboard interface
│   ├── tools/               # Tool system and built-in tools
│   ├── tools-manager/       # Tool manager
│   ├── query/               # Query orchestration
│   ├── wasm-sandbox/        # WebAssembly sandbox runtime
│   ├── wasm-tools/          # WASM tool wrappers
│   └── workspace/           # Workspace and configuration management
├── boxagnts-dashboard-web/  # Vue 3 frontend source code
│   ├── src/
│   │   ├── api/            # API interface wrappers
│   │   ├── components/     # Vue components
│   │   ├── composables/    # Composables
│   │   ├── stores/         # Pinia state management
│   │   ├── views/          # Page components
│   │   └── router/         # Router configuration
│   └── package.json        # Frontend dependencies
├── app/                     # Application resources
│   ├── dashboard-web/      # Compiled web interface static assets
│   └── extensions/         # Extensions (tools/skills)
└── Cargo.toml              # Rust workspace configuration

Backend Code Analysis

The backend is developed in Rust using Tokio async runtime. The main modules are:

api/: Wraps APIs from multiple AI providers including OpenAI, Anthropic, Google, Azure, Bedrock, providing unified interface calling and message format conversion
core/: Defines core data types, constants, error handling, and system prompts
gateway/: API gateway layer, handles HTTP requests, includes Cron task scheduling system (cron/ subdirectory), supporting scheduled task creation, management, and execution
server/: Web server, providing Dashboard REST API and WebSocket support
tools/: Tool system, implements execution framework for built-in tools and skills
wasm-sandbox/: WebAssembly sandbox based on Wasmtime, implementing secure code execution environment
workspace/: Workspace management, handles configuration, authentication, and history storage

Frontend Code Analysis

The frontend uses Vue 3 + TypeScript + Vuetify technology stack:

Uses Pinia for state management (stores/ directory)
Uses Vue Router for routing management (router/ directory)
Main pages: Chat, Agents, Cron tasks, Files, Skills, Tools, Sites, Settings, etc.
Supports Markdown rendering, code editor (CodeMirror), charts (Chart.js), etc.
Communicates with backend via REST API and WebSocket

Source Code Compilation Method

Environment Requirements

Rust 1.75+ (Install: https://www.rust-lang.org/tools/install)
Node.js 18+ (Install: https://nodejs.org/)
npm or pnpm

Compile Backend

# Enter project root directory
cd boxagnts-pub

# Compile Debug version
cargo build

# Compile Release version (optimize for size and performance)
cargo build --release

# Compiled executable is located at target/release/boxagnts

Compile Frontend

# Enter frontend directory
cd boxagnts-dashboard-web

# Install dependencies
npm install

# Start development mode (hot reload)
npm run dev

# Compile production version
npm run build

# Compiled static files will be output to app/dashboard-web/

Complete Build Process

# 1. Compile frontend
cd boxagnts-dashboard-web
npm install
npm run build

# 2. Compile backend
cd ..
cargo build --release

# 3. Run
./target/release/boxagnts

License

MIT

Repository: https://github.com/guyoung/boxagnts

Forem: Guyoung Studio

BoxAgnts Introduction (2) — AI Agent Toolbox

Architecture Overview: A Seven-Module Collaboration Network

boxagnts-api: Unified Multi-Model Abstraction Layer

LlmProvider Trait: The Foundation of Polymorphism

Unified Access for 20+ Providers

ProviderRegistry: Runtime Model Switching

API Key Management: Balancing Security and Convenience

boxagnts-query: The Core Engine of the Agent

Main Loop Skeleton

Key Mechanism Analysis

Token Exhaustion Recovery

Auto Context Compaction

Fallback Model Mechanism

Budget Control

Multimodal Content Blocks

Managed Agent Mode (Manager-Executor)

Key Configuration

System Prompt Injection

boxagnts-tools + tools-manager: Unified Tool Abstraction

Tool Trait: The Cornerstone of the Architecture

ToolContext: The Tool's Execution Environment

Central Tool Registry

boxagnts-gateway: Extending Time and Space Dimensions

Cron Scheduled Task Engine

Site Hosting System

boxagnts-workspace: The Agent's Memory System

QueryConfig: Full-Dimensional Query Control

Summary

Related Resources

BoxAgnts Introduction (1) — Out of the Box

What Does True "Out of the Box" Mean?

CLI Entry: Simple yet Powerful

Workspace Design Philosophy

Dashboard: Your AI Control Center

Full Page Matrix

Frontend Tech Stack Analysis

Elegant Design of Composables

Two Key Interaction Details

REST API Gateway: The Hidden Backbone

Site Hosting: More Than Just a Management Backend

Security Defense: Layered Protection

Pre-installed Resources: Capabilities Right Out of the Box

WASM Tool Components (7)

Pre-installed Skills (5)

Service Components

AGENTS.md: Define Your AI Assistant

Summary

Related Resources

Rebuilding the Security Model of AI Agents with WASM Sandbox

The Problem: AI Agents Have Too Much Power

Why WASM Changes Everything

Capability-Based AI Agents

What BoxAgnts Actually Implements

AI Infrastructure Is Shifting

Why Rust Is a Strong Fit

AI Agents Need a Runtime Layer

Beyond Docker

The Most Interesting Direction: WASM-Native Tools

Final Thoughts

BoxAgnts is an Out-Of-The-Box Secure AI Agent ToolBox in a WASM SandBox

Core Architecture

🎯 AI Agent Tool*Box*

🛡️ WebAssembly Sand*Box*

✨ Out of the Box

Key Features

🤖 AI Chat and Agents

🔧 Tool Execution

📦 Skill System

⏰ Automatic Tasks Cron

🌐 Web Service

Quick Start

Download Executable

Start Service

Access Dashboard

Configure Model

Project Structure and Source Code Compilation

Directory Structure

Backend Code Analysis

Frontend Code Analysis

`LlmProvider` Trait: The Foundation of Polymorphism

🎯 AI Agent ToolBox

🛡️ WebAssembly SandBox