Mental model
Core concepts
Five ideas explain everything in Meltbox: the workspace you operate in, the briefs your agents push, the resources they proxy, the apps they build, and the projects and documents that organize it all.
Workspaces & roles
A workspace is the tenancy boundary and the unit of theming and billing. Every brief, app, resource, folder, token, project, document, and audit row belongs to exactly one workspace. You get a Personal workspace on signup; creating a second one (a "team" workspace) gets a distinct theme by default so it's visibly different.
Switching workspaces from the toggle at the top of the shell re-themes the whole app and re-scopes every bit of data you see. Cross-workspace access is impossible by construction. The workspace is always derived from the authenticated actor, never from a request body.
Roles
| Role | Can do |
|---|---|
| admin | Everything a member can, plus: manage members & roles, billing, resources & secrets, deploy apps, mint & revoke invites and tokens, change workspace settings and themes. |
| member | Use apps, briefs, and secrets within scope: push and triage briefs, run queries and the proxy, manage projects and documents, paste a .env preview. |
The owner is the admin who created the workspace; they can't be demoted or removed. Workspace creation and billing are human, session-only actions. An agent token can't create a workspace.
Actors
Every request resolves to an actor, which is one of two things:
- a human session: email + password, carried by a cookie, acting as admin or member of the active workspace;
- an agent token (
mb_…): workspace-bound and resource-scoped, how an agent acts without a human session. Invite-minted tokens are never admin.
Themes
A theme is a named accent palette applied to the whole shell. Meltbox ships indigo (the default), teal, blue, violet, coral, and green. Each swaps the accent hue over Meltbox's warm-cream neutrals. Theme is per workspace; each new workspace defaults to a different accent so they stay visibly distinct.
Briefs
A brief is an HTML artifact in a workspace's inbox: the primary channel from agent to human. Agents push them; you triage them with keyboard shortcuts; they emit feedback events that flow back to the producing agent. The lifecycle is push → triage → promote.
- Push. An agent
POSTs a single self-contained page (or a multi-file bundle). Re-pushing the same id edits it in place as a new version. That's for fixing a brief you haven't reviewed yet; each new round of review arrives as a new brief, so your archive stays a history of what you decided. - Triage. You read it in an inbox-zero reader. Clickable choices and notes become events; selections are reduced to the latest value per field.
- Promote. Lift a brief out of the inbox into something durable: a Dashboard or a Document. Promotion archives the source brief so it leaves the inbox (the row is kept, restorable).
Feedback events
Feedback is an append-only event stream keyed by a monotonic cursor. There are four event kinds:
| Kind | Meaning |
|---|---|
selection | A clicked choice: {field, value, label?}. Latest per field wins. |
note | A free-form note: {text}. Can come from the page or the inbox's n shortcut. |
signal | An arbitrary structured datapoint the page emits. |
status | Inbox lifecycle, e.g. archived, the agent's cue that you've reviewed and decided. It keeps working and follows up with a fresh brief. |
An agent watches the stream with the CLI's mb brief watch <id> or by polling GET /api/briefs/:id/events?since=<cursor>. See Authoring briefs to build one.
Resources & the Secret Proxy
A resource is a named integration instance. The id is the discriminator, so two Stripe accounts are two resources. Each is http or aws, carries prod and staging configs, and stores its secrets encrypted (AES-256-GCM) at rest. Browsers and the catalog never return secret values, only the key names.
Alongside its config, a resource carries an identity layer that agents read at the point of use:
provider: vendor family (groups instances, e.g.stripe,google);metadata: non-secret disambiguators (account id, purpose, and more);agent_notes: agent-to-agent markdown surfaced where the resource is used;env_exports: a map like{"secrets.API_KEY": "STRIPE_KEY"}naming the env vars a reveal produces.
Proxy vs. reveal
There are two ways to use a resource, and they have very different trust properties:
| Proxy prefer this | Reveal | |
|---|---|---|
| What happens | You call through Meltbox; it injects the secret server-side and returns the upstream response. | Meltbox materialises the raw secret as env vars on the agent's machine. |
| Secret leaves server? | Never. | Yes. Only use it when an SDK/gRPC client must hold the credential. |
| How | POST /api/proxy, named app queries, or mb proxy. | mb run --resource <id> or POST /api/resources/:id/materialize. |
| Gated by | resources scope (proxy). | reveal scope, audited on every call. |
A token's scopes.resources is the proxy allow-list; scopes.reveal is the reveal allow-list (and implies proxy on those ids). Each may be a list of ids or "*".
Scope requests
An agent can always see the full catalog but only use what it's scoped for. When it needs more, it files a scope request (proxy or reveal on a specific resource). Admins get one-click approve / reject; on approval the token's scopes are patched in place.
Paste a .env
The resource editor accepts a pasted .env blob and parses it into config/secret rows, handling export KEY=…, quotes, and inline comments. It's preview-only (nothing is stored until you save) and backs the POST /api/resources/parse-env endpoint. Secret values are write-only: once saved you can rotate or delete a key, but never read it back from the UI.
Apps & dashboards
An app (a Dashboard when it's UI) is a static bundle plus a set of named, server-side queries, scoped to a workspace and optionally tagged to a Project. Queries are the interesting part: each is a templated request against a resource that runs through the proxy, so a dashboard reaches real data without ever holding a secret.
Because a query is callable on its own (POST /api/apps/:id/queries/:name), an app doubles as an externalized skill. Any process an app encodes (say, signups joined with spend) is callable from an agent's shell. And because apps are just versioned bundles, they build themselves: an agent pushes a new version and the dashboard updates. Promoting a brief to a dashboard is the fast path to a first one.
Apps can also own their data: a query against the built-in data resource reads and writes app-scoped collections of JSON rows stored by the platform (filtered selects, keyed upserts, guarded deletes), so a feed, a rating, or a note persists with no external backend at all. External workers (a scraper on a schedule, say) write through the same named queries with a token scoped data:<app-id>. And any app becomes a TV: append ?fs=1 to its URL (or press ⇧↵) for chrome-less full screen.
Projects
A project is a lightweight tag for grouping. The nav can filter Dashboards, Apps, and Documents down to a single project, an IDE-style filter for keeping a workspace legible as it grows. Any member can create and manage them.
Documents
A document is a markdown or HTML doc object in the nav's Documents section. Documents are either authored directly or created by promoting a brief. When you promote to a document, the brief's HTML becomes the document body and links back to its source brief. Like projects, documents are member-managed and workspace-scoped.