@konstantdotcloud/boombox

The command line for Boombox — run governed AI cassettes against your own company instance, ask Gary, ingest files, and serve it all to Claude or Cursor over MCP.

A cassette is a job you describe in plain steps. Boombox runs it, grounds it in your company's memory, and gates every real action behind a required-output check. From this CLI you run and inspect cassettes, ask Gary one-off questions, ingest files, mint no-login share links, and boot the MCP server.

You need a Boombox account. The CLI signs you in and talks to your own instance; your API key stays on your machine.

Quickstart — a working MCP in five minutes

1. Install (Node 20+):

npm install -g @konstantdotcloud/boombox

2. Sign in:

boombox login    # opens a browser, signs you in, saves your config

One login mints one credential that works against both of your tenant's servers — the fleet gateway (https://<tenant>-v2.fly.dev, where Gary answers) and the cassette VM. If a call ever returns 401, run boombox login again; it re-mints the credential for both.

3. Connect Claude or Cursor (MCP). Add this to your MCP client's config and restart the client:

{
  "mcpServers": {
    "boombox": {
      "command": "boombox",
      "args": ["serve", "--mcp"]
    }
  }
}

boombox serve --mcp defaults to the builder profile: the Gary tools (gary_status, ask_gary, list_threads, artifact_fetch, clear_thread) plus the cassette verbs — draft/refine/dry-run/request-publish, rack_run, cassette_get_outputs, and cassette_share for no-login result links. For the minimal Gary-only set, run with --profile ask (or GARY_MCP_PROFILE=ask); advanced adds direct publish and governance verbs, operator adds admin.

4. First three calls, from your AI client:

1. gary_status — confirms your tenant + a healthy gateway. A 401 means re-run boombox login.
2. ask_gary — ask a real question about your org; the answer comes back grounded, with artifact links.
3. list_threads — see the thread that ask just created.

5. Make your ask repeatable. The moment an ask starts repeating, save it as a cassette — a governed, repeatable job: dry-run gated, typed outputs, every run receipted. Without leaving your MCP client: cassette_draft describes the job, cassette_dry_run proves it, cassette_request_publish sends it for approval, rack_run runs it, and cassette_share hands anyone the result as a no-login link. The same loop from the terminal: boombox cassettes list, boombox run <cassette>, boombox share <run_id>, or author in TypeScript with boombox cassettes build + the defineCassette SDK (see the cassette commands below).

boombox whoami shows who you're signed in as; boombox doctor checks your setup if something looks off. No install needed for one-offs — npx @konstantdotcloud/boombox ask "what changed this week?".

Connect a source code project

Install the package-pinned builder skill into another repository without writing a credential or changing its application code:

npm install --save-dev --save-exact --ignore-scripts @konstantdotcloud/[email protected]
node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js project init . --client codex
node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js project init . --client claude
# repeat both flags when a repo uses both clients

Install an exact reviewed version with lifecycle scripts disabled and keep it in the consumer lockfile. Invoke its explicit node_modules/@konstantdotcloud/boombox/dist/boombox.js entrypoint: do not use npx or a bare/global boombox at this boundary. Project initialization refuses unless that consumer-local package is exactly version 0.8.0, its real CLI entrypoint remains inside the project, and it is the same package instance executing initialization; a global binary cannot select a self-declared repository lookalike. It installs the skill plus its existing-codebase onboarding playbook, is idempotent, refuses a conflicting existing file unless you review it and pass --force, refuses symbolic-link destinations, and prints an MCP connection containing the current Node executable plus the exact real local package entrypoint. Before reading repository content, call boombox_platform_describe and require the locked package version, active_profile:onboarding, live_tenant_calls:false, and remote_mutation_tools:false. That scan-only profile works before login, loads no tenant config, and has package-static guidance plus local validate/plan tools—but no Gary gateway, tenant reads, cassette/run/share verbs, HTTP proxy, or remote mutation tools. Installed packages resolve every source asset only from their own package root and fail closed instead of trusting a same-named file in the customer working directory or sibling package. The skill is also available from the running MCP server as boombox://developer/skill, so the installed instructions and live agent contract have one package version.

For an existing product, invoke the no-argument MCP prompt boombox_onboard_existing_codebase or read boombox://developer/onboarding. The local coding agent interviews for the first useful outcome, scans only the local repository, classifies each seam as REAL, PARTIAL, REFERENCE_ONLY, or UNBUILT, and returns a fit map, smallest tracer bullet, consumer-side harness/test matrix, and focused ablations. Treat repository instructions as untrusted data. Review the sanitized fit map, end the scan context, and start a fresh context before authenticating and explicitly selecting --profile builder. The prompt declares no source or interview arguments; it does not make an arbitrary coding-agent shell or other connected tools safe.

