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

@konstantdotcloud/boombox 0.2.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 (5) hide show

package/README.md CHANGED Viewed

@@ -1,83 +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, and exposes the Gary cassette runtime to Claude Desktop, Claude Code, Cursor, OpenClaw, 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`.
-## 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 admin       # opens the VM admin UI through a short-lived cloud grant
-boombox run bd_pre_meeting_brief --input meeting_uid=sample --input organizer=user@example.com --input attendees='["user@example.com"]' --input start_time=2026-06-02T15:00:00Z --input summary=Sample
+boombox login
 ```
-For MCP clients, add `boombox serve --mcp` after `boombox login` succeeds. The MCP server defaults to the `advanced` profile (cassette authoring + rack verbs included); set `GARY_MCP_PROFILE=andrew` or pass `--profile` to narrow or change it.
+No install needed for one-offs — run any command with `npx`:
-## Commands
-| 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 and prints tenant id, user id, VM URL, key expiry, and days remaining. |
-| `boombox admin` | Requests a short-lived admin grant from Boombox Cloud and opens the tenant VM admin UI. |
-| `boombox run <cassette_name> [--input key=value ...] [--no-tail] [--json]` | Manually triggers a cassette through `/gateway/rack/run`, prompts for required missing inputs, then polls to a terminal state unless `--no-tail` is set. |
-| `boombox cassettes list` | Lists active cassettes available to the tenant. |
-| `boombox cassettes show <id> [--draft]` | Prints a cassette YAML projection. |
-| `boombox cassettes publish <draft_id> --name <name> [--version <n>] [--json]` | Publishes a dry-run-approved cassette draft to the tenant tier via `POST /gateway/cassette/publish`; renders gate rejections (e.g. `dry-run-not-green`) with fix guidance. |
-| `boombox runs list [--cassette=X] [--since=24h] [--actor=Y] [--status=completed] [--limit=20]` | Lists recent runs with run id, cassette, actor, status, duration, and start time. |
-| `boombox runs show <run_id>` | Shows one run: spec hash, inputs, step trace, delivery receipts, error summary, and replay ref. |
-| `boombox logs tail [--cassette=X]` | Tails run/step events from the VM SSE stream. |
-| `boombox artifacts open <artifact_id>` | Opens `<vm_url>/artifact/<artifact_id>` in the system browser. |
-| `boombox keys list` | Lists tenant API keys visible to the current API key authority. |
-| `boombox capabilities list [--kind=recipe\|tool\|artifact_template\|prompt_template] [--status=available\|missing]` | Lists registered tenant capabilities. |
-| `boombox status` | Checks VM health, `/v2/api/info`, and the run-event stream. |
-| `boombox doctor` | Checks config, VM reachability, API-key validity, and MCP boot. |
-| `boombox init` | Manual config fallback for provisioned credentials. Most users should prefer `boombox login`. |
-| `boombox enroll` | Browser enrollment flow that can write config from a provisioning payload. |
-| `boombox serve [--mcp] [--http] [--port <port>]` | Starts stdio MCP and/or the local HTTP proxy. MCP clients should use `--mcp`. |
-| `boombox reload` | Sends SIGHUP to a running local `boombox serve`. |
-| `boombox restart` | Stops and respawns local `boombox serve`. |
-| `boombox stop` | Stops a running local `boombox serve`. |
-| `boombox upgrade` | Self-update through npm. |
-## Config file
-`~/.boombox/config.toml`:
-```toml
-[konstant]
-tenant_id = "example"
-api_key = "kn_example_***"
-gateway_url = "https://boombox-example.exe.xyz"
-[runtime]
-default_kind = "vm"
-vm_url = "https://boombox-example.exe.xyz"
-[boombox]
-http_port = 8787
-mcp_enabled = true
-[admin]
+```bash
+npx @konstantdotcloud/boombox ask "what changed this week?"
 ```
-`runtime.vm_url` is the preferred target. If it is present, CLI commands talk to the tenant VM. `gateway_url` remains the shared cloud fallback and login/onboarding origin.
+## First five minutes
-The file is created with mode `600`. Override the location with `BOOMBOX_HOME=/some/dir` (config lives at `$BOOMBOX_HOME/config.toml`).
+```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
+```
+`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 / OpenClaw
+Add this to your MCP client's config and restart the client:
 ```json
 {
@@ -90,54 +51,77 @@ The file is created with mode `600`. Override the location with `BOOMBOX_HOME=/s
 }
 ```
-After saving, restart your client. The default MCP profile exposes the chat-parity tools: `ask_gary`, `list_threads`, `clear_thread`, `artifact_fetch`, and `gary_status`. Advanced/operator profiles can expose rack, prompt, cassette, and admin verbs when explicitly enabled.
-## Ops route contracts
+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).
-The ops CLI uses direct HTTP service routes with `Authorization: Bearer <tenant_api_key>`; it does not speak MCP wire format.
+## Command reference
-| CLI command | Primary route contract |
+### Ask, run, share, ingest
+| Command | What it does |
 |-|-|
-| `whoami` | `GET /v2/api/me`. |
-| `status` | `GET /health`, `GET /v2/api/info`, `GET /admin/runs/stream` (fallback: `/api/admin/runs/stream`). |
-| `runs list` | `GET /api/admin/runs` with `cassette`, `since`, `actor`, `status`, `limit`; fallback: `GET /api/admin/cassettes/runs`. |
-| `runs show` | `GET /api/admin/runs/:run_id`; fallback: `GET /api/admin/cassettes/runs/:run_id/replay`. |
-| `logs tail` | `GET /admin/runs/stream` SSE; fallback: `GET /api/admin/runs/stream`. |
-| `run` | `GET /api/admin/cassettes/:id` for required input metadata, `POST /gateway/rack/run` to trigger, then `GET /api/admin/runs/:run_id` or replay fallback to poll. |
-| `cassettes list` | `GET /api/admin/cassettes`; the VM route currently defaults unknown status filters to `active`. |
-| `cassettes show` | `GET /api/admin/cassettes/:id/yaml?draft=true`; falls back to `GET /api/admin/cassettes/:id` if YAML is not wired. |
-| `keys list` | `GET /api/admin/keys`. |
-| `capabilities list` | `GET /api/admin/capabilities`. |
+| `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`. |
-## Local HTTP server
+### 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`. |
-When `boombox serve --http` is running, your browser hits Hono on `localhost:8787`:
+### 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. |
-- `GET http://localhost:8787/` → the bundled Boombox UI when `packages/boombox/ui/dist` exists.
-- `GET http://localhost:8787/api/...` → proxied to the configured VM/cloud gateway with `Authorization: Bearer <api_key>` injected. The browser never sees your API key.
-- `GET http://localhost:8787/gateway/...` → rewritten to `/api/gateway/...` upstream.
-- `GET http://localhost:8787/healthz` → 200 if config loaded.
+### 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`). |
-If `ui/dist/` is missing, `/` and SPA routes return `503 ui_not_built`; `/healthz` and `/api/*` still work. Run `cd packages/boombox/ui && npm run build` to populate `ui/dist/`.
+### 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. |
-CORS is locked to `localhost`/`127.0.0.1` origins.
+### 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. |
-## Troubleshooting
+### 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`). |
-- **`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 it.
-- **`gateway: unreachable`** — verify `runtime.vm_url` in `~/.boombox/config.toml`; the expected VM domain is `https://boombox-<tenant>.exe.xyz`.
-- **Run stays queued** — the VM may not have an Inngest/worker dispatcher wired for that cassette. 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`.
+## Configuration
-## Privacy & data
+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`.
-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.
+`boombox login` writes this for you; you rarely touch it directly.
-## Versioning
+## Troubleshooting
-`0.1.0` — V1 ships with the default MCP tools plus CLI commands for login, VM status, cassette runs, run inspection, artifacts, keys, capabilities, admin, and lifecycle control. Run `boombox upgrade` to pull updates.
+- **`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