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:
--dashboardflag onswamp servedashboard: truein the serve config file (.swamp/serve.yaml)SWAMP_DASHBOARD=trueenvironment variable
swamp serve --dashboard# .swamp/serve.yaml
dashboard: trueWhen 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>/dashboardWith the default settings (--host 127.0.0.1 --port 9090):
http://127.0.0.1:9090/dashboardURL 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 and report links
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
fleetlabel (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,platformortargetthe 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 8765With --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 startorswamp dashboard. The server listens only on127.0.0.1. - Read-only, apart from four workflow actions. Approve, reject, resume and
cancel run as the matching
swamp workflowcommand 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.
Related
- Serve Flags — full flag reference
including
--dashboard - Start a task with swamp start — workspaces, tasks and Open dashboard
- REST API — HTTP endpoints for health monitoring and run management
- Daemon Management — running
swamp serveas a system daemon