PUBLISH AN APP
This guide shows you how to publish a Swamp app in an extension, and how to enable it in a repository that pulls the extension.
Prerequisites
- An app in
extensions/apps/<folder>/, created withswamp app init - Membership in the collective the extension is named for
- A Swamp release with apps support wherever the extension is pulled
Grant the app only what it uses
Edit the app's app.yaml so it asks for the reads, workflows and methods the
app calls, and nothing else. Name each method a behavior may run:
name: "@acme/board"
title: Board
entry: dist/index.html
bridge: 1
platform: "1.4"
capabilities: [data:read]
run: ["@acme/nightly"]
methods:
- behavior: team-board
type: "@acme/board"
methods: [move_ticket, add_ticket]Set platform to the newest app platform minor whose APIs the app calls. The
App reference lists every field and
its limits.
Build the app
From the app folder, install its packages and build it:
cd extensions/apps/board
bun install
swamp app buildCommit bun.lock. Push checks every package in it, and refuses an app whose
lock does not satisfy package.json. Packages the app ships, what its
dependencies reach, are also audited on npm and OSV.dev; build tools in
devDependencies are not. See
Dependencies § Swamp apps.
List the app in the manifest
Add the app folder under apps: in the extension manifest, with the behaviors
and workflows it uses. Name those workflows in the extension's collective:
manifestVersion: 1
name: "@acme/board"
version: "2026.11.19.1"
behaviors:
- board.ts
apps:
- boardPush the extension
Check the push first, then publish:
swamp extension push extensions/behaviors/manifest.yaml --dry-run
swamp extension push extensions/behaviors/manifest.yamlIf push or the registry refuses an app, the message names the app and the rule it breaks. To fix a refused package, see Dependencies § Swamp apps; for anything else, see App § Registry checks.
Say what the app sends out
An app can send anything it reads to any HTTPS site. If the app calls an external site, name the site and what the app sends it in the extension's README.
Enable the app after a pull
In the repository that uses the extension, pull it and approve the app. Approval
needs admin on access:swamp/app-approval:
swamp extension pull @acme/board
swamp app approve @acme/boardswamp app approve shows what the app asks for before it enables it. When a
later version asks for more, approve it again.
Under swamp serve, give viewers read on the app:
swamp access grant create --subject group:ops --allow read --on 'access:swamp/apps/@acme/board'