Your first panel app

Last updated 2026-11-15

A panel is a web app that the box serves and the Plum shell shows. It is the shortest path onto a box: no native toolchain, no build step, one script tag.

You need Node 18 or newer. A box is optional until step 6 — and if you do not have one, the emulator stands in for it.

1. Install the CLI

npm i -g @plumbox/dev
plum-dev --version        # 0.2.0

If --version prints 0.1.0, update it (npm i -g @plumbox/dev@latest): 0.1.0 refuses the files:app scope and cannot publish a new app. To run an unreleased change instead, build the CLI from the repository: git clone https://github.com/plum-networks/plum-sdk, then cd plum-sdk/packages/cli && npm i && npm run build && npm link.

2. Make your keys

plum-dev keygen

Two Ed25519 keys land in ~/.config/plum-dev/: the signing key you use every day and a recovery key to keep offline. The command prints both public keys and their kid. Nothing unsigned ever runs on a box, and this is the key that signs. See Signing and trust.

3. Connect your developer account

Every app id lives under a namespace you own, and three places check it: your box trusts your key only for ids under the namespace you paired with, Plum Store accepts only ids under a namespace you own, and init writes the id. Let the CLI learn yours once, and all three agree:

  1. Sign up and open the console once — it gives you dev.<your handle> (see Namespaces).
  2. Make a token on the CLI tokens page and save it:
plum-dev login --publisher-token plum_pub_…
# namespace  dev.jan   — new apps get ids like dev.jan.my-app (plum-dev init uses it)

plum-dev whoami shows it again at any time. No account yet? You can still build and push to your own box: pass the same --namespace dev.yourname. to init and pair, and change the id to your real namespace before you publish.

4. Scaffold the app

plum-dev init my-notes --template panel
cd my-notes

You get a manifest, an index.html that loads the SDK, a placeholder icon.png, a .plumignore and a README. The app id is your namespace plus the name:

{
  "id": "dev.jan.my-notes",
  "name": "my-notes",
  "version": "0.1.0",
  "entry": "index.html",
  "icon": "icon.png",
  "description": "my-notes for Plum Box",
  "mobile": true,
  "permissions": ["user:profile"]
}

Replace icon.png with your own before you publish — a square PNG, 256–2048 px a side, at most 1 MiB (512×512 is a good size). Plum Store refuses a new app without an icon, and reviewers turn the placeholder down.

5. Run it locally

plum-dev serve
# http://127.0.0.1:4040/apps/dev.jan.my-notes/

serve injects the mock SDK, so plum.user.current(), plum.files.openPicker() and friends answer with fixtures and no box is involved. Edit, reload, repeat. (If your app also has a backend, run it on your laptop and pass --service http://127.0.0.1:8787: serve proxies /apps/<id>/svc/* to it with the identity headers the box would set — see Service apps.)

Write something that uses the SDK:

<script src="/apps/runtime/plum-sdk.js"></script>
<script type="module">
  const me = await plum.user.current();     // needs "user:profile"
  document.title = `Notes — ${me.displayName}`;
</script>

6. Pair with your box

Your box only runs code signed by a key it trusts, and you add your key by pairing:

plum-dev pair https://pb-1234.plumbox.me

The CLI asks the box to trust your key for your namespace (the one from step 3; --namespace overrides it). The box shows a 6-digit code to its owner in Settings › Developer (it expires in five minutes). Type it into the CLI. The box then trusts your key for app ids under that namespace, and hands the CLI a token with the apps:install and apps:dev scopes so it can install and read logs. On a LAN box with a self-signed certificate, add --insecure.

7. Push it

plum-dev push

push validates the app, checks that its id is under the namespace the box trusts, signs it in memory, and installs it over POST /api/apps/install. No store, no internet: this works on a LAN with the cloud unplugged. Open the app from the launchpad in the box's web UI or in the Plum app.

While you work:

plum-dev push --watch

Every change re-pushes, and the page reloads itself — a developer build's entry page is served with Cache-Control: no-store (its other files with no-cache), and the SDK reloads when the box publishes the apps:<id> {"type":"installed"} event.

plum-dev push --logs follows the service log afterwards; for a panel with no server in its manifest it just says there is nothing to follow.

What the box records

A directly installed app has your publisher key and no store countersignature. The box keeps both facts (GET /api/apps/overview returns publisherKid and countersignKind), marks it Developer build in the box's app list, and leaves it out of automatic updates.

Useful next commands:

plum-dev status dev.jan.my-notes
plum-dev logs dev.jan.my-notes -f
plum-dev restart dev.jan.my-notes
plum-dev uninstall dev.jan.my-notes

If something is refused

The CLI prints who refused it, the code and the reason, and what to do next:

plum-dev: Plum Store said 400 icon_required: an app icon is required: a square PNG, 256–2048 px a side (512×512 recommended), at most 1 MiB — upload it with the bundle, or set manifest.icon to a PNG inside the .plu
  → add a square PNG icon (256–2048 px, at most 1 MiB): "icon": "icon.png" in manifest.json, or plum-dev publish --icon <png>

The ones a first app meets: publisher_untrusted (the box trusts your key for another namespace — plum-dev whoami), namespace_required (the id is not under a namespace you own), key_not_registered (add your key on the Signing keys page), icon_required, and version_not_increasing (raise version). Stuck anyway? Open an issue on plum-sdk.

Next