Overview — build confidential AI apps around Spaces

Witbitz is the backend for confidential, multiplayer AI apps. You ship a static page; Witbitz runs the rest — the shared room, its members, the AI assistant, storage, sign-in and approvals — sealed so that neither Witbitz nor you can read your users' rooms, and built so that anyone can check that.

<script type="module">
  import { Witbitz } from 'https://witbitz-spaces.pages.dev/sdk/3.10.0/witbitz-sdk.js'

  const space = await new Witbitz({ tenant: 't_…' }).createSpace({   // your tenant id
    agent: { name: 'Helper', instructions: 'You help a small group plan and decide together.' }
  })
  space.on('message', (m) => console.log(m.from, m.text))  // everyone's messages, the assistant's too
  await space.send('Plan us a weekend in Kyoto')
  console.log('Share this:', space.shareLink)              // the link is the invitation
</script>

That page is a complete private, multiplayer AI app: no server of your own, no database, no key handling. Creating rooms needs a free tenant and the page's origin declared once (Do I need a tenant?); opening a room someone shared needs neither.

What you get

The whole map: the platform.

The guarantee

Privacy you can check. Rooms are sealed to keys made on the user's device; your page has no backend and reaches only Witbitz; every release is a reproducible build of published source. Neither Witbitz nor the app's builder can read the users' rooms — and you can verify it yourself.

Each room runs in one of two tiers, chosen by the app:

Details: privacy tiers.

Next

1. Build — the SDK: the example above, then members, tools, the store and private assistants.
2. Understand — the platform · the trust model.
3. Check — verify it yourself.

The platform — what Witbitz provides

Every collaborative AI app needs the same things: a room people share, an assistant inside it, storage, sign-in, permissions, a way to use outside services safely. Witbitz provides them as one platform, so your app can be a static page. This page is the map; each line links to its page.

What the platform provides

Rooms

The assistant

Data

Users

Trust

How it is built

In the browser, the app is split into realms the browser keeps apart — the vault that holds the account, the Kernel worker that holds room keys and does the cryptography, the frame that draws the screen — so a bug in the screen cannot reach a key. The app as an operating system.

On the server, a room's turns run in the standard tier or inside the confidential tier's enclave; credentials live in a separate always-on enclave, the Sentinel; storage holds only sealed records. The server can refuse service; it cannot read a room.

Your app is a static page that reaches only Witbitz. It is not backendless — Witbitz is the backend — but it is one backend, shared by every app, constrained and inspectable, instead of an opaque server per app.

The reference app: Spaces

Witbitz Spaces — a multiplayer AI room, on the web and installable on any device — is built on this same public surface. Its guide is the platform as its users see it.

What you can build

The shape of the rooms is often the product:

Access

The SDK is open: any static page can open, read and post in a room. Creating rooms from your own site needs a tenant (SDK — do I need a tenant?); the /v1 platform API is invite-only during the beta. Email hello@witbitz.chat.

How a turn runs — the assistant is a function, not a server

A Space keeps no process running. When a member posts, a turn opens the sealed room, runs the assistant with the room's tools, writes the reply, seals the room again and ends. Between turns a Space is ciphertext on disk, so an idle room costs almost nothing, and there is nothing running to read it.

This page follows one turn from the post to the reply, and then the tools, the approvals and the reads around it. The SDK does all of it for you (the SDK); this is what happens underneath.

One turn, step by step

1. A member posts — { op: 'turn', room, mk, message }.
2. Proof of the key. The server checks the key against the room's stored commitment — proof that the sender is a member, and that the reply will be sealed to the room's key.
3. Who wrote it. In a room that requires sign-in, the message is signed by the member's device and carries their sign-in; the turn checks both against the room's sealed allow-list and records only the verified author.
4. The room opens. The sealed ledger is opened, and the new message appended.
5. The assistant runs with the room's persona, model and tools.
6. The result lands — the reply, any widgets and files it made, any proposals waiting for approval.
7. The room is sealed again, and the key is dropped. Nothing about the turn is kept outside the sealed room.

Where it runs. In a standard room the turn runs on Witbitz's server, which holds the key for the length of the turn. In a confidential room the same turn runs inside a measured enclave the device verified first, and the key is sealed to that enclave alone (privacy tiers, the confidential tier).

When the assistant answers

Every message lands in the room. Whether the assistant replies is a per-room setting:

A turn with no reply returns silent: true, so the page can drop its "thinking" indicator at once. A room made only to observe (agentReplies: false) never replies. If the small model in auto cannot be reached, the assistant answers: an outage must not silently mute a group.

Tools, and what they produce

A room's tools are named in its sealed config — the server cannot read the persona, the tool list or the admission policy. A room gets only what it declares: with no tools, the assistant can talk and nothing else. Your page can add its own tools to a turn (the assistant).

Find, then show. A search_* tool returns candidates to the assistant; a second call puts the ones it chose on the shared view. Members see a curated set, not a raw result dump.

A widget is the room's, not one person's. A map, an itinerary or a chart is a shared document sealed in the room: every member sees the same one, edits reach everyone, and any shared view opens full-screen from the room's ⋯ menu.

Where a rule belongs. The persona says who the assistant is, and it is read at the top of every turn. A tool's description — and each parameter's — is read at the moment the model fills that field, so a rule about a field belongs on the field ("only if the member said one" on due). Rules moved from the persona onto the parameters are followed more reliably. Which tools a turn offers is how a page steers the assistant; what it must never do is enforced by approvals, below.

High-stakes tools become proposals

A tool that spends money, changes an outside system or crosses a policy line does not run in the turn. The turn records a proposal; a member approves or denies it; only an approved proposal runs, and only once. Your own tools can be declared the same way (proposals, end to end).

Reading the room

• Changes, without reading. A page asks with the last version it saw; the server compares a hash of the ciphertext. Unchanged, it answers at once and opens nothing.
• Sealed reads. pollsealed returns the new entries still sealed, and the device opens them with the key — the server takes no key and decrypts nothing. The SDK reads this way. The older poll op returns server-decrypted plaintext instead, opening the room with the key the page sends.
• The reply as it is written. While the model writes, the turn seals the partial reply and publishes it; every read carries it, and the page shows it growing. It is cleared the moment the finished reply lands, so it can never appear twice.
• Members who are away get a push that carries no content — only "something changed in this room". Their device wakes, reads, and shows the notification itself; the push service learns nothing.
• Gated reads. In a room that requires sign-in, every read needs an allow-listed sign-in too — the key alone does not open the history.

The sealed ledger

A room's conversation is its ledger, sealed under the room key and stored as ciphertext; there is no operator recovery key. New entries are sealed one by one as they are appended, and long ledgers are stored in segments, so a turn's work grows with what it adds, not with the room's whole history.

The operations

Every room operation is one call to POST /space, chosen by op (HTTP API):

In your own boundary

In an on-premises deployment with AIRGAP=1, the tools that reach the internet are refused; chat, files, PDFs, charts and diagrams keep working (deployment options).

Read next

• The SDK · The assistant · Embed a Space · Trust model

Run Spaces as your own tenant

Spaces — the multiplayer-AI room — is the reference app on Witbitz. This page runs it as you: your own origin, your own key vault, your own keys. You write no code; Witbitz builds and hosts it, and you can prove what it deployed.

Get Started: this → Verify it. Reference: HTTP API · SDK.

One paste

Needs curl and python3. Nothing to clone, no Cloudflare account.

# 1) Register (free). The secret is shown ONCE and cannot be reissued — this saves it.
resp=$(curl -sX POST https://api.witbitz.chat/v1/tenants/demo \
  -H 'content-type: application/json' -d '{"name":"My Space"}')
export TENANT_KEY=$(echo "$resp" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["keys"]["secret"])')
export TENANT_ID=$(echo "$resp"  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["tenant"]["tenant_id"])')
umask 077
{ echo "# $(date -u +%Y-%m-%dT%H:%M:%SZ)"; echo "TENANT_ID=$TENANT_ID"; echo "TENANT_KEY=$TENANT_KEY"; } >> ~/.witbitz-tenants
echo "saved → ~/.witbitz-tenants  (the only copy — lose it and this tenant is unreachable)"

# 2) Ask for your app. Names are first-come, first-served; set SLUG=yourname for a specific address.
SLUG="${SLUG:-myspace-$(od -An -N2 -tu2 /dev/urandom | tr -d ' ')}"
r=$(curl -sX POST https://api.witbitz.chat/v1/tenant/app \
  -H "authorization: Bearer $TENANT_KEY" -H 'content-type: application/json' \
  -d "{\"slug\":\"$SLUG\"}"); echo "$r"

