Summary

Comprehensive user guide for swamp serve — covering everything an admin and user needs to know to set up, secure, and operate a remote swamp server.

This guide should be written from the perspective of someone who has never used swamp serve before and needs to go from zero to a working authenticated deployment.

Sections

1. What is swamp serve?

What it does, when you'd use it, the architecture (server holds the repo, clients connect over WebSocket, workers execute remotely).

2. Getting started

Starting a basic server on loopback: ```bash swamp serve ``` What happens, what the output means, how to connect locally.

3. TLS setup

Two deployment variants, both verified end-to-end:

Direct TLS — swamp terminates TLS: ```bash swamp serve --cert-file server.crt --key-file server.key ``` Include the cert generation command with the `CA:FALSE` gotcha (Deno rejects CA certs as end-entity certs): ```bash openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \ -keyout server.key -out server.crt -days 30 -nodes \ -subj '/CN=localhost' \ -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \ -addext 'basicConstraints=critical,CA:FALSE' ``` Note: compiled binary bakes in cert store — self-signed certs must be added to OS trust store. `DENO_CERT` only works with `deno run`.

Reverse proxy (Caddy) — recommended for production: ```bash swamp serve # plain, loopback caddy reverse-proxy --from swamp.example.com --to 127.0.0.1:9090 ``` Caddy auto-provisions Let's Encrypt certs. Zero cert management. This is the recommended production approach.

Environment variables: `SWAMP_SERVE_CERT_FILE`, `SWAMP_SERVE_KEY_FILE`.

4. Hard refusals

Off-loopback binding requires both TLS and authentication. The server refuses to start without them — this is not configurable. Explain why (unauthenticated control plane on the network = arbitrary remote execution).

5. Authentication with mode: token

The full token lifecycle:

Admin sets up the server: ```bash swamp serve --auth-mode token --admins 'user:paul' ```

Admin mints tokens: ```bash swamp access token mint paul-token --principal user:paul swamp access token mint sarah-token --principal user:sarah ``` Token is shown once. Distribute securely.

Users store their token: ```bash swamp auth server-login --server wss://swamp.example.com --token 'paul-token.' ``` Stored in `~/.config/swamp/servers.json`. Auto-used on subsequent `--server` commands.

SWAMP_SERVE_URL for convenience: ```bash export SWAMP_SERVE_URL=wss://swamp.example.com swamp access can-i # no --server needed ```

Token management: ```bash swamp access token list swamp access token revoke sarah-token swamp access token rotate paul-token ```

Unauthenticated connections get HTTP 401.

6. Access control

The grant/policy model — who can do what:

Core concepts:

• Grants: subject → effect (allow/deny) → actions → resource selector
• Subjects: `user:paul`, `group:release-managers`, `idp-group:platform-eng`
• Actions: `run`, `read`, `write`, `admin`
• Resources: `workflow:@acme/`, `model:hello`, `data:`, `access:*`
• Deny wins over allow
• Default deny (no grant = denied)
• Admin on `access:*` implies all actions (superuser)

Creating grants: ```bash swamp access grant create --subject user:sarah --allow run --on 'model:' --server wss://... swamp access policy create --subject user:sarah --allow run --on 'model:' --server wss://... # alias ```

CEL conditions: ```bash swamp access grant create --subject user:sarah --allow run --on 'workflow:@acme/*' \ --when 'tags.env == "staging"' --server wss://... ```

Deny grants: ```bash swamp access grant create --subject user:adam --deny read --on 'data:@acme/secrets-*' --server wss://... ```

Applying changes (manual reload): ```bash swamp access reload --server wss://... ``` Grants are staged until reload. This is the safety mechanism — bad policy doesn't take effect until deliberately applied. Configurable with `--grant-reload auto` for teams that want immediate effect.

Listing and revoking: ```bash swamp access grant list --server wss://... swamp access grant revoke --server wss://... ```

Checking access (admin): ```bash swamp access check --subject user:sarah --action run --on 'model:hello' --server wss://... ```

7. User self-service: can-i

Users check their own permissions without asking the admin: ```bash

What can I do?

swamp access can-i --server wss://...

Can I do this specific thing?

swamp access can-i --action run --on 'workflow:@acme/deploy' --server wss://... ```

8. Admin materialization

The `--admins` flag materializes admin grants at startup from config. Reconciled on every boot — config is the source of truth. Add an admin: edit config, restart. Remove an admin: edit config, restart. Recovery path when locked out.

9. Remote operations

Everything works with `--server`: ```bash swamp model method run hello execute --input 'run=echo hi' --server wss://... swamp data get hello result --version 1 --server wss://... swamp data query 'modelType == "command/shell"' --server wss://... swamp model search --server wss://... swamp vault get default --server wss://... swamp audit --server wss://... swamp summary --server wss://... ```

10. Groups

Local groups for organizing users: ```bash swamp access group create release-managers --server wss://... swamp access group add-member release-managers user:sarah --server wss://... swamp access grant create --subject group:release-managers --allow run --on 'workflow:*' --server wss://... ```

11. Scenarios walkthrough

Real examples using the 3-team scenario from the design phase:

• Team isolation (platform-eng, development, marketing)
• Environment separation (staging vs production via CEL conditions)
• Deny overrides (compliance lockdown)
• Individual user overrides (temporary access)
• Self-service scoping (users can only delete data they created)
• Admin delegation
• User offboarding (revoke token, revoke grants)

12. Reference

• All `swamp access` commands with flags and examples
• All `swamp access token` commands
• Auth config flags (`--auth-mode`, `--admins`, etc.)
• Serve flags (`--host`, `--port`, `--cert-file`, `--key-file`, `--grant-reload`)
• Environment variables (`SWAMP_SERVE_URL`, `SWAMP_SERVE_CERT_FILE`, `SWAMP_SERVE_KEY_FILE`, `SWAMP_SERVER_TOKEN`)
• Credential storage (`~/.config/swamp/servers.json`)
• Grant source types (`method`, `config`, `file`, `extension:*`)

Scope

This is a user-facing guide, not a design document. Write it for an infra person or team lead who needs to set up and manage swamp serve. Assume they know what TLS and OAuth are but have never used swamp before.