REPOSITORY CONFIGURATION

The .swamp.yaml file is the repository-level configuration for swamp. It lives at the root of the repository and is created by swamp repo init. It is tracked in version control.

swampVersion: 20260430.202457.0
initializedAt: "2026-04-30T20:45:49.030Z"
repoId: 94735c06-fc0a-4d77-b712-04fbd801b18d
tools:
  - claude
gitignoreManaged: true

Repository Resolution

Swamp resolves the repository root — the directory containing .swamp.yaml — using the following priority chain:

When neither --repo-dir nor SWAMP_REPO_DIR is set, the CLI checks the current working directory for .swamp.yaml. If not found, it walks up the directory tree one level at a time. The search stops at the first directory containing .swamp.yaml.

Traversal boundaries

The upward walk is bounded by whichever limit is reached first:

If no .swamp.yaml is found within the boundary, the command fails with a not a swamp repository error.

swamp repo init

swamp repo init is unaffected by traversal. It always creates .swamp.yaml at the path argument (or the current working directory when no path is given), even if a parent directory already contains a .swamp.yaml.

Top-Level Fields

swampVersion

Version of Swamp that created or last upgraded this repository.

Updated to the new CLI version on swamp repo upgrade.

initializedAt

Timestamp when the repository was first initialized.

Never changes after initial creation. Preserved across upgrades.

upgradedAt

Timestamp of the most recent upgrade.

Only present after swamp repo upgrade has been run at least once.

repoId

Unique identifier for the repository.

Used for telemetry identification and extension installation tracking. If missing from an older .swamp.yaml, auto-generated on the next CLI invocation and persisted.

tools

AI coding tools to configure skills and instructions for.

Each entry must be a built-in tool name, none, or the name of a custom tool defined in .swamp-custom-tools.yaml (see Custom Tools). The first entry is the primary tool — operations that target a single tool (audit recording, extension skills resolution, doctor checks) use it. Order is preserved on upgrade; appending a tool keeps the existing primary stable.

Controls which tool-specific files are created and maintained. Built-in tools have fixed scaffolding paths:

Custom tools use paths configured during swamp agent setup. They receive an instructions file and a skills directory but no tool-specific settings files.

When tools contains multiple entries, each tool's scaffolding is written independently and lives alongside the others.

A tools value of [none] (or an empty list, written as tools: []) skips skill copying, instructions file creation, and tool-specific .gitignore entries.

Removing a tool from tools is non-destructive: the on-disk scaffolding (.claude/, .kiro/, etc.) remains in place for the user to delete by hand.

tool (legacy)

Single-tool field from earlier swamp versions.

A marker that contains tool: <name> is auto-promoted to tools: [<name>] on the next marker write (typically swamp repo upgrade). The legacy tool: line is removed from the YAML once promotion completes. Existing repositories need no manual migration.

gitignoreManaged

Whether Swamp manages a section in the .gitignore file.

When true, Swamp writes and maintains a # BEGIN swamp managed section block in .gitignore. The managed section includes .swamp/, .swamp-sources.yaml, and tool-specific paths for every entry in tools (e.g., .claude/ when tools contains claude).

Always set to true on swamp repo init. On swamp repo upgrade, the existing value is preserved unless --include-gitignore is passed.

logLevel

Minimum log level for CLI output.

telemetryDisabled

Disables telemetry collection for this repository.

When true, no telemetry data is collected or sent for commands run in this repository.

Telemetry opt-out is resolved in two layers. The first two always apply; the third depends on whether a repository is present:

Layers 3a and 3b are mutually exclusive. When running inside a Swamp repository, .swamp.yaml controls opt-out. When running outside a repository (no .swamp.yaml found), the user-global telemetry configuration controls opt-out instead. See User-Global Telemetry Configuration for the file schema and path resolution.

telemetryEndpoint

HTTP endpoint for telemetry data.

When the auth server is localhost, defaults to http://localhost:3000.

