# Build from source
cargo build --release -p wasmbox-cli

# Add a registry
wasmbox registry add https://registry.example.com

# Install a tool
wasmbox install fantasma

# Run it (prompts for capability approval)
wasmbox run fantasma

# Run in full sandbox (zero capabilities)
wasmbox run fantasma --sandbox

# Run a local .wasm file
wasmbox run --file ./my-tool.wasm --allow stdout

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 and capabilities
`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 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 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

No auth, no cookies, no tracking. Add registries with:

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

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#

# Prerequisites
rustup toolchain install stable
rustup target add wasm32-wasip2

# Build
cargo build --release -p wasmbox-cli

# Test (44 tests: 17 unit + 27 integration)
cargo test --workspace

# Lint
cargo clippy --workspace -- -D warnings

# Audit dependencies
cargo deny check

Exit Codes#

Code	Meaning
0	Success
1	General error
2	Permission denied
3	Hash verification failed

License#

MIT

Configure Feed