Skip to main content

DASHBOARD

Overview

The dashboard is a browser view of a Swamp repo's behaviors, workflows, runs and data. It runs in one of two modes:

Mode Opened by Repos Login
Serve dashboard swamp serve --dashboard The repo serve runs Serve's --auth-mode
Local dashboard swamp dashboard, or Open dashboard in swamp start Repos on this machine None; a one-time page token

The local dashboard needs no running swamp serve. Schedules, Webhooks, Logout and Serve Configuration exist only in the serve dashboard. See Local dashboard.

swamp serve includes the dashboard as an opt-in. It is disabled by default and adds no overhead when not enabled.

Enabling the dashboard

Enable the dashboard with any of:

  • --dashboard flag on swamp serve
  • dashboard: true in the serve config file (.swamp/serve.yaml)
  • SWAMP_DASHBOARD=true environment variable
swamp serve --dashboard
# .swamp/serve.yaml
dashboard: true

When running as a daemon, --dashboard is not yet available on swamp serve daemon enable. Use the config file or environment variable instead.

Accessing the dashboard

Once enabled, the dashboard is available at:

http://<host>:<port>/dashboard

With the default settings (--host 127.0.0.1 --port 9090):

http://127.0.0.1:9090/dashboard

URL routing

The dashboard reflects navigation state in the URL path, so every view is directly addressable. You can bookmark a URL, share it with a teammate, or paste it into a browser to jump straight to a specific behavior or workflow run.

Browser back and forward buttons navigate between views. Unknown paths fall back to the overview.

URL patterns

URL View
/dashboard Overview
/dashboard/workflows Workflows list
/dashboard/workflows/<name> Workflow detail
/dashboard/workflows/<name>/runs/<runId> Workflow run detail
/dashboard/workflows/<name>/runs/<runId>/reports/<reportName> A run's workflow-scope report, at the version that run produced
/dashboard/executions Executions
/dashboard/behaviors Behaviors list
/dashboard/behaviors/<name> Behavior detail
/dashboard/behaviors/<name>/data/<dataName> Latest version of a data item
/dashboard/behaviors/<name>/data/<dataName>/versions/<n> One exact version of a data item
/dashboard/behaviors/<name>/reports/<reportName> Latest report output for a behavior
/dashboard/behaviors/<name>/reports/<reportName>/variants/<variant> A forEach report variant
/dashboard/schedules Schedules
/dashboard/webhooks Webhooks
/dashboard/approvals Approvals
/dashboard/workers Workers
/dashboard/activity Activity
/dashboard/data Data
/dashboard/vaults Vaults
/dashboard/extensions Extensions
/dashboard/system System

/dashboard/behaviors/... is the canonical path. For compatibility, links that use the older /dashboard/models/... or /dashboard/behaviours/... segments still resolve, to the matching /dashboard/behaviors/... view.

Each path segment is percent-encoded with encodeURIComponent, except that @ stays readable. For example, a behavior named my behavior appears as /dashboard/behaviors/my%20behavior, and the / in a scoped report name is %2F: /reports/@swamp%2Fworkflow-summary. Names that contain .. cannot be deep-linked.

Data item and report pages have two buttons:

  • Copy link copies the URL of the latest version.
  • Copy permalink copies the URL of the version on screen.

A step's output, including a method-scope report, is linked through its behavior's /versions/<n> permalink.

A data version that has been pruned shows "This version is no longer available", since only a data item's most recent versions are kept and reports expire after 30 days. A run report that a later run has replaced, or that has expired, shows a "no longer available" message with links to the run.

Schedules

The Schedules view (/dashboard/schedules) lists each scheduled workflow with its cron expression, next run and status (running or idle). While fires are waiting to start, the status also shows how many are waiting and how long the oldest has waited, for example 2 queued · waiting 12m. The Overview's Upcoming Schedules panel shows the number of queued fires across all schedules. See Run Workflows on a Schedule.

Workers

The Workers view (/dashboard/workers) draws the remote-execution workers as a map of the pool. It requires admin on access:*, the same as swamp worker list.

  • Grouping: workers are grouped by the fleet label (the enrollment token), by any other label key, or by platform and architecture. Groups are laid out as a treemap weighted by slot capacity.
  • Workers: each worker is a square sized by its capacity, with one cell per dispatch slot. A cell shows that slot's step lease: green while the lease is active, then completed, failed or expired before the slot frees.
  • Status outlines: busy workers are outlined green, draining workers orange and disconnected workers red.
  • Visibility TTL: disconnected workers stay visible, fading out, for a TTL you can adjust in 30-minute steps. The default is 2h and the maximum is 24h, the worker garbage collection default.
  • Placement selector: enter labels, platform or target the way a step's placement block does. Workers the step would not reach are dimmed, and the view shows how many workers match and how many free slots they have. See Workflow Placement.
  • Slot links: each slot row links to the workflow run it is serving.

