Skip to main content

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 with swamp 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 build

Commit 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:
  - board

Push the extension

Check the push first, then publish:

swamp extension push extensions/behaviors/manifest.yaml --dry-run
swamp extension push extensions/behaviors/manifest.yaml

If 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/board

swamp 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'