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. Bundled skills install in your home directory and swamp update refreshes them; the repository's skills directory holds the skills of pulled extensions.

The opencode audit plugin requires OpenCode 1.3.4 or later, or OpenCode 2. On OpenCode 1.0 to 1.2.10 it crashes OpenCode runs, and on 1.2.11 to 1.3.3 it records commands but OpenCode reports a plugin load error. OpenCode installs only patch releases automatically, so update an older OpenCode 1 build before running swamp repo upgrade.

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 usage telemetry for this repository.

When true, nothing is recorded or sent for commands run in this repository, by anyone. It is one of several opt-outs, and any one of them disables telemetry: false does not re-enable telemetry that another opt-out disables. See Usage Telemetry.

telemetryEndpoint

HTTP endpoint for telemetry data.

When the auth server is localhost, 127.0.0.1, or [::1], defaults to http://localhost:8080. See Endpoint.

Events recorded in this repository are sent only to this endpoint. See Delivery.

telemetryKeepFlushed

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

When false (or not set), telemetry entry files in the 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.

autoGc

Enable automatic garbage collection after each behavior 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 behavior 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.

garbageCollection

How long each kind of history is kept, and whether Swamp removes it on its own. This is separate from the per-output garbageCollection policy on a data spec, which controls how many versions of a single output to keep, and from autoGc, which applies that per-output policy after method runs.

garbageCollection:
  retention: 30d
  automatic: true
  workflowRuns: 14d
  evaluatedSnapshots: 3d
  outputs: 7d
  data: 30d
  audit: 90d
  bookkeeping: 24h

A kind with no key and no retention is never removed by an automatic pass. swamp run gc still uses 30d for runs and outputs when neither is set.

Durations

Every key except automatic takes a duration: m=minutes, h=hours, d=days, w=weeks, mo=months, y=years. m is minutes, so data: 6m keeps six minutes of data. A value above 1000y is held at 1000y.

Precedence

For each kind: --older-than on a manual command, then the kind's own key, then retention. data and bookkeeping never fall back to retention.

An unset evaluatedSnapshots follows the run retention, so a snapshot is removed with its run. An evaluatedSnapshots longer than the run retention is ignored. A shorter one removes a kept run's snapshot early, aged from the later of the snapshot and the run's finish.

garbageCollection.data

data is opt-in: only an explicit data key turns it on, and retention never does. It is a repository-wide maximum age on top of each data spec's own policy, and it ignores lifetime: infinite and version-count caps.

A data name whose latest version is older than the cutoff is deleted, every version of it, the latest included. A behavior that has not run within the window has no data afterwards, and data.latest() finds nothing for it. swamp data gc applies data too.

garbageCollection.audit

Sets the age of .swamp/audit logs. With automatic on, it also sets the retention of each swamp serve audit store target that has no retention.days of its own, rounded up to whole days. Serve reads it at start, so a change needs a restart. Without automatic, audit logs keep their 7 days.

garbageCollection.bookkeeping

With automatic on, sets the grace period swamp serve gives disconnected workers, revoked or expired enrollment tokens, and finished step leases and dispatches before removing them. Serve reads it on every cycle. Without automatic, the grace period is 24 hours.

Automatic passes

With automatic: true, Swamp removes what is past its cutoff without a manual command:

Serve and the CLI each claim the hour separately, and of several serves on one datastore, one runs each hour's pass. Read-only commands never run a pass. A failed pass is logged at debug level and never fails the command.

Without automatic, the keys only set the defaults of swamp run gc and swamp data gc.

Never removed

• Workflow runs that have not finished (running, suspended, waiting, interrupted), their snapshots, and a finished nested run whose parent has not finished.
• Data of the built-in access and serve types: grants, groups, server tokens, enrollment tokens, workers, step leases, pending dispatches and fleet probes. Serve removes its own records under bookkeeping.
• A data name with a write that has not been promoted yet.
• Definitions, vaults and .swamp.yaml.

Validation

.swamp.yaml is refused when garbageCollection is not a mapping, or when workflowRuns or outputs is not a positive duration. Any other bad value is logged as a warning on each command and ignored:

[WRN] swamp·persistence·repo-marker: ".../.swamp.yaml": "garbageCollection.evaluatedSnapshots must be a positive duration like 1h, 7d, or 2w; ignoring it"

Unknown keys are logged and ignored the same way. A command that rewrites .swamp.yaml keeps the garbageCollection block as written.

See Configure Retention to set it up and check it, and Data Lifetimes for how it fits with per-output policies.

defaultVault

Default vault name for sensitive field storage.

swamp repo init sets defaultVault: default, naming the local_encryption vault it creates (see Initialization). A repository initialized with --no-vault, or before the default vault existed, has no defaultVault until you set one; swamp repo upgrade does not add it.

