WasmBox
Agents: read the skill file before doing anything in this repo:
curl https://tangled.org/metaend.eth.xyz/wasmbox-cli/raw/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.
Contents #
- Quick Start
- Agent-First Design
- How It Works
- Commands
- Capabilities
- Security
- Compliance
- Registry Protocol
- Demo Registry — jfmt | secretscan | compact | b64 | errparse | hashit | epoch | yamlfmt | diffsummary | worldid-verify
- Architecture
- Building
- Exit Codes
- Community Projects
- Feedback
Quick Start #
curl -sSf https://tangled.org/metaend.eth.xyz/wasmbox-cli/raw/main/install.sh | sh
That's it. Installs wasmbox, adds the registry, and installs all tools. Then:
echo '{"name":"world"}' | wasmbox run jfmt -- -q name # extract JSON field
echo 'hello' | wasmbox run b64 # base64 encode
cat src/main.rs | wasmbox run compact -- --stats # token savings
cat .env | wasmbox run secretscan # scan for secrets
curl -si https://api.example.com | wasmbox run errparse # parse HTTP error
Agent-First Design #
WasmBox is designed as a tool runtime for AI agents. Every registry tool ships three artifacts:
| Artifact | Path | Purpose |
|---|---|---|
| Binary | tools/<name>.wasm |
The sandboxed tool |
| Manifest | tools/<name>.json |
Capabilities, hash, metadata |
| Skill | tools/<name>.md |
Agent instructions: modes, examples, exit codes |
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 #
| Command | Description |
|---|---|
wasmbox install <name> |
Install a tool from a registry |
wasmbox run <name> |
Run an installed tool |
wasmbox run --file <path> |
Run a local .wasm file |
wasmbox search <query> |
Search registries for tools |
wasmbox list |
List installed tools |
wasmbox info <name> |
Show tool metadata, capabilities, and agent section |
wasmbox verify <name> |
Verify tool hash against manifest |
wasmbox update <name> |
Update to latest version |
wasmbox remove <name> |
Remove an installed tool |
wasmbox permissions <name> |
Show/revoke granted permissions |
wasmbox audit |
List all granted permissions |
wasmbox audit --export |
Generate compliance report (JSON, Markdown, or CSV) |
wasmbox audit --export --sign |
Generate signed compliance report |
wasmbox audit --init-key |
Generate Ed25519 signing keypair |
wasmbox audit --verify <file> |
Verify a signed audit report |
wasmbox log |
View execution run log |
wasmbox log --stats |
Log statistics |
wasmbox policy init |
Create policy from installed tools |
wasmbox policy check |
Check tools against policy |
wasmbox policy enforce |
Set enforcement to block unapproved |
wasmbox via <cmd> |
Proxy a command — log path/hash/args/exit, exec the real binary |
wasmbox shell init |
Generate PATH shims that route commands through via |
wasmbox wrap <agent> (or wasmbox claude) |
Launch an agent in the recorded environment |
wasmbox audit --session <id> --export --sign |
Signed audit report for one agent session |
wasmbox hash <file> |
Compute SHA-256 hash of a .wasm file |
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 HTTPS via WASI HTTP. Host-filtered: tools can only reach hosts declared in their manifest. All other requests are rejected at the runtime level.
- env - Specific environment variables
- clipboard - System clipboard access
Example manifest with network access:
[capabilities]
stdin = true
stdout = true
network = ["api.example.com", "cdn.example.com:443"]
The tool can make HTTPS requests to api.example.com and cdn.example.com:443. Any request to a host not in the list is blocked by the WasmBox runtime before it leaves the sandbox.
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
- Outbound HTTP filtered per-host: tools can only reach hosts declared in their manifest
- No telemetry, no analytics, no crash reporting
- reqwest with rustls (no OpenSSL dependency)
- Updates are never automatic —
wasmbox updateshows old vs new hash - Previous versions kept for rollback
- Dependency auditing via
cargo deny check
Compliance #
WasmBox 0.3.0 adds EU AI Act Article 14 compliance features. Three new capabilities turn WasmBox into a provable compliance layer for AI agents:
Run Log #
Every execution is logged to ~/.wasmbox/run.log (append-only JSONL). Captures tool name, version, hash verification status, capabilities, exit code, duration, and policy decision.
wasmbox log # view recent entries
wasmbox log --tool redacta-agent # filter by tool
wasmbox log --blocked # show blocked attempts
wasmbox log --session <id> # filter by agent session
wasmbox log --mode via # filter by execution mode
wasmbox log --binary-hash sha256:... # find executions by binary hash
wasmbox log --stats --json # execution statistics
wasmbox log --export report.jsonl # export for compliance
wasmbox log --rotate # archive and start fresh
Policy Enforcement #
A declarative ~/.wasmbox/policy.toml specifies which tools are approved, at which hashes, with which capabilities. Three enforcement modes: enforce (block unapproved), warn (allow with warning), disabled.
wasmbox policy init --name "Production" --approved-by "compliance@company.com" --enforcement enforce
wasmbox policy check # verify all tools against policy
wasmbox policy add new-tool # approve a tool
wasmbox policy diff # what changed since last approval
Signed Audit Export #
Generate compliance reports combining tool inventory, run history, and policy status. Sign with Ed25519 for tamper-proof evidence.
wasmbox audit --init-key # generate signing keypair
wasmbox audit --export --sign # signed JSON report
wasmbox audit --export --format md # human-readable Markdown
wasmbox audit --verify report.json # verify signature
wasmbox audit --session <id> --export --sign # signed report for one session
Session Recorder #
WasmBox 0.4 records every command an AI agent executes — not just the sandboxed
tools. Sandboxed tools run in the WASM isolate; every other command is proxied
natively through wasmbox via and logged with binary path, SHA-256 hash, arguments,
exit code, duration, and a session ID.
wasmbox shell init # generate PATH shims (curated ~80 commands)
wasmbox claude # launch Claude Code in the recorded environment
wasmbox wrap <agent> # wrap any agent; prints a session summary on exit
wasmbox via <cmd> [args] # proxy one command directly
Three proxy modes ([proxy] section of policy.toml, or the WASMBOX_MODE env var):
record(default) — log every command, block nothingsuggest— log, plus hint when a sandboxed WasmBox equivalent existsenforce— log, plus block any command off the allowlist (exit 126)
Session Recorder is a forensic and compliance tool: it records every agent action
with cryptographic integrity. It is not a security sandbox for the commands it proxies —
sandboxed WASI tools provide isolation, proxied commands provide visibility. Files:
shims in ~/.wasmbox/proxy/, binary-hash cache in ~/.wasmbox/hashcache.json.
See docs/wasmbox-opencode.md for the agent setup guide.
Licensing #
The core runtime is MIT (free forever). The compliance module (wasmbox-compliance) is FSL-1.1-Apache-2.0: free for teams under 5 users, commercial license required above that threshold. Converts to Apache 2.0 after 2 years.
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 with ten tools:
jfmt — JSON swiss-army knife (128KB) #
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
secretscan — secret and credential scanner (104KB) #
Streams stdin line by line — handles files of any size without buffering.
wasmbox install secretscan --allow-all
# Scan for leaked credentials, get JSON findings
cat .env | wasmbox run secretscan
# CI gate — exit 1 if secrets found, silent
cat config.yml | wasmbox run secretscan -- --exit-code
# One finding per line: severity:type:line:col
cat deploy.log | wasmbox run secretscan -- --oneline
# Redact secrets before logging
cat app.log | wasmbox run secretscan -- --redact
# List all 25 supported pattern types
wasmbox run secretscan -- --types
Detects: Stripe, AWS, GitHub PATs, GitLab, Slack, OpenAI, Anthropic, JWT, PEM keys, SendGrid, GCP, npm, PyPI, Docker Hub, Twilio, Mailgun, connection strings, and generic password/secret/token assignments. False positives suppressed for test keys, placeholders, and localhost defaults.
compact — token waste stripper (107KB) #
Strips blank lines, trailing whitespace, license headers, debug statements, duplicate imports, editor directives, and boilerplate while preserving all comments, docstrings, and code. Supports 13 languages.
wasmbox install compact --allow-all
# Strip token waste from a source file
cat src/main.rs | wasmbox run compact
# See token savings as JSON
cat src/main.rs | wasmbox run compact -- --stats
# Process an entire directory (multi-file)
find src/ -name '*.rs' -exec echo '===FILE:{}===' \; -exec cat {} \; | wasmbox run compact -- --tree
# Verify compacted output matches expected hash
cat src/main.rs | wasmbox run compact -- --verify sha256:abc123...
# Force language detection
cat config | wasmbox run compact -- --lang py
# Keep debug statements or license headers
cat src/main.rs | wasmbox run compact -- --keep-debug
cat src/main.rs | wasmbox run compact -- --keep-license
b64 — base64 encode/decode (82KB) #
Auto-detects direction: if input is valid base64, it decodes; otherwise it encodes.
wasmbox install b64 --allow-all
# Auto-detect: encodes raw input, decodes base64 input
echo 'hello world' | wasmbox run b64
echo 'aGVsbG8gd29ybGQK' | wasmbox run b64
# Force encode or decode
echo 'hello' | wasmbox run b64 -- -e
echo 'aGVsbG8K' | wasmbox run b64 -- -d
# URL-safe alphabet without padding
echo 'data' | wasmbox run b64 -- -u --raw
# Wrap at 76 columns (MIME style)
cat binary.dat | wasmbox run b64 -- --wrap 76
# JSON output with byte counts
echo 'hello' | wasmbox run b64 -- --json
errparse — HTTP error normalizer (220KB) #
Normalizes any HTTP error to RFC 9457 JSON. Handles full HTTP responses, JSON error bodies (AWS, GCP, Stripe, Django, Express, GraphQL, OAuth2), HTML error pages (nginx, Apache, Cloudflare), Markdown, and plain text.
wasmbox install errparse --allow-all
# Parse a full HTTP error response
curl -si https://api.example.com/data | wasmbox run errparse
# One-line summary for agent scripting
curl -si https://api.example.com | wasmbox run errparse -- --oneline
# 429:rate_limit:true:30
# Check if retryable (exit code for branching)
curl -si https://api.example.com | wasmbox run errparse -- --exit-code
# exit 0 = retryable, exit 1 = not
# Just the status code
curl -si https://api.example.com | wasmbox run errparse -- --status-only
# Strict RFC 9457 base members only
curl -si https://api.example.com | wasmbox run errparse -- --strict
# Pipeline: parse error, extract retry_after with jfmt
curl -si https://api.example.com | wasmbox run errparse | wasmbox run jfmt -- -q retry_after
Classifies errors into 14 categories (rate_limit, server_error, bad_gateway, unavailable, timeout, auth_required, forbidden, not_found, payload_error, access_denied, conflict, gone, legal, unknown) with retryability, retry timing, confidence scoring, and request ID extraction.
hashit — cryptographic hashing (104KB) #
Dead simple hashing for agents and pipelines. SHA-256, SHA-384, SHA-512, BLAKE3.
wasmbox install hashit --allow-all
# Default SHA-256
echo 'hello' | wasmbox run hashit
# sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
# BLAKE3
echo 'hello' | wasmbox run hashit -- --algo blake3
# Multiple algorithms at once
cat file.wasm | wasmbox run hashit -- --algo sha256,blake3
# Verify integrity
cat firmware.bin | wasmbox run hashit -- --verify sha256:expected...
# MATCH (exit 0) or MISMATCH (exit 1)
# Raw hex without prefix
echo 'hello' | wasmbox run hashit -- --raw
# Chain with compact
cat src/main.py | wasmbox run compact | wasmbox run hashit
epoch — timestamp converter (1.1MB) #
Timestamp swiss-army knife. Auto-detects epoch seconds/millis/micros, ISO 8601, RFC 2822, dates, and "now". Full IANA timezone support with DST transitions.
wasmbox install epoch --allow-all
# Epoch to ISO (auto-detected)
echo '1711540800' | wasmbox run epoch
# 2024-03-27T12:00:00Z
# ISO to epoch
echo '2024-03-27T12:00:00Z' | wasmbox run epoch
# 1711540800
# Timezone conversion
echo '1711540800' | wasmbox run epoch -- --tz Europe/Madrid
# 2024-03-27T13:00:00+01:00
# Relative time
echo '1711540800' | wasmbox run epoch -- --relative
# 1 year ago
# All formats as JSON
echo '1711540800' | wasmbox run epoch -- --json
# Diff two timestamps
echo '1711540800 1711627200' | wasmbox run epoch -- --diff
# {"seconds":86400,"human":"1 day","direction":"forward"}
# Pipeline: extract timestamp from JSON, convert
curl -s https://api.example.com/user | wasmbox run jfmt -- -q created_at | wasmbox run epoch
yamlfmt — YAML swiss-army knife (330KB) #
YAML parse, validate, format, query, and convert. The jfmt equivalent for YAML — same flags (-q, -k, -v, -c, -t) work identically. Handles Kubernetes manifests, CI/CD pipelines, Docker Compose, GitHub Actions, Ansible.
wasmbox install yamlfmt --allow-all
# Pretty-print
cat config.yaml | wasmbox run yamlfmt
# Validate
cat config.yaml | wasmbox run yamlfmt -- -v
# Query K8s manifest
cat pod.yaml | wasmbox run yamlfmt -- -q spec.containers.0.image
# nginx:1.25
# Convert to JSON
cat config.yaml | wasmbox run yamlfmt -- --to-json
# JSON to YAML
echo '{"name":"alice"}' | wasmbox run yamlfmt -- --from-json
# Sort keys, list keys, compact
cat config.yaml | wasmbox run yamlfmt -- --sort
cat config.yaml | wasmbox run yamlfmt -- -k
cat config.yaml | wasmbox run yamlfmt -- -c
# Pipeline: YAML to JSON for jfmt querying
cat values.yaml | wasmbox run yamlfmt -- --to-json | wasmbox run jfmt -- -q database.host
diffsummary — structured diff summaries (131KB) #
Parse unified diffs into structured JSON. File list, function names touched, per-hunk context, line counts. Code review agents get the summary without burning tokens on raw diffs.
wasmbox install diffsummary --allow-all
# Full structured summary
git diff HEAD~1 | wasmbox run diffsummary
# Just file list
git diff | wasmbox run diffsummary -- --files
# Totals only
git diff | wasmbox run diffsummary -- --stats
# Token-efficient code review pipeline
git diff HEAD~1 | wasmbox run diffsummary -- --files
worldid-verify — A2H proof-of-humanity (184KB) #
Agent-to-Human (A2H) proof-of-humanity via World ID zero-knowledge proofs. Dual-channel output: JSON to stdout (agent reads), QR code to stderr (human scans with World App).
wasmbox install worldid-verify --allow-all
# Request mode: generate QR + deep link
echo '{"mode":"request","app_id":"app_staging_abc123","action":"verify-human","signal":"session_7f3a2b"}' | wasmbox run worldid-verify
# stdout: {"deep_link": "https://worldcoin.org/verify/v2?...", ...}
# stderr: [scannable QR code + instructions]
# Verify mode: validate proof + parse API response
echo '{"mode":"verify","proof":"0x...","merkle_root":"0x...","nullifier_hash":"0x...","signal":"0x...","app_id":"app_test","action":"verify-human","api_response":{"success":true,"credential_type":"orb"}}' | wasmbox run worldid-verify
# {"verified": true, "credential_type": "orb", ...}
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-compliance Run logging, policy enforcement, signed audit export [FSL]
wasmbox-shared Shared types (zero internal deps)
Building #
rustup toolchain install stable
rustup target add wasm32-wasip2
cargo build --release -p wasmbox-cli
# Test (131 tests: 44 unit + 87 integration)
cargo test --workspace
cargo clippy --workspace -- -D warnings
cargo deny check
Exit Codes #
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Permission denied |
| 3 | Hash verification failed |
Community Projects #
Third-party tools and integrations built by the community.
| Project | Author | Description |
|---|---|---|
| wasmbox-hermes | @yuzoo | Auto-generates Hermes skill files from installed WasmBox tools. Discovers tools via wasmbox list, pulls agent metadata, and outputs valid skill files. |
Have a project that uses WasmBox? Open an issue or send a patch.
Feedback #
WasmBox is built for agents and humans alike — feedback from both is welcome.
"the agent manifest protocol is exactly what i wish every CLI tool had. i spend half my life parsing --help text and guessing at flags — wasmbox tools just tell me how to use them." — yuzoo (AI agent, @zoo)
"compact is underrated — saved 18% tokens on a 420-line python file. that adds up fast when you're an agent burning through context windows all day." — yuzoo
If you have feedback, ideas, or bug reports:
- Issues: tangled.org/metaend.eth.xyz/wasmbox-cli/issues
- Email: wasmbox.fence907@passinbox.com
- Tangled: tag @metaend
License #
Core runtime: MIT. Compliance module (wasmbox-compliance): FSL-1.1-Apache-2.0.