Agents

Credentials

Content keys, remix grants, claimable pushes and the browser sign-in.

Everything local runs with no credential at all: recording, planning, rendering, frames. Only the cloud seams need one, and there is a rung for every situation, including "the user has no account yet". Never print a credential anywhere; the tools are built so you never have to.

The resolution ladder

Before asking the user, resolve in this order:

  1. the VOS_API_KEY environment variable
  2. ~/.config/vos/credentials (first line; written by vos login)
  3. a vos_rg_ remix grant embedded in your prompt

If the user pastes a key into the chat, use it, and suggest rotating it afterward; transcripts persist.

The four credential shapes

A content key (vos_sk_...) is the durable one, minted by a human at vos.so/app/api. It can create and read voses, iterate versions, upload models and recipes, and pull folders. It can never publish, never set official status, and creates are quota'd at 50 per 24 hours, version pushes at 200 per 24 hours across every vos, recording uploads at 20 per 24 hours (re-pushing the same bytes never counts). The full table is in Limits.

A remix grant (vos_rg_...) is the zero-setup rung a watch page's "remix with your agent" prompt embeds. It lives 24 hours, is bound to one source vos, can push at most 5 remixes of it, and can read only what it created.

vos login turns a terminal into a key without copying anything: it prints a short code and an approval URL (vos.so/cli/auth?code=...). Relay both to the human and keep the command running; they sign in, check the code matches, and approve. The CLI then stores a content key named cli:<hostname> itself, revocable any time at vos.so/app/api. The code lasts 15 minutes; denial and expiry exit with the reason, and the key is never displayed, not even in --json events.

A claimable push needs no credential at all, for a program and the files it draws with:

Shell
vos push config.json --claimable --share --prompt "<their prompt>"

It creates a private vos and prints a claim link. Hand that link to the user and nowhere else; it is the only reference and the only credential. Claiming moves the vos into their projects and starts its hosted preview. Unclaimed work is deleted after 72 hours; that is deliberate cleanup, not data loss. Re-push if it lapses.

Every local file the program names rides along (@vosjs/cli 0.63 or later): its manifest, an element's src, a font's url, a path in data, and the document's overlays, 3D props and sound. The push opens the claim's own upload session, with no credential, and the claim spends it. Until the user claims it, only the claim link reads those files; at the claim they become theirs. A file the push could not carry is a warning event under --json: tell the user which one.

  • --share makes the claim page lead with Claim and share, which claims it and gives it a link anyone can watch, in one press.
  • --prompt shows the prompt that made it on its watch page. Pass only what the user wrote, and only when they said to show it.

Limits: config at most 200KB, at most 12 files and 50 MB, sound up to 5 minutes, video up to 60 seconds, 5 pushes and 5 upload sessions per 24 hours per network. A recording take still needs an account.