The Overview header shows a Workers │ busy · idle · unavailable summary of the pool, which links to the Workers view.

Approvals

The dashboard can approve, reject, and resume manual_approval gates. The Approvals view (/dashboard/approvals) lists every gate awaiting a decision, longest waiting first, with Approve and Reject buttons. Each action addresses the gate's run by its run ID.

Pending gates

Each pending gate shows:

  • the workflow and the gated step
  • the first eight characters of the run ID, linked to the run
  • "by" and the principal that started the run, from its initiatedBy, when the run has one
  • how long the gate has waited
  • the gate's prompt, with its line breaks kept

Expanding a gate shows the run, Started by, the gated step and its job, the prompt, and the run's Inputs. Input values are shown as plain text.

Decide a gate

Approve and Reject each open a confirmation with an optional Reason of up to 1024 characters. Confirm approve or Confirm reject sends the decision; Back cancels it. The reason is recorded on the run with decidedBy, as with swamp workflow approve --reason and swamp workflow reject --reason. The local dashboard runs those commands, passing the reason as --reason.

On swamp serve --dashboard, a viewer who does not hold approve on the workflow sees both buttons disabled, with "You don't hold approve on this workflow". Serve tells each viewer only whether they themselves can decide; it never lists who else may approve. An allow grant of run implies approve unless serve runs with --approve-requires-explicit-grant — see Run implies approve.

After a decision, the gate shows "Approved by" or "Rejected by" and the principal recorded as decidedBy, until the listing refreshes without it. A notice names the workflow, step, decision and time, followed by what happens next:

Notice ends with Meaning
"serve is resuming the run" The approval decided the run's last gate and auto-resume applies.
"the run waits for Resume under Awaiting resume" The run's last gate is decided, but the run stays suspended. See Awaiting resume.
"other gates on this run are still pending" The run has more gates to decide.
"the run is rejected" The rejection ended the run.

The local dashboard never resumes a run itself, so its approvals never end with "serve is resuming the run".

A gate already decided somewhere else, such as another tab or the CLI, reports "This gate was already decided; the run is shown where it now is" instead of a failure.

Awaiting resume

A run that is approved but still suspended appears under Awaiting resume on the Approvals view, in Live Runs on the Overview, and on the run detail view. Each entry shows:

  • the label "Approved — awaiting resume"

  • a Resume button

  • the equivalent CLI command:

    swamp workflow resume <workflow> --run <runId>

Resume resumes the run with its original inputs, like swamp workflow resume without --input, and supplies no new inputs. For a workflow that declares inputs, the command carries an --input <key>=<value> placeholder, and the entry notes that resuming from the dashboard supplies no new inputs. To supply resume-time inputs, run the command from the CLI instead.

Authentication

The dashboard uses the same authentication as the rest of swamp serve. When --auth-mode is set to token or oauth, the dashboard requires authentication. See Serve Flags — Authentication modes for details.

Local dashboard

The local dashboard shows repos on this machine with no swamp serve running. It is opened two ways.

swamp dashboard

swamp dashboard [--repo-dir <dir>] [--no-browser] [--host <address>] [--port <port>] [--trusted-hosts <hosts>]
Flag Description
--repo-dir <dir> The repo to open (default: the current folder)
--no-browser Print the URL instead of opening a browser
--host <address> The IP address to listen on (default: 127.0.0.1, this machine only). 0.0.0.0 listens on every address of the machine. localhost is accepted and means 127.0.0.1; any other name is refused
--port <port> Listen on this port instead of any free port. A whole number from 1 to 65535. A port in use is an error that names it and the address
--trusted-hosts <hosts> Comma-separated host names or host:port entries, in the same shape as swamp serve --trusted-hosts. A request whose Host is one of them is served instead of answered with 421. The page token is still required. An entry with a scheme, path, user info or wildcard is refused at startup

swamp start takes the same --host, --port and --trusted-hosts flags. swamp start --json serves no page and refuses all three:

{
  "error": "With --json, swamp start only reports and serves no page, so it can't use --host, --port or --trusted-hosts. Leave out --json to serve the page."
}

swamp dashboard opens one initialized repo, and only that repo: there is no workspace picker, and the repo is not added to the swamp start workspaces:

$ swamp dashboard --no-browser

Open this page in your browser to continue:
  http://127.0.0.1:56668/dashboard/w/infra#token=...
