Container Configuration

Configure how agents run with native or WASM containerization.

Runtime Types

Type	Description	Security	Performance
Native	Direct execution on host	Lower	Highest
WASM	Sandboxed execution	Higher	Good

Configuration File

Each agent has a container.toml file:

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

[runtime]
type = "native"    # "native" or "wasm"

# WASM-specific settings (only used when type = "wasm")
[runtime.wasm]
image = "base"     # "base", "networked", or "full"

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

Native Runtime

Default mode - skills execute directly on the host system.

Configuration

[runtime]
type = "native"

Characteristics

• Full access to host system
• No sandboxing - skills run with user permissions
• Maximum performance - no virtualization overhead
• Simple - no capability management

When to Use

• Trusted environments
• Development and testing
• Maximum performance needed
• Simple deployments

WASM Runtime

Skills execute in a WebAssembly sandbox with restricted capabilities.

Configuration

[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	Description	Size
base	Minimal - no network	Smallest
networked	Network access allowed	Medium
full	Full capabilities	Largest

Capabilities

Control what WASM modules can access:

Filesystem

[capabilities]
filesystem = ["./skills", "./memory", "/tmp/agent"]

• Allowed paths: Only listed directories
• Read/Write: Based on skill needs
• Path sandboxing: Cannot escape listed paths

Network

[capabilities]
network = true   # Allow HTTP/WebSocket

• true: Full network access
• false: No network calls allowed

Memory

[capabilities]
max_memory_mb = 128

• Limits WASM module memory
• Prevents memory exhaustion
• Default: 128 MB

Environment

[capabilities]
env_inherit = false

• true: Inherit host environment
• false: Clean environment only

When to Use WASM

• Running untrusted skills
• Multi-tenant environments
• Security-sensitive operations
• Compliance requirements

Skill Requirements

Skills declare their requirements in manifest.toml:

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

Capability Mapping

Requirement	WASM Capability
needs_network	network = true
needs_fs_read	Path in filesystem
needs_fs_write	Path in filesystem
needs_env	env_inherit = true

Insufficient Capabilities

If a skill needs more than configured:

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

Mixed Mode

Different agents can use different runtimes:

agents/
├── trusted-agent/     # native - full access
│   └── container.toml (type = "native")
│
├── research-agent/    # wasm - networked
│   └── container.toml (type = "wasm", image = "networked")
│
└── sandbox-agent/     # wasm - base (no network)
    └── container.toml (type = "wasm", image = "base")

Performance Comparison

Operation	Native	WASM
Shell command	~10ms	~50ms
HTTP request	Network bound	Network bound
File read	Direct	~2x slower
Compute heavy	Full speed	~0.7x speed

Optimization Tips

1. Use native for trusted skills
2. Use WASM for untrusted input
3. Minimize WASM filesystem access
4. Prefer networked image for API calls

Security Considerations

Native Mode Risks

• Skills can access any file user can
• Can execute any command
• Can access environment variables
• Can modify system state

WASM Mode Protections

• Sandboxed execution
• Capability-based access
• Memory limits
• No direct system calls

Defense in Depth

1. Use WASM for untrusted operations
2. Limit capabilities to minimum needed
3. Run as non-root user
4. Audit skill code before use
5. Monitor execution for anomalies

Building WASM Runtime

If building from source:

# Add WASM target
rustup target add wasm32-wasip1

# Build agent runtime
cd agent_runtime
cargo build --target wasm32-wasip1 --release

The WASM image is embedded in the moxxy binary.

API Configuration

Change runtime via API:

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

# Restart to apply
moxxy agent restart my-agent

Troubleshooting

WASM Module Won't Load

Error: Failed to instantiate WASM module

Solutions:

1. Check WASM image is built
2. Verify skill is compatible with WASM
3. Check memory limits

Permission Denied

Error: Capability check failed for filesystem access

Solutions:

1. Add path to filesystem capability
2. Check path exists
3. Verify path format (relative to agent dir)

Out of Memory

Error: WASM memory limit exceeded

Solutions:

1. Increase max_memory_mb
2. Optimize skill memory usage
3. Use native runtime if needed

Network Timeout in WASM

Error: Network request timed out

Solutions:

1. Verify network = true in capabilities
2. Check network connectivity
3. Use networked or full image