telemetryKeepFlushed

Retain telemetry entries after they are sent to the remote endpoint.

When false (or not set), telemetry entry files in the user-global spool are deleted after a successful flush. When true, they are renamed to .flushed.json instead of deleted. This setting is only read from .swamp.yaml — there is no user-global equivalent. For repo-less runs, keepFlushed defaults to false.

User-Global Telemetry Configuration

Telemetry data is stored in a single, user-level spool directory — not inside each repository. This allows swamp telemetry stats to report across all repositories and to work outside a repository entirely.

Configuration file

~/.config/swamp/telemetry.yaml controls telemetry for repo-less runs (commands run outside any Swamp repository). The file has a single field:

disabled: true

When disabled is true, telemetry is not collected for commands run outside a repository. This file is only consulted when no .swamp.yaml is found — inside a repository, the telemetryDisabled field in .swamp.yaml controls opt-out instead. If the file is missing, malformed, or disabled is not a boolean, telemetry defaults to enabled.

Spool directory

Telemetry entries are written to a user-global spool directory:

~/.config/swamp/telemetry/

The spool path follows the same XDG-aware resolution as the Swamp config directory:

Both swamp telemetry stats and the flush process read from and write to this single spool directory.

autoGc

Enable automatic garbage collection after each model method run.

When true, garbage collection is enabled in two ways:

• Incremental write-time pruning — each save() call enforces the garbageCollection policy immediately, capping stored versions at the declared limit as data is written.
• Batch GC after model method runs — a full garbage collection pass runs after the method's completed event, so the user sees the method result before GC begins.

When false (the default), versions accumulate without limit and are only removed by explicit swamp data gc runs.

Errors during automatic GC are logged at warn level and never fail the method run.

defaultVault

Default vault name for sensitive field storage.

When set, Swamp uses this vault as the fallback for storing sensitive resource output fields during model execution, OAuth token storage in swamp serve, and device authorization token storage. Field-level and spec-level vaultName overrides take precedence over defaultVault. When not set, Swamp falls back to the first available vault.

See the vault resolution order for the full precedence chain.

defaultVault: prod-secrets

Ephemeral Data Budget

The SWAMP_EPHEMERAL_BUDGET environment variable controls the maximum memory allocated to ephemeral data storage.

Ephemeral data lives in memory only and is never written to disk. This budget caps the total in-memory footprint. Writes that would exceed the budget fail with an error. The budget applies per process — each swamp invocation has its own ephemeral store. See the data reference for how the ephemeral lifetime behaves.

Directory Overrides

Six fields override the default locations for extension source directories. All paths are relative to the repository root.

Each field follows the same resolution priority: environment variable > .swamp.yaml value > default.

These directories hold extension source files loaded by Swamp at runtime. They are separate from the top-level models/, workflows/, and vaults/ directories that hold user-authored definitions.

modelsDir: custom/models
workflowsDir: custom/workflows

Extensions Directory

By default, Swamp discovers local extension sources from extensions/<kind>/ relative to the repository root (--repo-dir / SWAMP_REPO_DIR). The --extensions-dir flag or SWAMP_EXTENSIONS_DIR environment variable overrides the root directory used for local extension source scanning.

When set, --extensions-dir changes where Swamp looks for local extension sources (all content types: models, vaults, datastores, reports). All data stays at the repository root:

This is useful for git worktree workflows where the working tree (code) is separate from the .swamp/ data directory:

# Point at the main repo for data, worktree for extension sources
export SWAMP_REPO_DIR=~/repo
export SWAMP_EXTENSIONS_DIR=~/repo/worktrees/feature-branch
swamp model type search my-model

Validation

The CLI rejects --extensions-dir values that:

• Point inside the .swamp/ data directory
• Do not exist on the filesystem
• Are not a directory (e.g. a file)

Trust Configuration

Two fields control which collectives are trusted for extension auto-resolution.

trustedCollectives