Press Ctrl-C to stop it. Closing this terminal leaves it running.

The dashboard ignores SIGHUP, so it keeps running when its terminal or session closes, and it does not stop when its last tab closes. It can run in the background with &. Stop it with Ctrl-C in its terminal, or with SIGTERM.

A port already in use is refused, naming the address it was asked for:

Error: Port 47811 on 127.0.0.1 is already in use. Pick another --port, or leave it out to use any free port.

A --host that is not an IP address is refused:

Error: --host must be an IP address of this machine, e.g. --host 0.0.0.0 to listen on every address, got "example.com".

From another machine

With a --host that is not a loopback address, the output lists the page through each name other machines can use, followed by a warning. You will see output like:

$ swamp dashboard --no-browser --host 0.0.0.0

Open this page in your browser to continue:
  http://127.0.0.1:56930/dashboard/w/infra#token=...
From another machine, open:
  http://my-machine.local:56930/dashboard/w/infra#token=...
  http://192.168.1.20:56930/dashboard/w/infra#token=...
! Anyone who can reach this address and has the link can use this page, which runs this repo's workflows on this machine. The link is sent unencrypted (HTTP).
Press Ctrl-C to stop it. Closing this terminal leaves it running.

swamp start prints the same block, with "launches agents on this machine" in the warning.

127.0.0.1, localhost and [::1] are always served. A --host that is not a loopback address adds these names, which are also the ones listed:

--host Names added
0.0.0.0 The machine's host name, and each of its addresses of the same family except loopback and link-local
A specific IP That address

A request is served only when its Host header is one of these names or a --trusted-hosts entry. It is matched as text, with no DNS lookup, and any other Host is answered with 421. Every request still needs the page token. The page is plain HTTP: there is no TLS option.

With a --host that is not a loopback address, or in an SSH session, the swamp start page shows a command to copy instead of opening a terminal window, and Browse… is not available.

On a loopback address in an SSH session, the output adds a hint before the last line:

This page opens only on this machine. To open it from yours, run `swamp dashboard --no-browser --host 0.0.0.0`.

A --trusted-hosts entry that is not a host name or host:port is refused:

Error: --trusted-hosts entry "https://example.ts.net" is not a host name or host:port. Give the name your proxy sends, with no scheme, path or wildcard.

Behind a reverse proxy

--port gives a reverse proxy on this machine a fixed upstream. A proxy that forwards the client's Host, such as tailscale serve, also needs that name in --trusted-hosts:

$ swamp dashboard --no-browser --port 8765 --trusted-hosts my-machine.tailnet-name.ts.net &
$ tailscale serve --bg 8765

With --trusted-hosts, the output lists the page through each name, just before the last line. You will see output like:

Open this page in your browser to continue:
  http://127.0.0.1:8765/dashboard/w/infra#token=...
Through your proxy (it must serve HTTPS), open:
  https://my-machine.tailnet-name.ts.net/dashboard/w/infra#token=...
Press Ctrl-C to stop it. Closing this terminal leaves it running.

nginx sends its upstream address as Host by default, so it needs only --port. The URL carries the page token: through a proxy that serves plain HTTP, the token crosses the network unencrypted.

The URL names a registered workspace by its workspace name, and any other repo by its folder name. Run outside a repo, it fails:

Error: /Users/alice/code is not a swamp repo. Run `swamp dashboard` inside a swamp repo, point --repo-dir at one, or run `swamp repo init` there first.

--json is refused, because the command's only result is a page in a browser:

{
  "error": "swamp dashboard opens a page in your browser and has no JSON output. Remove --json to open it."
}

From swamp start

Once a workspace is open in swamp start, Open dashboard in the page header opens that workspace's dashboard. The sidebar's Workspace picker switches between registered workspaces, and All workspaces and tasks goes back to the swamp start page. See Start a task with swamp start.

What the local dashboard does

  • No login. The page URL carries a one-time token, in the URL fragment; a workspace page opened without it says to open it from swamp start or swamp dashboard. The server listens only on 127.0.0.1.
  • Read-only, apart from four workflow actions. Approve, reject, resume and cancel run as the matching swamp workflow command in the repo, so they take the repo's locks and sync like any CLI command. A resumed workflow keeps running after the dashboard is closed. Every other change is refused.
  • Runs from the CLI show as live, as well as the runs the dashboard acts on.
  • Schedules and Webhooks show as "Needs swamp serve", and explain how to run serve. Logout and Serve Configuration on the System page are absent.

Use swamp serve --dashboard for schedules, webhooks, workers, and a dashboard other machines can reach.