Parent

Sub-issue of #662 (serve authentication & authorization). Phase 1 remaining.

Problem

Only run and access commands support `--server` today. A user operating a remote server can run models and manage grants, but can't retrieve output, explore data, check secrets, run reports, or discover what's available. They'd need SSH, which defeats the purpose.

Principle: if you're an operator or user of a remote server, you shouldn't need SSH for anything except starting the server and minting tokens.

What to build

Add `--server` and `--token` support to every read/query/operations command. One commit per command, verified against a running swamp serve instance before moving to the next.

Commands in implementation order

Each command is one commit. Verify each works against the live server before starting the next.

Priority 1 — Data access (most urgent):

1. `swamp data get` — retrieve model output. This is the critical gap: remote run tells you "swamp data get hello result --version 2" but you can't run it remotely.
2. `swamp data query` — search data with CEL predicates
3. `swamp data list` — list data for a model

Priority 2 — Discovery: 4. `swamp model list` / `swamp model search` — what models exist on the server 5. `swamp model method describe` — what methods and inputs a model has 6. `swamp workflow list` — what workflows exist 7. `swamp workflow describe` — workflow structure

Priority 3 — Operations: 8. `swamp vault get` — read secrets remotely 9. `swamp vault put` — write secrets remotely 10. `swamp audit` — audit the repo state 11. `swamp summary` — summarise the repo 12. `swamp report` — run reports

Already working (no changes needed)

• ✅ `swamp model method run`
• ✅ `swamp workflow run`
• ✅ `swamp access grant create/list/revoke`
• ✅ `swamp access group create/add-member/remove-member/list/members`
• ✅ `swamp access check/reload/can-i`
• ✅ `swamp access policy` (alias)
• ✅ `swamp access token list/revoke/rotate`

Local-only (no --server, by design)

• `swamp serve` — starts the server itself
• `swamp repo init` — initialises a local repo
• `swamp model create` — creates local model definitions
• `swamp access token mint` — requires local vault access
• `swamp auth login` — `--server` here means swamp-club registry URL, different semantics
• `swamp worker connect` — `--token` here means enrollment token, different semantics

Implementation pattern

Keep `--server` and `--token` as per-command options, NOT global. `auth login --server` means swamp-club registry URL (env: `SWAMP_CLUB_URL`), `worker connect --token` means enrollment token. Global options would create semantic collisions.

Create a shared helper to reduce boilerplate. Every remote-capable command has the same setup: define `--server` option with `SWAMP_SERVE_URL` fallback, define `--token` option, resolve the token via `resolveServerToken()`. Extract into a reusable `withRemoteOptions(command)` wrapper or `resolveRemoteOptions(options)` helper. Look at `model_method_run.ts` and `workflow_run.ts` for the current pattern — factor out the common parts.

Each command follows the same five steps:

1. Add `--server` and `--token` options (via shared helper)
2. In the action handler, check `options.server` early — if present, resolve token, call remote path, return
3. Add protocol frame type in `src/serve/protocol.ts` (request + response)
4. Add server-side handler in `src/serve/connection.ts` — Zod schema, dispatcher wiring, handler with `authorizeOrReject`
5. Client calls `requestServerResponse()` and renders through the same renderer the local path uses

Don't change the renderers. Local and remote must produce identical output.

Authorization on all remote paths:

• `data get/query/list` → `read` on `data:`
• `model list/search` → `read` on `model:*`
• `model method describe` → `read` on `model:`
• `workflow list` → `read` on `workflow:*`
• `workflow describe` → `read` on `workflow:`
• `vault get` → `read` on `data:vault`
• `vault put` → `write` on `data:vault`
• `audit/summary/report` → `read` on `model:*`
• Admin fallback (`admin` on `access:*`) already handles admins

Binary content for `data get`. Data can be JSON resources or binary files (logs). The protocol response needs a `kind` field (`resource` or `file`). For resources, include parsed JSON. For files, base64-encode the content. Check how `src/serve/data_plane.ts` serves binary content to workers.

Delivery

One PR with one commit per command. Each commit is independently verifiable against the live server. Do NOT batch all commands into one commit — each should be tested and confirmed working before moving to the next.

The running swamp serve instance at `demo.swamp-club.ai` is available for verification. After each commit: ```bash

Recompile

deno run compile

Upload to server and restart

scp swamp root@demo.swamp-club.ai:/usr/local/bin/swamp

ssh root@demo.swamp-club.ai systemctl restart swamp-serve

Test from laptop

SWAMP_SERVE_URL=wss://demo.swamp-club.ai swamp data get hello result --version 2 ```

References

• Existing `--server` pattern: `src/cli/commands/model_method_run.ts` (lines 168-174 for option, early exit to remote path)
• Token resolution: `src/cli/remote_run.ts` (`resolveServerToken`, `resolveServeUrl`, `requestServerResponse`)
• Serve protocol: `src/serve/protocol.ts`
• Connection handler + authorization: `src/serve/connection.ts` (`authorizeOrReject`)
• Data plane binary handling: `src/serve/data_plane.ts`
• Renderers: `src/presentation/renderers/` and `src/presentation/output/`