Scryboard

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.

Download for 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.

Sign in to make a sample campaignOne per account. Reset makes a fresh copy, up to 10 times a day.

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.

or drop it here

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.

External downloadScryboard downloadTerminalIn Scryboard

Phase 2 — Build & test offline

4In Scryboard

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.

5Terminal

Run the mock server

node mock-server.mjs → localhost:4747

6Terminal

Run your app

node dev-runner.mjs with SCRY_BASE_URL at the mock and a mock_* token. It runs browser apps too.

7

Preview the widget

Open localhost:4747 in a browser.

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.

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.