# 3) Watch it — two builds and two deploys, about 90 seconds.
while s=$(curl -s https://api.witbitz.chat/v1/tenant/app -H "authorization: Bearer $TENANT_KEY"); echo "$s"; ! echo "$s" | grep -qE '"status":"(live|failed)"|"error"'; do sleep 20; done

It ends with your address:

{"status":"live","slug":"myspace-41287","url":"https://myspace-41287.witbitz.chat", …}

What you got

• A vault at <slug>.witbitz.chat — the small key-holder that runs sign-in and confines your keys. It is the address you give people and the one they install. The app it frames sits at <slug>-app.witbitz.chat.
• The app, which is Spaces. You write nothing. Witbitz builds the reference app from a pinned commit and deploys it to your origins. Your copy is pinned to your deploy — it does not change when the reference app updates.
• Your own keys. A K_eco nobody else holds, so your rooms are cryptographically isolated from every other tenant's; your own app key; your own OTP namespace. Rooms are stamped to you and split-key by default.
• Your own look. An accent colour and name derived from your slug — the welcome page, the icon and the installed app carry them, so yours is not a second copy of ours on someone's home screen.
• Sign-in that needs no setup. Google and email codes run through the central Witbitz auth service, minted as your origin. Nothing to register with Google.

While you wait

A workflow runs it one named step at a time: create the projects and the domain, mint your keys, build and deploy the vault, configure it and redeploy, the same for the app, then admit your origins, register your issuers and grant your permissions. If any step fails the ones before it are undone — projects, namespaces, keys and secrets deleted rather than left as debris — and the poll tells you which step failed.

When it refuses: refused — the slug is malformed or reserved. conflict — that name is another tenant's. too_many_requests — ten apps per address per day; registering a fresh tenant does not reset it. A refusal queues nothing, so there is no job to poll.

One app per tenant. Re-asking with the same slug re-provisions it, keeping your K_eco so existing rooms still open.

Taking it down

Three levels, because they are three decisions. Each needs the key for that tenant.

# 1. The app: projects, domain, admission, its key. KEEPS K_eco, so your rooms survive.
curl -sX DELETE https://api.witbitz.chat/v1/tenant/app -H "authorization: Bearer $TENANT_KEY"; echo
while s=$(curl -s https://api.witbitz.chat/v1/tenant/app -H "authorization: Bearer $TENANT_KEY"); echo "$s"; ! echo "$s" | grep -qE '"status":"(deleted|live)"|"error"'; do sleep 10; done

# 2. The rooms and everything in them. GET first — it deletes nothing and returns the confirmation value.
curl -s  https://api.witbitz.chat/v1/tenant/rooms -H "authorization: Bearer $TENANT_KEY"; echo
curl -sX DELETE https://api.witbitz.chat/v1/tenant/rooms -H "authorization: Bearer $TENANT_KEY" \
  -H 'content-type: application/json' -d "{\"confirm\":\"$TENANT_ID\",\"slug\":\"$SLUG\"}"; echo

# 3. The account: every key, every row.
curl -sX DELETE https://api.witbitz.chat/v1/tenant -H "authorization: Bearer $TENANT_KEY" \
  -H 'content-type: application/json' -d "{\"confirm\":\"$TENANT_ID\"}"; echo

Taking the app down keeps K_eco, the key your rooms' halves are sealed under — deleting it would not delete the rooms, it would make them permanently unopenable. Put the same slug back and they open again. Step 2 is what removes them, and it takes K_eco last. Step 3 refuses while an app or rooms remain, and tells you what is left.

Steps 2 and 3 are irreversible, so each must name the tenant it is destroying. Ask without the confirmation and the reply gives you the value.

In a new shell: set -a; . ~/.witbitz-tenants; set +a.

Proving what it deployed

Your app ships an asset manifest — every file hashed, stamped with the commit it was built from:

curl -s https://<slug>-app.witbitz.chat/assets-manifest.json | head -3
# → {"v":1,"gitCommit":"…","algo":"sha256", …}

That commit is the platform build your app was made from, and that build is fully verifiable: rebuild the published source and get the hash AWS runs (Verify it, Tests 6–7). The client is served unminified, so you can also just read it.

Your origin also serves its own signed certificate, bound to that origin, committing to the exact bytes above:

curl -s https://<slug>.witbitz.chat/cert.json | python3 -c 'import sys,json;print(json.load(sys.stdin)["signed"])'
# → {"service":"witbitz-vault","env":"tenant","origin":"https://<slug>.witbitz.chat","frontendSha256":"…", …}

So the verified-client extension reports your origin as verified, and builds the policy it enforces from that signed manifest rather than from your page.

Two limits, stated plainly rather than left to be discovered:

• It is signed by the tenant key, not the platform key. That key lives in the provisioning pipeline, and the verifier accepts it only on tenant origins — so it can attest what it deployed for you and can never speak for spaces.witbitz.chat. The separation is the point; it also means your certificate is only as trustworthy as that pipeline.
• It commits to the frontend, not to a backend. Your tenant does not run its own render, so the certificate claims the bytes it served and nothing more. The reproducible-source check (Test 7) still runs against the first-party app — the same code at the commit your manifest names.

Everything else on the Verify it page — the admission gate, the egress lock, the sealed store — is checkable against your own Space today.

Keeping it

A demo tenant is real and works immediately, but auto-purges at its expires_at. To make it permanent — same id and keys — upgrade with an author coupon, or sign up non-expiring from the start with POST /v1/tenants/signup:

curl -sX POST https://api.witbitz.chat/v1/tenant/upgrade \
  -H "authorization: Bearer $TENANT_KEY" -H "X-Author-Coupon: <code>"

No coupon? Email hello@witbitz.chat.

Not locked in. Witbitz-hosted is the easy default, not the only one. The same app is portable: point its one backend switch at your own boundary and run the entire stack yourself — same code, same verifiable-privacy properties. To embed a Space in a page you already have, see embed.

Next

• Verify it — prove the deployed bytes are the published, readable code.
• Deployment options · Embed · HTTP API · SDK

Verify It Yourself

Witbitz's claim is verifiable, not promised — so this page is where you check it, in your own terminal, instead of taking our word. It's the honest counterpart to every "enforcement-proven" line in the other docs: here are the exact commands, and here — just as plainly — is what they do not prove yet.

See also: The Verified Room (the model you're checking) · the Space link is the auth (how a real member passes) · the double blind (the privacy claim + its north-star).

What this page proves — and what it doesn't

Be exact about the scope, because "verify it yourself" is itself a claim that can overreach:

Today you can check five things on your own traffic: the gate enforces (Tests 1–3), the front-end's egress is locked to a published allowlist (Test 4), the store holds only ciphertext sealed to a key the platform never holds (Test 5), the deployed render is a faithful, reproducible build of published source (Tests 6–7) — and, in a confidential Space, that the render is unobservable in use: the room key is born inside AWS Nitro hardware, the image measurement is reproducible from published source, the enclave runs always on, and the whole check runs in your browser against a fresh nonce (the attested tier). Which Spaces are confidential is chosen per Space when it's created.

Honest position: the code is exactly this — readable, reproducible, and what AWS runs — and "it can't be watched while it runs" is buildable, checkable, and in production for any Space run in the enclave.

On a tenant app of your own. Tests 1–5 and 8 work against any Space, including one you provisioned with one paste. Since 2026-09-07 a provisioned tenant also serves its own signed certificate, bound to its own origin and signed by a key held only by the provisioning pipeline — so Test 6 closes on your origin and the verifier reports it as verified. Test 7 still does not: that certificate commits to the frontend bytes and says nothing about a backend your tenant does not run, so the reproducible-source check goes against the first-party app — the same code your tenant was built from, at the commit its manifest names.

The verifier extension — install it, and read it

Every test below is something you run by hand. The extension does it automatically, on every page load, and enforces the result — you cannot be served an unverified app with it installed.

curl -O https://witbitz.chat/site/verified-client/witbitz-verified-client-ddk9p7JsjS.zip
openssl dgst -sha256 -binary witbitz-verified-client-ddk9p7JsjS.zip | base64
# → ddk9p7/JsjSTRZGs/VUF3ruEb+wniO2rzNqsQF7Qijc=
unzip witbitz-verified-client-ddk9p7JsjS.zip -d witbitz-verified-client
# chrome://extensions → Developer mode → Load unpacked → that folder

The download is the source. Four files, 33 KB of plain JavaScript — no build step, no bundler, nothing minified. Installing it and auditing it are the same act, which is the only honest way to ship something whose job is to be trusted. Read them first: sw.js is all of the logic, config.json is what it points at and the key it pins.

What you should see. Nothing changes on the page — the signal is the toolbar icon, which a page cannot forge:

The other visible sign is the address bar: /space becomes /space?vc=1, because verification is forced rather than offered.

What it does on every load:

1. Forces ?vc=1 on /space, so verification cannot be skipped.
2. Forces a CSP built from the signed manifest — every approved script named by its hash, 'self' dropped, and the report-only twin stripped. The policy comes from material it verified against a pinned key, never from the page, so the origin cannot supply the hashes it is measured against. Its own JavaScript then executes only if the bytes match what the certificate vouches for.
3. Clears unapproved service workers, which would otherwise synthesize a response the forced CSP never reaches.
4. Checks the signed release against a pinned P-256 key and paints a badge the page cannot forge.

Honest limits. It is not in a browser store, so Load unpacked is the only route today. It is Chromium-only (Chrome, Edge, Brave), and on an engine older than Chromium 127 it keeps enforcing but stops pinning script-src by hash — below that the browser does not enforce import-map integrity, and a hash-only policy would refuse the app's own modules rather than protect them. Nothing checks freshness: a compromised origin cannot forge a certificate, but it could serve an older genuine release. And one key-holding Web Worker is no longer loaded by URL at all: the page fetches its bundle, checks the bytes, and runs it from a blob, failing closed if they do not match.

Read the render — the code that touches your plaintext

Verification is only worth as much as your ability to read what you're verifying. Plaintext opens in one place — the render: in a confidential room, inside the always-on attested enclave; in a standard room, in the server's request handler — and that surface is readable: about 1,500 lines for the seal / turn / read core, 2,700 with storage. It's published, readable, Apache-2.0:

→ the published render source

That repo is a readable mirror; the hash-verified canonical is /source.tar.gz (Test 7), which rebuilds byte-for-byte to the deployed hash. Read the logic there; confirm the bytes here.

Setup (30 seconds)

1. In the Spaces app, create a Space with "Who can post?" → Only specific Google accounts, and add any email to the allow-list. This is an admission:'email' Space.
2. From its link …/space?room=sp-XXXX#mk=YYYY&gate=email, copy the room (sp-XXXX) and the mk (YYYY) — the room key that everyone with the link holds.
3. Discover the API endpoint (it's public; the app fetches it the same way):

SPACE=$(curl -s https://witbitz-spaces.pages.dev/space-config \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["spaceEndpoint"])')
echo "$SPACE"   # the /space Lambda URL the client posts to

You now hold exactly what a link-holder holds: the room and its key. The tests below show that is not enough.

Test 1 — the read gate: the link alone reveals nothing

A token-less poll — the read op — with a valid room key:

curl -sX POST "$SPACE" -H 'content-type: application/json' -w '\n%{http_code}\n' \
  -d '{"op":"poll","room":"<ROOM>","mk":"<MK>","sinceEtag":"","sinceCount":0}'
# → {"error":"not_authorized","reason":"unsigned"}
#   403

Holding mk returns no history. Reads require an allow-listed Google sign-in — the server won't decrypt-and-return without one.

Test 2 — the write gate: you can't post without an allowed identity

A token-less turn — the write op:

curl -sX POST "$SPACE" -H 'content-type: application/json' -w '\n%{http_code}\n' \
  -d '{"op":"turn","room":"<ROOM>","mk":"<MK>","message":{"text":"hi"}}'
# → {"error":"not_authorized","reason":"unsigned"}
#   403

Rejected before anything is written — nothing lands in the Space.

Test 3 — positive control: the key is valid; the 403 is the gate, not a bad key

Create a second Space with "Who can post?" → Anyone with the link (an open Space), and poll it the same way with its room/key:

curl -sX POST "$SPACE" -H 'content-type: application/json' -w '\n%{http_code}\n' \
  -d '{"op":"poll","room":"<OPEN_ROOM>","mk":"<OPEN_MK>","sinceEtag":"","sinceCount":0}'
# → 200  (returns entries)

Same request shape, a valid key — but no admission policy, so it reads. This is the control that proves Tests 1–2 are the admission gate refusing you, not a malformed request or a wrong key. An open Space reads by the link; an email Space does not.

Test 4 — the egress footprint: the app can only talk to a published allowlist

The other three tests check the server. This one checks the app itself: a static page can fetch() anywhere, so "the app doesn't leak your data to third parties" is a real claim — and it's now browser-enforced, not promised. Read the enforced Content-Security-Policy straight off the response header — it is the exhaustive list of hosts the loaded app is permitted to reach:

curl -sI https://witbitz-spaces.pages.dev/space | grep -i '^content-security-policy:'
# default-src 'none'; script-src 'self' 'sha256-…' 'wasm-unsafe-eval' https://accounts.google.com; …
#   connect-src 'self' blob: https://api.witbitz.chat https://accounts.google.com https://kibitz.chat https://auth.witbitz.chat
#     wss://code-relay.witbitz.chat wss://inference.tinfoil.sh https://inference.tinfoil.sh; … frame-ancestors 'self'

Read it directly:

• connect-src is the data path — where the app may send anything. Each entry, and why it is there:
• 'self' — the same-origin app and its map/tile proxy; blob: — files the app made itself (a PDF you open).
• https://api.witbitz.chat — the Space backend (every read and write, sealed).
• https://accounts.google.com, https://auth.witbitz.chat, https://kibitz.chat — sign-in: Google, the Witbitz email sign-in, and the older issuer some rooms were created under.
• wss://code-relay.witbitz.chat — the room's live stream: content-free change signals and the reply as it is written, sealed with the room's key (the relay forwards bytes it cannot read).
• wss://inference.tinfoil.sh, https://inference.tinfoil.sh — press-to-talk and Play aloud: the microphone and the text go straight to Tinfoil's attested speech enclave, not through Witbitz.
• script-src allows only same-origin files and each inline block by its sha256 — no 'unsafe-inline'. So even injected script can't run, and can't exfiltrate.
• default-src 'none' means anything not named above is denied by default; form-action and object-src are shut; frame-ancestors 'self' blocks cross-origin framing.

This is the egress-allowlist half of the signed certificate (the double blind §4–6) — now shipped and enforced. You are reading the app's true data footprint off ground truth. (What it does not prove is that the render is unobservable while it runs — that's the attested tier, now live as a per-room option (the attested tier). That the render binary is the published, reproducible build is proven separately by Tests 6–7. This test bounds the front-end; the gate tests bound access.)

Test 5 — the store holds only ciphertext, sealed to a key we never hold

The other tests check access and egress. This one checks what the operator actually holds. The sealed op returns the exact bytes the server stores for a room's chat — no key required, because reading ciphertext reveals nothing:

curl -sX POST "$SPACE" -H 'content-type: application/json' -d '{"op":"sealed","room":"<ROOM>"}' | python3 -m json.tool
# {
#   "alg": "AES-256-GCM · multi-recipient envelope v1",
#   "bytes": 14554,
#   "sha256": "ad7c09…",                                     ← hash of the exact stored bytes
#   "recipients": ["room"],                                  ← WHO can decrypt: only the room key. NOT the operator.
#   "sealed": "{\"v\":1,\"iv\":\"…\",\"ct\":\"…\",\"recipients\":{\"room\":{…}}}"   ← the opaque envelope itself
# }

Two things to read straight off it:

• recipients is ["room"]. The envelope is sealed to exactly one key — the room key (mk), which lives in your link's #fragment and never reached the server (you didn't send it in the request above). The operator would be a recipient only if "beta" or "admin" appeared in that list. It doesn't. So the operator holds no key that opens this blob — an aws s3 cp, a backup, or a subpoena returns exactly these bytes: noise.
• sealed is opaque. It's an AES-256-GCM ciphertext; without mk it is indistinguishable from random. Confirm it's genuinely your chat, not a decoy, by decrypting it locally with the mk from your link — the same key the server never saw.

This is content-blindness, made checkable: what the operator stores is ciphertext sealed to a key it does not have. (What it still can't prove: that the render — the one transient moment plaintext exists to run the model — doesn't secretly keep mk. That's declared-program-in-use, addressed next.)

Test 6 — the signed build certificate: what the platform DEPLOYED, committed in public

The last surface is the render code itself — where plaintext opens (to run the model on a turn, and to return the new entries on a changed read). Full proof (that the running binary is a faithful, un-tampered build) needs an attested tier (below). But the first step ships today: the platform publishes a signed certificate at /cert.json binding what it deployed to ground truth — a build identifier (git commit), the running Lambda's AWS CodeSha256, and the egress allowlist — and the running service reports the same identifier via op:attest.

curl -s https://witbitz-spaces.pages.dev/cert.json | python3 -m json.tool
# { "signed": "{\"v\":1,\"service\":\"witbitz-space\",\"env\":\"prod\",\"gitCommit\":\"…\",\"source\":\"…/source.tar.gz\",\"sourceSha256\":\"…\",\n#     \"lambdaCodeSha256\":\"…\",\"egress\":\"…\",\"builtAt\":\"…\",\"frontendSha256\":\"…\",\"frontendCommit\":\"…\",\"origin\":\"…\"}",
#   "sig": "…", "alg": "ES256", "pubkey": {"kty":"EC","crv":"P-256","x":"…","y":"…"} }

curl -sX POST "$SPACE" -H 'content-type: application/json' -d '{"op":"attest"}'
# → { "service":"witbitz-space", "gitCommit":"<same sha>", "runtime":"aws-lambda", "platformTools":{ … } }

Verify the signature yourself — the platform's public key is published here, so compare it to the pubkey in the cert and check the signature over the exact signed string (ES256 / ECDSA P-256):

{"kty":"EC","crv":"P-256","x":"TFXrR5DFL3Oo3rBwa6clwJnrfvw0TN2AewDDEcy8hBM","y":"MgLLzEq7g8B86qS7NNxkIW64ytp296d1kkK1wSKBoec"}

// node — verifies the cert's signature against the published key (WebCrypto)
const c = await (await fetch('https://witbitz-spaces.pages.dev/cert.json')).json()
const ub = (s) => Uint8Array.from(Buffer.from(s.replace(/-/g,'+').replace(/_/g,'/'),'base64'))
const k = await crypto.subtle.importKey('jwk', { ...c.pubkey, ext:true, key_ops:['verify'] }, { name:'ECDSA', namedCurve:'P-256' }, false, ['verify'])
console.log(await crypto.subtle.verify({ name:'ECDSA', hash:'SHA-256' }, k, ub(c.sig), new TextEncoder().encode(c.signed)))  // true

What it proves: the platform has publicly, cryptographically committed to a specific deployed build (a named build id + the Lambda's exact code hash) with a specific egress. The commitment is tamper-evident (a changed cert fails the signature), and the running service reports the same build id — so the operator can't quietly point the certificate at one build while running another without it showing.

On its own, Test 6 is a tamper-evident commitment to a build. Test 7 turns it into a check of the actual code — the cert also carries sourceSha256, the hash of the published, readable source that reproduces lambdaCodeSha256.

Test 7 — the faithful build: rebuild the published source, get the deployed hash

The cert commits to a code hash. Test 7 lets you confirm that hash is a faithful build of source you can read — not a black box. The exact render source is published at /source.tar.gz; the cert's sourceSha256 pins it, and it rebuilds byte-for-byte to lambdaCodeSha256.

Needs only Node + Python 3 — no Docker. The zip is STORED (uncompressed), so the bytes don't depend on a zlib version; npm ci is deterministic for this pure-JS graph (no native binaries).

# 1) download the published render source and confirm it's the one the cert names
curl -s -o source.tar.gz https://witbitz-spaces.pages.dev/source.tar.gz
python3 -c 'import hashlib,base64;print(base64.b64encode(hashlib.sha256(open("source.tar.gz","rb").read()).digest()).decode())'
curl -s https://witbitz-spaces.pages.dev/cert.json | python3 -c 'import sys,json;print(json.loads(json.load(sys.stdin)["signed"])["sourceSha256"])'
#   ↑ these two must match — the source you downloaded IS the source the cert commits to.

# 2) rebuild it and compare to the deployed hash
tar xzf source.tar.gz && bash tools/reproduce-space-build.sh
#   → reproduced CodeSha256: <base64>
curl -s https://witbitz-spaces.pages.dev/cert.json | python3 -c 'import sys,json;print(json.loads(json.load(sys.stdin)["signed"])["lambdaCodeSha256"])'
#   ↑ these two must match — you just rebuilt the exact bytes AWS is running (its CodeSha256).

Both match ⇒ the deployed render is a faithful build of code you just read. No trust in the build server: you reproduced it.

Honest scope — the one thing left. This proves the deployed code is a faithful build of readable source. It does not prove the running process is unobservable in use — that during the transient decrypt-and-render instant, the operator (or the cloud) can't read the plaintext out of memory. That is the attested/TEE tier (a confidential-compute enclave whose remote attestation binds the running measurement to this reproducible build). Production, and independently verifiable: see the attested tier. Everything up to and including "the code is exactly this, and it's readable and reproducible" is checkable today; "and it can't be watched while it runs" is now in production for any Space the app builder runs in the enclave — its per-room choice.

Test 8 — drive the real browser: prove the locks are enforced (the CDP verifier)

Tests 1–7 read a response — a header, a stored blob, a cert. That proves what the server declares, but not what your browser actually enforces on the live app — and a passive fetch is blind to a Service Worker, which can serve tampered bytes from its own cache with no network request at all. To close that, drive a real browser and check the app's claims from the browser's ground truth — below the page, below any Service Worker:

node tools/lumen-verifier.mjs            # drives https://witbitz.chat/lumen  (pass a URL to point elsewhere)

It proves, from the running app rather than from a fetch:

• the egress-lock is enforced — it runs a forbidden fetch() inside the room and confirms the browser blocks it with a connect-src violation (not merely that the header says so);
• cross-origin isolation holds — the embedding site gets a SecurityError trying to read the room's DOM ("can't read a word");
• no rogue Service Worker — it enumerates the browser-owned registration list, which a Service Worker cannot forge; the one thing a load-time or curl check can't see;
• byte identity — the inline shell's SHA-256 is surfaced and confirmed to be one of the CSP hashes the browser pinned, so you can compare it to the reproducible source (Test 7).

Honest scope. It verifies the browser it drives — so run it yourself, or it's just checking someone else's browser (the "whose fetch" caveat, now at the browser level). It's a desktop tool; a stock mobile browser can't be driven this way — which is exactly what the native attested client (the attested client) is for: it is a controlled, bundled-local browser, so there's no rogue-worker surface and no external driver needed.

Reading the result codes

The gate is fail-closed; every rejection is a 403 not_authorized with a precise reason:

How a real member passes (the signed path)

An allow-listed member's client sends, with each request, an idToken (a fresh Google ID token) and spk (its device signing public key). The server checks, in order: the token verifies RS256 against Google's JWKS; its nonce equals spkNonce(spk) = base64url(SHA-256(canonical-JWK(spk))) (so the token is bound to this device's key); and the email is on the sealed allow-list. Only then does it decrypt-and-return, or accept the write. Full mechanism: the Space link is the auth §4. This is the async analog of the live call binding an OIDC token to a live DTLS cert — "signed by the keyholder who authenticated as this account, now."

What you can't check here yet — and why

Being explicit, so this page doesn't become the overclaim it's meant to prevent:

• Unobservable-in-use — the attested/TEE tier. The render decrypts with mk for a transient instant — on an AI turn and on every changed read, the one door plaintext opens. Tests 6–7 now prove the deployed code is a faithful, reproducible build of readable source — you can rebuild it and read it. The last thing they can't prove is that the running process can't be watched while it runs: that during that instant the operator (or the cloud) can't read the plaintext out of memory. That needs a TEE — a confidential-compute enclave whose remote attestation binds the running measurement to this reproducible build (and thereby excludes even the operator + AWS from the render). Live on real AWS Nitro hardware, always on (the attested tier); which Spaces run in it is chosen per Space when it's created. On that tier the model call also closes the last plaintext reader, the model vendor: it leaves the measured image only through an attested no-log gateway into confidential-compute inference on an open-weights model (fail-closed if that gateway does not attest) — shipped, with the frontier model kept as a per-room choice; your enclave check transitively covers that gateway's attestation.

This page grew "verify the gate" → "footprint" → "store" → "the build." The gate is live (Tests 1–3), the footprint is live (Test 4), the store is sealed to a key we never hold (Test 5), the signed build commitment is live (Test 6), and the faithful, reproducible build of published source is live (Test 7). Everything up to "the code is exactly this — readable, reproducible, and what AWS runs" is now checkable. What remains is only "and it can't be watched while it runs" — the attested/TEE tier, live and always on — create the Space confidential and verify it against the running enclave's published measurement (above).

The SDK — build an app on Witbitz

The SDK is one ES module a static page imports. With it your page creates and opens Spaces, sends and reads messages, runs the room's assistant, keeps your app's data in the room, signs people in and checks where a room runs — while the room key, the sealing and the polling stay inside it. Your server, if you have one, uses a second module, WitbitzAdmin, for your tenant's own settings.

Why your users can trust what you build with it: the overview and the trust model.

Status: public beta. Usable today from any static page. The core — create a room, open it, send, listen — is small and meant to stay stable; around it the surface has grown with the platform (lanes, the store, sign-in, connections, voice, certificates), and any change that can break your code is listed under Changes. It wraps the exact reference client the production Spaces app runs on — nothing is forked or reimplemented.

The whole thing

Creating a room needs your tenant id on the page and the page's origin declared once (Do I need a tenant?); opening or posting in a room someone shared needs neither.

<script type="module">
  import { Witbitz } from 'https://witbitz-spaces.pages.dev/sdk/3.10.0/witbitz-sdk.js'

  const wb = new Witbitz({ tenant: 't_…' })   // your tenant id

  // A private, agent-backed room. The link IS the auth — share it to let someone in.
  const space = await wb.createSpace({
    agent: { name: 'Helper', instructions: 'You help a small group plan and decide together.' }
  })

  space.on('message', (m) => console.log(m.from, m.text))   // yours, others', and the agent's — all arrive here
  await space.send('Plan us a weekend in Kyoto')            // the agent answers on its own turn → via on('message')

  console.log('Share this:', space.shareLink)
</script>

That page is a complete multiplayer AI app, private to its members: no backend of your own, no key handling, no database.

Try it

Three example apps run live; each one's source is beside it on the same origin.

The pages

Start with Rooms and messages and The assistant; the rest you need when your app needs it.

Load it

Versions

Load a version in production: https://witbitz-spaces.pages.dev/sdk/<version>/witbitz-sdk.js (and witbitz-admin.js, witbitz-sdk.d.ts, witbitz-admin.d.ts beside it; from 2.2.4 also witbitz-admin.mjs, the admin client in one file for your server). A released version never changes, so our next release reaches your app only when you move the number. Each version's manifest.json lists a sha384 integrity hash for every file it contains, if you want the browser to check them too. The versions so far: /sdk/versions.json.

Versions follow semver: a change that can break your code comes in a new major version, listed under Changes (3.0.0 retired fork() — members change in place). An older release keeps working at its fixed address until what it depends on is retired, and Changes says when. An npm package is coming.

Your page's CSP

The SDK is a single ES module; importing it from the address above pulls its other files from the same origin. Your page's Content Security Policy must allow:

Invite links

A link reads <viewer>/space?room=<id>#mk=<key> — viewer is new Witbitz({ viewer }) (default: the reference app), so links open on your page if you set it to your origin and serve /space there. Variants in the fragment: #s=<share> (a shared-key room), #us=<half>&spc=<commit> (a split-key room), plus &enc=1 (confidential) and &gate=email (email-gated). The fragment never reaches a server. openSpace does not read the page's URL for you; to check it:

function isSpaceLink(href) {
  try {
    const u = new URL(href)
    const frag = new URLSearchParams(u.hash.slice(1).split('?')[0])
    return !!u.searchParams.get('room') && (frag.has('mk') || frag.has('s') || frag.has('us'))
  } catch { return false }
}
if (isSpaceLink(location.href)) space = await wb.openSpace(location.href)

The reference viewer is the fastest way to see a Space; a production app usually draws its own with on('message') and send, as the example does.

Do I need a tenant?

So "any static page, no backend" holds for everything except creating rooms, which needs a tenant id on the page and a one-time origin declaration — no key on the page, still no backend.

Get a tenant (free; the secret key is shown once — keep it off your page), then declare the origin your page runs on:

curl -sX POST https://api.witbitz.chat/v1/tenants/demo -H 'content-type: application/json' -d '{"name":"My app"}'
# → data.tenant.tenant_id (t_…, for the page) and data.keys.secret (wsk_…, for your terminal or server only)

curl -sX PUT https://api.witbitz.chat/v1/tenant/webhooks -H "authorization: Bearer $WSK" \
  -H 'content-type: application/json' -d '{"origins":["https://app.example.com"]}'

A demo tenant expires unless you upgrade it, keeping the same id and keys (Keeping it). The origin rules: Your page origins.

Rooms and messages — what a Space holds

A Space is a room: its members, their messages and the assistant's, a name, and the files people share. This page is how your page makes or opens a room, reads what is in it and writes to it.

Part of the SDK · every call: the reference.

Create and open a room

const space = await wb.createSpace({ agent: { name: 'Helper', instructions: 'You help a small group plan together.' } })
const same = await wb.openSpace(link)
await space.ready
const saved = space.snapshot()
space.close()

• wb.createSpace(opts) makes a room and returns it, live. agent is { name, instructions, tools?, model? }: the name up to 80 characters, the instructions up to 4,000. tools, immediateTools, tier and key are fixed when the room is made, and admission changes only through changeMembers(); everything else changes in place. An option the SDK does not know is refused.
• wb.openSpace(link, { resume?, tier? }) joins a room from its link. The key is in the link's fragment, which never reaches a server. openSpace does not read the page's own address; to open it, pass location.href (invite links).
• space.ready resolves once the room's whole history has been read — a long room loads in pages. From then, messages and data.rows() hold everything the room had. It rejects only when the key can never open the room (cannot_open) or the handle was closed first (closed).
• space.snapshot() returns { count, etag, messages, rows } as JSON. Pass it back as resume and the next open continues from it instead of reading the whole room again.
• space.shareLink is the link to give someone: holding it lets them in. space.room is the room's id.
• space.close() stops listening and releases the handle.

Temporary rooms

const desk = await wb.createSpace({ agent, tier: 'enclave', temporary: { days: 7 } })   // kept 7 days after its last question
const quick = await wb.createSpace({ agent, temporary: true })                          // wiped about 30 minutes after it goes quiet

• temporary: true makes a room Witbitz wipes once it has been idle for about 30 minutes, like the app's temporary Spaces. temporary: { days } (1 to 7) keeps it that many days after its last question, then wipes it: a help desk on a public page that a visitor comes back to. Each question pushes the date out again.
• A temporary room is never in the account backup. space.temporary is true for one.
• Where a deployment cannot wipe rooms, the call is refused (temporary_unavailable) rather than making a room that stays. A value other than true or { days: 1–7 } is refused (invalid_temporary). Not in a vault yet (vault_unsupported).

Messages: who sent what

space.on('message', cb) hears every entry in the room — your messages, other members', the assistant's replies, store writes and system lines — and space.messages is the list so far. On a room you open, the history is replayed to cb first; pass { replay: false } to hear only what arrives after it. Every on() returns a function that removes the listener.

A message is the room's entry as stored, decrypted on the device, with from taken from name when it has none. Its fields depend on its kind (Message types them all):

Any message may also carry verified, user and spk (the sender passed the room's gate), replyTo, md, and voice (it was dictated). One copied in by an older client's move carries carried — its marks from the room it was written in — and carriedBy.

self: true means the room's assistant produced it. The server sets it on the assistant's replies and data writes and on nothing else; it never means "I sent this".

space.on('message', (m) => {
  if (m.sys) return renderSystemLine(m)                    // a settings change, a connection call
  if (m.self && m.kind === 'text') return renderReply(m)   // the assistant
  render(m, { mine: m.from === MY_NAME })                  // MY_NAME: the `from` you send with
})

In a gated room, from is only a name the sender typed. What the server verified is m.user, the sender's @username when they have one, and m.spk, the signing key of the device that sent it — each device has its own. So "is this mine" is m.user against your own @username, or, for a member with none, m.spk against this device's key, which reads your other devices' messages as someone else's. The Spaces app checks both:

const me = await wb.usernames.mine().catch(() => null)   // throws when signed out
const isMine = (m) => !!(me && me.username && m.user === me.username) ||
  !!(m.spk && session.sign && m.spk.x === session.sign.pub.x && m.spk.y === session.sign.pub.y)

Send

const r = await space.send('Plan us a weekend in Kyoto', { from: 'Dana' })
if (!r.ok) showError(r.error)

• The answer comes separately. The assistant decides whether to reply, on its own turn, and the reply arrives on on('message'). To wait for the answer to this message, use space.turn().
• send() never throws. It answers { ok: true } when the message was posted, and { ok: false, status, error } for a refusal; every case is in Error codes.
• instructions (up to 8,000 characters) reach the assistant for this reply only — today's date, "answer in Hebrew" — and are never stored. mode overrides the reply mode for this turn.
• images (up to 4) and files (up to 2) are { b64 | bytes, mime, name? }, stored sealed in the room. Over the limits, the call is refused before anything is sent.

Replies and reactions

await space.send('Saturday works for me', { replyTo: m })
await space.react(m, '👍')
await space.react(m, '👍', { off: true })
space.on('update', ({ message, fields }) => rerender(message))

A reply is shown with the message it answers quoted beside it, as in the Spaces app; it carries replyTo: { key, name?, excerpt? }. A reaction is written on the message itself — no new entry, no assistant turn — and reaches every device as an 'update', the event for any message changed in place (a reaction, an image's caption, a reply's cards). A reacted message carries reactions, emoji → the names that reacted; in a verified room reactKeys maps each name to its key.

Attachments

The images and files on a message are stored apart from it, sealed under the room key. await space.attachment(att) fetches one — message.images[i] or message.files[i] — and opens it on the device: { b64, mime, name? }.

Safe media

In a room with Safe media on, a photo or a PDF someone else posted is never opened on a member's device. What is shown is a safe copy: JPEG images made once, when the file is posted, by an attested Witbitz enclave (the tools enclave). It opens the file in a one-shot process with no network and no keys, and keeps nothing. A PDF's copy is its first page. The copy is stored beside its original, and each device checks the enclave's hardware attestation over the copy's exact bytes before it draws anything. A copy that does not check out is never shown. The same setting is Safe media in the Spaces app (⋯ → This Space).

const space = await wb.createSpace({ agent: { name: 'Desk' }, safeMedia: true })   // or, later:
await space.safeMedia.set(true)                    // = space.configure({ safeMedia: true }); a line says who turned it on

space.on('message', async (m) => {
  if (!m.images?.length || m.self) return
  const copy = await space.safeMedia.copy(m)       // { ok, versions: [{ w, h, b64 }] }, or { ok: false, why }
  if (copy.ok) draw(copy.versions.at(-1).b64)      // the largest version, image/jpeg
  else showCard(m)                                 // no verified copy (yet): show a card with the name instead, never the original
})
space.on('safeCopy', ({ for: f }) => redraw(f.id)) // a copy arrived after its message

• The setting. createSpace({ safeMedia: true }), space.configure({ safeMedia }) or space.safeMedia.set(on). In a room that names admins, only an admin may change it. In a room without admins, any member may. Every member sees a line saying who did, and 'safeMedia' fires ({ on, from, ts }). space.safeMedia.on is what this handle knows (null before await space.safeMedia.refresh()).
• Making the copies. While the setting is on, send() makes the copies of the photos and PDFs it sends, and posts each one beside its message once the room has stored it. This needs a signed-in session (Sign in): it is counted to the account (300 files an hour). If the page is signed out or offline, or a file is over 3 MB, the message goes without a copy. Anyone may then call await space.safeMedia.make(message, { at, i }) (→ { ok, error? }).
• Reading. await space.safeMedia.copy(message, { at, i }) returns the first copy whose every version verifies here. at is 'images' or 'files', i the attachment's index; the default is the first image, else the first file. Copies are kept beside their message: they never appear in messages.
• Opening the original is the reader's choice, and only after asking. Fetch it with space.attachment(…). Before you open it, await space.safeMedia.isOriginal(copy, b64) checks that it is the file the copy was made from.
• Your own files are yours: draw them as you sent them.

What the enclave sees: the file, sealed by the posting device to the enclave's attested key. The Space server carries it but cannot read it. The enclave answers with the copies and a signed statement that names the original's hash and each copy's hash; the hardware attests that statement. In a vault (vault mode), the setting and copy() work, make() is refused (vault_unsupported), and send() makes no copies.

The room's name

space.title is the room's name, the same on every member's device and in the Spaces app; null until it has one. space.rename(name) changes it: every member sees the new name and is notified as for a message, and the Spaces app shows "Alon renamed this Space to “Kyoto”".

space.on('title', ({ title, manual, by }) => { document.title = title })
await space.rename('Kyoto in September', { by: 'Alon' })   // → { ok: true, title: 'Kyoto in September' }

While a room holds one person and the assistant, its name follows the conversation: one is made after the first exchange and revised as the subject changes, with no line and no notification. Once anyone renames the room, or a second person joins, no name is made again.

• A name is 1–80 characters; whitespace is folded and control characters dropped.
• A name is not a message: it is never in messages and never fires message. snapshot() keeps it.
• When two renames arrive at nearly the same moment, every device keeps the one the server stamped last.
• Refusals: an empty name throws bad_request. In a room with owners or admins only they may rename it (not_admin); in a room without them, any member may. A direct chat is named after the other person and is never renamed (direct_chat). In a gated room a rename is a write like any other: not_authorized with e.reason not_on_list (the signed-in email is not on the list) or unsigned (no one is signed in; a sign-in that did not verify says token: …).
• unavailable: the room did not answer, and nothing was stored — try again. ok: false means an older server stored the name without announcing it; members see it the next time they open the room.

Live updates

In a browser, each open room holds one socket on the Witbitz relay (wss://code-relay.witbitz.chat), and what happens in the room arrives down it at once: the assistant's reply grows on partial as it is written, and a new message is fetched the moment it lands. It works in every room — open, gated and confidential.

• The relay learns nothing. The socket's channel is derived from the room key and every frame is sealed under it. A gated room's channel also needs a short-lived grant that only a read that passed the gate hands out, so a member you remove stops hearing the room from the next message on.
• Every write, not only replies. A store write, a reaction, an approved card, a copied message or a settings change sends a signal that carries no content, so other open devices fetch it at once.
• Polling is still the record. If the socket cannot open, the room reads every 0.9 s after activity and every 3 s when idle; a lost frame costs one read, never a message.
• Cards come with the reply. A card the assistant proposed during a turn is fetched as that reply lands, not at the next 1.5 s check, whenever you listen for proposal.
• Your CSP needs wss://code-relay.witbitz.chat in connect-src. new Witbitz({ live: false }) turns the socket off.

The assistant — who it is, when it answers, what it may use

Every Space has an assistant. This page is how you set it up and change it, when it answers, how your code gets its answer — or runs it as a function — which tools it may use, and voice.

Part of the SDK · every call: the reference.

Its name, instructions and model

You name the assistant when you make the room (createSpace({ agent: { name, instructions, model? } })), and change it later, in place, with configure:

await space.configure({ agent: { instructions: 'Never invent a value. Never create a project unasked.' } })

• What changes in place: the assistant's name, instructions and model; the store's collections (data; data: null removes them); which platform tools it gets (platformTools); the builder framing; and whether it may write rows (dataWrites). configure answers { changed }, the fields it applied.
• Every change is visible. The room's settings are sealed again with the change, and a system line — “⚙️ You changed the assistant's instructions” — lands in the room for every member, and in the assistant's own context. The next turn runs on the new settings. A room's assistant never changes silently.
• What does not change in place: the room's tools (tools, immediateTools, agent.tools), its tier and its key are fixed when it is made; its members change only through changeMembers(). For a different setting, make a new room and copy what you need into it.
• Refusals, made by configure before anything is sent: create_time (a field fixed at creation), use_fork (admission — use changeMembers), lane (on a lane), unknown_field (anything else). A room whose owner signed its policy refuses every change in place with governed_room; another client that tries gets config_immutable from the server.

The model and its reasoning effort

model is a model id — 'kimi-k3' — or an object that also sets how hard the model reasons before it answers:

const models = await wb.models({ tier: 'enclave' })   // [{ id, label, wire, efforts, defaultEffort, default }]
await space.configure({ agent: { model: { catalog: 'kimi-k3', params: { reasoning_effort: 'high' } } } })

The levels run none · minimal · low · medium · high · xhigh · max, and each model takes only some of them — the list differs by model, and for some models by tier. wb.models() returns each model's efforts, measured against the live provider rather than copied from its documentation; an empty list means the model takes none, so leave the field out.

• A room that names no effort gets defaultEffort, which is low. A room that names no model gets the tier's default: gpt-6-sol on the standard tier, deepseek-v4.1-flash on the confidential one.
• createSpace, privateLane and configure refuse a level the model does not take, before anything is made, with invalid_effort and a message naming the levels it does take. A stored room whose model no longer takes its level (after switching models) runs at low rather than failing.
• Higher levels cost more tokens and time. On most models low is right for a conversational assistant; reach for high or above in a room whose job is analysis.

The table is generated from the live catalog; when they differ, wb.models() is right.

When it answers

await space.setReplyMode('ondemand')
await space.replyMode()                             // → 'ondemand'
await space.send('Thoughts?', { mode: 'always' })   // this turn only

It is the same setting as the Spaces app's reply chip, and a turn re-reads it once it is 20 s old. How the choice is made: how a turn runs.

A turn you can hold

send() behaves like a room: you post, and whatever happens next arrives on on('message') — the assistant may answer or stay quiet, and other people may speak first. When your code needs the answer to this message, use turn():

const t = space.turn('Plan the trip', { timeoutMs: 120_000 })
t.on('partial', ({ text }) => draft.textContent = text)
const { status, reply, error } = await t.finished
if (status === 'done') show(reply)
else if (status === 'silent') hint('The assistant stayed out of it.')
else if (status === 'failed') warn(error)

• finished resolves { status, reply, text, proposed, usage?, error? } and never rejects. status is 'done', 'silent' (the assistant chose not to answer), 'failed' (with the server's error, such as not_admitted), 'aborted' or 'timeout'. reply is the reply as a message — the same object on('message') receives.
• partial streams this reply as it is written; t.text is the text so far, and t.result is send()'s answer once the server gave it.
• t.abort() stops the reply and keeps what was written as the reply. Only the device that started a turn can stop it. timeoutMs (default 180 s) stops it the same way.
• One reply at a time. A message sent while another reply is running is held and sent again, as send() does; a held message is not sent after abort() or the timeout. The turn's reply is the first assistant message after the attempt that ran.

What a turn used

send()'s answer and finished carry usage — the turn's model calls added up, from the provider's own figures — so you can measure a turn without waiting for the day's billing:

const { usage } = await space.turn('Summarise the week').finished
// { tokensIn: 18240, tokensOut: 612, tokensCached: 15872, costMicros: 2140, costUsd: 0.00214,
//   calls: 2, models: ['deepseek/deepseek-v4.1-flash'], source: 'provider' }

• costMicros is in millionths of a dollar. source: 'provider-partial' or 'none' means some calls reported no cost, and the total counts only those that did. No usage means the turn made no model call.
• A reply longer than about 30 s reaches send() as pending: true, with no usage; space.turn() then reads it from the stored reply. Every assistant message in messages carries the server's record as usage (in, out, cached, costMicros, models).

The assistant as a function

space.run(input, opts) runs the room's assistant once and gives you its answer. Nothing is written to the room — no message, no reply, no card, no notification. Use it for work that is not a conversation: pull fields out of a text, classify a request, draft something your app shows its own way.

const r = await space.run('Invoice 2291 from Acme, total 1,240.50 EUR, due 30 Nov', {
  instructions: 'Extract the invoice fields.',
  schema: { vendor: 'string', total: 'number', due: 'string' },
})
if (r.ok) console.log(r.output)   // { vendor: 'Acme', total: 1240.5, due: '30 Nov' }
else console.log(r.error, r.detail)

• The room is the container. It admits the call (its gate and its key) and pays for it, as for a turn; its store is readable to the assistant through data_query. The assistant sees input, not the room's conversation.
• Your prompt only. A run gets the room's instructions plus instructions, with no Spaces framing — as in builder mode, whatever the room is set to.
• Only tools that need no approval. A card is a write, and a run has no member to approve it, so tools that would propose — data writes, effectful app tools, a lane's message into the room — are not offered.
• schema asks for structured output: { field: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' } (every field required, no others) or a JSON Schema object. The assistant hands its result to a final_answer tool, the result is checked, and output always fits.
• Text and images (images, up to 4). Files are read through the room, with read_file.
• Who pays: your user's own key (a user token), your app's key, or a funded room — never Witbitz.
• Limits, per room: 4 runs at once and 60 a minute.

Tools

Name the tools the assistant may use when you make the room. The ones in immediateTools it calls directly; the rest become proposals a member approves before they run.

const space = await wb.createSpace({
  agent: { name: 'Travel', instructions: 'Plan trips; put options on the shared map and list.' },
  tools: ['search_places', 'show_places', 'add_place', 'search_flights', 'show_flights', 'set_itinerary'],
  immediateTools: ['search_places', 'show_places', 'set_itinerary'],
})

The whole catalogue — places, flights, the itinerary, charts, photos, read_file, read_url, write_pdf — and what each produces: How a turn runs. Your page's own functions become tools as a private lane's actions, or for one question in any room (below).

Your page's tools, for one question

send(text, { tools }) offers the assistant your page's own functions for that question only, in the shape a lane's actions take. An await tool runs on this page while the turn waits and its result goes back to the assistant; a propose tool becomes a proposal a member approves.

await space.send(question, { tools: [
  { name: 'search_guide', description: 'Search the help guide', input: { topic: 'string' }, mode: 'await',
    run: async ({ topic }) => searchGuide(topic) },
  { name: 'where_am_i', description: 'The screen the person is on', mode: 'await', run: async () => currentScreen() },
] })

• Nothing is stored in the room: offer the tools again with each question that may need them.
• At most 20 tools a question; the call is refused before anything is sent over that.

Choosing the platform tools

Every assistant also gets Witbitz's platform tools: web_search, fetch_url, read_file, write_pdf, look_at_image, show_photo, show_chart, show_diagram, search_places, show_places and add_place; connection_call in a room with an API-key connection; and cross_to_shared in a private lane. Their descriptions go with every model call — about 4k tokens, plus about 1k of guidance for places and photos, paid again on each round of a turn's tool loop — so if your assistant uses only some, name them:

await wb.createSpace({ agent, platformTools: ['web_search', 'read_file'] })   // only these two
await wb.createSpace({ agent, platformTools: false })                         // none
await space.configure({ platformTools: true })                                // all again (the default)

• Your own tools, a lane's actions and the store's tools are not platform tools; this setting leaves them alone.
• The guidance for places, photos and shared files goes to the model only when those tools are offered.
• cross_to_shared is how a private lane posts into its shared room, after the member approves. A lane whose list leaves it out cannot post there, and its assistant says so when asked to.

Builder mode: only your prompt

By default the assistant is framed as a member of a Spaces group chat: a line saying so, rules for formatting and place links, and, in a private lane, how the member's shared room works and how cross_to_shared reaches it. That suits a chat app; in an app of your own it can get in the way. framing: 'builder' leaves it all out: the model gets your instructions, the conversation, the message and the tools you chose, and nothing else.

const lane = await space.privateLane({
  agent: { name: 'Keep', instructions: 'You are Keepwarden\'s assistant. Change things only through our actions.' },
  framing: 'builder',
  data: { tasks: { title: 'string', done: 'boolean' } },
  dataWrites: false,              // it may read the store (data_query) but proposes no data_put / data_delete
  platformTools: ['web_search'],
})
await space.configure({ framing: null, dataWrites: null })   // back to the defaults

framing works on createSpace, privateLane and configure. Tool descriptions are unchanged — they describe each tool, not your app — and a shared file is still announced to the model when read_file is offered.

See the prompt. send(text, { showPrompt: true }) (and turn() with the same option) answers with prompt: the exact system text, user text, model and tools that turn sent. Nothing extra is stored. A turn longer than about 30 s answers pending without it; send a quick message to read it.

const { prompt } = await lane.send('explain how to use the app', { showPrompt: true })
console.log(prompt.system, '\n---\n', prompt.user, prompt.tools.map((t) => t.name))

Voice input

wb.dictation() is the press-to-talk the Spaces app uses: words appear as the person speaks, and the final text arrives about half a second after they let go.

const mic = wb.dictation()
button.onpointerdown = () => mic.start({ onPartial: (text) => (input.value = text) })
button.onpointerup = async () => { input.value = await mic.stop() }

mic.cancel() throws a press away, mic.close() hangs up at once (otherwise after 15 quiet minutes), and mic.listening is true while it records.

• The audio never reaches Witbitz. The page streams it straight to Tinfoil's confidential realtime enclave (Voxtral Mini 4B Realtime); Witbitz only gives the page a short-lived key, capped at a few cents.
• Who may use it: a signed-in person (wb.signIn) or one your server vouched for (wb.useUserToken, see billing, per user). With neither, start() throws sign_in_required before it asks for the microphone.
• Languages: 13, among them English, French, Spanish and German. Not Hebrew — Hebrew speech comes back in Latin letters.
• Cost: one connection stays open across presses, about $0.002 each. Today Witbitz pays; it is not yet billed to your tenant.
• Your CSP needs wss://inference.tinfoil.sh in connect-src; the browser needs a secure context and the person's permission for the microphone.
• Errors (code): sign_in_required (not signed in, or the sign-in or token was refused), stt_rate_limited (a few keys per person per hour), stt_unavailable, voice_unattested (the speech service did not prove what it runs — nothing was sent to it), mic_denied, already_listening.

Reading aloud

wb.speak(text) reads text aloud with the Spaces app's Play aloud player, and resolves when it has finished:

button.onclick = () => wb.speak(lastReply.text)
stopButton.onclick = () => wb.speech.stop()

wb.speech.playing is true while it plays, and wb.speech.play(text) is the same call.

• The text never reaches Witbitz. The page sends it straight to Tinfoil's attested speech model and plays what comes back; Witbitz only gives the page a short-lived, capped key.
• Who may use it: as for voice input — a signed-in person or one your server vouched for; with neither, speak() rejects with sign_in_required before anything is sent.
• Long text is read in pieces cut at sentence ends: a short first piece, so sound starts in about two seconds, and each next piece fetched while the one before plays. A new speak() stops the one playing.
• Languages: not Hebrew — neither speech model has it.
• Cost: about $0.002 a request whatever its length; a paragraph is two to four. Today Witbitz pays.
• Your CSP needs https://inference.tinfoil.sh in connect-src and blob: in media-src. Most browsers play sound only after the person has tapped something on the page.
• Errors (code): no_hebrew (refused before anything is spent), empty, sign_in_required, tts_rate_limited, tts_unavailable, voice_unattested, http_<status>, audio / play (the browser would not play it).

Approvals — nothing effectful runs until a person says yes

The assistant can propose; only a member makes it happen. A tool not in immediateTools, a write to the store, a private lane's message into the shared room, a call on a connected service: each is parked as a proposal — a card a member approves or denies — and nothing happens until they do. The one exception is an MCP tool a room was granted to run on its own (connection calls). This page is that round trip.

Part of the SDK · every call: the reference.

Proposals, end to end

A proposal is { id, kind, action, args, text, approve(opts?), deny(opts?) }. kind is 'action' — a tool call — or 'message', a private lane's message into its shared room; action is the tool's name, and args the whole parked call, type included. data_put and data_delete are always proposals.

In a shared room, the server runs the action on approval:

const space = await wb.createSpace({ agent: { name: 'Ops', instructions: 'Track tickets.' }, data: { tickets: { title: 'string' } } })
space.on('proposal', (proposal) => showCard({
  title: proposal.action, args: proposal.args,
  onApprove: () => proposal.approve({ from: 'Ann' }),   // your card's buttons
  onDeny: () => proposal.deny({ from: 'Ann' }),
}))
space.on('resolved', (e) => hideCard(e.id))
await space.send('Open a ticket: printer on 3 is down')   // the assistant calls data_put: a card

showCard and hideCard are your page's own interface.

The approved write then arrives as a message (kind 'data') and a 'data' event. 'resolved' carries { id, approved, action, result }, where result is what the server did; result.ok === false means it did not go through (a message the room refused, for one).

In a private lane, your page runs the action on approval:

const lane = await space.privateLane({
  agent: { name: 'My assistant' },
  actions: [{ name: 'book_room', description: 'Book a meeting room', input: { room: 'string', at: 'string' },
              run: async (act) => api.book(act.room, act.at) }],   // act = { type: 'book_room', room, at }
})
lane.on('proposal', (proposal) => showCard({
  title: proposal.action, args: proposal.args,
  onApprove: () => proposal.approve({ from: 'Ann' }),   // the server records the approval, then the SDK calls run(act)
  onDeny: () => proposal.deny({ from: 'Ann' }),
}))
lane.on('resolved', (e) => console.log(e.result))
await lane.send('Book Kyoto for 3pm')

run()'s return value comes back as result, on 'resolved' and in approve()'s answer ({ error } if it threw); it is not sent to the assistant. A lane's message into the shared room (kind: 'message') is posted when approved.

• Listening starts the check. on('proposal') starts a check for waiting cards every 1.5 s, in any room; a lane looks at once, as soon as your listener is attached, so a card already waiting when the app reopens arrives straight away. A card proposed during a turn arrives with that turn's reply.
• A refusal keeps the card. If the room refuses the decision, approve() and deny() throw and the card stays pending.

Actions your page runs

A private lane's actions are your page's own functions, offered to its assistant as tools. The assistant can only propose them; when the member approves, the runtime records the approval and the SDK runs your run() handler on the member's device — the runtime never runs it, so the credential and the side effect stay with you. That is the part that is hard to build safely by hand: the propose → approve → run state machine, the record of who approved what, and the guarantee that the assistant cannot act alone.

An action can also be a read. Give it mode: 'await' and the assistant may call it during the turn for something only the device knows; the SDK runs your handler and hands its return value back to the turn (within 25 s). It needs no approval, because it changes nothing.

How to offer actions for one turn only, or change the standing set: private lanes. The limits on actions: Reference.

Deciding by id

const waiting = await space.pending()                 // checks now → the waiting cards
await space.approve(waiting[0].id, { from: 'Ann' })   // the same as the card's own approve()
await space.deny(id, { from: 'Ann' })

approve(id, { recordResult: false }) is for a connection call whose answer you hand the assistant yourself: the room records the call — who approved it, what it was, how it went — but not the answer.

Who may decide

In a room with admins, a member who is not one cannot approve or deny a card that would do something they may not do themselves: an admin-only row, or a connection call that spends the room's connected account. The room refuses with not_admin, and the card stays pending for an admin. A member's own lane is theirs to decide.

Connection calls

A call through an API-key or OAuth connection is always a proposal a member approves. An MCP tool is too, unless it is in the connection's auto set — chosen by whoever grants the connection to the room (the member in the Spaces app, or your page with grant(conn, { auto })); by default it is the tools the server itself marks read-only, a claim the server makes and Witbitz does not verify. An auto call still goes through the Sentinel: the model never sees the credential, and the connection's host and scope still apply.

The Sentinel adds the secret and makes the call; see connections and MCP servers.

The room as a store — your app's data, sealed with the conversation

A Space can hold your app's data, not only its conversation: rows in named collections, sealed like everything else, ordered by the server without reading them, and readable by the assistant. An app can keep all its state in its rooms, with no database of its own.

Part of the SDK · every call: the reference.

Declare and write

Declare the collections when you make the room, or later with configure. Give each field one line: what it is, and the rule for it. Those lines go into the assistant's tool descriptions on every turn and are read at the moment it fills the field, so a rule about a field belongs on the field; who the assistant is belongs in its instructions.

const space = await wb.createSpace({
  agent: { name: 'Planner', instructions: 'Keep my week honest.' },
  data: {
    tasks:    { description: 'things to do', fields: { title: 'short text', due: 'ISO date — only if I said one', done: '0 or 1' } },
    projects: { fields: { name: 'short text' } },
  },
})

await space.data.put('tasks', { title: 'Buy milk', due: '2026-09-22', done: 0 })
await space.data.put('tasks', { title: 'Buy oat milk', done: 1 }, { id: 't1' })   // with an id: replace that row
await space.data.delete('tasks', 't2')
space.data.rows('tasks')   // [{ id, title, due, done, _updated, _by, _v }, …]
space.data.get('tasks', 't1')
space.on('data', ({ ops, from, self }) => rerender())   // every write, yours or the assistant's

space.data.batch(ops) writes several rows as one entry. A write answers { ok: true, id, ops } and throws on a refusal.

The store is the room's history. Every write is one entry in the room — ▦ Dana saved tasks “Buy milk” — so every member sees it, two devices writing different rows never collide, and any device holding the key rebuilds the store by reading the room. There is no second copy to drift. A row is at most 16 KB.

What the assistant gets, in a room that declares collections:

dataWrites: false lets the assistant read the store without proposing writes (builder mode). id and every field name starting with _ are the room's own: a write that sets one is refused (reserved_field) — what they carry is in who did what.

Row schemas

Field descriptions guide the assistant; a schema is enforced. Give a collection schema — JSON Schema for one row — and the room checks every write against it, so a row that does not fit is never stored:

const space = await wb.createSpace({
  agent: { name: 'Ops' },
  data: {
    tasks: {
      description: 'things to do',
      schema: {
        type: 'object',
        properties: {
          title:    { type: 'string', minLength: 1, maxLength: 80, description: 'what to do' },
          due:      { type: 'string', format: 'date' },
          priority: { enum: ['low', 'normal', 'high'] },
          estimate: { type: 'number', minimum: 0, maximum: 40, description: 'hours' },
        },
        required: ['title'],
        additionalProperties: false,
      },
    },
  },
})

try { await space.data.put('tasks', { title: 'Call', priority: 'urgent' }) }
catch (e) { e.code === 'invalid_row' /* tasks: priority must be one of "low", "normal", "high" */ }

• Your writes: a row that does not fit is refused with invalid_row, naming the field. In a batch, one bad row refuses the whole batch.
• The assistant's writes: a data_put that does not fit is never proposed — the assistant is told why and tries again, so no member is asked to approve a row that would fail. A card is checked again when it is approved, in case the schema changed meanwhile.
• The assistant reads the rules: each field's type, allowed values, required and description appear in its data tools. A schema's descriptions take the place of fields.
• Supported: type, properties, required, additionalProperties (true/false), enum, const, minLength/maxLength, minimum/maximum/exclusiveMinimum/exclusiveMaximum, items, minItems/maxItems, and format (date, date-time, email, uri); description, title, default and examples are kept as notes. Anything else — pattern too, since our servers do not run regular expressions from a room's settings — is refused when you declare it (invalid_schema), never silently ignored. Up to 8 KB a schema, nested 6 levels.
• New writes only. Changing a schema with configure({ data }) does not touch the rows already stored, and rows an older client's move carried are not checked again. Confidential rooms run the same checks.

Conditional writes

Two devices editing the same row is the one case a room's history cannot settle by itself — the last write would win — so a write can be made conditional. Every row carries _v, the id of the entry that last wrote it; pass it back, and the write is refused if the row has changed since:

const t = space.data.get('tasks', 't1')
try {
  await space.data.put('tasks', { ...t, done: 1 }, { id: 't1', ifVersion: t._v })
} catch (e) {
  if (e.code === 'row_changed') { /* e.conflicts: [{ collection, id, version }] — read again, merge, retry */ }
  else throw e
}
await space.data.put('tasks', { title: 'first' }, { id: 't9', ifVersion: null })   // only if t9 does not exist yet
await space.data.delete('tasks', 't1', { ifVersion: t._v })

• The check and the write are one step on the server: it reads, compares, and appends only if the room has not grown in between, retrying under contention, so the losing device gets a clean 409 row_changed and never a silent overwrite.
• snapshot() keeps _v, so a conditional write after a resume compares against the right version.
• Without ifVersion, a write is unconditional.

Collections only admins write

Declare a collection write: 'admins' and only the room's admins may write it — see admins. The limits on collections and fields: Reference.

People — sign-in, who may enter, who runs the room

A room is open to anyone with its link, or gated: only signed-in people on its list may read or write it. This page is signing people in, gating a room, its admins and owners, direct chats, and changing who is in it.

Part of the SDK · every call: the reference.

Sign in

Your app needs no accounts of its own. The SDK signs people in the way the Spaces app's Email me a code does: a six-digit code to any address, from any origin.

const wb = new Witbitz()
const { ticket } = await wb.signIn({ email })      // a code is emailed
const session = await wb.signIn({ email, code })   // → { email, idToken, exp, sign }
localStorage.setItem('wb:session', JSON.stringify(session))
const renewed = await wb.refreshSession()          // before session.exp, with no new code

• Keep the session. Pass it back as new Witbitz({ session }), or wb.useSession(session) on a running client (null drops it). wb.signOut() forgets it.
• Renew it before it expires (session.exp) with refreshSession(), the renewal the Spaces app runs. It throws refresh_failed when the person has to sign in again, and no_session when there is nothing to renew.
• A sign-in on your site is your app's, not the person's whole Witbitz account. The token names the site that asked for it. Connections, the Siri inbox, outside agents and speech keys made on your page live under an account of your app's own; the person's own Witbitz account — their connections elsewhere, their @username, the account itself — cannot be changed from your page. It still proves the email, so room gates work as for any sign-in. This is the builder's half of the double blind: your page cannot spend or erase what the person did in other apps.
• Your server can check a sign-in on its own: knowing who is signed in.

Gated rooms

A room's gate is chosen when it is made, with wb.createSpace or space.privateLane; a room with none is open to anyone holding its link.

const space = await wb.createSpace({
  agent: { name: 'Warden' },
  admission: { emails: ['dana@example.com'], domains: ['keepwarden.com'] },
})

• Every operation is gated, reads included. The SDK sends the signed-in identity with each request, from the session wb.signIn() returned — so sign in before opening a gated room, or its reads come back refused.
• The list is sealed with the rest of the room's settings: the platform can tell that a room is gated, never who is on its list.
• A list takes emails and domains (acme.com). The Spaces app's own form also admits by @username — see usernames, discovery, and who is in the room.
• A list that admits nobody is refused at the call: it would lock you out of your own room.

Reading the gate

A member holds the room key, so your app can read the gate the server enforces instead of keeping a list of its own:

await space.admission()
// → { gated: true, emails: ['lead@keepwarden.com'], domains: ['keepwarden.com'], hidden: 3,
//     admins: ['lead@keepwarden.com'], owners: [] }
await space.admits('dana@example.com')   // → true / false, against the sealed list

• Addresses are hidden by default. Each is stored as a hash salted with the room id, so a member can check an address but not read the list; hidden counts them. To show some to members, list them in advertise when you make the room (admission: { emails, advertise: ['lead@keepwarden.com'] }), or pass true for all.
• "Hidden" hides the list, not the people. A member cannot enumerate who was invited, but a signed-in member's messages carry their @username (unless the room set usernames: false), their rows carry their email, and the room's member list shows who has signed in.
• The link alone reads nothing. A gated room's sealed settings — the list, the admins, the connection grants — are served only to a signed-in member on the list; anyone else learns only that the room is gated.
• A member admitted only by @username cannot be checked on the device: that match needs the server's key.
• Errors: config_unavailable when the settings cannot be read (the SDK refuses to guess), and sign_in_required before the member signs in.

Who did what

In a gated room every write needs an allowed sign-in, and the server marks what a signed-in member wrote:

A message does not carry the email, so its author's address is not readable by every member. from and a row's _by stay the display name the writer chose; lane.approve(id, { from }) sets the one a lane's message shows.

• A lane's message into the room is verified only when the member who approved it signed in — to the room it lands in or, when that room is open, to the gated lane it came from. A message into an open room in another region carries no mark: that region never sees the lane's sign-in.
• A row's own fields cannot pose as these marks. id and every name starting with _ are the room's: data.put refuses them (reserved_field), and a row is always read without them.
• Copied history keeps its old marks apart. Rows and messages an older client's move carried keep the marks they had as carried ({ from, verified, user? }), never as this room's own verified, which was not earned here, and name who carried them (carriedBy on a message, _carriedBy on a row). A lane's mirror copies messages only (rows as lines, with mirror: { data: true }), with no marks.

Admins

A gated room can name admins, and the room itself — not your app's interface — enforces what only they may do:

const team = await wb.createSpace({
  admission: { emails: ['lead@keepwarden.com', 'dana@example.com'], admins: ['lead@keepwarden.com'] },
  data: {
    tasks:  { fields: { title: 'text', done: 'boolean' } },                    // every member
    budget: { fields: { item: 'text', amount: 'number' }, write: 'admins' },   // admins only
  },
})
await team.isAdmin('dana@example.com')   // → false

In a room with admins, the room refuses a member who is not one (not_admin) when they:

• change the assistant (configure);
• write a collection declared write: 'admins';
• approve or deny a card that would do something they may not do themselves — an admin-only row, or a connection call, which spends the room's connected account. The card stays pending for an admin.

Posting, reading, the other collections and a member's own lane stay open to every member.

• Admins must be admitted by the gate: an address in emails, or one in a listed domain.
• They are sealed in the room's settings, so members can see who they are (isAdmin, admission().admins) and the platform cannot.
• They are set when the room is made and changed in place with changeMembers().
• A collection declared write: 'admins' in a room with no admins or owners is refused when declared (admins_required): nobody could be held to it.

Owners

Admins are equal, and any admin can change the room's members — so on its own, any admin could change the list to one without the other admins, or without the person who made the room. Owners are a level above, enforced by the room too:

const team = await wb.createSpace({
  admission: { emails: ['founder@keepwarden.com', 'lead@keepwarden.com', 'dana@example.com'],
               owners: ['founder@keepwarden.com'], admins: ['lead@keepwarden.com'] },
})

• An owner is an admin: whatever an admin may do, an owner may.
• Only an owner can change the owners, or lower or remove an admin. Admins still add and remove members and raise members to admin.
• The server refuses a member change by someone who is not an owner that breaks this rule (not_owner); the SDK checks before it changes anything.
• space.isOwner(email), admission().owners. Owners must be admitted by the gate, like admins.

Direct chats

A direct chat is the Spaces app's one-to-one chat: a gated room for exactly you and one other person. Each of you sees it under the other's name, nobody renames it, and the assistant is in it but answers only when @-mentioned.

const chat = await wb.createSpace({ agent: { name: 'Helper' }, direct: 'sam@example.com' })   // needs wb.signIn
// give Sam chat.shareLink; Sam opens it signed in as sam@example.com
await chat.directPeer()   // → { email: 'sam@example.com' } (on Sam's side: you)

• direct takes the other person's email in place of admission: the room admits exactly the two of you (both addresses visible to members), you are its owner, and direct: true is sealed in its settings.
• directPeer() reads the other person from the room's sealed list — never from an invite or a link — so it is the name to show. It is null for any other room.
• You can make several direct chats with the same person. A room for two that you give a name is an ordinary gated room, made with admission.
• Refusals: no sign-in (sign_in_required); direct together with admission, or with your own address (invalid_argument); rename() (direct_chat).

Changing members in place

A gated room changes who is in it without becoming a new room: the same id, link, history, store and lanes, and, from that moment, a new key that only the people still on the list receive.

const r = await team.changeMembers({ emails: ['lead@keepwarden.com', 'dana@example.com'], admins: ['lead@keepwarden.com'] })
// r → { inPlace: true, epoch, link, removed: ['eve@example.com'], added: [], unreachable: [] }
await team.rotateKey()   // the same members, a new key — for a lost phone, or a link sent to the wrong place

team.on('rekeyed', ({ epoch, link }) => saveLink(link))
team.on('removed', () => showGone())
team.on('pending', ({ reason }) => askForTheLink())

changeMembers takes the whole new list. Every member's open copy of the room takes the new key by itself, on its next request: 'rekeyed' gives the new link (null in a vault), 'removed' means this account is no longer on the list, and 'pending' means it is on the list but has no key this device can open yet.

• How the key reaches each member. When a person signs in, their account publishes an invite key for your app (wb.invite) in Witbitz's directory, under your app's own scope — the origin your page signs in from; no other app can write there. A change seals the room's new key to each remaining member's invite key. Their devices fetch it when the old key is refused (stale_key), check it against the room's commitment, and carry on.
• Keep wb.invite.state like the session. It holds a private key: persist it and pass it back as new Witbitz({ invite }). With the account backup on, it is kept there too, so a restored device follows. Signing in publishes the key by itself; await wb.invite.enroll() publishes it now and answers the status.
• A second device of the same account that has neither the state nor the backup never takes the published key over — that would cut the first device off. wb.invite.status reads held_elsewhere, and its rooms say pending with reason: 'no_invite_key', until you wb.invite.restore(state). In vault mode the vault keeps and publishes the key: status reads vault, and restore is refused (vault_unsupported).
• unreachable lists members with no invite key for your app — they never signed in to it, or only to another app, which has its own scope. Their devices are told pending; send them link.
• Who may change it, or rotate its key: a signed-in owner or admin (not_admin otherwise), within the owners' rules. A rotation goes to everyone still on the list. A room you make names you its owner when you are on its list. A room with no owners or admins is changed by its creator, in the Spaces app.
• A removed member keeps what they had read, and reads nothing written after: the room refuses their old key.
• Only the roles changed (the same people, new admins or owners): the room keeps its key and nobody's key changes; the answer says roles: true.
• Members added by @username in the Spaces app are on the list as a tag that no email names. A change keeps them; removing a person drops their @username entry too, once they have signed in to the room.
• A room without a gate whose members the Spaces app changed seals its new key to the app's own member keys, which the SDK does not hold: its rooms say pending with reason: 'link_changed'. Ask for the link again.
• plan() answers in_place for a new list, with call: 'space.changeMembers(admission)'. A lane is one member's own room: changeMembers on a lane throws lane.
• In a vault, changeMembers and rotateKey go through the vault, which asks the person in its own screen and makes and keeps the new key; the page sees neither key and gets no link.

@usernames

await wb.usernames.claim('dana', { publish: true, name: 'Dana' })   // → { username, published }
await wb.usernames.mine()                                          // → { username, published }; throws when signed out
await wb.usernames.resolve('dana')                                 // → { username, exists }; no sign-in needed
await wb.usernames.release()

One @username means one person across all of Witbitz, not per app. Verified messages and rows carry it (user, _user), and the Spaces app can admit a person to a room by it; the SDK's admission takes emails and domains.

• claim refuses a name that is taken (taken) or was released in the last 30 days (held).
• publish: true also lists the person in the public directory, under the display name when you pass one. It is off by default.
• Releasing a name does not change what the person already wrote.

Rooms an older client moved

A room changes its members only in place (above). space.fork() makes nothing and throws use_change_members, and plan() refuses a change that names a history with the same code. For a fresh start, make a new room with wb.createSpace({ admission }); nothing is carried into it.

An older client (a 2.2.x page) could still move a room to a new one, and the SDK follows such a move:

team.on('moved', ({ room, link }) => switchTo(wb.openSpace(link)))
team.on('moveRefused', ({ reason }) => showWhy(reason))

• 'moved' fires only for a notice the server stamped and sealed to this device's key: in a room with admins, an admin's; in a room with owners, one whose new room keeps exactly the owners and admins it declares. Anything else is 'moveRefused', with the reason.
• A confidential move is taken into the enclave before its settings are read.
• History such a move carried keeps its marks as carried on a message and _carried on a row: { from, verified, user? / email? }, the server's marks from the room it was first written in, plus carriedBy.
• In a vault, the vault reads the notice from the room itself and follows it by the same rules; the page gets 'moved' with { room, link: null } — open it with wb.vault.openRoom(room). Following a confidential room's move is refused there (vault_unsupported).

Private assistants and outside agents

Each member can have a private assistant beside the shared room; a member's assistants can ask each other; outside agents can reach a member's assistant over A2A or MCP; and a Space can sit behind any AG-UI front end.

Part of the SDK · every call: the reference.

Private lanes

A private lane is a member's own room beside a shared one, with its own assistant. That assistant reads the shared room's messages — and its store, read-only, through shared_data_query — and works with the member in private. It can post into the shared room only as a message the member approves, and it can only propose the lane's actions, which run on the member's device when approved (actions). It never holds a credential.

const shared = await wb.createSpace({ agent: { name: 'Team' } })

const lane = await shared.privateLane({
  agent: { name: 'Ops assistant', instructions: 'Help me run the store. Propose refunds and emails; I approve.' },
  actions: [
    { name: 'issue_refund', description: 'Refund a customer',
      input: { type: 'object', properties: { customer: { type: 'string' }, amount: { type: 'number' } }, required: ['customer', 'amount'] },
      run: (a) => myBackend.refund(a.customer, a.amount) },   // runs only after the member approves
  ],
})

lane.on('message', renderPrivateThread)
lane.on('proposal', (p) => showApproveDeny(p))
await lane.send('Refund Jane $40 for the late order, and email her an apology')

A Lane is a Space — its private thread arrives on message — with what this section adds. Its cards arrive on proposal: kind: 'message' is a drafted message to the shared room, kind: 'action' one of your actions, and nothing happens until approve() or deny() (approvals).

A lane is the member's to keep. Store its link, and on the next page load reopen it rather than making a new one:

localStorage.setItem('lane:' + shared.room, lane.shareLink)
// a later page load:
const lane = await wb.openLane(localStorage.getItem('lane:' + shared.room), { space: shared, actions, resume: saved })
await lane.ready   // the private thread is loaded: show it, not an empty list

Actions for one turn

await lane.send('Plan the offsite', { tools: [proposePlan] })                 // offered beside the standing actions
await lane.send('Just the plan, please', { tools: [proposePlan], replace: true })   // only these, this turn
lane.setActions([issueRefund, sendEmail])                                       // the standing set, from now on

• tools offers extra actions — the same shape as actions — for this turn only, for actions that depend on what the member is talking about. replace: true makes them the whole set for the turn; an empty list means none.
• setActions replaces the standing actions for every later turn; handlers for names you keep are kept.
• What a turn actually proposed. send()'s answer carries proposed: [{ id, action }], the cards this turn created ([] when none). The platform knows this for certain and the reply's words do not, so a page waiting for a card should wait only when proposed names one.
• A call that leaves out a required argument is never proposed: the model is told what is missing and calls again, so no empty card reaches a member.

The mirror

const lane = await shared.privateLane({ agent, mirror: true })   // or wb.openLane(link, { space, mirror: true })
await lane.mirrorNow()                                           // copy what is new right away

With mirror: true, this device copies the shared room's messages into the lane as they arrive, so the lane's own history holds the whole shared conversation and its assistant reads it like any other. Without it, a lane's turn sees only the newest 20 shared messages.

• Telling copies apart. A copy arrives on the lane with source: 'shared' and an sh: id. isLaneCopy(m), exported by the SDK, is the Spaces app's own test: filter on it to show a lane's private messages only. Do not filter on source alone — a recreated room's own history is copied in with source: 'shared' too.
• Attachments are copied as bytes and stored again under the lane's key.
• It runs while both handles are open. snapshot() keeps its position as mirrored, so a lane reopened with resume catches up without copying anything twice.
• Messages only, unless you pass mirror: { data: true }, which also copies the shared room's row writes, as lines. Off by default.

One lane, several rooms

lane.setLinks([teamA, { space: teamB, label: 'Team B' }])   // every turn
await lane.send('What did both teams decide?', { links: [teamA, teamB] })   // this turn only

The lane's assistant also reads the latest messages of each linked room, read-only and labelled; it can still post only into the lane's own shared room. Up to 16 rooms. Each linked room keeps its own gate: a gated room is read only if the signed-in member is on its list.