Emulator

Last updated 2026-11-15

plum-box-dev is the box's core running on your machine: the same binary, with mock isolation, a seeded owner account and unsigned installs allowed. It is to a Plum Box what the iOS simulator is to an iPhone — good enough for almost all of the work, and not the real thing.

No Docker needed. plum-dev emulator up downloads the prebuilt core for your platform and runs it as an ordinary child process (native mode, the default). A Docker mode exists for the plum-box-dev image, but that image is not on a public registry yet — use native mode.

What runs What you need
native (default) the prebuilt core binary as an ordinary child process nothing but plum-dev
docker (--docker) ghcr.io/plum-networks/plum-box-dev under docker compose the image — not published yet

Everything after up — down, logs, token, login, status — follows the mode up recorded.

Native mode is a real answer on macOS too, not only Linux: the core builds for darwin (arm64 and amd64), so an Apple-silicon laptop runs it without Docker Desktop.

Start it

plum-dev emulator up          # native: no Docker
plum-dev emulator login       # waits for the seeded token, then saves the session
plum-dev push . --target emulator

The web UI is at http://127.0.0.1:8080 — reachable from this machine only — with the seeded owner:

user dev
password plumbox-dev
email dev@plum.local

On first boot the emulator writes a personal access token named plum-dev (emulator), with the apps:install and apps:dev scopes, to <data>/emulator/pat.txt, and sets the box's trust level to 3. That is what plum-dev emulator login reads — no pairing, no 6-digit code.

Override the seeded owner with PLUMBOX_DEV_OWNER_USER, PLUMBOX_DEV_OWNER_PASSWORD and PLUMBOX_DEV_OWNER_EMAIL before the first boot (the seed runs once): in your shell for native mode, in the compose file for Docker mode.

Native mode, in detail

plum-dev emulator up [--core-version <x.y.z>] [--port 8080]
  1. It asks GitHub for the newest release of the public repository plum-networks/plum-sdk tagged emulator-<core version>, or the one --core-version pins (it must exist: see the releases). plum-dev emulator status prints the core you are running; a box feature newer than that core is not in the emulator yet.
  2. It downloads the asset for your platform — plum-server-<goos>-<goarch>, one of linux-amd64, linux-arm64, darwin-amd64, darwin-arm64 — and verifies its SHA-256 against the SHA256SUMS in the same release before running it. A mismatch deletes the file and stops there.
  3. The binary is cached at ~/.cache/plum-dev/emulator/<version>/ ($XDG_CACHE_HOME respected) and re-checked against the recorded digest on every start, so it is downloaded once.
  4. It runs as a child process with PLUMBOX_EMULATOR=1, listening on 127.0.0.1 only (PLUMBOX_LISTEN_HOST=127.0.0.1), so the seeded owner and its token never reach your network. Data, logfile and pidfile live under ~/.local/share/plum-dev/emulator/ ($XDG_DATA_HOME respected).

down sends SIGTERM and, if the core is still there 5 seconds later, SIGKILL. down --volumes also deletes the data directory, which is how you reset the box. logs prints the last 200 lines of the logfile, and -f follows it.

On a platform with no published asset — Windows, or anything not in the list above — up says so and names the platform. On Windows, run plum-dev inside WSL 2: Linux has a prebuilt core.

Docker mode (not available yet)

plum-dev emulator up --docker [--pull]

up --docker runs docker compose with the compose file that ships inside the CLI package: the ghcr.io/plum-networks/plum-box-dev:latest image, a container named plum-box-dev, port 127.0.0.1:8080, and two named volumes (/data/plum, /mnt/storage). The image is not on a public registry yet, so the pull fails and the CLI tells you to use native mode — which needs nothing but the release assets.

--container <name> changes which container the commands act on (default plum-box-dev).

Commands

plum-dev emulator up [--native|--docker] [--core-version x.y.z] [--port 8080] [--pull]
plum-dev emulator down [--volumes]            # --volumes also deletes the data
plum-dev emulator logs [-f]                   # without -f: the last 200 lines
plum-dev emulator token                       # print the PAT
plum-dev emulator login [--token …] [--box …] # default box http://127.0.0.1:8080
plum-dev emulator status                      # mode, core version, whether it is up

Once logged in, every box command takes --target emulator (or set PLUM_DEV_TARGET=emulator):

plum-dev push . --target emulator --logs
plum-dev logs dev.jan.notes -f --target emulator
plum-dev status dev.jan.notes --target emulator

What is different from a real box

Emulator Box
Signatures unsigned bundles are accepted never
Architecture host architecture allowed (amd64 runs amd64) arm64 only
Isolation mock — no per-app OS accounts, no uid switching app-owned uid, cgroups
Transport plain HTTP on 127.0.0.1:8080 TLS on :8443, relay, LAN certificate
Plum services store, mail, auth, identity all off unless you set their URLs configured

plum-dev validate still enforces the real rules, so validate before you publish even when the emulator let something through. --allow-host-arch downgrades the architecture error to a warning for emulator builds; never publish such a binary. plum-dev build always targets arm64, which is what the box and the store require.

Not available at all: Bluetooth onboarding, WiFi setup, the relay and remote access, push notifications, and the NPU features (photo recognition). Available and worth testing here: the control socket, the event channel, and GET /api/apps/{id}/entitlement (an empty list marked stale: true, since no store has ever answered). The emulator checks a manifest's clients[] at install, but a companion app's sign-in needs a real box: the SDKs accept only a box address (https://pb-….plumbox.me) as the issuer, and the flow starts at the Plum portal.

Useful environment variables

Variable Effect
PLUMBOX_EMULATOR=1 the master switch inside the core: mock isolation, no mount check, Plum services off unless set, unsigned bundles allowed (native mode sets it for you)
PLUMBOX_DEV_STORE_CATALOG path to a JSON catalog file used instead of the store, so you can exercise the store install path locally
PLUMBOX_APP_CGROUPS=0 turn resource limits off (some container hosts cannot delegate cgroups); status then reports limits.reason
PLUMBOX_LISTEN_HOST the address the emulator listens on; native mode sets 127.0.0.1 (a real box ignores it)
PLUM_DEV_EMULATOR_MODE native (default) or docker
PLUM_DEV_CACHE where downloaded cores live (default ~/.cache/plum-dev/emulator)
PLUM_DEV_DATA where the emulator's data, log and pidfile live (default ~/.local/share/plum-dev/emulator)

Running a core binary yourself

Native mode is exactly this, automated. If you already have a plum-server binary — the core sources are not public, but the release assets and the container image both carry one — the manual equivalent is:

PLUMBOX_EMULATOR=1 PLUMBOX_LISTEN_HOST=127.0.0.1 ./plum-server -port 8080 \
  -data-dir ./demo-data -storage-dir ./demo-storage -dev-skip-mount-check
cat ./demo-data/emulator/pat.txt          # the seeded token
plum-dev login --box http://127.0.0.1:8080 --token plum_pat_…

Everything above about the seeded account and the relaxations applies the same way.