Explicitly trusted collective names.

Each name must match [a-z0-9][a-z0-9_-]*.

Managed with swamp extension trust add <collective> and swamp extension trust rm <collective>.

trustedCollectives:
  - swamp
  - my-collective

trustMemberCollectives

Whether to include the authenticated user's membership collectives in the trust list.

When true, the user's membership collectives from their auth credentials are merged with trustedCollectives. When false (or not set), only the explicit list is used.

Managed with swamp extension trust auto-trust enable and swamp extension trust auto-trust disable.

$ swamp extension trust list --json

{
  "explicit": [
    "swamp"
  ],
  "membership": [],
  "resolved": [
    "swamp"
  ],
  "trustMemberCollectives": false
}

Datastore Configuration

The datastore field configures where Swamp stores runtime data. When not set, Swamp uses the local filesystem at .swamp/ within the repository.

datastore:
  type: filesystem
  path: /data/swamp-store

datastore.type

Datastore backend type.

datastore.path

Absolute path for the filesystem datastore.

datastore.bucket

S3 bucket name.

datastore.prefix

Key prefix within the S3 bucket.

datastore.region

AWS region.

datastore.endpoint

Custom S3-compatible endpoint URL.

datastore.forcePathStyle

Force path-style S3 URLs instead of virtual-hosted-style.

datastore.config

Arbitrary configuration for extension-provided datastores.

datastore.namespace

Namespace identifier for this repository within a shared datastore. When set, data is scoped under .swamp/<namespace>/ instead of .swamp/ directly.

Set via swamp datastore namespace set <slug>. See Namespace Commands.

datastore.directories

Which .swamp/ subdirectories use this datastore. When not set, all default directories are included.

Default directories:

definitions-evaluated    workflows-evaluated    data
outputs                  workflow-runs          secrets
bundles                  vault-bundles          report-bundles
audit                    telemetry
logs                     files

datastore.exclude

Gitignore-style patterns for files to exclude from datastore operations.

$ swamp datastore status --json

{
  "type": "filesystem",
  "path": "/home/user/my-repo/.swamp",
  "healthy": true,
  "message": "Filesystem datastore at /home/user/my-repo/.swamp is healthy",
  "latencyMs": 0.43,
  "directories": [
    "definitions-evaluated",
    "workflows-evaluated",
    "data",
    "outputs",
    "workflow-runs",
    "secrets",
    "bundles",
    "vault-bundles",
    "report-bundles",
    "audit",
    "telemetry",
    "logs",
    "files"
  ]
}

Created Directory Structure

swamp repo init creates the following directories:

my-repo/
  .swamp.yaml
  .gitignore
  models/                          # User model definitions
  workflows/                       # User workflow definitions
  vaults/                          # User vault configurations
  .swamp/
    audit/
    data/
    definitions-evaluated/
    outputs/
    secrets/
    vault-bundles/
    workflow-runs/
    workflows-evaluated/

When tools is non-empty (and not [none]), tool-specific files are created for each entry — for example, CLAUDE.md and .claude/ for the claude tool, .kiro/steering/swamp-rules.md and .kiro/ for the kiro tool. With multiple tools, every tool's scaffolding is written.

Initialization

$ swamp repo init [path] [options]

--tool none (alone) skips tool scaffolding. Combining --tool none with any other --tool value is rejected:

$ swamp repo init --tool none --tool claude --json

{
  "error": "Cannot combine --tool none with other --tool values. Use --tool none alone to clear the enrolled tool list."
}

Creates .swamp.yaml with swampVersion, initializedAt, repoId, tools, and gitignoreManaged set. Creates the directory structure, copies tool skills for every entry in tools, and generates each tool's instructions file.

$ swamp repo init --json

