npm - @konstantdotcloud/boombox - Versions diffs - 0.3.0 → 0.3.1 - Mend

@konstantdotcloud/boombox 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,96 +1,44 @@
 # @konstantdotcloud/boombox
-CLI and MCP bridge for a tenant's Boombox VM.
+The command line for **Boombox** — your company's governed AI runtime.
-Boombox Cloud lives at <https://boombox.konstant.cloud>. Each tenant VM is served at `https://boombox-<tenant>.exe.xyz`. The CLI stores your tenant identity, talks to the VM, asks Gary questions, ingests files into HomeBase, runs and shares cassettes, and exposes the Gary cassette runtime to Claude Desktop, Claude Code, Cursor, or any MCP client.
+Ask Gary (the expert inside Boombox) about your business, add files to its memory, run and share **cassettes** (reusable, governed jobs), and connect Boombox to Claude or Cursor as an MCP server.
+> You need a Boombox account. The CLI signs you in, then talks to your own Boombox instance. Everything runs against your tenant; your API key stays on your machine.
 ## Install
 ```bash
-curl -fsSL https://boombox.konstant.cloud/install/boombox.sh | sh
+npm install -g @konstantdotcloud/boombox
 ```
-The installer installs `@konstantdotcloud/boombox` and then tells you to run `boombox login`. (Or run it ad hoc with `npx @konstantdotcloud/boombox <command>`.)
-## Quickstart
+Then sign in:
 ```bash
-boombox login                       # browser sign-in via boombox.konstant.cloud; writes ~/.boombox/config.toml
-boombox whoami                      # verifies tenant, user, VM URL, and key expiry
-boombox ask "what's at risk on the BNY deal this week?"   # one-shot Gary answer over your org
-boombox ingest ./transcripts        # upload local files into HomeBase so Gary can answer
-boombox run weekly_recap            # trigger a cassette and tail it to a terminal state
-boombox share <run_id>              # mint a no-login link to the run's surface
-boombox admin ui                    # open the VM admin UI through a short-lived cloud grant
+boombox login
 ```
