▲ Bunbox (@bunboxnode/bunbx)

Bunbox (@bunboxnode/bunbx) is a security-first package manager and Model Context Protocol runtime for AI agents and autonomous coding assistants.

It exists because traditional package managers assume a human operator can vet dependencies, react to advisories, and spot malicious packages before execution. Bunbox replaces that assumption with a zero-trust workflow:

1. Cryptographic identity through decentralized DIDs.
2. Capability declarations that state what a package can access.
3. Static auditing that blocks undeclared network, filesystem, eval, and command execution.
4. Immutable witness logging that anchors releases to a transparent provenance trail.

---

🏛️ System Architecture

Bunbox bridges secure source control, package registries, and agent execution runtimes. The diagram below illustrates how code flows from development to agent execution under cryptographic validation and sandbox checks:

flowchart TD
    %% Developer Flow
    subgraph Dev ["Developer Environment"]
        id[Generate did:key Identity] --> sign[Cryptographically Sign Package]
        src[Source Code + manifest] --> build[Build Artifacts]
    end

    %% Provenance & Registry
    subgraph Trust ["Provenance & Registry Layer"]
        gl[Gitlawb Network] -->|Issues Build Receipt| cert[UCAN Authorization Token]
        pub[Registry Endpoint] -->|Ledger Record| wit[Append-Only Witness Ledger]
    end

    %% Package Delivery
    subgraph Client ["Agent Runtime (Local CLI)"]
        npm[NPM Registry / @bunboxnode/bunbx] --> install[Bunbox Local CLI Sandbox]
        install --> audit[Static Capability Scanner]
        audit --> check{Declared vs Actual?}
        check -->|Violation or Secret Leak| Block[Block Installation & Alert Agent]
        check -->|Approved & Verified| sandbox[Secure bunbox_modules/]
    end

    %% Integrations
    subgraph Agents ["AI Assistant Integrations"]
        mcp[Bunbox MCP Server] -->|Exposes Tools| claude[Claude Desktop / Claude Code]
        sandbox --> mcp
    end

    %% Connectors
    sign --> gl
    build --> gl
    cert --> pub
    pub --> npm
    wit -->|Checkpoint Verification| install

Loading

---

🔒 The Cryptographic Provenance Standard

Bunbox anchors all package authorship in decentralized identities and signed release metadata:

1. DID Identities (did:key): Publishers generate a local Ed25519 keypair. The public key is encoded into a W3C-compliant DID (e.g. did:key:z6Mkp52AN6L...) using Base58 multicodec formatting.
2. Payload Attestation: When publishing, the author signs a payload containing the package name, version, files digest, declared permissions, and git commit ID.
3. Gitlawb Receipts: Source code build receipts and UCAN delegation proofs guarantee that the compiled code matches the declared repository and commit.
4. Witness Checkpoints: Package listings are backed by an append-only witness transparency ledger. Each release is structured in cryptographic blocks containing prevHash, timestamp, and the release digest.

---

🔍 Sandboxed Static Capability Audits

Before any package is written to the local workspace (bunbox_modules/), the Bunbox static analyzer scans every file's source code against the declared capability permissions in the package manifest.

Capability Detection Patterns

Bunbox flags undeclared system accesses using high-fidelity regex matching:

