Packages
Packages are the units Peers installs, runs, and administers. A package is installed
into a data context: your personal context or a group. Its Packages and
PackageVersions rows sync to every member device, and each device loads the selected
version on its own. When synced rows arrive, a device restarts a package only if the version
or bundle it should run changed; otherwise the running worker keeps serving calls, and a
promotion updates the reported tag and isolated contract maturity without restarting the
worker. Promoting to stable freezes those contract shapes, so later dev builds must use a
new contract version to change them.
At startup, Peers loads packages for your personal context and current group before opening the app. Packages in other groups load in the background, and each group starts syncing once its packages are ready. Calls into a group that is still loading wait until it is ready. Package workers start on first use, so the first call after a start may take longer while the package's code loads.
You administer packages from the Packages screen, from peers packages, or from any
local client of the System Packages contract. All three use the same contract, so they
behave the same way and are checked against the same access levels. To build a package,
start with Getting started.
The official Git package shares repositories and personal branches through
peers:// remotes. It requires Git on a desktop or headless host and is installed separately.
A package's source can be a peers:// URL shared that way (peers git share in the
package's folder records it); package details then offer to copy it, since it opens with
git clone, not a browser.
The Apps screen
The Apps tab is the home screen of each group, and of Personal. It shows the apps installed there:
- Pinned apps come first, in the order you choose. Your pins are kept per group and sync to your other devices. When you upgrade, each group's initial pins are up to four apps from its old Recently Used list. Opening an app doesn't change your pins; choose Edit to change them. New groups start with no pins.
- More in <group> lists the group's other apps by name.
- System apps are the apps built into Peers. The System apps button shows or hides them. Each device remembers its choice; they start hidden on a phone.
The search box filters all three. An app matches on its name, its package's name, and its package's description; a built-in app matches on its own name only.
Get apps lists the apps your other groups use that this one doesn't, by group, and, in a group, the apps in Personal too. Its count is how many packages you can add here; a package listed under two groups counts once. Add copies the version that group runs into this one, for every device here; it appears under More. Only admins can add apps. A package that adds no screen (a widget or a voice skill) says No screen, and one this device can't run says so instead of offering Add. If an added package then fails to start here, its row says why; it stays installed for the group's other devices, and its menu on the Apps screen shows the same reason.
Apps that are waiting
Some apps are built on another package and can't work without it. An app whose package needs one that the group doesn't have yet is installed but waiting:
- Its tile shows an hourglass, and its menu says what it's waiting for.
- Opening it shows what it needs, why it can't start, and the packages that provide it: ones already in the group but not running (turned off, or waiting themselves), and ones your other groups use. An admin can Add one from there; if that package needs another in turn, Add brings both. Turn on turns one that was turned off back on.
- It starts by itself as soon as a package it needs is running in the group, on this device or any other, and its own screen replaces the waiting one. Nothing needs restarting.
- The package it needs has to be in the same group: a copy in Personal or another group doesn't count, though you can add it from there.
- If that package is removed later, the app goes back to waiting.
- Its data keeps syncing while it waits, and its items still show up in search and mentions.
When the app's own package only has an update waiting (the new version needs a package the group doesn't have), the version you have keeps working, and the menu says the update waits.
Choose Edit to change your pins: − unpins an app, + pins it at the end, and dragging a pinned app moves it. In edit mode, choosing an app opens its menu, where Move earlier and Move later reorder pins from the keyboard. Done or Escape leaves edit mode. A pinned app that isn't installed any more stays pinned but hidden, so installing it again brings it back.
An app's menu opens with a right-click, a press-and-hold on a touch screen, or Shift+F10 (or the context-menu key). Its header shows the version running on this device and the channel it follows. It offers:
| Item | What it does |
|---|---|
| Open | Opens the app. |
| Pin or Unpin | Adds the app to your pins, or takes it off. |
| Update | Shown when a newer release is ready on the channel the package follows. Selects it, as the Packages screen's update button does. |
| Details and versions | Opens the package on the Packages screen. |
| Remove from <group>… | Admins only. Asks first, then uninstalls the package for every device in the group (Uninstall). |
A built-in app's menu says Built into Peers in its header and offers only Open, Pin or Unpin, and, when it's pinned and you're editing, Move earlier and Move later.
A tile's corner shows when an app needs you:
- a blue arrow: an update is ready;
- a red ! on a dimmed icon: the app failed to start on this device, and its menu says why;
- an hourglass on a dimmed icon: the app is waiting for a package it needs;
- DEV: this device runs a dev build from a local folder.
Each app's icon has a color: the one its package names (App icons), or one picked from its package id and name. Built-in apps are grey.
Quick reference
peers packages # list packages and their status on this device
peers packages get <packageId> # versions, runtime state, last load error, and
# for a waiting package what provides what it needs
peers packages import ./my-package # import a built package folder
peers packages import https://github.com/org/pkg.git # clone, build, import
peers packages create "My Package" # scaffold from the template
peers packages reload <packageId> # rebuild from the folder, reload here
peers packages reload --all # re-read every package folder on this device
peers packages activate <packageId> <packageVersionId> # run a version on this device
peers packages activate <packageId> # drop the device override; follow the group
peers packages activate <packageId> <packageVersionId> --group # set the group's version
peers packages promote <packageVersionId> beta # dev -> beta (or stable)
peers packages promote <packageVersionId> beta --group # also select it for the group (Admin)
peers packages install <packageId> --from personal # copy a package into a group
peers packages uninstall <packageId> # remove it from the context
peers packages defaults # install the default packages
peers packages capabilities # what this host supports
Add -c <groupId> to work in a group. The default is your personal context. Add --json
for machine-readable output: list prints one JSON object per line, and every other
command prints one object. get returns the same shape as the getPackage tool below, and
promote prints the whole promotePackageVersion result, including signed and
activated, groupRunsPromotedVersion, and activationNote. Version ids come from get. With --json, app-startup progress goes to stderr
so stdout stays parseable even when the desktop app needs to be started first.
Exit code 0 means the operation succeeded. 1 means it failed. That includes an enabled
package that failed to load after import, create, clone, install, activation, or reload,
including missing bundles and unsupported execution modes, and reload --all when any
package failed. A package that installs but waits for a contract it requires
succeeds (exit 0), and the command says what it waits for. Errors go to stderr. A deliberately disabled package may be imported or
cloned successfully without running it. A promote whose automatic activation fails to
load also exits 1, but the promotion itself is kept and the error starts with
Promoted ...; do not retry it. Check peers packages get.
reload --all cannot be combined with a package id. Folder arguments, including folders
whose names end in .git, are resolved against the CLI's working directory; ~/ means your
home folder, and other ~user paths are rejected. Cloning accepts HTTP(S) URLs and
git@host:owner/repo remotes; shell syntax and . or .. path segments are rejected. An
existing folder wins over a remote with the same spelling. The Packages screen's search box
routes input the same way: a URL clones, a package id installs, anything else creates or
imports a local package.
Contract calls have no timeout, and create and import <url> run npm install and
npm run build. If you stop the CLI partway through, the outcome is unknown. Check
peers packages get before retrying.
Requested and observed state
Each package summary has two parts.
requested: what this device should run.
groupActivePackageVersionId: the group's version.groupVersionMissing(optional): the group's version isn't on this device, possibly pending sync.getand Versions warn even with a device override. Wait for sync, or select an available release withpeers packages activate <packageId> <packageVersionId> --group(Admin; same-c <groupId>).deviceActivePackageVersionId: this device's override, when one is set.effectivePackageVersionId,version, andversionTag: what results from the two.pinned,followRange, andfollowTags: the version-follow policy.
runtime: what this device is actually running, observed by the package loader.
runtime.status | Meaning |
|---|---|
running | The selected version loaded and is serving. |
failed | The last load failed. runtime.running still names the previous version when it kept serving. |
waiting | The selected version requires a contract that no package running in this context provides, so it hasn't started (Waiting packages). runtime.running names an older version that keeps serving until it can, when one was running. |
unavailable | The selected version's bundle has not reached this device yet (usually still syncing). |
unsupported | This host cannot run the package, for example an isolated package on a host without an isolated runtime. |
disabled | The package is disabled for the group. |
unloaded | The package was unloaded or uninstalled, or the only selected version is a dev version this device has not activated (reason says so). |
notLoaded | A version is selected, but this device has not tried to load it. |
inactive | No version is selected yet. |
The other runtime fields:
running: the version that is serving. GivespackageVersionId,version,versionTag,kind(alwaysisolated; Peers versions before the host-backed loader was removed also reportcontract), andexecutionMode. It also givesprovidesandconsumes, and eachconsumesentry says whether a provider was found (satisfied). A system contract counts only when this host serves it.lastError: the most recent load failure. Givesphase,message,version, andat, and is cleared by the next successful load.waiting: set while the status iswaiting. Gives the waiting version (packageVersionId,version,versionTag),missing(each required contract no package here provides:contractId,version,namewhen this device knows it, andproviderPackageIdswhen the package accepts only those), andprovides(what it serves once it starts, so a package waiting on one of those can show the chain).worker: isolated worker health,workerRunningpluslastWorkerError. Isolated workers start on the first tool call, so a provider that throws while starting shows up only after a call has failed. A bundle that becomes unavailable or fails verification can also cause a worker error on first use. An unexpected worker exit also updates health immediately, including an exit while idle. A tool call that times out is rejected and the worker keeps running; only if the worker then misses a liveness check (its event loop is stuck) is it stopped, with the timeout recorded as the worker error. A successful worker restart clears the worker error.
Runtime state is in memory. It describes the current process and starts again when Peers restarts, which reloads every package anyway. The Packages screen shows the status as a badge, and package details show the running version and the last error.
Waiting packages
A package whose selected version requires a contract (consumes it without optional) that no
package running in the same context provides doesn't start: its tools don't run, its background
work doesn't start, and its screens show why it waits (its routes still load, so it can be opened
to see that). Its own contracts aren't served, so what requires those waits too. Each context is
checked on its own: a provider in Personal doesn't meet a requirement in a group. Contracts Peers
itself provides never hold a package back. Installing is never refused for this.
- The loader checks again whenever a package in the context starts or stops. A waiting package whose requirements are now met starts, once. A running package whose required provider stopped is stopped and waits again.
- A new version that needs an unmet contract doesn't replace the one running; the older one keeps serving, and the screens shown are its own, so they match the worker that answers them. When the new version starts, open screens switch to its UI. After a restart only the selected version runs, so it waits.
- Its tables keep syncing and its rows stay mentionable: only its tools, background work and screens are held back.
peers packages get <packageId>prints each missing contract and what could provide it, with the command to add it, from thegetPackageRequirementstool. With--json, the same report is underrequirements.
Diagnosing a broken package
peers packages get <packageId> --json, then readruntime.status,runtime.lastError, andruntime.worker.lastWorkerError.- Fix the package and rebuild it (
npm run build). peers packages reload <packageId>. It exits0once the new version is running.
A failed reload leaves the previous version serving: the old worker keeps answering calls until a replacement loads successfully.
Operations
| Operation | What it does |
|---|---|
| Import | Registers an existing package folder, stores its path on this device, and installs its dev version. The folder must exist; import never scaffolds. Importing (or creating or cloning) on a device runs the folder's dev build on that device, even when another device already stored the same build. |
| Create | Scaffolds a new package from the template, with a Git repository on main, or imports the folder if it already exists. A folder to scaffold may use only letters, digits, and . _ - @ + ~ / \ :, because the template step passes it to a shell. |
| Clone | Clones a git repository, builds it, and imports it. Repositories outside github.com/peers-app start disabled; enable one with peers packages install <packageId>. |
| Install | Re-enables a disabled package, or copies one into this context from another of your contexts, then loads it. On the Packages screen, enter the package id in the search box. Fails with the load error if the package does not run; it stays installed. Installing is an explicit choice on this device: when the selected version is dev, it becomes this device's own selection, and other devices still have to activate it themselves. |
| Activate | Selects a version for this device, or for the whole group with scope: group, then loads that exact version immediately. Explicit activation preserves the device's pin policy and clears any automatic compatibility fallback; later automatic resolution still uses the follow policy. Device scope with no version clears the override, so the device follows the group again. Fails with the load error if the selected version does not run; the selection is kept. A dev version can only be activated for this device; group scope refuses it, because dev builds never run on other devices until promoted. |
| Reload | Reads the local build, then reloads the selected version even when unchanged. An identical release creates no dev version or device selection. Changed builds at a released number are refused: bump version in package.json, rebuild, and reload. Failures leave the previous code running (details). |
| Reload all | Checks every enabled package folder and reloads changed builds. Unchanged packages keep running. Released-number conflicts fail; the CLI exits 1 if any package fails. Page refresh does this by default and logs failures to the developer console. |
| Uninstall | Deletes the Packages row for the whole context, so every member device unloads the package. Unloads it on this device immediately. Version rows, bundle files, device preferences, and the signing key are kept, so a later import keeps the same identity. |
| Promote | Moves dev to beta or stable, or beta to stable (Admin). Signs when the device has the key; otherwise warns. Reports what the group runs and, if unchanged, why and how to select the release. --group selects it for the group and follows it here, preserving pin and update policies; Versions offers … and use for group. If activation fails, promotion is kept; retry activation. A build duplicating a released number cannot be promoted: bump, rebuild, and reload. See release selection rules. |
| Install defaults | Installs the default packages into the context. The UI and the create-group tool call it for every new group. |
Who can release a version
In a group, every member's device runs the version the group selects, so only an Admin can choose it:
- A Writer can add a package without selecting a group version and store dev builds. A dev build runs only on a device that activates it while it is tagged dev; automatic updates never switch from a release to dev, even when following all tags.
- Promoting a version to beta or stable, and selecting it for the group, needs an Admin. So does changing a package's update settings (follow range, followed tags, update URL, publisher key, repository, disabled).
- An approval applies to the group where it was signed. Copying a release into another group requires approval there, even when the same person administers both groups.
- An Admin's device installs updates from a package's update URL, or copies in a release from another of your groups, only for a package an Admin added or last saved. If a Writer added the package, an Admin saves its settings once to turn automatic updates on. Copying releases between contexts also requires a publisher key already trusted in the destination. A missing publisher key is not filled from another group's package settings; install from the publisher's release source to establish it.
- An unauthorized release or group selection appears in Sync recovery as Parked, not authorized. The device keeps running the version it had.
- peers-core releases signed by the Peers publisher are accepted from any member: the publisher key every host pins vouches for them.
Removing a package or version does not let an older approval replace a newer decision that this device already received. Reinstalling requires a fresh signature from someone allowed to approve that package or version.
If an existing dev selection stops loading after an update, activate that dev build again on that device. If a release fails verification, reinstall an approved release or ask an Admin for a new release. If the group's selection lacks an Admin's approval, ask an Admin to select an approved version again. You can also activate an approved release just for this device.
Administering your other devices
Add --device <deviceId> to any peers packages command to run it on another of your
devices instead of this one. Your local host forwards the call over the existing
connection, and the target device runs it with its own folders, signing keys, and runtime,
so get and list show that device's running versions and errors, and activate without
--group selects a version for that device. Find device ids with peers devices.
peers packages list --device <deviceId>
peers packages activate <packageId> <packageVersionId> --device <deviceId> -c <groupId>
peers packages reload <packageId> --device <deviceId>
- The target device must trust the caller as Self (see Trust): another device of your own account, or an account you have explicitly granted Self trust. Anyone else, including group Admins, is refused: "Device … does not trust this account as Self". An older device that does not accept remote package administration says so.
- Folder arguments (
import,create --location) must be absolute or~/paths on the target device; this shell's working directory means nothing there. - Tools only: the live
runtimeStatesobservable does not cross devices, so pollget. - Without
-c, the command runs in the target device's own personal context, where a Self-trusted caller has full access. Another account's device (a shared hub that trusts you as Self) is reached this way over a direct connection, for example on the same network; otherwise the call fails with a routing or unavailable-context error. With-c <groupId>, the call travels through that group and access is checked against your role in it on the target device.
System Packages contract
System Packages (packagesContractId, version 1) is a system contract.
- Local, plus your own devices. Reachable over the UI and CLI host transport. Another
device may call it only if this device trusts that caller as Self (see
Administering your other devices); every other remote
caller is refused, group Admins included. This is the ordinary rule for contract tools
without a
remoteAccessLevel, the same one System App Updates uses. - Not for packages. It refuses calls that come from package code, and a device refuses to forward a package's call to it on another device (see Trust).
Every call is bound to one data context, and the access level is checked against your role in that context. In your personal context you are Self, so every tool is allowed.
| Tool | Access level | Notes |
|---|---|---|
getCapabilities | Reader (20) | { fileSystem, linkRemote, installDefaults, isolatedRuntime } |
listPackages | Reader (20) | Summaries, sorted by name. |
getPackage | Reader (20) | Summary plus versions (newest first) and localPath. Throws when the package is not installed. |
importPackage | Admin (60) | { path, name? }. path must be absolute or start with ~. |
createPackage | Admin (60) | { name, location? }. Returns created and an optional warning. |
clonePackage | Admin (60) | { url } |
listPackagesToAdd | Reader (20) | { packages }: each package in your other contexts that this one doesn't have, as { sourceDataContextId, sourceName, packageId, name, description?, appNavs, version?, unsupportedHere }, listed once per context it's in. Pass sourceDataContextId to installPackage as fromDataContextId. |
getPackageRequirements | Reader (20) | { packageId, fromDataContextId? } returns { requirements: { packageId, name, missing } }: each required contract no package serves here, with the packages that could provide it, installed here but not running (with status, and a waiting one's own missing) and toAdd from your other contexts (shaped like listPackagesToAdd's entries, plus their own missing). cycle: true marks a provider that needs, further down, a package already in the chain. With fromDataContextId, it reports on that context's copy of the package, before adding it here. |
installPackage | Admin (60) | { packageId, fromDataContextId? }. A package that waits for a contract it requires is still installed. |
activatePackageVersion | Reader (20) | { packageId, packageVersionId?, scope? }. Group scope also needs Admin, enforced when the Packages row is signed. |
reloadPackage | Writer (40) | { packageId }. Writers may update dev versions. |
reloadAllPackages | Writer (40) | Returns { skipped?, results: [{ packageId, name, ok, changed?, error? }] }. |
linkRemoteRepo | Admin (60) | With remoteRepo (an https://, git@host: or peers:// URL), records it as the package's source on any host. Without it, desktop only: creates a private GitHub repository with gh. A package that already has a source keeps it. |
uninstallPackage | Admin (60) | { packageId } returns { packageId, removed }. |
promotePackageVersion | Admin (60) | { packageVersionId, versionTag, activateForGroup? } returns { packageId, packageVersionId, version, versionTag, signed, activated, groupActivePackageVersionId?, groupRunsPromotedVersion?, activationNote?, warning?, package }. activateForGroup: true is the CLI's --group option. See Promote above. |
installDefaultPackages | Admin (60) | { installed } |
The tools that add or change a package return
{ packageId, created?, warning?, package }, where package is the same as getPackage.
Legacy versions with a missing or empty release tag are treated as dev for promotion
and activation scope, matching the Versions screen: they can only be activated on this
device until promoted.
The runtimeStates observable streams this device's runtime state for the context's
packages, keyed by package id, including worker startup and failure changes. Mutating tools
are serialized within each context, including bulk reloads and uninstalls.
Host support
Every host provides every tool. A host that cannot perform one throws
System Packages <tool> is not supported on this host (<reason>). getCapabilities
reports support up front.
| Host | fileSystem | linkRemote | installDefaults | isolatedRuntime |
|---|---|---|---|---|
| Desktop (Electron) | yes | yes | yes | yes |
| Headless | yes | no | yes | yes |
| PWA | no | no | yes | no |
On the PWA, import, create, clone, and reload from disk are unavailable. Reading, activating, and uninstalling still work. A CLI talking to an older host without System Packages reports that the host does not support package administration.
Related
- Getting started: create, import, and build a package.
- Package lifecycle: versions, channels, promotion, and permissions.
- CLI: every
peerscommand. - Tools: access levels and how contract tools are called.