swamp serve currently accepts a single --grants-file path for external grants. In Kubernetes deployments, teams often want to manage grants as separate files — one per team, environment, or concern — mounted from individual ConfigMaps into a shared directory. Today this requires concatenating all grants into a single file.

Proposed Solution

Add --grants-dir <path> (env: SWAMP_GRANTS_DIR) that loads all .yaml/.yml files from the given directory as grant sources.

How `--grants-file` and `--grants-dir` work together

Both may be specified — they are additive. Grants from --grants-file and all files in --grants-dir are merged into the same validEntries map that already supports multiple file sources (keyed by filename).
Neither is required — the server starts with only repo-level grant definitions if neither is passed.
Duplicates across files — a grant with the same subject/action/resource appearing in multiple files is not an error. Each file is reconciled independently (same as today's repo-level grant files vs the external file). If two files grant the same permission, both produce a grant-config model instance; revocation of one file's grants does not affect the other's.
Validation — each file in the directory is parsed and validated independently. A validation error in any file is fatal at startup (same as --grants-file today), with the error message identifying the specific file and entry.
Empty/missing directory — an empty directory is not an error (0 grants loaded). A missing directory path is a fatal startup error.
Non-YAML files ignored — files not ending in .yaml or .yml are silently skipped. This avoids issues with ConfigMap-mounted ..data symlinks and other Kubernetes projected volume artifacts.
Not recursive — only top-level files in the directory are loaded. Subdirectories are ignored.

Interaction with `--grant-reload auto`

When --grant-reload auto is set, changes to files in the grants directory should trigger a policy snapshot reload, the same way changes to repo-level grant definitions do today.

Example

# Kubernetes: mount multiple ConfigMaps into one directory
volumes:
  - name: grants
    projected:
      sources:
        - configMap:
            name: grants-engineering
        - configMap:
            name: grants-data-science
        - configMap:
            name: grants-platform

containers:
  - name: swamp
    command:
      - swamp
      - serve
      - --grants-dir
      - /etc/swamp/grants/
      - --grant-reload
      - auto
    volumeMounts:
      - name: grants
        mountPath: /etc/swamp/grants
        readOnly: true

Alternatives

Glob pattern (--grants-file '/etc/swamp/grants/*.yaml') — more flexible but harder to validate, and shell globbing behavior varies
Repeatable --grants-file — allows multiple files but requires listing each one explicitly, which doesn't work well with dynamic ConfigMap mounts

02Bog Flow

Open

8/11/2026, 8:00:35 PM

No activity in this phase yet.

03Sludge Pulse

Cluster health snapshots with SSE streaming for swamp serve

Add swamp access group list-idp to enumerate IdP groups seen by the server

Docs: add swamp access group list-idp to access commands reference

Grants directory loader skips symlinks — breaks Kubernetes ConfigMap mounts

--grant-reload auto does not detect filesystem changes — blind to ConfigMap updates

Daemon telemetry flush: stop() can skip its final flush when a timer drain is already in flight

Support --grants-dir for loading grants from a directory

Docs: `swamp compile` subcommand doesn't exist

Guard the projector's full rewrites against the fail-open lease (ADV-6 from #1575/#1576)

Projector write amplification: board_totals/owner_devices full rewrites are owners × runs/day

Profile candidateIds prune costs a full ledger scan to build itself — 42.88M rows for one keyed read

Leaderboard phase 3: owner-grain board_totals so a cache miss is survivable at 10B

serve telemetry identity warnings are diagnostic but not actionable — say how to fix them

swamp serve is telemetry-dark: scheduled workflow runs never reach /ingest, and the daemon never flushes

CLI has never sent insert_id: retried telemetry batches are double-counted into cli_daily, inflating XP in an append-only ledger

Catalog backfill reconciles against the local cache, not the datastore

Extension bundle cache not invalidated when an imported sibling module changes (entry-file fingerprint only)

swamp serve: data.query fails permanently with "UNIQUE constraint failed: catalog.*" — one duplicate catalog 5-tuple aborts every catalog rebuild

dailyHistory range pushdown — deferred from #1576, and the measurement says why

score-rollup projector runs N× per cadence — the run gate is per-replica memory, not shared state

Docs: manual never mentions telemetry, and the serve/scheduling pages imply automated runs are visible when they are not

Explore: CLI binary update integrity lacks independent verification

Leaderboard phase 2: take score_grants off the board read path — read today from score_daily

Explore: reconcile quality rubric's dormant provenance factor

Explore: pull-time signature verification for extensions

Explore: transparency-log integration (Rekor) for extension signatures

Explore: publish-time artifact signing for extensions (cosign keyless)

Profile day drill-down returns 0 entries at the 5s ClickHouse ceiling for every operative

A ledger read failure still renders as 'no activity': loadProfileScore swallows to an empty standing behind HTTP 200

swamp quest: drop the heartbeat field the server no longer sends

reconcile_from_disk_bench.ts fails deno check (stale DenoRuntime stub)

Improve multi-word search query handling and guidance

Retire the genesis_public flag and delete the dead cutover transcription scaffolding

Leaderboard phase 1: cache the board read and bust it on tier crossings (no schema change)

Catalog backfill deletes rows for any model whose data names are numeric

migrate-index silently drops entries with shallow paths — all of workflows-evaluated/ and any root-level file

Docs: document catalog completeness check and --repair in doctor reference

Leaderboard board windows re-anchor on wall-clock while the rest of the view is frozen at asOf

Decision: move per-event grant MVs to day-grain — ledger is on track for ~1.5B score_grants / ~4B quest_grants

Leaderboard phase 5: score-rollup-projector write cost at 10B — ~430M rows scanned per 60s tick

Epic: /leaderboard and /u/{username} do not survive 10B events — measured audit + phased plan

Add native Bedrock Knowledge Base Retrieve support

Datastore-managed configuration for multi-instance serve deployments

Ghosts on the leaderboard 500

swamp command doesn't check cwd

swamp auth login process fails when run remotely

serve boot OOM: findAllGlobalSince loads all workflow runs as full aggregates during reconciliation

extension search: channel-filtered results carry null version fields, and multiple --channel values collapse instead of unioning

s3-datastore: localHasAllRemoteEntries uses bare rel instead of localRelPath, always returns false in namespaced mode

datastoreSetupExtension migrates .swamp/ to cache root instead of namespace directory

swamp serve writes outputs/ outside the bound namespace — silently never persisted to the remote datastore

s3-datastore: bulk pull writes to cache root instead of the namespace, wedging push and arming a full-datastore delete

git: add pull, fetch --tags, and cherry-pick methods

Workflow runs with wide dataArtifact fan-out (~400/run) OOM both workflow history get and swamp serve boot, crash-looping the scheduler; rollback doesn't help (state-triggered, not release-triggered)

Show user:<name> instead of user:<id> in grant list output

Reusable long-lived invite link: one URL to bring people into the swamp

Exclude swamp internal model types from model list output

Skill docs use invalid two-argument 'vault get' form

access token mint prints an invalid retrieval command (vault get, not vault read-secret)

serve reload and model edit timeout over --server in Kubernetes

swamp auth whoami should report paid tier and trial status

Use whoami entitlement to explain private-extension push refusals

Document --restricted-commands flag for swamp serve

vault put: pass tags through to extension provider CreateSecret/setSecret calls

Docs: update manual for 23 new --server commands

Update VaultProvider interface in @systeminit/swamp-testing to support optional tags in put()

Docs: document --grants-file flag for swamp serve

Docs: document --server support for serve reload

Docs: add --tag flag to vault put reference

Docs: update manual for --detach-runs deprecation and HA auto-detection

Document the Codex plugin in swamp docs

Add --server support to CLI commands missing it

Document the swamp Claude Code plugin in the swamp documentation

Make --server a global CLI option

Add --server support to model cancel (server-side run cancellation)

Load grants from external source on swamp serve startup

swamp vault put should support tags for secret governance

Improve hot reload of the deamon, include extension source/bundle changes

Authenticated users must re-login after swamp serve restart

Add --server support to serve reload