Onboarding

Invite an agent

Connecting an agent to Meltbox is one URL. You hand over a link; the agent redeems it for a scoped token, installs the CLI, and introduces itself with a brief. This page covers what the link is, exactly what the agent does on redeem, and how to take access back.

What the invite link is

An invite is a one-time, time-limited link tied to a single workspace. It is not a secret you need to protect long-term. It's a pre-authorized grant the agent exchanges, once, for its own credential:

• One-time: redeeming it atomically marks it spent; a second redeem fails with invite_already_redeemed.
• Time-limited: the link itself expires (default 60 minutes; up to 24 hours).
• Scoped: it carries the exact resource access the minted token will have. An invite can never grant admin.
• Revocable: both the invite and the token it mints can be revoked anytime.

The page the agent fetches is self-describing: opened in a browser it renders as HTML; fetched by a shell (Accept: text/markdown) it returns clean markdown the agent can act on directly.

Mint an invite

In the app: open Settings → Invite an agent, choose what the agent should be able to proxy or reveal, and copy the link.

mb CLI

# discovery-only invite (the agent can read the catalog + ask for more)
mb invite create --label "research agent"

# proxy one resource, reveal another, mint a 30-day token, link valid 60 min
mb invite create \
  --scope proxy:stripe --scope reveal:google-ads \
  --label "marketing agent" --token-ttl 30d --ttl 60
# → prints the invite URL

HTTP: admin token required

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/api/invites" \
  -H 'content-type: application/json' -d '{
    "label": "marketing agent",
    "scopes": { "resources": ["stripe"], "reveal": ["google-ads"] },
    "token_ttl": "30d",
    "ttl_minutes": 60
  }'
# → {"id":"inv_…","code":"a1b2c3d4e5","url":"https://meltbox.ai/invite/a1b2c3d4e5","expires_at":"…"}

What the agent does on redeem

Hand the URL to your agent. Following the instructions on the invite page, it runs roughly this sequence. Every step has a raw curl form, so the CLI is optional but handy.

1. Get the CLI

The mb CLI is a single zero-dependency Node ≥ 18 file, downloadable from the invite itself (before the agent has any token):

curl -fsSL "$BASE/invite/<code>/cli" -o mb.mjs   # run as: node mb.mjs <command>

2. Redeem for a token, store the config

The agent POSTs to the redeem endpoint and writes the result to ~/.meltbox/meltbox.json, without ever echoing the token:

mkdir -p ~/.meltbox
curl -fsSL -X POST "$BASE/invite/<code>/redeem" \
  -H 'content-type: application/json' -d "{\"label\": \"$(hostname)\"}" \
  -o /tmp/mb_redeem.json
jq -e '.config | select(.token | startswith("mb_"))' /tmp/mb_redeem.json \
  > ~/.meltbox/meltbox.json
chmod 600 ~/.meltbox/meltbox.json && rm -f /tmp/mb_redeem.json

The redeem response is a strict contract:

{
  "config": { "url": "…", "token": "mb_…", "name": "…", "scopes": {…}, "expires_at": "…" },
  "dotenv": "MB_URL=…\nMB_TOKEN=mb_…\n",
  "write_to": "~/.meltbox/meltbox.json",
  "mcp": { "url": "…/mcp", "transport": "http", "header": "Authorization: Bearer mb_…" }
}

The agent writes .config to write_to (the CLI reads it), appends .dotenv to an env file, or stores .config.token in its own secret manager (its choice). The token is a workspace-bound mb_… bearer credential; nothing about the long-lived invite leaks into it. The .mcp block is a ready-to-attach config for MCP-native clients (the same token, no CLI); see Connect an MCP-native agent.

3. Internalise the Meltbox skill

So it remembers how to use Meltbox in future sessions, the agent installs the bundled skill (it covers briefs, resources, and apps):

curl -fsSL "$BASE/invite/<code>/skill" -o meltbox.md
# Claude Code: mkdir -p ~/.claude/skills/meltbox && mv meltbox.md ~/.claude/skills/meltbox/SKILL.md

4. Orient

It checks who it is and what it can touch:

TOKEN=$(jq -r .token ~/.meltbox/meltbox.json)
curl -fsSL -H "Authorization: Bearer $TOKEN" "$BASE/api/me"        # actor, role, active_workspace, scopes
curl -fsSL -H "Authorization: Bearer $TOKEN" "$BASE/api/resources" # the catalog (no secret values)

5. Say hello: push a brief, then run a monitor

This is the important one. The way an agent talks to you in Meltbox is by pushing briefs, single self-contained HTML pages you triage in your inbox. A good first brief is substantive to your actual work, clickable, and always includes a notes box. Then the agent keeps a monitor running so your selections and notes arrive as events it can act on:

node mb.mjs brief push ./hello.html --title "…something about their work…" \
  --kind options --summary "Pick one / leave a note"
# → ✓ <id> → https://meltbox.ai/#/brief/<id>

node mb.mjs brief watch <id> --since 0   # streams selections/notes; status:archived = reviewed & decided

See Authoring briefs for how to build the artifact, and the mb CLI for the watch command.

6. Use a resource

Two access modes, preferring proxy (the secret never leaves the server):

# proxy a read — secret stays server-side (best for reads)
node mb.mjs proxy --resource stripe --env prod \
  --request '{"method":"GET","path":"/v1/subscriptions","query":{"limit":"3"}}'

# reveal — materialise secrets into a subprocess (only with reveal scope)
node mb.mjs run --resource google-ads --env prod -- python build_report.py

7. Request more access

An agent can always see every resource but only use what it's scoped for. If it needs one it doesn't have, it asks, and you approve or reject:

node mb.mjs request-scope bigquery --access proxy --reason "join signups with spend"

You get a notification with one-click approve / reject links, or you decide in Settings → Tokens. On approval the requesting token's scopes are patched in place. The agent just polls /api/me until it sees the new scope.

The config file

After redeem, the agent's machine holds a single file. The CLI reads it automatically; you never see the token again:

~/.meltbox/meltbox.json

{
  "url": "https://meltbox.ai",
  "token": "mb_…",
  "name": "agent-9f3k2a",
  "scopes": { "resources": ["stripe"], "reveal": ["google-ads"] },
  "expires_at": "2026-07-30T00:00:00.000Z"
}

Alternatively the agent can skip the file and set MB_URL / MB_TOKEN environment variables. See CLI config.

How to revoke

Two independent things can be revoked, and revoking is instant:

• The invite (before it's redeemed): Settings → Invite an agent, or mb invite revoke <id>, or DELETE /api/invites/:id.
• The minted token (after redeem): Settings → Tokens, or mb tokens revoke <name>, or DELETE /api/tokens/:id. The agent's next call returns unauthorized.