When set, Swamp uses this vault as the fallback for storing sensitive resource output fields during behavior 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, or when it names a vault that is not registered, Swamp falls back to the first user vault ordered by vault type, then by vault id — the first entry of swamp vault list, not the oldest vault. In a repository with more than one vault, set defaultVault explicitly; swamp doctor vaults warns when a behavior relies on the fallback.

See the vault resolution order for the full precedence chain.

To send sensitive outputs to a shared vault instead, create it and point defaultVault at it. The default vault stays in place for per-machine secrets:

swamp vault create @swamp/aws-sm prod-secrets --config '{"region":"us-east-1"}'

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

Five 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.

modelsDir sets the directory Swamp loads behavior sources from. By default Swamp loads them from extensions/behaviors/ and from the compatibility directory described below.

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 (the top-level models/ directory holds behavior definitions).

modelsDir: custom/behaviors
workflowsDir: custom/workflows

Behaviors directory compatibility

The modelsDir key keeps the model name. Its default is extensions/models, and SWAMP_MODELS_DIR sets it as SWAMP_BEHAVIORS_DIR does. When both variables are set, SWAMP_MODELS_DIR wins, and different non-empty values are refused at startup. While modelsDir is the default, Swamp loads behavior sources from extensions/behaviors/ as well as extensions/models/; a configured modelsDir replaces both.

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 names the directory that contains extensions/; Swamp appends extensions/behaviors and the other typed directories to it. It changes where Swamp looks for local extension sources: behaviors, vaults, datastores, and reports, and, for extension push, quality, and fmt, also workflows and skills. All data stays at the repository root:

For extension push, quality, and fmt, a relative manifest argument is tried against --extensions-dir, then the current directory, then the repository root. Without the flag, the extensions root is inferred from the manifest's location when no entry resolves under the repository root. See Publishing Commands § Manifest argument.

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 behavior type search my-behavior

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.managedConfig

Opt-in flag that stores configuration — behavior definitions, workflow definitions, vault configs, the extension lockfile, and pulled extension sources — in the datastore tier instead of top-level directories.

When true, the datastore becomes the single source of truth for configuration across swamp serve instances. Config changes (behavior create, extension pull, vault update) push immediately to the datastore, and other instances pull them via the ConfigPoller.

Set automatically by swamp datastore config migrate. Can also be set manually in .swamp.yaml:

datastore:
  type: "@swamp/s3-datastore"
  managedConfig: true
  config:
    bucket: my-bucket
    region: us-east-1

Requires the datastore extension to support the configRefresh sync capability. See Datastore Configuration — Managed Config and Enable Managed Config for the setup guide.

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 behavior definitions
  workflows/                       # User workflow definitions
  vaults/                          # User vault configurations
    local_encryption/
      <id>.yaml                    # The default vault (omitted with --no-vault)
  .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, defaultVault 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": "20261012.200126.0",
  "initializedAt": "2026-10-12T20:59:28.010Z",
  "skillsCopied": [
    "swamp",
    "swamp-getting-started"
  ],
  "instructionsFileCreated": true,
  "settingsCreated": true,
  "gitignoreAction": "created",
  "tools": [
    "claude",
    "kiro"
  ],
  "removedTools": [],
  "vault": {
    "name": "default",
    "type": "local_encryption",
    "created": true
  },
  "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.

The default vault

Init creates a local_encryption vault named default at vaults/local_encryption/<id>.yaml and sets defaultVault: default in .swamp.yaml. Secrets and sensitive outputs work in a new repository without creating a vault first. The stored config is only:

id: d1228bcb-1957-43f6-911d-569fd14de62a
name: default
type: local_encryption
config:
  auto_generate: true
createdAt: "2026-10-12T20:59:28.011Z"

No key exists until the first secret is written. The key and the encrypted secrets live under .swamp/secrets/local_encryption/default/, which is gitignored, so they never leave the machine. Log mode reports the vault on its own line:

Created vault default (local_encryption) for secrets and sensitive outputs

See Per-machine storage for what a clone of the repository gets.

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-level 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, powershell, 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)

• powershell — add to the file named by $PROFILE, in PowerShell 7:

  swamp completions powershell | Out-String | Invoke-Expression

• zsh — add to ~/.zshrc:

  source <(swamp completions zsh)

Configuration

User-level settings, stored in the Swamp config directory rather than .swamp.yaml.

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
defaultVault: default
logLevel: debug
telemetryDisabled: false
telemetryEndpoint: https://telemetry.swamp-club.com
modelsDir: custom/behaviors
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
garbageCollection:
  outputs: 14d
  workflowRuns: 7d
datastore:
  type: filesystem
  path: /data/swamp-store