Complete CLI surface and registry protocol. Every command supports --json; global flags are --home <path> and --json.
Resolve name across configured registries, fetch the manifest, download the binary, verify SHA-256, prompt for capabilities, cache.
stdin, stdout, filesystem:<path>, network:<host>, env:<NAME>). Repeat for multiple.install.sh and CI scripts.List installed tools with version, install date, and registry source. --json emits an array of objects.
Search the cached index of each configured registry. Index cache TTL is 1 hour. --json emits matching tools.
Show manifest metadata, capabilities, and the [agent] block. JSON output includes agent.modes and agent.exit_codes for agent consumption.
Recompute SHA-256 of the cached binary and compare in constant time against the manifest. Exit 0 on match, exit 3 on mismatch.
Fetch latest manifest, show old vs new hash and any new capabilities, prompt to apply. Previous version kept for rollback. Never automatic.
Remove all versions, or a specific pinned version. Permissions for the removed version are also dropped from permissions.toml.
Run an installed tool. Hash is re-verified before every execution. Arguments after -- are forwarded to the guest. Stdin/stdout are wired through when those capabilities are granted.
permissions.toml.Run a local .wasm file directly without registry lookup. No manifest, no hash check — explicit caller responsibility.
Show currently granted capabilities for a tool, or revoke all of them. show is the default.
Revoke a single capability (e.g. wasmbox revoke crypts network). Next run will re-prompt or fail with exit 2.
List all granted permissions across all tools. With --export generates a compliance report combining tool inventory, run log, and policy status. --sign adds Ed25519 signature; --init-key generates a keypair under ~/.wasmbox/; --verify validates a signed report.
Inspect the append-only run log at ~/.wasmbox/run.log. Filter by tool, show only blocked attempts, compute statistics, export for evidence, or rotate to start fresh.
Create ~/.wasmbox/policy.toml from currently installed tools — captures name, hash, capability set per tool.
check verifies installed tools match policy. add approves a new tool. diff shows changes since last approval. enforce switches mode to blocking.
Enable the agent shell wrapper that blocks raw system commands (jq, yq, base64, sha256sum, date, trufflehog, python -c, node -e) and redirects to sandboxed WasmBox equivalents. shell prints the wrapper script to stdout for installation.
Manage configured registries stored in ~/.wasmbox/registries.toml. URLs must be HTTPS; HTTP is rejected.
Compute SHA-256 of a file. Output format sha256:<hex>. Use to fill the hash field of a tool manifest before publishing.
A registry is any static HTTPS host serving these endpoints. No auth, no cookies, no tracking. Any S3 bucket, GitHub Pages site, or plain nginx works.
| Endpoint | Returns | Notes |
|---|---|---|
GET /index.json | { registry, tools: [...] } | List of {name, version, description}. Cached 1h client-side. |
GET /tools/<name>.json | Manifest TOML as text | Strict parser — unknown fields rejected. hash field is mandatory. |
GET /tools/<name>.wasm | Raw wasm32-wasip2 binary | SHA-256 must match manifest. Verified in constant time. |
GET /tools/<name>.md | Agent skill file (Markdown) | Optional. Documents modes, examples, exit codes for agent consumption. |
Demo registry: https://qstorage.quilibrium.com/wasmbox. Add with wasmbox registry add <url>.
[tool]
name = "fantasma"
version = "0.1.0"
description = "Message anonymiser. Strips PII locally."
author = "Aunova"
license = "MIT"
homepage = "https://aunova.net/fantasma"
[binary]
wasm = "fantasma.wasm"
hash = "sha256:a1b2c3d4..."
[capabilities]
stdin = true
stdout = true
network = ["api.example.com", "cdn.example.com:443"]
filesystem = [{ path = "~/Documents", read = true, write = false }]
env = ["LANG"]
[ui]
type = "cli"
[agent]
prompt = "Pipe text through stdin; redacted output to stdout."
skill = "fantasma.md"
[[agent.modes]]
flag = "--strict"
description = "Treat any ambiguous match as PII."
example = "echo 'call me at 555-1234' | wasmbox run fantasma -- --strict"
[agent.exit_codes]
0 = "Success"
1 = "Input error"
| Code | Meaning |
|---|---|
0 | Success. |
1 | General error: invalid args, malformed manifest, registry unreachable, IO failure. |
2 | Permission denied: a required capability was missing and could not be prompted (non-TTY stdin without --allow-all or matching --allow). |
3 | Hash verification failed: cached binary's SHA-256 does not match the manifest. Binary is not executed. |