{
  "path": "/home/user/my-repo",
  "version": "20260605.190813.0",
  "initializedAt": "2026-06-05T19:46:35.748Z",
  "skillsCopied": [
    "swamp",
    "swamp-getting-started"
  ],
  "instructionsFileCreated": true,
  "settingsCreated": true,
  "gitignoreAction": "created",
  "tools": [
    "claude",
    "kiro"
  ],
  "removedTools": [],
  "tool": null
}

The legacy tool field in the output mirrors tools[0] when there is exactly one entry, is null when there are multiple, and is "none" when the list is empty.

Upgrade

$ swamp repo upgrade [path] [options]

--tool on upgrade has replace semantics: the value passed is the full new list. To add kiro to a [claude] repo, run swamp repo upgrade --tool claude --tool kiro — passing only --tool kiro would replace the list with [kiro]. Plain swamp repo upgrade (no --tool flag) preserves the existing list and just bumps the Swamp version.

Updates swampVersion and sets upgradedAt. All other fields are preserved unless explicitly overridden by CLI flags.

$ swamp repo upgrade --json

{
  "path": "/home/user/my-repo",
  "previousVersion": "20260605.190813.0",
  "newVersion": "20260605.190813.0",
  "upgradedAt": "2026-06-05T19:46:42.349Z",
  "skillsUpdated": [
    "swamp",
    "swamp-getting-started"
  ],
  "instructionsUpdated": false,
  "settingsUpdated": false,
  "gitignoreAction": "updated",
  "previousTools": [
    "claude",
    "kiro"
  ],
  "tools": [
    "kiro"
  ],
  "addedTools": [],
  "removedTools": [
    "claude"
  ],
  "extensionsToReinstall": [],
  "tool": "kiro",
  "extensionInstall": {
    "entries": [],
    "installed": 0,
    "migrated": 0,
    "upToDate": 0,
    "failed": 0
  }
}

previousTools and tools show the before/after enrolled lists. addedTools and removedTools are the diff — removedTools lists tools whose scaffolding remains on disk after the upgrade.

Telemetry spool migration

swamp repo upgrade migrates unflushed telemetry entries from the legacy repo-local spool (.swamp/telemetry/) to the user-global spool. The migration:

• Moves telemetry-*.json files to the global spool directory.
• Skips repositories that have telemetryDisabled: true — a disabled repository's leftover entries are never moved, so they cannot be sent despite the opt-out.
• Leaves already-flushed entries (.flushed.json files) in the old directory.
• Leaves the old .swamp/telemetry/ directory in place (orphaned, not deleted).
• Is best-effort — a migration failure never blocks the upgrade.

Update

$ swamp update [options]

Update Swamp to the latest version.

Shell Completions

$ swamp completions <shell>

Generate shell completions. Subcommands: bash, fish, zsh. Each accepts a -n / --name flag.

Installation:

• bash — add to ~/.bashrc:

  source <(swamp completions bash)

• fish — add to ~/.config/fish/config.fish:

  source (swamp completions fish | psub)

• zsh — add to ~/.zshrc:

  source <(swamp completions zsh)

Configuration

swamp config get <key>

Get a configuration value.

swamp config set <key> <value>

Set a configuration value.

swamp config list

List all configuration keys and current values. No arguments.

Complete Example

A .swamp.yaml with all optional fields configured:

swampVersion: 20260430.202457.0
initializedAt: "2026-04-30T20:45:49.030Z"
upgradedAt: "2026-04-30T20:45:49.312Z"
repoId: 94735c06-fc0a-4d77-b712-04fbd801b18d
tools:
  - claude
  - kiro
gitignoreManaged: true
logLevel: debug
telemetryDisabled: false
telemetryEndpoint: https://api.swamp-club.com
modelsDir: custom/models
workflowsDir: custom/workflows
vaultsDir: custom/vaults
datastoresDir: custom/datastores
reportsDir: custom/reports
trustedCollectives: # illustrative; default is ["swamp"]
  - swamp
  - si
  - my-collective
trustMemberCollectives: true # illustrative; default is false
datastore:
  type: filesystem
  path: /data/swamp-store