agent-swarm.devagent-swarm.dev
Apps

App concepts

Models, queries, actions, interfaces, configuration, versioning, access, and synchronized sources in Swarm Apps.

Beta — requires agent-swarm 1.129.0 or later

Apps are in beta. The definition contract and APIs may change between releases. Core Apps require agent-swarm 1.129.0; source-backed model sync requires 1.130.0; canonical asset namespace support for Apps requires 1.131.0.

An App definition is the versioned contract for its data and interface. The server validates the complete definition before saving it, so a rejected update leaves the current App unchanged.

Models

Models define persistent rows. A definition has up to 50 models with up to 200 columns each and up to 100 actions by default (APPS_MAX_MODELS, APPS_MAX_COLUMNS_PER_MODEL, APPS_MAX_ACTIONS). Each model has typed columns: string, number, boolean, date, enum, or json (any JSON value; serialized size capped at 256 KB by default, APPS_JSON_COLUMN_MAX_BYTES). Columns can be required, defaulted, or indexed where the kind supports it; a json column cannot be indexed, filtered, or sorted. The server adds identity, timestamps, and authorship fields to every row.

Prefer hiding a column when a field is being retired. Hiding preserves existing values and keeps rollback possible. Purging a column is an explicit, irreversible migration and should be reserved for data that really must be removed.

Named queries

Queries give an App a declared read surface. A query selects one model and can add equality filters, sorting, and a row limit. Parameter placeholders such as { "$param": "competitor" } let a detail page or agent request one specific record without exposing an unfiltered fallback.

Agents call named queries with app-query; saved scripts use ctx.swarm.app_query. Scripts also receive generated per-App TypeScript types for models and queries starting in 1.129.0. A script is typechecked against only the apps it names. Types are budgeted at 1 MiB per app and 4 MiB for all the apps one script names. An app past a budget stays callable untyped: an app write over the per-app budget returns a warning, and so does a script-upsert that names an untyped app.

Actions

An App can declare up to 20 named actions:

  • task dispatches a prompt to the swarm. Invocation input is appended as context, so a table row can travel with the task.
  • script runs a saved script with definition defaults plus invocation input.
  • sync refreshes all or a selected subset of the App's external sources.

Pages invoke these through app.action. A task action also accepts an optional parentTaskId, which chains the new task under an existing one. The caller needs the same parent access as POST /api/tasks, and script or sync actions reject the field. Built-in interface actions also create, update, or delete rows; refresh queries; and navigate between App pages.

Script actions receive caller as a reserved, server-stamped argument. The server overwrites caller from definition defaults and request input.

type AppActionCaller = {
  kind: "user" | "agent" | "operator" | "guest";
  id: string | null;
  name?: string;
  pageId?: string;
};

The caller identifies the authenticated user or agent. Operator and guest callers have id: null. A signed page session adds pageId. With the swarm key, a registered X-Agent-ID produces an agent caller and agent:<id> row provenance. Missing or unknown agent IDs remain operator callers. Task actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.

Pages and reusable elements

Pages are flat, validated element trees rendered by the dashboard. The component catalog includes layout, headings, text, forms, tables, filters, metrics, alerts, badges, drawers, and detail views. Bindings such as { "$state": "/queries/allItems/data" } connect declared queries and actions to those elements.

Reusable elements live in the versioned definition. They are private by default and can be explicitly exported for another App to reference. The server compatibility-checks breaking changes to exported elements.

Per-user configuration and theme

userConfig declares typed settings, but each user's values are stored separately from the shared definition and rows. This is useful for preferences such as a default region, reporting window, or whether archived records are shown.

An optional definition theme sets the App's default canvas preset. Viewers can override it per App without changing the shared definition. Treat the definition theme as a default, not an enforcement mechanism. An optional definition icon is shown next to the App on the dashboard Apps page. It takes the same shapes as agent avatars: a Lucide glyph ({ type: "lucide", icon: "<name>", color?: "#RRGGBB" }), an HTTPS image ({ type: "url", url }), or an image in agent-fs ({ type: "agent-fs", path } on the swarm drive, or with both orgId and driveId for another drive). The page shows a generic icon when the name is unknown or the image cannot load.

Versioning, migrations, and rollback

Every successful definition write snapshots the previous definition. Use app-history to find a version, app-diff to inspect it against the current definition, and app-rollback to restore it.

Rollback is a forward schema migration over today's rows, not row-level time travel. A lossy migration or rollback must state how values are mapped, coerced, backfilled, or purged. If validation rejects it, no definition or row changes are written.

RBAC, ownership, and scope

Apps have permission-aware lifecycle and use operations. Ownership and App permissions determine who can inspect, change, or use an App; they do not make every connected source private. In particular, synchronized rows are visible to principals with app.use, so scope task sources and external projections to the audience intended to read them.

From 1.131.0, Apps participate in canonical asset namespaces. That makes App ownership and movement fit the same namespace model as other swarm assets while preserving RBAC checks.

Source-backed models

Source-backed model sync arrived in 1.130.0. A model can project records from a saved script or from the swarm task pool into normal App rows. Each source declares a stable join key, and source-bound columns are read-only between refreshes; App-owned columns on the same row remain editable.

Synced rows expose provenance and freshness through source, syncedAt, and stale. Refresh through a sync action, the sync API, app-sync, or a schedule. Script sources use the source script owner's credentials and should reference a registered connection instead of embedding secrets.

Next, build a complete App and iterate on it, or consult the Apps API reference.

On this page