Scryboard

App manifest (scryboard.json)

Every app submitted to the Marketplace ships a scryboard.json alongside its code. It's what lets Scryboard know which file to start, what the app claims it needs, and what to prompt a buyer for — without anyone having to read the source to find out.

This replaces the free-text "setup instructions" box as the machine-readable half of a listing. That box still exists for prose a human should read; the manifest is for things software acts on.

{
  "name": "Recap Bard",
  "version": "1.0.0",
  "description": "Turns last session's synopsis into a sung recap for the start of the next one.",
  "entry": "agent.mjs",
  "runtime": "node_cli",
  "scopes": {
    "reads": ["sessions"],
    "writes": ["widgets"]
  },
  "dependencies": ["@anthropic-ai/sdk"],
  "secrets": [
    {
      "key": "ANTHROPIC_API_KEY",
      "label": "Anthropic API key",
      "help": "From console.anthropic.com. Used to write the recap's lyrics.",
      "required": true
    }
  ],
  "poll": { "activeSeconds": 30, "idleSeconds": 300 },
  "external": [
    {
      "name": "Example Music Service",
      "reads": "a backing track for the recap",
      "writes": "the recap lyrics",
      "requires_paid_account": true,
      "cost_note": "Requires an active subscription to the music service (see its pricing page), paid to them, separate from this app's price."
    }
  ]
}

Fields

