Skip to main content

APP

A Swamp app is a sandboxed web page served by swamp serve and the dashboard. An app folder lives in extensions/apps/<folder>/ and holds an app.yaml and a build. An extension ships apps listed under apps in its manifest.

app.yaml

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]

Unknown keys are rejected.

Field Type Required Default Rules
name string Yes — @<collective>/<name>, at most 100 characters. The collective must be the extension's.
title string Yes — 1 to 100 characters.
entry string No dist/index.html Relative, inside a build folder of the app, at most 500 characters. No .., ., empty segment or backslash.
bridge integer Yes — 1.
platform integer / string No 1 A major from 1 to 999, or a quoted minimum minor such as "1.4".
capabilities string[] No [] At most 20, each one of the capabilities below.
run string[] No [] At most 50 workflow names, each 1 to 200 characters.
methods object[] No [] At most 50 method grants, one per behavior.

Capabilities

Capability Allows
runs:read Workflow run search, summaries and history
data:read Data reads, queries and change feeds
catalog:read Workflow and behavior definitions
health:read Serve health
workers:read The worker list

Method grants

Each methods entry names one behavior:

Field Type Required Rules
behavior string One of 1 to 200 characters. model is a synonym; an entry sets exactly one.
type string Yes 1 to 200 characters. The app may run methods only while the type matches.
methods string[] Yes 1 to 50 method names, each 1 to 200 characters, none repeated.

The app may run only the listed methods of that behavior. Two entries for one behavior are rejected.

Platform

platform names the app platform the build needs. A major, such as 1, needs that major. A minor, such as "1.4", needs that major at that minor or later. A Swamp release that does not carry the platform refuses to run the app.

Archive contents

Push ships each listed app at apps/<folder>/ in the archive, where <folder> is the last segment of the manifest entry:

File Shipped
app.yaml Always
The entry folder Always, every file under it
package.json When present
bun.lock When present
Sources, node_modules Never

Files in the entry folder must be regular files with one of these extensions: .html, .js, .mjs, .css, .json, .map, .svg, .png, .jpg, .jpeg, .webp, .ico, .woff, .woff2, .ttf. Hidden files and symlinks are rejected.

Limit Value
One file 5,000,000 bytes
One app, files 500
One app, bytes 25,000,000 bytes
Whole archive 50 MiB compressed

The app's packages are checked from package.json and bun.lock, and those its dist/ can hold audited on npm and OSV.dev: every one at push, and up to 1,000 per extension by the registry, which reports the rest as not audited; see Dependencies § Swamp apps.

Registry checks

On confirmation the registry reads the archive itself and applies the rules above to every app the manifest lists. It refuses the version with 422 when:

  • the manifest lists an app with no apps/<folder>/app.yaml, or two apps with one folder name
  • an app.yaml breaks a rule above, or names another collective
  • the entry file is missing, or the app folder holds a file outside the rules above
  • anything under apps/ is a link, a special file, or a path with ..
  • a file or app exceeds the limits above
  • the manifest cannot be read while the archive holds apps/
  • the archive cannot be read to its end, whether or not it holds apps

An archive over 50 MiB is refused with 413 before it is read, and so is one that unpacks to more than 1,000,000,000 bytes.

The registry lists each app from the archive's app.yaml, never from the client's metadata. An apps/ folder the manifest does not list is not listed, and Swamp does not run it.

Swamp release requirement

A Swamp release without apps support installs an extension without its apps, and fails to pull an extension that holds only apps. The registry marks each version that ships apps: the extension page shows a notice in its Apps section, and the versions API sets swampRequirement on that version. swampRequirement is null for a version without apps.