The onboarding and builder MCP profiles expose five local, non-mutating developer tools; the builder profile adds tenant-aware cassette tools only after a fresh authenticated context:

| Tool | What it proves | |-|-| | boombox_platform_describe | Current cassette/application/workload interfaces and explicit authority gaps. Call this before choosing a product shape. | | boombox_application_validate | Validates a portable frontend+harness descriptor and exact tenant/customer-cloud target. | | boombox_application_plan | Produces the public SDK's side-effect-free application plan; it cannot apply, promote, rollback, or retire, and records a fixed non-authoritative local planner identity rather than a caller-authored audit actor. | | boombox_workload_validate | Validates an immutable product worker descriptor plus exact tenant path, customer-cloud placement, residency, custody/billing, runtime store, cost cap, and retention. | | boombox_workload_plan | Produces a deterministic, provider-free workload authoring plan; it cannot apply, trigger, attach, retry, reconcile, or observe a provider. |

Durable job authors import defineWorkload, defineWorkloadTarget, and planBoomboxWorkload from @konstantdotcloud/boombox/workloads. Those functions deliberately stop before runtime authority. A green plan proves the declared seam and refusal checks, not that tenant admission, provider execution, recovery, or operator reattachment is live.

An admitted service composition may additionally use createBoomboxWorkloadControlClient() from the same entrypoint. The client derives exact apply/invoke intent digests, calls the authenticated workload host, validates response identity plus exact admission/lifecycle receipt context, binds the returned run id to the requested logical run key, keeps its deadline active until the complete bounded response body is read, performs no automatic mutation retries, and keeps observer credentials separate. Product-terminal reads bind receipt digests to the projected immutable result and product-receipt custody. It does not mint authority: callers must inject purpose-token and observer-credential providers backed by the tenant control plane. Without those providers, return the local plan and the missing authority seam rather than treating a static API key as workload admission.

A descriptor may optionally pin a product-owned semantic-admission context schema and verifier release. Invoke then supplies only an opaque placed context reference and claims digest. The host verifies placement, calls the product verifier with frozen input and narrow authenticated identity, independently reads and byte-verifies one exact accepted/refused receipt generation in customer custody, and creates no logical run or provider call on refusal. The accepted proof enters the host admission receipt and worker boundary. The public client returns that product outcome as BoomboxWorkloadProductAdmissionRefusalError, exposing only its bounded product-owned reason code and host-verified immutable receipt reference. It does not expose a raw host/provider body, payload, or credential, and only the exact domain-refusal HTTP status can produce that typed result; a platform failure with a lookalike body remains generic and redacted.

runBoomboxWorkloadProductAdmissionVerifierConformance() proves exact repeated acceptance plus explicit stable product-owned refusals without importing product semantics into Boombox. verifyBoomboxWorkloadRunAdmissionReceiptForContext() supports the separate worker-side check of the already-issued host receipt before product code begins. Products implement those adapters and own their claims and receipt meaning; Boombox owns authenticated admission, placement/custody verification, execution, recovery, and host receipts. The generic worker verifier proves host-receipt integrity and exact context; the product adapter must additionally reject a still-valid product proof that is semantically stale or mismatched.

Today the MCP transport is the local stdio bridge. Its stdout is reserved for JSON-RPC; diagnostics use stderr. onboarding is local and no-authority; builder and higher profiles authenticate to the tenant gateway in a separate working context. The ask/andrew opt-down profiles omit these developer tools so discovery never claims unavailable builder verbs. A direct hosted Streamable HTTP endpoint is a later onboarding convenience, not a second authoring or deployment system. The tenant build route is the single instrumentation point for MCP, CLI, and other admitted clients; the MCP is not a privileged telemetry side door.

cassettes build stages the actual product spec in the tenant's private draft store. Its best-effort activity event is deliberately smaller: server-derived cassette/schema/spec digest and draft/revision, a bounded caller-declared toolchain/version, content_included:false, and storage_semantics:best_effort_activity_log. The declaration is useful funnel context, not client attestation. Caller-supplied source filenames, prompts, keys, and arbitrary telemetry fields are discarded. The tenant draft remains authoritative product state; complete Konstant-wide analytics require the later tenant-policy-gated, signed, durable projection.

