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.yamlbreaks a rule above, or names another collective - the
entryfile 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.