Capability	Detected APIs & Keywords	Description
network	fetch(, http.request(, https.request(, socket, ws:, wss:	Outbound network requests, WebSockets, or raw socket creation.
fs_read	fs.readFile, fs.createReadStream, fs.promises.readFile, fs.read	Host filesystem read operations.
fs_write	fs.writeFile, fs.createWriteStream, fs.promises.writeFile, fs.mkdir, fs.rm	Host filesystem write or delete operations.
unsafe_eval	eval(, new Function(	Dynamic string execution.
commands	child_process, exec(, spawn(, fork(, execSync	Subprocess execution or terminal command spawning.

Hardcoded Secret & Token Leak Detection

Bunbox scans all package files for inadvertent API keys, tokens, or credential leaks using high-entropy key heuristics:

• Pattern: api[-_]?key|secret|token|password|bk_[a-zA-Z0-9_]{16,}
• Assignment: Detects direct assignment string literals (e.g. const API_KEY = "bk_...").
• Severity: Automatically treated as a CRITICAL advisory, blocking publication or installation instantly.

---

🛠️ CLI Installation & Complete Reference

Global Installation

To install the global CLI client, run:

bun install -g @bunboxnode/bunbx

This maps both the bunbx and bunbox executable commands to your PATH.

---

📖 Command Reference

bunbx <command> [options]

Core Security Commands

• search <query> [--online] Search the verified registry locally or against the live endpoint. Returns name, version, declared capabilities, and description.

  bunbx search file-reader --online

• view <package> Retrieve package metadata including publisher DID, commit hash, capability list, and digest.

  bunbx view web-searcher

• inspect <specifier> Perform deep trust validation of a package or PURL. Verifies the Ed25519 signature, DID origin, and advisory quarantine log.

  bunbx inspect web-searcher@1.0.0
  # Or inspect via canonical PURL:
  bunbx inspect pkg:did:key:z6Mkp52AN6L6AymVvV9bVJfmt5UG3Lwrx7JUm2VPfcTG2bJF/web-searcher@1.0.0

• provenance [--provenance URL] [--canonical PURL] [--digest hash] Verify Gitlawb source proofs, Merkle root integrity, and witness ledger anchorage checks.

  bunbx provenance --source-commit 6c04f95... --digest 8d65da8...

• install <package> [--plan] [--json] Resolve a package dependency graph and install files inside bunbox_modules/.
  • --plan: Preview the install plan, including signatures and declared sandbox capabilities.
  • --json: Output the plan structure as machine-readable JSON.

  bunbx install file-reader --plan

• audit [--online] Scan local workspace files and bunbox-lock.json for unannounced capability breaches or active advisories.

  bunbx audit --online

• ci [--online] Enforces strict audit standards for automated build pipelines. Exits with exit code 1 if any capability anomalies or critical advisories are found in the local setup.

  bunbx ci --online

• sbom Export the full Software Bill of Materials (SBOM) as JSON.

  bunbx sbom

• explain <package> Explain why a package is present in the local directory, displaying its signature, integrity hash, and capability scope.

  bunbx explain file-reader

• doctor Diagnose connection status, verify registry endpoints, resolve well-known manifests, and confirm witness checkpoint health.

  bunbx doctor

Publisher Commands

• init --name <package> Scaffold a secure, sandboxed custom agent package. Generates package.json, index.js, and default identity parameters.

  bunbx init --name my-secure-evaluator

• manifest validate [--json] Validate a package's configuration, metadata, and capability manifests before submitting to registries.

  bunbx manifest validate

• identity [new|show] Generate or view your developer DID identity profile inside ~/.gitlawb/.

  bunbx identity new

• register Sign and submit a DID payload to the Gitlawb network to receive your UCAN publishing delegation authorization.

  bunbx register

• publish <dir> [--dry-run] Publish your secure package directly to the registry server. Signs the payload, uploads indices, and seals the block on the append-only witness ledger.

  bunbx publish . --dry-run

---

🧠 AI Chat — Powered by Gitlawb's OpenGateway

Talk to AI directly from your terminal. Bunbox integrates with Gitlawb's OpenGateway — a unified API gateway for frontier AI models — giving you instant access to powerful language models without leaving your workflow.

Quick Usage

# One-shot message
bunbx chat "explain how merkle trees work"

# Interactive conversation (with full history)
bunbx chat

# Use a specific model
bunbx chat "hello" --model mimo-v2.5-pro

# Stream the response token-by-token
bunbx chat "write a haiku about security" --stream

Configuration

Option	Description	Default
--model <name>	Choose the AI model to use	mimo-v2.5-pro
--stream	Stream response tokens in real-time	false

Set your API key via environment variable:

export OPENGATEWAY_API_KEY="ogw_live_..."

💡 Get your API key at opengateway.gitlawb.com to start chatting with AI models through Bunbox.

---

🤖 Integrate as a Model Context Protocol (MCP) Server

Bunbox functions natively as an Model Context Protocol (MCP) server, permitting AI agents to securely query the registry and verify files in real-time.

Claude Desktop Integration

Locate your local Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following block to register the Bunbox server:

{
  "mcpServers": {
    "bunbox": {
      "command": "bunbx",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code CLI Integration

To integrate Bunbox inside a Claude Code CLI session, run the following command directly in your shell:

claude mcp add bunbox -- bunbx mcp serve