-For MCP clients, run `boombox serve --mcp` after `boombox login` succeeds (see [MCP client setup](#mcp-client-setup)).
-## Commands
+No install needed for one-offs — run any command with `npx`:
-### Identity & setup
-| Command | What it does |
-|-|-|
-| `boombox login [--tenant <tenant_id>]` | Browser sign-in through `boombox.konstant.cloud`; writes tenant id, VM URL, API key, and expiry to `~/.boombox/config.toml`. |
-| `boombox whoami` | Calls the VM identity endpoint; prints tenant id, user id, VM URL, key expiry, days remaining. |
-| `boombox enroll` | Browser enrollment flow that signs in via WorkOS, provisions an inbox + key, and writes config. |
-| `boombox init` | Manual config fallback for raw provisioned credentials. Prefer `boombox login`. |
-| `boombox doctor` | Connectivity + auth check (config, VM reachability, key validity, MCP boot). |
+```bash
+npx @konstantdotcloud/boombox ask "what changed this week?"
+```
-### Ask, run, share, ingest
-| Command | What it does |
-|-|-|
-| `boombox ask <question> [--model <tier>] [--thinking <level>] [--thread <id>] [--fresh] [--json]` | One-shot question to Gary (HomeBase synthesis + artifacts). `--model`: auto\|fast\|reason\|explore\|premium\|opus. `--thinking`: off\|minimal\|low\|medium\|high\|xhigh. |
-| `boombox run <cassette_name> [--input key=value ...] [--no-tail] [--json]` | Triggers a cassette, prompts for required missing inputs, then polls to a terminal state unless `--no-tail`. |
-| `boombox share <run_id> [--ttl <days>] [--email <addr>] [--json]` | Mints a no-login, signed, expiring run-room link for a run and prints the shareable URL (default TTL 14 days). |
-| `boombox ingest <path...> [--recursive] [--json]` | Uploads local files (transcripts, docs) into HomeBase via presigned upload so Gary can answer over them. |
+## First five minutes
-### Cassettes
-| Command | What it does |
-|-|-|
-| `boombox cassettes list [--status published\|draft\|all]` | Lists cassettes available to the tenant. |
-| `boombox cassettes show <id> [--draft]` | Prints a cassette YAML projection. |
-| `boombox cassettes validate <id> [--draft] [--json]` | Runs cassette oracle readiness checks. |
-| `boombox cassettes dry-run <id> [--draft] [--json]` | Dry-runs a draft and prints verdict + blockers. No durable writes. |
-| `boombox cassettes publish <draft_id> --name <name> [--version <n>] [--json]` | Publishes a dry-run-approved draft to the tenant tier; renders gate rejections (e.g. `dry-run-not-green`) with fix guidance. |
-### Runs, logs, artifacts
-| Command | What it does |
-|-|-|
-| `boombox runs list [--cassette <id>] [--since 24h] [--actor <id>] [--status <s>] [--limit 20]` | Lists recent runs (run id, cassette, actor, status, duration, start). |
-| `boombox runs show <run_id>` | One run: spec hash, inputs, step trace, delivery receipts, error summary, replay ref. |
-| `boombox logs tail [--cassette <id>]` | Tails run/step events from the VM SSE stream. Ctrl+C exits cleanly. |
-| `boombox artifacts open <artifact_id>` | Opens the artifact URL in the system browser. |
+```bash
+boombox login                              # opens a browser, signs you in, saves your config
+boombox ask "what's at risk on the BNY deal this week?"   # one-shot answer over your org
+boombox ingest ./transcripts               # add local files to your company's memory
+boombox run weekly_recap                   # run a cassette and watch it to completion
+boombox share <run_id>                     # get a no-login link to the result
+```
-### Tenant MCP servers, capabilities, keys
-| Command | What it does |
-|-|-|
-| `boombox mcp add --id <server_id> --name <display> --url <url> [--transport streamable_http\|sse] [--auth-header <h>] [--secret-ref <ENV_KEY>] [--tools t1,t2]` | Registers a tenant-owned MCP server on this VM for cassettes to reference. |
-| `boombox mcp list` | Lists tenant MCP servers registered on this VM. |
-| `boombox mcp rm <server_id>` | Removes a tenant MCP server registration. |
-| `boombox mcp status <server_id> [--enable\|--disable]` | Enables or disables a tenant MCP server registration. |
-| `boombox capabilities list [--kind <k>] [--status available\|missing]` | Lists registered recipes, tools, artifact templates, prompt templates. |
-| `boombox keys list` | Lists tenant API keys visible to the current API key authority. |
-### Serve (MCP / HTTP) & process control
-| Command | What it does |
-|-|-|
-| `boombox serve [--mcp] [--http] [--port <port>] [--profile default\|advanced\|operator]` | Boots the stdio MCP server (`--mcp`) and/or the local HTTP proxy (`--http`). |
-| `boombox status` | Checks VM health, `/v2/api/info`, and run-event stream reachability. |
-| `boombox reload` | SIGHUP a running `boombox serve` to re-read config. |
-| `boombox restart [--no-detach] [--timeout <ms>]` | Stops and respawns `boombox serve` (detached by default). |
-| `boombox stop [--timeout <ms>]` | Stops a running `boombox serve`. |
-| `boombox upgrade [--check] [--force]` | Self-update through the npm registry. |
-### Admin (super-admin)
-| Command | What it does |
-|-|-|
-| `boombox admin ui [--cloud-url <url>]` | Requests a short-lived admin grant and opens the tenant VM admin UI. |
-| `boombox admin provision <tenant> [--name <n>] [--company <c>] [--ceo <c>] [--control-plane <url>] [--admin-key <key>] [--json]` | Super-admin: provision a tenant (doc + keypair + VM) via the control plane. Needs `ADMIN_API_KEY` (flag or `BOOMBOX_ADMIN_API_KEY`). |
+`boombox whoami` shows who you're signed in as; `boombox doctor` checks your setup if something looks off.
-## MCP client setup
+## Connect it to Claude or Cursor (MCP)
-### Claude Desktop / Claude Code / Cursor
+Add this to your MCP client's config and restart the client:
 ```json
 {
@@ -103,56 +51,77 @@ For MCP clients, run `boombox serve --mcp` after `boombox login` succeeds (see [
 }
 ```
-After saving, restart your client. The MCP profile is selected with `--profile` (or `GARY_MCP_PROFILE`): `default` exposes the chat-parity tools (`ask_gary`, `list_threads`, `clear_thread`, `artifact_fetch`, `gary_status`); `advanced` adds cassette authoring + rack verbs; `operator` adds admin verbs.
-## Config file
+Your AI client can then call Gary directly — ask questions, manage threads, fetch artifacts. Choose how much it can do with `--profile` (or the `GARY_MCP_PROFILE` env var): `default` (ask + threads + artifacts), `advanced` (adds cassette authoring), `operator` (adds admin).
-`~/.boombox/config.toml`:
+## Command reference
-```toml
-[konstant]
-tenant_id = "example"
-api_key = "kn_example_***"
-gateway_url = "https://boombox-example.exe.xyz"
+### 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`. |
-[runtime]
-default_kind = "vm"
-vm_url = "https://boombox-example.exe.xyz"
+### 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]
-http_port = 8787
-mcp_enabled = true
+### 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. |
-[admin]
-```
+### 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`). |
-`runtime.vm_url` is the preferred target. If present, CLI commands talk to the tenant VM; `gateway_url` remains the shared cloud fallback and login/onboarding origin.
+### Connect your own MCP servers, capabilities, keys
+| Command | What it does |
+|-|-|
+| `boombox mcp add --id <id> --name <name> --url <url> [--transport streamable_http\|sse] [--tools a,b]` | Register a tenant-owned MCP server your cassettes can call. |
+| `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. |
-The file is created with mode `600`. Override the location with `BOOMBOX_HOME=/some/dir` (config lives at `$BOOMBOX_HOME/config.toml`).
+### 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. |
-## Local HTTP server
+### 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 `ADMIN_API_KEY`). |
-When `boombox serve --http` is running, your browser hits Hono on `localhost:8787`:
+## Configuration
-- `GET /` → the bundled Boombox UI when `ui/dist` exists.
-- `GET /api/...` → proxied to the configured VM/cloud gateway with `Authorization: Bearer <api_key>` injected. The browser never sees your API key.
-- `GET /gateway/...` → rewritten to `/api/gateway/...` upstream.
-- `GET /healthz` → 200 if config loaded.
+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`.
-If `ui/dist/` is missing, `/` and SPA routes return `503 ui_not_built`; `/healthz` and `/api/*` still work. CORS is locked to `localhost`/`127.0.0.1` origins.
+`boombox login` writes this for you; you rarely touch it directly.
 ## Troubleshooting
-- **`boombox doctor` says "config not found"** — run `boombox login`; use `boombox init` only when Konstant gave you raw VM credentials.
-- **`whoami` returns 401/403** — the API key is invalid, expired, or lacks authority. Run `boombox login` to refresh.
-- **`gateway: unreachable`** — verify `runtime.vm_url` in `~/.boombox/config.toml`; the expected VM domain is `https://boombox-<tenant>.exe.xyz`.
-- **Run stays queued** — check `boombox runs show <run_id>` and the VM admin run trace.
-- **Port 8787 already in use** — pass `--port 9000` to `boombox serve --http`, or set `http_port` in config.
-- **MCP boot test fails** — make sure your Node version is `>= 20`.
-## Privacy & data
-The CLI stores config and API keys locally; it does not store run output, telemetry, or tenant data on disk. Runtime data, replay packets, artifacts, and events live in the tenant VM/Mongo path configured for that tenant. LLM calls route through the tenant's configured provider path.
+- **`config not found`** — run `boombox login`.
+- **`401` / `403`** — your key expired or is invalid; run `boombox login` again.
+- **can't reach your instance** — check `boombox status`; confirm your instance URL in `~/.boombox/config.toml`.
+- **MCP won't boot** — make sure you're on Node 20+.
 ## License

package/dist/boombox.js CHANGED Viewed

@@ -37694,7 +37694,7 @@ var {
 init_esm_shims();
 // package.json
-var version = "0.3.0";
+var version = "0.3.1";
 // src/lib/version.ts
 var BOOMBOX_VERSION = version;

package/dist/index.js CHANGED Viewed

@@ -34669,7 +34669,7 @@ init_esm_shims();
 init_esm_shims();
 // package.json
-var version = "0.3.0";
+var version = "0.3.1";
 // src/lib/version.ts
 var BOOMBOX_VERSION = version;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@konstantdotcloud/boombox",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local Boombox runtime for Konstant cassettes — CLI, stdio MCP server, and local Hono proxy.",
   "license": "UNLICENSED",
   "type": "module",