Skip to content

SDK overview

Apps run in a sandbox with no cookies, no network and no keys. window.bunker is how they get things done. Every call runs with the viewer’s own permissions, and Bunker checks the app, the viewer and their role on every call.

bunker.js is added to the top of every HTML page automatically, and window.bunker exists before your own scripts run. Don’t add a script tag for it.

<!doctype html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Lunch orders</title>
<link rel="stylesheet" href="/_/kit.css"> <!-- optional: Bunker's clean default styles, light and dark -->
<ul id="list"></ul>
<script type="module">
const me = await bunker.me();
const orders = bunker.db.collection('orders');
const render = async () => {
const { items } = await orders.list({ limit: 100 });
list.innerHTML = items.map(o => `<li>${o._authorName}: ${o.meal}</li>`).join('');
};
orders.subscribe(render); // live for everyone
render();
</script>

await bunker.ready (or the bunker:ready event) resolves once the connection to Bunker is up and localStorage has been restored. Calls made earlier are queued, so you rarely need it.

bunker.me() Who is viewing, their role and relevant groups
bunker.db Shared JSON collections with access rules and live updates
bunker.files Upload, list, read and serve files and images
bunker.storage Per-person key/value storage, plus working localStorage
bunker.room() Live broadcast and presence
bunker.ai Chat, JSON and streaming answers from the admin’s AI provider
bunker.m365 SharePoint lists, Excel ranges, OneDrive files and Graph reads, as the viewer
bunker.connections Admin-defined company APIs, keys kept on the server
notify, toast, download, open Notifications and small helpers
bunker.fn() Call one of the app’s server functions
Server SDK The bunker object inside server functions: the same calls plus secrets and fetch
Sandbox limits What pages can’t do, and what to do instead

bunker.site holds { slug, id, title, role, version, draft, icon } for the current app.

Every method returns a Promise. Failures throw a BunkerError (also window.BunkerError) with a machine-readable code, the HTTP status, and a plain-English message you can show as is:

code Meaning
forbidden The viewer’s role or the collection rule doesn’t allow it
not_found No such document, file or app
invalid Bad input
quota_exceeded A daily or rate limit was hit
consent_required Microsoft 365 needs the viewer’s consent
unavailable The feature isn’t set up (for example no AI provider), or the page was opened outside Bunker
functions_off, busy, timeout, function_error From bunker.fn
try { await orders.add(data); }
catch (err) { status.textContent = err.message; }

When the page loads, the SDK asks the Bunker shell around it for a private MessageChannel. The shell:

  • accepts the request only from its own iframe (event.source === iframe.contentWindow) and binds the channel to this app,
  • forwards calls only to the app’s own API (/api/v1/sites/<app>/...),
  • adds the viewer’s session, the CSRF header and X-Bunker-Page: 1.

Bunker only lets page-safe operations through that bridge: data, files, storage, AI, Microsoft 365, rooms, events, notify, connections, function calls and me. A page can never deploy, share, change data rules or settings, or touch another app, even if its code tries.

Live updates (database changes, rooms, presence, new versions) arrive over one server-sent events stream per tab, owned by the shell.

Server functions use the same page-safe operations from the server, with the caller’s rights unless the function is marked elevated.

Every SDK call is an ordinary operation in GET /api/v1/ops marked pageSafe, so scripts and the CLI can call the same endpoints with a token.