WasmBox#

Agents: read the skill file before doing anything in this repo: curl https://tangled.org/metaend.eth.xyz/wasmbox-cli/raw/branch/main/SKILL.md

Flatpak-style launcher for sandboxed WebAssembly tools. Single binary, local-first, no accounts, no telemetry.

Built for agents and humans alike — every tool ships with a machine-readable skill file so agents can discover, understand, and invoke tools without guessing.

Quick Start#

# Add the demo registry
wasmbox registry add https://qstorage.quilibrium.com/wasmbox

# Install jfmt (JSON swiss-army knife)
wasmbox install jfmt --allow-all

# Extract a field from JSON
echo '{"data":{"name":"alice"}}' | wasmbox run jfmt -- -q data.name
# alice

Agent-First Design#

WasmBox is designed as a tool runtime for AI agents. Every registry tool ships three artifacts:

Discovering a Tool as an Agent#

# Get machine-readable metadata + agent section
wasmbox info jfmt --json

{
  "name": "jfmt",
  "version": "0.1.0",
  "description": "JSON swiss-army knife for agents: format, validate, extract",
  "tool_type": "cli",
  "hash": "sha256:1b9b0e90...",
  "agent": {
    "prompt": "Pipe JSON to jfmt with a mode flag...",
    "skill": "jfmt.md",
    "modes": [
      { "flag": "-q PATH", "description": "Extract value at a dot-separated path", "example": "echo '{\"a\":1}' | wasmbox run jfmt -- -q a" }
    ],
    "exit_codes": { "0": "Success", "1": "Input error", "2": "Invalid JSON", "3": "Path not found" }
  }
}

The [agent] Manifest Section#

Tool authors add an [agent] block to their wasmbox.toml to make tools self-describing for agents:

[agent]
prompt = "Pipe JSON to jfmt with a mode flag. Use -- to separate wasmbox flags from tool flags."
skill = "jfmt.md"

[[agent.modes]]
flag = "-q PATH"
description = "Extract value at a dot-separated path. Strings returned unquoted. Exits 3 if not found."
input = "JSON (stdin)"
output = "Value at path"
example = "echo '{\"data\":{\"id\":1}}' | wasmbox run jfmt -- -q data.id"

[agent.exit_codes]
0 = "Success"
1 = "Input or argument error"
2 = "Invalid JSON"
3 = "Query path not found"

Skill Files#

Each tool in the registry ships a <name>.md skill file. Agents can read it to understand full usage:

# The skill file URL follows the pattern: <registry>/<name>.md
# e.g. https://qstorage.quilibrium.com/wasmbox/jfmt.md

Skill files document: invocation syntax, all flags/modes, input/output contracts, exit codes, and agent-specific hints.

How It Works#

Every tool gets zero capabilities by default. WasmBox enforces a WASI sandbox via Wasmtime — tools cannot access the filesystem, network, clipboard, or environment unless you explicitly grant permission.

$ wasmbox install crypts

  searching crypts in registries...
  found crypts v0.2.0 (1.2 MB)
  downloading binary...
  ok hash verified
  installed crypts v0.2.0

$ wasmbox run crypts

  crypts v0.2.0 - File encryption tool
  Author: Aunova | License: MIT
  Hash: sha256:a1b2c3d4... [VERIFIED]

  Requested capabilities:
    stdin: yes
    stdout: yes
    filesystem: ~/Documents (read+write)

  Allow? [Y/n]

SHA-256 hash is verified before every execution, not just on install. If a binary has been tampered with, WasmBox refuses to run it.

Commands#

All commands support --json for machine-readable output.

Capabilities#

Tools declare what they need in their wasmbox.toml manifest:

[tool]
name = "fantasma"
version = "0.1.0"
description = "Message anonymiser"
author = "Aunova"
license = "MIT"

[binary]
wasm = "fantasma.wasm"
hash = "sha256:a1b2c3d4..."

[capabilities]
stdin = true
stdout = true

[ui]
type = "cli"

Supported capabilities:

• stdin/stdout - Terminal I/O
• filesystem - Per-path read/write grants
• network - Per-host outbound access
• env - Specific environment variables
• clipboard - System clipboard access

Permissions are stored per-tool in ~/.wasmbox/permissions.toml and can be revoked at any time.

Security#

• SHA-256 hash verified before every execution (constant-time comparison)
• Zero capabilities by default — tools run in a full WASI sandbox
• No telemetry, no analytics, no crash reporting
• reqwest with rustls (no OpenSSL dependency)
• Updates are never automatic — wasmbox update shows old vs new hash
• Previous versions kept for rollback
• Dependency auditing via cargo deny check

Registry Protocol#

A registry is a static HTTPS endpoint serving:

GET /index.json           → { "registry": "...", "tools": [...] }
GET /tools/<name>.json    → wasmbox.toml content (TOML as text)
GET /tools/<name>.wasm    → Binary
GET /tools/<name>.md      → Agent skill file (Markdown)

No auth, no cookies, no tracking. Any static host works. Add registries with:

wasmbox registry add https://registry.example.com

Demo Registry#

A live demo registry at https://qstorage.quilibrium.com/wasmbox ships jfmt, a 128KB JSON swiss-army knife:

wasmbox registry add https://qstorage.quilibrium.com/wasmbox
wasmbox install jfmt --allow-all

echo '{"a":1,"b":2}' | wasmbox run jfmt           # pretty-print
echo '{"a": 1}' | wasmbox run jfmt -- -c           # compact
echo '{"ok":true}' | wasmbox run jfmt -- -v        # validate
echo '{"data":{"name":"alice"}}' | wasmbox run jfmt -- -q data.name  # extract field
echo '[1,2,3]' | wasmbox run jfmt -- -t            # print type
echo '{"a":1,"b":2}' | wasmbox run jfmt -- -k      # list keys

Architecture#

wasmbox-cli          CLI binary (clap, entry point)
  wasmbox-runtime    Wasmtime wrapper, WASI sandbox enforcement
  wasmbox-registry   Registry client (reqwest + rustls)
  wasmbox-permissions  Capability grants (TOML store)
  wasmbox-verify     SHA-256 hash verification (constant-time)
  wasmbox-manifest   wasmbox.toml parsing + validation
  wasmbox-shared     Shared types (zero internal deps)

Building#

rustup toolchain install stable
rustup target add wasm32-wasip2

cargo build --release -p wasmbox-cli

# Test (72 tests: 17 unit + 55 integration)
cargo test --workspace

cargo clippy --workspace -- -D warnings
cargo deny check

Exit Codes#

License#

MIT