You don't need to be a programmer to benefit from apps, and if you are one, you don't need to be a Scryboard expert to build something people will actually use. Here's the whole picture, from why this exists to the exact steps to ship one.
Get the Scryboard App Runner
The free desktop program that runs apps on your own computer, with no terminal. You need it for any app that calls an outside service, uses a package, or reads a file — and it's the easiest way to run one you've installed from the Marketplace. Windows.
The Scryboard Ecosystem
Scryboard listens to your table and turns what actually happens there — the transcript, your prep notes, the rules that come up, the fights that break out — into structured, tagged data: beats, characters, factions, locations, items, rules, history. Scryboard's own dashboard is just one thing built on top of that data.
The App API opens that same data up to anyone. Instead of waiting for Scryboard to build the exact tool you want, you (or a player, or a third-party developer) can write a small program — an app — that reads exactly the slice of it you find valuable and turns it into something useful: a spell-usage histogram, a running NPC roster, a character stat card, a story timeline.
Apps never run on Scryboard's servers. Browser apps run inside the campaign page, and everything else runs on your own computer (or a player's) through the App Runner. Each one reads only what its access token allows. Beyond display cards drawn in Scryboard's own style, an app can write back what its manifest declares: new canon for the DM to verify, canon imported from a wiki, details such as portraits attached to existing entries, a player's own character data, images, and encounters or XP awards for the DM to confirm. Every write an app makes is listed on its Marketplace page before anyone installs it and checked when it's submitted. Build one for yourself, or publish it to the Marketplace for everyone else running the same kind of table.
Before You Start
Prerequisites: underneath everything below is a plain REST API (JSON
over HTTPS), so any language works, and you can run an app yourself —
self-hosted, on your own machine or server — without ever touching the
Marketplace. The example apps on the Downloads list are
Node.js scripts written this way — Node.js 18+ (for the built-in fetch) is the
only thing you need installed to run or adapt them. If you've just installed
Node.js and a command like node --version still says it's not recognized,
open a new terminal window — Windows in particular won't pick up a PATH
change in a window that was already open.
If you want to list on the Marketplace instead, what a buyer's install
actually downloads depends on your app's runtime: a browser_sandboxed
app is one code file, submitted as a .zip with its scryboard.json —
no git clone needed, and there's a ready-to-submit starter template on
the Downloads list at the top of the App API docs page. A node_cli app —
anything calling an outside API, using a package, or needing a secret — ships
as a small .zip (your code plus a scryboard.json manifest) and runs
through the Scryboard App Runner,
a small desktop app, rather than the buyer's browser. See
Choosing a runtime below and the
manifest reference before you start writing code — the
runtime you pick determines what you can build with.
Trying your app on your own campaign before (or without) publishing:
upload it as a personal app. Sign in, open /agents, and under Your
Own Apps click Upload your app (.zip). It gets the same automatic
checks a Marketplace submission gets, but nobody reviews it and nobody else
can see it. To see those checks before uploading, use Check Your App on
the Create an app page: it runs them in
your browser on your .zip and sends nothing anywhere. Then pick one of your campaigns under Connect to: and click
Connect. A browser_sandboxed app then runs whenever you have that
campaign's page open. To try a change to a browser app, click Replace
code on the app and pick the new .zip. This is the real test for
browser_sandboxed apps: before it, you can check their logic against the
mock server with dev-runner.mjs (in the node_cli starter template),
but plain Node is less strict than the browser sandbox.
A personal node_cli app runs from a folder on your computer, not from
the zip. It offers Get Runner link, which hands its token to the App
Runner. The Runner then asks where the app is on your computer: point it at
the folder holding your scryboard.json and code, and that folder is what
runs. Edits there apply on the next run, with no re-upload. The uploaded
zip is only what Check Your App and the upload checks looked at, so the
two can drift apart: re-upload with Replace code when you change the
manifest (scopes, settings, services), and before you submit. A Marketplace
install is different: the Runner downloads the approved zip.
Making the zip on Windows. Any of these works: in File Explorer, select
scryboard.json and your code files (not the folder around them),
right-click, Send to → Compressed (zipped) folder; or in a terminal,
tar.exe -a -c -f my-app.zip scryboard.json agent.mjs lib (built into
Windows 10 and 11). Run that from PowerShell or Command Prompt: in Git Bash
tar is a different program that writes a tar file whatever you name it,
and Scryboard will say the file isn't a zip. Windows PowerShell 5.1's Compress-Archive writes
paths with backslashes (lib\render.mjs); Scryboard's checks and the App
Runner both read those correctly, but other zip tools may not, so prefer
the two above. Leave out state/, dev/ and node_modules/: they're
dropped anyway.
Testing without touching production: there's currently no separate
staging deployment of Scryboard — the only live environment is production.
Rather than pointing a new app under development at your real campaign
with a real token, use the mock server first: it's a
zero-dependency local stand-in for this entire API, backed by fixture data,
with a preview page so you can see your pushed widgets rendered without
writing anything to a real database. Do one final pass against a real token
before publishing, since the mock is a fixture and can drift from actual
behavior over time. To test offline against the same campaign as your
sample campaign (below), download Sample campaign for the mock from the
Downloads list and start the mock with
node mock-server.mjs --fixtures=sample-campaign.json. The mock covers
everything on this page except voices (501) and the fight's less common
changes (death saves, undo, adding and removing combatants). Claude
answers 501 too, unless you give it a canned reply: start the mock with
--claude-reply=reply.json (or set MOCK_CLAUDE_REPLY), and every
scryboard.claude() call gets that file's answer. The file can be a whole
Messages API response (anything with a content array) or just the text
you want back, which is wrapped as one text block. It's read on every
call, so you can edit it between ticks to test how your app parses odd
answers. Nothing checks your model or allowance in the mock; on Scryboard
your manifest's services block does. To try your own settings boxes on
the preview page, add --app=<your app's folder>: the mock reads the
settings your scryboard.json declares (without it you get a sample
"appearance" box).
A sample campaign to test against: an empty new account has nothing for
an app to read. On the Create an app page, Make a sample campaign copies a
ready-made campaign into your account, with you as its DM: five played
sessions, a live session with a fight in round two, every prep layer
reviewed (some World Bible entries still Planned, one with an open
conflict, one imported), history from session reviews, events waiting for
approval, rules lookups and three players with character sheets. Connect
your personal app to it like any campaign; it goes through the real API
with the real permission checks. Recording and Scryboard's own AI are
switched off there. Its sixth session is the live one; if you end it, it
becomes a sixth played session until the next Reset, which brings back
five played sessions and a live one. The downloadable Sample campaign
for the mock is built from the same source, so it matches a freshly
reset sample.
Reset refreshes it with fresh data (up to 10 times a day), keeping
your apps connected. The three players are placeholder accounts, but you
also play a fourth hero, Wren Ashdown, from your own seat: a
player-scope app you connect acts as Wren. It reads and writes Wren's sheet
with character, and takes Wren's turn in the fight. Its cards show on the
player pages. View as Player, on the campaign page and in the live
session's toolbar, opens them in a new tab, so your DM screen stays open
beside them; they show only what a player sees. Your seat is still the DM's, so a DM-scope party
list (character from a DM token) leaves Wren out, and Wren's sheet
changes only through an app (the character editor is for players).
That's the short version — every endpoint, every payload shape, and the full read/write contract lives at /docs/agent-api.
Your Sample Campaign
A new account has no campaign data, so an app has nothing to read until you've played a few sessions. Make a sample campaign instead: a ready-made campaign in your own account, with you as its DM. It has five played sessions, a live session with a fight in round two, a full World Bible (some of it still Planned), history, events waiting for approval and three players with character sheets. You also play a fourth hero, Wren Ashdown, so an app connected as a player acts as Wren, and View as Player on the campaign page shows what a player sees. Upload your app on Your Apps, connect it to the sample campaign there, and it reads the sample through the real API with the real permission checks. Recording and Scryboard's AI are switched off in it, and nothing you do there touches anyone else's game.
Check Your App
Pick your app's .zip and see what the upload will say, before you upload: whether scryboard.json is right, whether your code only uses what it declares, and what a buyer will be asked to agree to. These are the same checks the upload and the Marketplace run. They happen here in your browser; nothing is sent anywhere.
Step-by-Step Workflow
The whole path from a blank script to a listed Marketplace app, thirteen steps across four phases. Each card is clickable where there's somewhere real to go.
Phase 1 — Set up
Install Node.js
18+, from nodejs.org. If a command still isn't recognized right after installing, open a new terminal window.
2In ScryboardRead the API docs
The full technical reference — public, no account needed.
3Scryboard downloadGrab starter files
Mock server + a starter template for each runtime, from that same page.
Phase 2 — Build & test offline
Pick a runtime & write your app
Sandboxed (one file, browser-only) or Node (packages, secrets, outside APIs). See the manifest reference for scryboard.json, and Check Your App (on this page) before uploading.
Run the mock server
node mock-server.mjs → localhost:4747
Run your app
node dev-runner.mjs with SCRY_BASE_URL at the mock and a mock_* token. It runs browser apps too.
Preview the widget
Open localhost:4747 in a browser.
Phase 3 — Test for real
Connect it to a campaign
No campaign with data yet? Make a sample campaign (Your Sample Campaign, on this page). Browser app: upload it as a personal app on /agents and connect it. Node app: get a token from Advanced (developer) at the bottom of the campaign page (DM: App Access Tokens; player: Your App Tokens).
Run against production
Browser app: open the campaign page and it runs. Node app: same script, real scry_... token.
Confirm the widget
Check your campaign, session, or player page.
Only building this for your own table? You're already done — stop after Phase 3. Publishing to the Marketplace is entirely optional and only matters once someone else wants to install it; it doesn't gate whether you can run your own app.
Phase 4 — Publish to Marketplace
Submit your app
Upload the .zip (code + scryboard.json); describe placement and setup.
Wait for review
Approved, or sent back with a specific reason.
Live — buyers install it
Installing mints a token. Sandboxed runs in their browser; Node runs through the Scryboard App Runner, one click either way.
Getting Noticed & Pricing
A clear, honest description matters more than anything else — say exactly what your app does and what a DM or player will actually see. People are more likely to install something they can picture using right away.
Once people have installed your app, they can leave a star rating and a written review — this is the main way other users judge whether something is worth trying, so it's worth asking early users for honest feedback. A small number of apps are periodically featured at the top of the Marketplace page — there's no submission process for that, it's simply apps worth highlighting.
Anyone can submit an app to the Marketplace; each one is reviewed before it goes live. Personal apps you only run yourself aren't reviewed.
Apps can be free, a one-time purchase, or a monthly subscription ($0.99–$500), and one purchase covers every campaign the buyer runs. To charge, first finish the one-time Stripe payout setup on Developer & Sales, then set a price from your listing's own page. Scryboard keeps 15% of the sale, Stripe's processing fee comes off separately, and the rest is paid out to you. If a sale is refunded, your share of it is taken back in proportion. Most first apps start free.