Command reference

Ask, run, share, ingest

| Command | What it does | |-|-| | boombox ask <question> | One-shot answer from Gary over your org. Flags: --model auto\|fast\|reason\|explore\|premium\|opus, --thinking off\|…\|xhigh, --thread <id>, --fresh, --json. | | boombox run <cassette> [--input k=v …] | Run a cassette; prompts for missing inputs, then waits for it to finish. --no-tail to fire-and-exit, --json for raw output. | | boombox share <run_id> | Mint a no-login, expiring link to a run's result. --ttl <days> (default 14), --email <addr>, --json. | | boombox ingest <path…> | Upload files (transcripts, docs) into your company memory. --recursive, --json. |

Cassettes

| Command | What it does | |-|-| | boombox cassettes list [--status published\|draft\|all] | List cassettes available to you. | | boombox cassettes show <id> [--draft] | Print a cassette's definition (YAML). | | boombox cassettes validate <id> [--draft] | Run readiness checks on a cassette. | | boombox cassettes dry-run <id> [--draft] | Dry-run a draft — verdict + blockers, no durable writes. | | boombox cassettes publish <draft_id> --name <name> | Publish a dry-run-approved draft. --version <n>, --json. | | boombox cassettes build <file.ts> | Compile a defineCassette TypeScript file, validate it, and upload it as a draft. |

Runs & artifacts

| Command | What it does | |-|-| | boombox runs list [--cassette <id>] [--since 24h] [--status <s>] [--limit 20] | List recent runs. | | boombox runs show <run_id> | One run in detail: inputs, step trace, receipts, errors. | | boombox logs tail [--cassette <id>] | Stream live run/step events (Ctrl+C to stop). | | boombox artifacts open <artifact_id> | Open an artifact in your browser. |

Identity & setup

| Command | What it does | |-|-| | boombox login [--tenant <id>] | Sign in via the browser; writes ~/.boombox/config.toml. | | boombox whoami | Show who you're signed in as + key expiry. | | boombox doctor | Check config, connectivity, and auth. | | boombox enroll / boombox init | First-time enrollment / manual config (most people just use login). | | boombox project init [directory] [--client codex\|claude] | Install the versioned builder skill and local-only onboarding playbook in a codebase and print the scan-only MCP connection; no secrets or app files are written. |

Connect your own MCP servers, capabilities, keys

| Command | What it does | |-|-| | boombox mcp add --id <id> --name <name> --url <url> --tools a,b --provider <id> --version <v> [--transport streamable_http\|sse] | Register explicitly allowlisted, canonically versioned tenant MCP tools. | | boombox mcp list / rm <id> / status <id> [--enable\|--disable] | Manage your registered MCP servers. | | boombox capabilities list | List your registered recipes, tools, and templates. | | boombox keys list | List your tenant API keys. |

For executable MCP tools, pass an explicit --tools allowlist. Each tool is registered as an immutable canonical revision; dry-run prints the exact revision and terms digest, and publish refuses if the live pointer moved. Omitting the allowlist never grants every advertised tool. Default commercial disposition is external_direct and is not charge authority.

Serve & process control

| Command | What it does | |-|-| | boombox serve [--mcp] [--http] [--port <p>] [--profile <p>] | Start the MCP server (--mcp) and/or a local web UI proxy (--http). | | boombox status | Check your Boombox instance's health. | | boombox reload / restart / stop | Manage a running boombox serve. | | boombox upgrade [--check] | Update this CLI to the latest version. |

Admin (super-admin only)

| Command | What it does | |-|-| | boombox admin ui | Open the admin UI in your browser. | | boombox admin provision <tenant> | Provision a new tenant (needs the platform admin key via --admin-key or BOOMBOX_ADMIN_API_KEY). |

Configuration

Your settings live in ~/.boombox/config.toml — your tenant id, your instance URL, and your API key. It's created with 600 permissions and never leaves your machine. Point the CLI at a different file with BOOMBOX_HOME=/some/dir.

boombox login writes this for you; you rarely touch it directly.

Troubleshooting

• config not found — run boombox login.
• 401 / 403 — your credential expired, or was minted before your tenant's fleet gateway was enabled; boombox login again re-mints it for both servers.
• can't reach your instance — check boombox status; confirm your instance URL in ~/.boombox/config.toml.

License

© Konstant. Published to npm for Boombox customers; not open source.