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:
- Sign up and open the console once — it gives you
dev.<your handle>(see Namespaces). - 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
- Panel SDK — everything
window.plumcan do. - Service apps — add a Go backend that runs on the box.
- Manifest reference — permissions, mime types, limits.
- Publishing — when you want it on other people's boxes.