Field Required Meaning
name yes Display name, at most 60 characters.
version yes A semantic version — 1.0.0, 1.2.3-beta.1. Updates are ordered by it, so anything else is rejected.
description yes One or two sentences, at most 1000 characters. Put the detail in your listing.
entry yes Which file the runner starts. Must exist in the archive.
runtime yes node_cli or browser_sandboxed — see below.
scopes.reads yes Resources you read. Must match what your code actually calls. Includes actions if you poll clicks on your own widgets' action buttons — see the action node — and events if you read the structured campaign event log (DM-only, so declaring it forces a DM installer, same as transcript or members).
scopes.writes yes widgets, widgets:video (YouTube embeds in widgets — requires widgets too; see the video node), widgets:link (anything clickable that leaves Scryboard — a link node, or [label](https://…) inside a richtext value — requires widgets too; see Links, and the widgets:link scope), character, media (upload images Scryboard stores and serves — see Uploading media), extractions (DM-scope only — see Proposing canon; declaring it forces your listing to require a DM installer, same as a DM-only read), extractions:attributes (merge structured data into one confirmed item's attributes — see Attaching data to confirmed canon; DM-scope only and forces a DM installer, same as extractions), and/or events (propose structured campaign events — encounter, scene, spell_cast, xp_award — that stay unconfirmed until the DM reviews them; see Proposing events; DM-scope only and forces a DM installer, same as extractions), and/or canon_import (import structured items the DM already treats as truth — e.g. their own world-building wiki — into the World Bible as confirmed canon with a visible source tag, resolved against existing canon rather than overwriting it; see Importing canon; DM-scope only, world_bible only, forces a DM installer), and/or canon_save ("Save to World Bible" buttons in its card that copy the DM's own typed text into one entry or a new one, on the DM's click — see Save to World Bible buttons; DM-scope only, forces a DM installer).
requires_dm_scope no true to say "only the campaign's DM may install this, and issue my token with DM scope" even though none of your resources is DM-only by name. Use it when your job needs the DM's full view: extractions is readable by both roles, but a player-scope token sees only homebrew_registry — an app that works with the World Bible is blind without this. Reading a DM-only resource or writing a DM-only one implies it anyway. Surfaced on the listing as a permission and to the reviewer as a finding.
capabilities no Device capabilities — things your app may do on the machine it runs on, as opposed to scopes, which govern Scryboard data. Currently: plays_audio (play sound through the buyer's speakers — see below). node_cli only.
dependencies no Vetted packages only — see the list below.
secrets no Anything the buyer must supply (API keys): [{ "key", "label"?, "help"?, "required"?, "per_campaign"? }], at most 10. key must be usable as an environment-variable name (letters, digits, _). The Runner prompts for these and stores them in the OS keychain. node_cli only.
services no Claude and ElevenLabs voices called through Scryboard, which holds your keys so your app never contains one and buyers never need one. Works for browser_sandboxed apps too, Claude and voices both. See below.
settings no Short text values you want the buyer to fill in — Scryboard collects them, you read them back with getSettings(). See below. Not to be confused with inputs, which is the App Runner's separate file picker.
poll no How often the runner ticks you, in seconds. activeSeconds/idleSeconds split by whether a session is live; defaults to 30/300. Optional encounterSeconds ticks faster than activeSeconds while the session has an active encounter (only checked if you set this — it costs your token an extra combatants read every tick, and needs combatants in scopes.reads). Each is a number of seconds from 1 to 86400 (under 5 gets a warning; the Runner may clamp short intervals). For the Marketplace, an App Runner app must check in no more often than every 10 seconds during a session (activeSeconds, encounterSeconds) and every 60 seconds outside one (idleSeconds); shorter is fine for a personal app. Check Your App on the Create an app page flags it. Ignored by browser_sandboxed apps, which tick every 5s during a live session and 30s otherwise.
external no Third-party services you talk to directly, outside Scryboard's own API (a world-building wiki, an image generator, a soundboard service, …) — see below. node_cli only: a sandboxed app can't reach another service.
inputs no The App Runner's install-time file picker — see the note under settings. node_cli only.
opens_at_session_start no Up to 3 exact hostnames (["player.example.com"]) the DM may let your app open in a new tab when they begin a live session. Needs widgets:link. Off until the DM switches it on — see below.

Any other top-level field is reported back to you at upload as a warning ("did you mean scopes?") and otherwise ignored. A field with the wrong type — "reads": "sessions" instead of ["sessions"] — is an error, not quietly dropped.

scopes is checked, not trusted

At submission, Scryboard scans your code and compares what it actually calls against what you declared. Reading transcript without declaring it is a rejection, not a warning. Declaring transcript also means only a DM can install your app, since player tokens can't read it — as does declaring any DM-only write, or setting requires_dm_scope: true yourself.

Changing scopes in a new version

A token's role and granted scopes are fixed when it is minted. If a new version of your app needs more (a new read/write scope, or DM scope where the old version ran as a player), a buyer clicking Update is shown exactly what changed and offered Update and re-issue token — the old token is revoked and a new one minted with the listing's current access. For node_cli the new token is shown once, with the App Runner link; Runner v0.2.1+ swaps it on the app it already has (settings and state kept). Say in your changelog when a version needs this.

secrets is how API keys stop being painful

Declare what you need and the runner handles the rest: it prompts the buyer once, stores the value in the operating system's credential store, and sets it as an environment variable when your app runs. Your code just reads process.env.ANTHROPIC_API_KEY. Nobody edits a config file, and the secret never sits in plain text.

When the same buyer installs your app into a second campaign, the Runner reuses the keys they typed for the first one, so an API key is only pasted once. That is wrong for a value that points at ONE campaign's data -- an ID for a wiki, a world, a folder. Mark those "per_campaign": true and the Runner (0.2.13+) asks for them on every install and never copies them to the app's other campaigns. A wiki app's campaign ID is one: reused, it imported one campaign's whole wiki into another.

Never put a secret value in the manifest. This file is public.

services: Scryboard holds the key

For Claude and ElevenLabs voices you don't need secrets at all. Declare the service, save your own key for it on your app's Marketplace page, and call it through the client library: Scryboard attaches your key on its own server. The key is never in your package, never on the buyer's computer, and never visible to your code. Your app pays for what it uses: buyers never supply keys, so an app can only ever spend its own developer's money.

"services": [
  {
    "service": "claude",
    "key": "developer",
    "models": ["claude-haiku-4-5"],
    "max_output_tokens": 300,
    "why": "Writes each insult line."
  },
  {
    "service": "elevenlabs_tts",
    "key": "developer",
    "voices": [{ "id": "<ElevenLabs voice id>", "name": "Goblin Insult Artist" }],
    "max_characters": 220,
    "why": "Speaks the insult in the goblin's voice."
  }
]
  • Every service runs on your key ("key": "developer"). Once a version declaring a service is uploaded, an App keys and allowance box appears in Listing management on your app's page. Paste your Anthropic and/or ElevenLabs key there; Scryboard checks it can use every model and voice you declare before saving it, then never shows it again.
  • Personal apps (uploaded on /agents, private to you) run on your own key too: a Keys for this app box appears under the app there. There is no allowance, since only you can run it; the 10-a-minute limit still applies.
  • claude: list every model you call under models and the largest max_tokens you send as max_output_tokens (up to 16,000).
  • elevenlabs_tts: list each voice you use and the longest text you send (up to 5,000 characters).
  • You set one allowance in the same box: how many uses each buyer gets per month or per year. There is no unlimited option, so a popular app or a misbehaving install can't run up a surprise bill. A voice line is one use; Claude may make up to two requests per use (a draft and a revision, say), so Scryboard allows twice your allowance in Claude requests.
  • Only what you declare works. A request for another model, another voice or longer text is refused, so a token copied out of your app can't be used for anything else. Each install is also held to 10 service requests a minute.
  • why is required: one sentence the buyer reads on your listing and in the App Runner's install prompt.
  • Remove ANTHROPIC_API_KEY / ELEVENLABS_API_KEY from secrets when you switch; submission warns if both are present.
  • Calls: Claude and voices through Scryboard. Needs App Runner 0.2.9 or later.

capabilities is for what your app does on the buyer's machine

scopes govern Scryboard data; capabilities govern the computer your app runs on. They're enforced by whatever runs the app (the App Runner, or the Scryboard page running a browser app), not by your code — the buyer consents to each one explicitly at install time, on top of whatever data scopes the listing already discloses.

Currently one exists:

  • plays_audio — your app may play sound through the machine's speakers, via scryboard.playMedia(...) / playAudio(...) (see the client library below). Playback goes through the Runner's own built-in player, or, for a browser_sandboxed app, the page's own player on whatever device has it open; your code never touches an audio device, a child process, or a native binding. One thing plays at a time — a new play replaces whatever any app was playing, and the player always shows what's playing with a Stop button the buyer can hit.

Capability strings are deliberately one-per-media-type (plays_audio now; video would be its own plays_video consent if it ever lands) — "can make sound" and "can put video on my screen" are different things for a buyer to agree to, even though the machinery underneath is shared.

Like scopes, capabilities are checked, not trusted: calling playMedia without declaring plays_audio is a submission rejection, and declaring it flags the listing for the reviewer — audio has no content constraint the platform can enforce, so the reviewer is told to actually listen to what your app produces. Say what you play and why in your description.

settings is how you ask the buyer a question

Some apps need a short piece of text only the buyer can supply — "describe your character's appearance", "what tone should this be", "what's your party called". Widgets can't collect it: the layout schema deliberately has no text-input node (the input node is only a bookmark for where Scryboard draws its own box), because an app-rendered input field is a spoofing surface the platform won't open.

So settings works exactly like secrets: you declare, Scryboard collects, you read back. Your app never renders the box.

"settings": [
  {
    "key": "appearance",
    "label": "Describe your character's appearance",
    "help": "Hair, build, scars, what they wear. Used to draw the portrait.",
    "type": "text",
    "max_length": 500,
    "required": false
  }
]
Field Required Meaning
key yes Stable identifier you read the value back by. Lowercase a-z, 0-9, _, starting with a letter, ≤40 chars.
label yes The prompt shown above the box. ≤80 chars.
help no A line of explanation under the label. ≤300 chars.
type no text — the only kind today, and the default.
max_length no Your own cap on the answer. Defaults to (and can never exceed) the platform's 2000.
required no Shows the buyer it's expected. Not enforced — your code still has to cope with an empty value.
scope no install (default) — one box for your whole app. item — one box per thing your app lists. See One box, or one per thing? below.

At most 12 settings per app.

Read them back with scryboard.getSettings(). Declared-but-unanswered keys come back as '', so "not answered" is one case rather than two. No read scope is needed: declaring the setting is the declaration.

const { appearance } = await scryboard.getSettings()

Two things to design around:

Values are per-install. The same person installing your app on two campaigns answers twice, independently — which is what you want when the answer is "my character looks like X" and they play different characters.

A buyer can edit any value at any time, from the Settings control on their installed app — not just at install. A campaign runs for months and answers change. So read the value fresh each tick rather than caching it from the first one, and expect it to change under you.

Critically: changing a value never triggers anything on its own. You see the new value on your next tick and decide what to do with it. If acting on it costs the buyer money at a third party — an image generation, an AI call — do not act automatically. Show that the result is out of date and let them press a button. An edit that silently spends someone's balance is how an app gets uninstalled. (A player-facing portrait app does exactly this: it compares the current text against what the existing portrait was drawn from, and says "regenerate to update it" rather than redrawing.)

Every declared setting is shown to the reviewer at submission, with its label and help text — nothing mechanical can judge whether a question is reasonable to ask or where the answer ends up going, so a setting that feeds a third-party service should say so in its help.

One box, or one per thing?

The example above is one box for the whole app. That's right when your app has one subject — a player-facing portrait app draws one character, so one "describe your character" box is that character's box.

It falls apart the moment your app has a list. A DM edition drawing every NPC in a World Bible can't use one shared box for "extra detail": whatever was typed last would silently apply to whichever character is drawn next. For a paid image generation, that means paying for the wrong picture — and nothing about it looks wrong until the picture arrives.

So a setting can say which it is:

"settings": [
  { "key": "art_direction", "label": "How should these look?" },
  { "key": "portrait_note",  "label": "Extra detail for this character",
    "scope": "item", "max_length": 300 }
]

art_direction has no scope, so it's app-wide — one box, applying to everything you draw. portrait_note is per-item.

You push the list of items at runtime, because only you know what your items are and they change constantly:

await scryboard.setSettingItems([
  {
    key: 'npc-123',                         // your own stable id
    label: 'Marta the Innkeeper',           // what the buyer reads
    placeholder: 'Runs the Thornwatch Inn…' // greyed-out suggestion
  },
])

and read the answers back grouped by item:

const s = await scryboard.getSettings()
s.art_direction                   // 'grim oil painting'
s.items['npc-123'].portrait_note  // 'tired, greying, missing a tooth'

items is always present, possibly empty — you never have to guard for it.

You decide how many boxes the buyer sees. This is the important part. An app with 300 NPCs should push the one its widget currently has selected, not all 300 — click a character in your widget, and the box below becomes that character's box. The 50-item cap exists to stop abuse, not to be the thing you design against.

placeholder is a suggestion, never a value. It shows only while the box is empty, so you can show a buyer exactly what they'd be overriding — the NPC's own description, say — without putting words in their mouth. Nothing you send is ever stored as their answer. An app still cannot write a settings value; that boundary is what makes the whole feature safe.

Values outlive an item leaving your list. Stop sending npc-123 and what the buyer typed against it is kept, not deleted — send it again and it comes back. But it isn't returned by getSettings() while the item is absent, so you never act on something you no longer list. (Uninstalling clears everything, as always.)

Field Required Meaning
key yes Your own stable id for the thing. ≤100 chars. Opaque to Scryboard.
label yes What the buyer reads above the group. ≤80 chars.
placeholder no Greyed-out suggestion text, shown while empty. ≤300 chars.

At most 50 items. Pushing items is rejected if your manifest declares no "scope": "item" setting — a list with nothing to render against it is almost always a mistake worth hearing about.

Not the same as inputs. The App Runner has its own separate manifest field called inputs — a file picker (accept, multiple) that it prompts for once, at install, dropping the chosen files in input/<key>/ next to your code. That is a different feature at a different moment, and it is collected by the Runner, not by Scryboard. Use inputs when you need a file from the buyer's machine; use settings when you need a line of text they can change later. Putting accept/multiple inside settings is rejected at submission, since it almost always means the wrong field was used.

external is how a bridge agent declares the other service it talks to

scopes only covers Scryboard's own API. A bridge agent — one that also reads from or writes to a third-party service, such as a world-building wiki or an image generator — declares that separately, so buyers and reviewers can see it:

"external": [
  {
    "name": "Example Wiki",
    "reads": "your campaign wiki (NPCs, locations, factions)",
    "writes": "session summaries and new canon",
    "requires_paid_account": false
  }
]

name is required (which service). reads/writes are short plain-language descriptions — free text, since there's no fixed resource list for an arbitrary partner API the way there is for Scryboard's own scopes.

Scryboard never bills on a partner's behalf. If the partner service itself requires its own paid tier or subscription — separate from whatever you charge for this app on the Marketplace — set requires_paid_account: true and fill in cost_note (required whenever requires_paid_account is true; submission is rejected without it) explaining what it costs and where. This gets shown to buyers on the listing page, before Buy or Install, clearly separated from your app's own price — a buyer should never discover a second bill mid-setup. Scryboard has no way to verify a partner's actual pricing, so this is your responsibility to keep accurate; the reviewer is shown it as a flag on every submission, and a false or missing disclosure is treated as a policy violation like any other misleading listing content.

opens_at_session_start is how a page opens with the session

Some apps only work if a page from another service is open while you play. A soundboard service's web player, for example, is where the sound comes out. An app can offer to open that page for the DM at the moment they click Begin on Begin Live Session:

{
  "scopes": { "reads": ["sessions"], "writes": ["widgets", "widgets:link"] },
  "opens_at_session_start": ["player.example.com"]
}

A page that opens by itself is a bigger thing to agree to than a link you click: a fake sign-in page at the start of a session, or something embarrassing on a screen the whole table can see. So:

  • You name exact hosts. Lowercase hostnames only (no https://, no path, no wildcards), at most 3, and never a Scryboard address. The listing shows them by name, and the reviewer is warned to check them.
  • You never hand over a URL separately. What opens is the first link node, on one of your own cards, whose href is https on a declared host. So the page that opens is always a button the DM can already see on your card. Keep that link current, and never put a token or password in it. richtext links don't count. Without such a link nothing opens, and no switch is shown.
  • It's off until the DM ticks it, inside your card. Scryboard draws the switch ("Also open … when I begin a live session") at the bottom of whichever of your cards on the DM's campaign page (dm_landing) shows that link, below your own output, the same way it draws your settings boxes. So push a dm_landing card that carries the link. Only the person who installed your app sees the switch. Your app can't switch it on, and can't tell whether it is on. Nothing about your app appears in Scryboard's own Begin Live Session panel.
  • Scryboard opens it, one tab per Begin. It opens in a new tab with noopener/noreferrer, as part of the DM's own Begin click (browsers only allow a page to open a tab in response to a click). They allow only one new tab per click, so if several apps are switched on, the first opens; the others' links are still on their own cards.

Installs see this only on a Marketplace install. A personal app has no install to keep the switch on.

Runtimes

node_cli — a real Node program. Multiple files, vetted packages, full access to the machine it runs on. Runs via the Scryboard App Runner (a Windows desktop app the buyer installs once) or by hand during development. This is the tier for anything needing an outside service of its own, a package or a buyer's API key: PDFs, image processing, other platforms, an AI service other than Claude through services.

browser_sandboxed — runs automatically in the buyer's browser with no install at all, but only while they have the campaign page (or, for a DM's app, the live session screen) open, and with no network beyond Scryboard's API (Claude and voices through services included), no packages, no files, no secrets, and a single code file (this manifest aside). It remembers things between ticks in its own small store (getState / setState, 256 KB). Good for anything built from data Scryboard already has. It gets the same scryboard methods as a Node app; see the table below.

The full side-by-side comparison, with a "can I use the sandbox?" checklist, is in Choosing a runtime. A sandboxed app installs in one click, so use it whenever it's sufficient — but check the list first.

Vetted packages

node_cli apps may depend on the packages below and nothing else. They ship inside the runner, so there's no install step for the buyer, no version drift between apps, and everything that executes has been reviewed once rather than pulled fresh from the internet on someone's machine.

Package For
@anthropic-ai/sdk Calling Claude
pdf-parse Extracting text from PDFs
jimp Image resizing and conversion
zod Validating data shapes
date-fns Date handling

Most apps need none of these — reading Scryboard and pushing a widget uses only built-in Node features plus the client library below.

To request an addition, write to us through the Contact page (email or Discord) with the package name and what your app needs it for. Packages are judged on whether they're widely used, actively maintained, reasonably small, and free of native compiled binaries (which are painful to bundle across platforms — this is why jimp is on the list and sharp isn't).

The tick convention and the client library

Export an async tick() function. The runner hands it the Scryboard client — you don't import or install anything:

export async function tick(scryboard) {
  const session = await scryboard.getActiveSession()
  if (!session) return

  const combatants = await scryboard.get('combatants', { session_id: session.id })

  await scryboard.pushWidget({
    widget: 'Initiative',
    placement: 'session_dashboard',
    visibility: 'table',
    session_id: session.id,
    layout: {
      type: 'table',
      columns: ['Name', 'Initiative'],
      rows: combatants.map((c) => [c.name, c.initiative]),
    },
  })
}

The Runner calls tick() on the poll schedule from your manifest (a sandboxed app is ticked every 5 seconds during a live session and every 30 otherwise, whatever poll says) and owns the loop, retries, and backoff — so you never write setInterval, and a mistake in your timing can't hammer the API. Sandboxed apps get the same tick() shape and the same methods, so code reads identically in both runtimes; the table below shows the few differences in how a method behaves.

tick() should be safe to call repeatedly. Pushing the same widget name replaces its content rather than duplicating it, so re-pushing every tick is the normal pattern, not a leak.

What's on scryboard depends on the runtime:

Method node_cli browser_sandboxed
get, getActiveSession, pushWidget yes yes
reportProblem in scryboard.mjs; not in the App Runner yet (dev-runner leaves it out unless --all-methods) yes
setCharacterData, updateCharacterData yes yes
getActions, getEvents, writeEvent yes yes
getSettings, setSettingItems yes yes
proposeExtractions, setItemAttributes yes yes
importCanon, canonImportStatus yes yes
uploadMedia, setMediaTier yes yes — pass data as a Uint8Array, ArrayBuffer or Blob
claude, speak yes yes — speak returns audio as a Uint8Array
getState, setState yes, from App Runner 0.2.19 (on an older Runner they're undefined: check first, and use a state/ folder next to your code) yes
playMedia, playAudio, stopMedia yes (App Runner only) yes — bytes only (no file paths), played by the page on whatever device has it open
showFile yes, from App Runner 0.2.20 (check first; see "Showing a file you made" in the API docs) no — a browser app has no files to show

The sandbox also gives you console.log / console.error, which print to the buyer's browser console.

Full source of the Node client: scryboard.mjs, at the root of the node_cli starter template zip (on the Downloads list), next to dev-runner.mjs, which runs your tick() locally the way the Runner does. dev-runner.mjs runs a browser_sandboxed app too, as plain Node, which is handy for checking its logic against the mock server; plain Node is less strict than the real sandbox, so the real test is uploading it as a personal app — see "Trying your app on your own campaign" in Before you start.

The three playback methods play under the App Runner or in a browser app (and need the matching capability declared — see above). In a browser app, pass bytes, not a path, and expect a refusal ("tap the page once") if nothing on the page has been tapped yet: start sound from a button click where you can. playMedia({ data or file, contentType, title?, volume? }) takes raw bytes or a path; playAudio(bytesOrPath, opts?) is sugar for the audio case; stopMedia() stops your app's own playback. Outside the Runner (standalone script, dev-runner) playMedia throws a clear "no player here" error — wrap playback in try/catch so a missing player degrades to silence rather than failing your tick.

If you need to remember something between ticks, use getState / setState (see "Remembering things" in agent-api.md), or in a node_cli app a file in a state/ folder next to your code (App Runner 0.2.19 and later has both methods; older ones don't). Find that folder from import.meta.url, not the working directory: the Runner runs every app in its own process, so process.cwd() is the Runner's folder.

For a method the App Runner doesn't have yet, check first: if (typeof scryboard.getState === 'function') …. Under the Runner such a method is undefined, and calling it throws.

The Runner hands your tick() a client already bound to your app's token. It does not set SCRY_TOKEN or SCRY_BASE_URL (those are for running scryboard.mjs yourself, as dev-runner does), so always talk to Scryboard through scryboard.*. The only environment variables it sets for your app are your declared secrets.