#343 Official @swamp/ssh extension supporting multiple SSH transport styles

Okay, it's trending toward something like this:

10 hosts: 6 web (4 prod, 2 staging), 2 db (prod, via bastion ProxyJump), 2 edge (prod, Tailscale).

Fleet definition — fleets/awesome.yaml

modelType: "@swamp/ssh-fleet"
modelName: awesome
globalArguments:
  name: awesome
  transport:
    kind: ssh
    user: deploy
    identityFile: ~/.ssh/awesome_ed25519
    knownHostsFile: ~/.ssh/awesome_known_hosts
    strictHostKeyChecking: accept-new
    connectTimeoutSec: 10
    controlMaster: { enabled: true, persistSec: 600 }
  defaultParallel: 8
  captureOutput: true
  hosts:
    - name: web-1
      address: web-1.prod.example.com
      tags: [web, prod]
      attrs: { region: us-east-1, role: api }
    - name: web-2
      address: web-2.prod.example.com
      tags: [web, prod]
      attrs: { region: us-east-1, role: api }
    - name: web-3
      address: web-3.prod.example.com
      tags: [web, prod]
      attrs: { region: us-east-1, role: api }
    - name: web-4
      address: web-4.prod.example.com
      tags: [web, prod]
      attrs: { region: us-east-1, role: api }
    - name: web-5
      address: web-5.staging.example.com
      tags: [web, staging]
      attrs: { region: us-east-1, role: api }
    - name: web-6
      address: web-6.staging.example.com
      tags: [web, staging]
      attrs: { region: us-east-1, role: api }
    - name: db-1
      address: 10.0.5.21
      tags: [db, prod]
      attrs: { region: us-east-1, role: postgres }
      transport:
        proxyJump: deploy@bastion.prod.example.com
    - name: db-2
      address: 10.0.5.22
      tags: [db, prod]
      attrs: { region: us-east-1, role: postgres }
      transport:
        proxyJump: deploy@bastion.prod.example.com
    - name: edge-1
      address: edge-1                                    # short tailnet name
      tags: [edge, prod]
      attrs: { region: eu-west-1, role: edge }
      transport: { kind: tailscale, user: deploy }
    - name: edge-2
      address: edge-2
      tags: [edge, prod]
      attrs: { region: eu-west-1, role: edge }
      transport: { kind: tailscale, user: deploy }

Apply + warm masters

swamp model apply -f fleets/awesome.yaml
swamp model run awesome open --json   # opens CM for the 8 ssh hosts; no-op for edge-1/edge-2

After apply, ten host-* resources exist, each tagged {fleet: awesome}.

1. exec uptime on every prod host (mix of ssh + tailscale)

swamp model run awesome exec \
  --arg hosts='"prod" in host.tags' \
  --arg command='uptime' \
  --json

CEL matches web-1..4, db-1..2, edge-1..2 (8 hosts). web-5 / web-6 are staging and are skipped.

Resources written by this single call, one per matched host:

run-exec-web-1   run-exec-web-2   run-exec-web-3   run-exec-web-4
run-exec-db-1    run-exec-db-2
run-exec-edge-1  run-exec-edge-2

Edge-1's record:

{
  "method": "exec",
  "host": "edge-1",
  "transport": "tailscale",
  "startedAt": "2026-05-18T17:42:11.108Z",
  "finishedAt": "2026-05-18T17:42:11.864Z",
  "durationMs": 756,
  "exitCode": 0,
  "signal": null,
  "stdout": " 17:42:11 up 12 days,  4:11,  0 users,  load average: 0.08, 0.10, 0.09\n",
  "stderr": "",
  "args": { "command": "uptime" },
  "argv": ["tailscale", "ssh", "deploy@edge-1", "--", "uptime"]
}

vs. the ssh equivalent for web-1:

