WASM Sandboxing

Run agent skills in a secure WebAssembly sandbox with capability-based permissions.

Overview

WASM sandboxing provides an additional security layer by running skills in an isolated environment with restricted access to system resources.

┌─────────────────────────────────────────────────────┐
│                 Native Runtime                       │
│  ┌───────────────────────────────────────────────┐ │
│  │         Skills run directly on host            │ │
│  │         Full system access                     │ │
│  └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                  WASM Runtime                       │
│  ┌───────────────────────────────────────────────┐ │
│  │         Skills run in sandbox                  │ │
│  │  ┌─────────────────────────────────────────┐  │ │
│  │  │         Capability Checks               │  │ │
│  │  │  • Filesystem: Only allowed paths       │  │ │
│  │  │  • Network: Only if enabled             │  │ │
│  │  │  • Memory: Limited allocation           │  │ │
│  │  └─────────────────────────────────────────┘  │ │
│  └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

When to Use WASM

Good Use Cases

• Running untrusted or third-party skills
• Processing user-provided input
• Multi-tenant environments
• Compliance requirements
• Security-sensitive operations

When Native is Better

• Trusted internal skills
• Maximum performance needed
• Simple, well-audited code
• Development and testing

Configuration

Enable WASM Runtime

Edit ~/.moxxy/agents/<name>/container.toml:

[runtime]
type = "wasm"

[runtime.wasm]
image = "networked"    # base, networked, or full

[capabilities]
filesystem = ["./skills", "./memory"]
network = true
max_memory_mb = 128
env_inherit = false

WASM Images

Image	Network	Filesystem	Use Case
base	❌	❌	Pure computation
networked	✅	❌	API calls, web requests
full	✅	✅	General purpose

Capability Configuration

[capabilities]
# Allowed filesystem paths (relative to agent directory)
filesystem = ["./skills", "./memory", "/tmp/agent"]

# Network access
network = true

# Memory limit in MB
max_memory_mb = 128

# Inherit host environment variables
env_inherit = false

How It Works

Skill Execution Flow

1. Agent invokes skill

   <invoke name="web_crawler">["https://example.com"]</invoke>

2. System checks requirements

   • Does skill need network? Yes
   • Is network capability enabled? Check config
   • If no capability → Error

3. Execute in WASM sandbox

   • Skill code compiled to WASM
   • Runs in isolated runtime
   • Capabilities enforced

4. Return result

   • Output captured
   • Returned to agent

Capability Enforcement

// Pseudo-code of capability check
fn execute_skill(skill: &Skill, caps: &Capabilities) -> Result {
    if skill.needs_network && !caps.network {
        return Err("Network capability required");
    }
    
    if skill.needs_fs_read {
        for path in &skill.requested_paths {
            if !caps.filesystem.iter().any(|p| path.starts_with(p)) {
                return Err("Path not in allowed filesystem");
            }
        }
    }
    
    // Execute in WASM
    wasm_runtime.execute(skill, caps)
}

Skill Compatibility

Skill Manifest

Skills declare their requirements:

name = "web_crawler"
description = "Fetch web content"
needs_network = true      # Requires network
needs_fs_read = false     # No filesystem read
needs_fs_write = false    # No filesystem write
needs_env = false         # No environment access

Compatibility Matrix

Skill	base	networked	full
host_shell	❌	❌	⚠️
host_python	❌	❌	⚠️
web_crawler	❌	✅	✅
git	❌	✅	✅
telegram_notify	❌	✅	✅
manage_vault	❌	❌	✅

⚠️ = May work but not recommended

Building WASM Runtime

Prerequisites

# Add WASM target
rustup target add wasm32-wasip1

Build Agent Runtime

cd agent_runtime
cargo build --target wasm32-wasip1 --release

The resulting WASM module is embedded in the moxxy binary.

Performance

Benchmarks

Operation	Native	WASM	Overhead
Shell command	10ms	50ms	5x
HTTP request	100ms	105ms	5%
File read (1KB)	1ms	2ms	2x
Compute (SHA256)	5ms	7ms	1.4x

Optimization Tips

1. Use networked image for API-heavy skills
2. Minimize filesystem access
3. Batch operations to reduce overhead
4. Use native for compute-intensive tasks

Security Model

Isolation Guarantees

• Memory isolation - WASM cannot access host memory
• No syscalls - Only through provided APIs
• Path sandboxing - Cannot escape allowed directories
• Network filtering - Only if explicitly enabled

Limitations

• WASM runtime itself has some attack surface
• Side-channel attacks possible (timing, etc.)
• Not a replacement for proper security practices

Troubleshooting

"Capability check failed"

Error: Skill 'web_crawler' requires network but capability is disabled

Solution:

1. Enable network in capabilities:

   [capabilities]
   network = true

2. Or use networked/full image

"Path not allowed"

Error: Path '/etc/passwd' not in allowed filesystem

Solution:

1. Add path to filesystem capability
2. Or adjust skill to use allowed paths

"Out of memory"

Error: WASM memory limit exceeded

Solution:

1. Increase memory limit:

   max_memory_mb = 256

2. Optimize skill memory usage

"Module instantiation failed"

Error: Failed to instantiate WASM module

Solution:

1. Rebuild WASM runtime
2. Check agent_runtime compilation
3. Verify wasm32-wasip1 target

API Reference

Update Container Config

curl -X PUT http://localhost:17890/api/agents/default/container \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": {
      "type": "wasm",
      "wasm": {
        "image": "networked"
      }
    },
    "capabilities": {
      "filesystem": ["./skills", "./memory"],
      "network": true,
      "max_memory_mb": 128
    }
  }'

Get Container Config

curl http://localhost:17890/api/agents/default/container

Check Capability Status

curl http://localhost:17890/api/agents/default/container/capabilities