The app store for Calimero: where signed apps are published, and where clusters install them from.
Calimero is an app backend, like Firebase, that runs every app inside attested Intel TDX hardware so nobody operating the servers can read its data. This registry is how an app gets there: a developer signs a .mpk package with their own key, publishes it here, and a cluster installs it on request. The registry checks the signature on every upload, pins each package to its signer, and the node checks the signature again before it installs.
Live at apps.calimero.network. It is also Calimero Cloud's package registry (see Calimero Cloud orgs).
app-registry/
├── api/ # the production API: Vercel functions (/api/...)
├── shared/ # code the functions and the backend share (sessions, orgs, storage env)
├── packages/
│ ├── backend/ # bundle validation, storage and policy; a Fastify server for local development
│ ├── frontend/ # React + TypeScript web app
│ └── cli/ # calimero-registry CLI
├── scripts/ # maintenance and migration scripts
└── .github/ # GitHub Actions workflows
| Part | Description | Stack |
|---|---|---|
| api | The production API, deployed as Vercel functions | Node.js, Vercel |
| backend | Signature validation, bundle storage, metadata policy; local dev server | Node.js, Fastify |
| frontend | Web UI: browse, upload, organizations, in-app docs | React, TypeScript, Vite |
| cli | Organization administration, metadata edits | TypeScript, Commander.js |
Storage: package records, organizations and sessions live in Redis; the .mpk files themselves live in a Google Cloud Storage bucket. ENV_CONFIG.md lists every variable.
Apps are built, signed and published with core's meroctl (see Publishing). Nothing in this monorepo builds bundles.
# Prerequisites: Node.js 24+, pnpm 8 (the version in package.json's packageManager)
git clone https://github.com/calimero-network/app-registry.git
cd app-registry
pnpm install
pnpm build
# Start backend + frontend together
pnpm dev:all
# Backend: http://localhost:8080 (an in-memory store when REDIS_URL is unset)
# Frontend: http://localhost:5173 (proxies /api to the backend)A .mpk is a gzip-compressed tar holding a signed manifest.json and a calimero:app WebAssembly component:
bundle.mpk
├── manifest.json # package, version, minRuntimeVersion, artifact hashes, signature
├── app.wasm # the calimero:app component, with its ABI embedded
├── compute.wasm # optional: compute methods
├── frontend/ # optional: the app's web build, served by the node
└── pipelines/ # optional: pipeline YAML files
The ABI travels inside the component (its calimero:abi section), which is what a node reads to check an upgrade.
Install core's meroctl (curl -fsSL https://raw.githubusercontent.com/calimero-network/core/master/scripts/install.sh | sh -s -- meroctl), then:
1. meroctl app signer new key.json # one-time; keep it out of git
2. meroctl app build path/to/app # build the component
meroctl app pack path/to/app --key key.json # write and sign manifest.json, pack the .mpk
# → path/to/app/dist/<package>-<version>.mpk; package and version come from the crate's Cargo.toml
# → add --previous <last .mpk> to check the new ABI against the last release
3. export CALIMERO_REGISTRY_API_KEY=<token> # Organizations page → CLI Access
meroctl app publish path/to/app/dist/<package>-<version>.mpk
# → registry validates the Ed25519 signature and the signer's ownership
# → app visible in the UI
meroctl app publish --org <org> publishes as a Calimero Cloud organization instead; a Cloud package starts private unless you pass --public. A request body is capped at 4.5 MB and meroctl app publish sends the whole .mpk hex-encoded, so it handles bundles up to about 2.2 MB. Larger bundles go through POST /api/bundles/upload-url (the archive goes straight to storage), then POST /api/bundles/push with the manifest; the apps repository's publish-bundle.sh does this. For CI, see PUBLISHING.md.
Every manifest is verified using:
- Remove
signatureand all_*-prefixed fields - RFC 8785 (JCS) canonicalize → deterministic JSON bytes
- SHA-256 hash of the domain tag
calimero.bundle.manifest.v1\0followed by the canonical bytes - Ed25519 verify(sig, hash, pubkey)
A signature over the bare SHA-256 of the canonical bytes is refused.
A node runs the same check again before it installs a bundle.
The HTTP API is at /api: /api/bundles, /api/orgs, /api/packages,
/api/invitations, /api/downloads, /api/auth, /api/admin and the rest.
There is no version segment. /api/v2/... was removed on 2026-11-16 and now
answers 404; clients that still call it (meroctl before 1.0.0-rc.25, older
desktop builds) have to be upgraded. The Vercel functions live under api/ at
the same paths they serve, and the Fastify dev server registers the same
paths (tests/api-paths.test.js holds both to that).
There are two push endpoints, and they do not authorize the same way:
| Endpoint | Used by | Authorization for an existing package |
|---|---|---|
POST /api/bundles/push |
calimero-registry, CI scripts |
Signing key matches the package's signer. A key in owners[] is also accepted, but do not use it 1 |
POST /api/bundles/push-file |
Browser upload | The same |
Both also accept a version signed with another key when the publishing account is an admin or owner of the org linked to the package (plain members publish with a package key). Such a version does not change the package's key set: the keys allowed before it stay allowed after it, and the admin's own key is not added, so their access ends with their role.
Both require a valid Ed25519 signature, and both refuse the well-known dev key. Both also reject a version that is not greater than the latest published one (400 version_not_allowed), so a CI script asks the registry for the latest version first.
The rest is common ground. Both push endpoints gate ownership behind versions.length > 0, so neither applies it - nor the increasing-version rule - to a package's first version. Deleting is a third endpoint again:
| Scenario | Endpoint | Authorization |
|---|---|---|
| First publish | either push endpoint | Any signed request. The account behind the token or session becomes the author |
| Delete version | DELETE /api/bundles/<package>/<version> |
Signed in as metadata.author (or _ownerEmail) |
| Delete package | DELETE /api/bundles/<package> |
The same, for every version at once |
metadata.author is set server-side on first publish and carried forward from the oldest version onto every later one, so a manifest cannot set or change it.
A delete takes effect immediately, but GET /api/bundles is cached at the CDN and nothing purges it, so a listing can trail the registry by up to a minute - long enough for a deleted package to look like it survived. Add fresh=1 when a read has to reflect a write that just happened; the site does this automatically for a while after any change you make. fresh=1 is honoured for a single-package read (?package=<name>) from anyone, and for any other listing only when the request is signed in.
A node derives an app's ApplicationId from SHA-256(borsh(package, signerId)), not from the wasm.
Publishing the same package under a different key produces a different application, not an upgrade, and existing installs never see it.
That is what the signer pin above protects: the registry refuses the mismatch rather than letting the identity break silently.
Organizations let teams collectively manage packages. Members are identified by email address, so there are no shared keys to distribute or rotate. Browser org management uses your Google session. CLI org management uses an API token.
admin@example.com creates org → adds alice@example.com (member)
→ links com.my-org.app to org
alice@example.com uploads a new version from the browser:
→ bundle signed with the package's signing key
→ session resolves → alice@example.com
→ registry: is alice@example.com in org members? YES → 201 Created
Admin removes alice:
→ registry: is alice@example.com in org members? NO → 403 Forbidden (immediate)
Org membership decides who may operate the package's registry entry. It does not decide what signs the bundle, and the two are not interchangeable: ApplicationId is derived from package and signerId, so a member uploading under their own key mints a different application rather than a new version, which the registry accepts and no existing install ever sees.
So a package has one signing key, and the org governs who may use it. Hold it as an organization secret (MERO_SIGN_KEY) and let a bot account publish with it, which keeps releases off any individual's credentials. Membership is still what you revoke: removing someone stops them uploading immediately, with no key rotation, which is the property a shared key on its own does not give you.
The registry is also Calimero Cloud's package registry. A Cloud org publishes with a short-lived Cloud JWT (minted by the Cloud manager; Authorization: Bearer <jwt>, scope publish or read) instead of a registry API token. Its packages are private by default: they are left out of every listing and read, and answer 404 to anyone outside the org. Cloud clusters download them with the per-cluster credential in their --registry-url, which the registry checks with the Cloud manager. An org also owns the namespace of its first package (com.acme.app claims com.acme), every Cloud publish counts against per-org quotas, and every publish, visibility change, yank and delete lands in the org's audit log (GET /api/orgs/:id/audit). Making a private package public (PUT /api/packages/:pkg/visibility) goes through the admin review queue.
The full contract, including the endpoints the Cloud manager exposes, is docs/cloud-integration.md. Packages published without Cloud behave exactly as before.
- Sign in with Google at the registry web UI
- Create an org from the Organizations page, where you become the admin
- Get a CLI API token from the Organizations page → CLI Access section:
calimero-registry config set api-key # paste the token when asked # or: export CALIMERO_API_KEY=<token>
- Add members by email from the web UI or CLI
- Link packages from the web UI or CLI (must be the original package author or org admin)
- Members upload bundles signed with the package's key, and the registry checks their email against the org
All write operations require an API token (set via config set api-key or CALIMERO_API_KEY):
# List your orgs (resolves your email from the token automatically)
calimero-registry org list
# Create
calimero-registry org create -n "My Org" -s "my-org"
# Members — invite by username (they accept from the Organizations page), remove by username
calimero-registry org members add <org-id> alice --role member
calimero-registry org members remove <org-id> alice
# Link packages
calimero-registry org packages link <org-id> com.my-org.app
calimero-registry org packages unlink <org-id> com.my-org.appBuilding, signing and publishing is core's meroctl (app build, app pack, app sign, app inspect, app publish; meroctl reference).
calimero-registry covers administration of the registry itself:
# Bundle commands
calimero-registry bundle edit <package> <version> --remote [--manifest signed.json]
calimero-registry bundle get <package> <version> --local
calimero-registry bundle push <bundle-file> [--local | --remote]
calimero-registry bundle create <wasm-file> [package] [version] [options]
# Org commands (require CALIMERO_API_KEY or config api-key)
calimero-registry org list
calimero-registry org create -n <name> -s <slug>
calimero-registry org get <org-id> # public
calimero-registry org update <org-id> [--name <name>] [--metadata <json>]
calimero-registry org delete <org-id>
calimero-registry org members list <org-id> # public
calimero-registry org members add <org-id> <username> [--role member|admin]
calimero-registry org members update <org-id> <username> --role member|admin
calimero-registry org members remove <org-id> <username>
calimero-registry org packages link <org-id> <package>
calimero-registry org packages unlink <org-id> <package>
# Config
calimero-registry config set registry-url <url>
calimero-registry config set api-key # paste the token when asked
calimero-registry config get | list | reset
# A local registry for development
calimero-registry local start | stop | status | reset | seed | backup | restore
calimero-registry healthEnvironment variables: CALIMERO_REGISTRY_URL, CALIMERO_API_KEY. (meroctl app publish reads CALIMERO_REGISTRY_URL and CALIMERO_REGISTRY_API_KEY.)
pnpm install # install all dependencies
pnpm build # build all packages
pnpm dev:all # start backend + frontend in parallel
pnpm dev # backend only
pnpm dev:frontend # frontend only
pnpm test # run all tests
pnpm test:e2e # Playwright end-to-end tests
pnpm lint # lint all packages
pnpm lint:fix # auto-fix lint issues
pnpm format # prettier format
pnpm quality # format check + lint + type-check + test (what CI runs)
pnpm quality:fix # fix all quality issuesnode scripts/create-mpk-bundle.js # create a sample test bundle
node scripts/cleanup-registry.js # remove test data from a running registry
node scripts/prune-old-versions.js # delete versions beyond BUNDLE_KEEP_VERSIONS
# Standalone signature verification (no server required)
node packages/backend/scripts/verify-signature-standalone.js manifest.jsonLocal development needs no configuration: without REDIS_URL the backend keeps everything in memory, on port 8080. The variables that matter elsewhere:
PORT=8080 # backend port
REDIS_URL=redis://... # package records, orgs, sessions (required in production)
GCS_BUCKET=calimero-app-registry # where .mpk files are stored
GCS_CLIENT_EMAIL= / GCS_PRIVATE_KEY= # the bucket's service account (or GOOGLE_APPLICATION_CREDENTIALS)
CORS_ORIGIN=http://localhost:5173
VITE_API_PROXY=http://localhost:8080 # frontend dev server: where /api goesPreview deployments read the PREVIEW_-prefixed form of each storage variable and refuse to touch production storage. ENV_CONFIG.md has the full list, including the Calimero Cloud settings.
pnpm test # all packages
pnpm test:backend
pnpm test:frontend
pnpm test:cli
pnpm test:e2e # PlaywrightThe registry frontend ships a built-in Docs page (/docs) covering:
- The bundle format and the manifest, single- and multi-service
- Signing keys,
signerIdderivation, and why app identity is package + signer - Publishing from the terminal, from the browser, and from CI
- Organizations: setup, membership, bot accounts, package linking, revocation
- Registry CLI reference for org administration and metadata edits
- Installation and signature validation on a node
- Calimero docs
- Publishing guide - building, signing, and releasing from CI
- meroctl reference - building, signing and publishing an app
- GitHub
- Issues
- Contributing
- License
Built by the Calimero Network team.
Footnotes
-
owners[]predates the identity model below and core's signing tools never write it. A key listed there does publish: the endpoint accepts it and stores the version.ApplicationIdcomes frompackageandsignerId, so that version belongs to a different application, which no node with the original installed will ever see. ↩