Ssh

Run commands, copy files, and open port forwards across a declared set of hosts over SSH. Define the hosts once on the model, then target any subset by host name or tag (controlplane), an explicit name list, a CEL expression ('cel:"prod" in host.tags'), or all. Every host runs in parallel and records its own result resource, so individual outcomes are auditable and workflows can gate on them.

OpenSSH targets reuse long-lived connections via ControlMaster; Tailscale SSH targets authenticate with tailnet identity and bypass multiplexing. Hosts can mix both transports in one fleet, and each host can override the fleet defaults (user, port, identity, proxy jump, auth mode, and more).

Highlights

• Define your fleet once via globalArguments.hosts[] — each host can override the fleet-default transport (kind, user, port, identity, etc.).
• Mix OpenSSH and Tailscale hosts in the same fleet.
• Per-host operations land as one resource each — run-<method>-<name> — tagged fleet / host / method / exitCode, so you can diff, gate workflows, query the audit trail by tag, and read a run's outcome straight off the returned data handle.
• exec and script take an optional okExitCodes for guard commands whose non-zero exit is an answer, not a failure — an array replacing the default [0], or "any".
• Selector forms: "all", an explicit name list ["web-1"], a bare host name or tag (controlplane), name:/tag:/cel: prefixes, or a cel: predicate (e.g. 'cel:"prod" in host.tags'). A bare CEL string is deprecated — prefix it with cel:.
• CEL helpers bundled on every call: matchesRegex(s, pat), cidrContains(cidr, addr).
• resolve answers "which hosts does this selector match?" as pure data — no SSH connection, zero matches is a success with count: 0, and the write's count tag lets a runModel caller gate without reading the resource.
• Auth modes: key-based (file, agent, IdentityAgent, inline content via identityContent) and password-based via sshpass -e with the password supplied through ${{ vault.get('<vault>', '<key>') }}.

Methods

Exit codes

A host fails when it exits with a code that isn't allowed, is killed by a signal, or fails to spawn — and one failed host fails the method. By default the only allowed code is 0.

exec and script take an optional okExitCodes to widen that:

Codes must be integers in 0..255. Spawn errors, timeouts, and signal kills still fail the host whatever the setting — they produce no exit status for a guard command to interpret. An allowed exit code is not a failure and does not trip failFast. Prefer an explicit list to "any": OpenSSH reports its own errors (unreachable host, rejected key) as exit 255, and "any" accepts those too.

# `test -f` answers 0 or 1; both are legitimate answers, not failures.
swamp model method run awesome exec \
  --input hosts=all \
  --input command='test -f /etc/nginx/nginx.conf' \
  --input okExitCodes:json='[0, 1]' --json

Results and tags

Each selected host records a run-<method>-<host> resource with the verbatim exitCode, and the method returns one data handle per host in fleet order. An allowed non-zero exit leaves the resource's error field unset. Resources are written before any error is raised, so they are there whether the method succeeded or failed.

Every run-<method>-<host> write is tagged:

A model calling this one via context.runModel() gets those handles back as result.resources on success, and can branch on handle.tags.exitCode === "0" without fetching resource content — which is the point of okExitCodes, since a thrown method returns { ok: false, error } with no handles at all. In workflow CEL, data.findByTag("host", "web-1") selects by the same tags.

See the bundled README for worked examples and per-command recipes.

Output capture

Captured by default, opt out at the fleet (captureOutput: false) or per call. No cap — stdout/stderr land verbatim in the matching run-<method>-<host> resource.

Requirements

• OpenSSH client (ssh, scp) on the runner.
• rsync if any copy call sets useRsync: true.
• tailscale if any host uses the tailscale transport.
• sshpass if any host uses auth.kind: password.
• The swamp host must expose ctx.createCelEnvironment() on the extension model context (introduced 2026-05).

Usage

swamp extension pull @swamp/ssh

# Create the fleet, then author its globalArguments (transport + hosts).
swamp model create @swamp/ssh awesome
swamp model edit awesome

# Run methods — every selector-taking method requires a `hosts` argument.
swamp model method run awesome open --input hosts=all --json
swamp model method run awesome exec \
  --input hosts='tag:prod' \
  --input command='uptime' --json

See the bundled README for the full configuration shape, transport options, authentication modes, and worked examples.