{
  "method": "exec",
  "host": "web-1",
  "transport": "ssh",
  "exitCode": 0,
  "stdout": " 17:42:11 up 6 days, 8:02,  0 users, load average: 0.42, 0.51, 0.58\n",
  "argv": [
    "ssh",
    "-o", "ControlMaster=auto",
    "-o", "ControlPath=/run/user/1000/swamp-ssh/awesome/8f3c…sock",
    "-o", "ControlPersist=600",
    "-i", "/home/adam/.ssh/awesome_ed25519",
    "-p", "22",
    "deploy@web-1.prod.example.com",
    "--", "uptime"
  ]
}

2. copy nginx.conf to all us-east-1 web hosts

swamp model run awesome copy \
  --arg hosts='"web" in host.tags && host.attrs.region == "us-east-1"' \
  --arg src=./nginx.conf \
  --arg dst=/etc/nginx/nginx.conf \
  --arg direction=to \
  --json

CEL matches all six web-* hosts (prod + staging are both us-east-1). Six per-host resources:

run-copy-web-1  run-copy-web-2  run-copy-web-3
run-copy-web-4  run-copy-web-5  run-copy-web-6

web-1's record (scp reuses the master socket; the argv shows it):

{
  "method": "copy",
  "host": "web-1",
  "transport": "ssh",
  "exitCode": 0,
  "durationMs": 412,
  "args": { "src": "./nginx.conf", "dst": "/etc/nginx/nginx.conf", "direction": "to" },
  "argv": [
    "scp",
    "-o", "ControlPath=/run/user/1000/swamp-ssh/awesome/8f3c…sock",
    "-i", "/home/adam/.ssh/awesome_ed25519",
    "-P", "22",
    "./nginx.conf",
    "deploy@web-1.prod.example.com:/etc/nginx/nginx.conf"
  ]
}

Same thing from a workflow

In YAML the selector is just a string — no quoting acrobatics, and swamp's evaluator leaves it alone because there's no ${{ … }} to trigger it:

# workflows/reload-prod-web.yaml
name: reload-prod-web
on: manual
jobs:
  reload:
    steps:
      - name: ship config
        model: awesome
        method: copy
        arguments:
          hosts: '"web" in host.tags && "prod" in host.tags'
          src: ./nginx.conf
          dst: /etc/nginx/nginx.conf
          direction: to

      - name: reload nginx
        model: awesome
        method: exec
        arguments:
          hosts: '"web" in host.tags && "prod" in host.tags'
          command: systemctl reload nginx
          sudo: true

A few selector variants worth knowing

host.transport == "tailscale"                            # only edge-1, edge-2
host.attrs.role == "postgres"                            # only db-1, db-2
"prod" in host.tags && host.transport == "ssh"           # everything prod except the edges
host.name.startsWith("web-") && size(host.tags) > 1      # all web hosts (all have 2 tags)
host.attrs.region != "us-east-1"                         # only the two tailscale edges

You can override everything on a per method run basis - so it all works from the CLI, and you could get by without even static definitions of hosts if you wanted

The YAML pattern here (for the model/workflows) looks great. On thing to note for our use-case is that we'd need to support ssh-agent and password as well as keyfiles.

I like this idea of making the transport more flexible.

Just curious, if we make the transport quite flexible, what's the point of tying this to SSH? Would it be bad to make it even more generic?

Many configuration management tools in the past did their own transport mechanism (with different level of success) that we could tap into...

If you are running things locally, your transport might simply be local execution. If you run something over RPC (or any non-ssh tunnel), you might want to use that as transport mechanism. Those should ideally be implementable from a base, reusable, transport mechanism.. don't you think?

At the same time, a generic transport might become too open-ended, compared to an "ssh transport system with variants" ...

@bixu - should be no problem to have ssh-agent. password too, I suppose (although I have to admit, I don't know why you would do that - but who am I to judge?)

@evrardjp - I think it might be a little to wacky to move beyond ssh as the transport. But once it exists, it would be easy enough to port the pattern.

I don't know why you would do that -- we are digging out of the brownest of brownfield systems at $job 😅

shipped as @swamp/ssh