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

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 one of the listed values. 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:

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.

When true, no telemetry data is sent.

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 are deleted after a successful flush. When true, they are renamed to .flushed.json instead of deleted.

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

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
  - si
  - my-collective

trustMemberCollectives

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

When true (or not set), the user's membership collectives from their auth credentials are merged with trustedCollectives. When false, 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",
    "si"
  ],
  "membership": [
    "adam"
  ],
  "resolved": [
    "swamp",
    "si",
    "adam"
  ],
  "trustMemberCollectives": true
}

Execution Driver

Two fields configure the repository-level default execution driver. Both apply only when no higher-precedence layer (CLI flag, step, job, workflow, or definition) selects a driver.

defaultDriver

Repository-level default execution driver name.

Resolution priority for a method or workflow run, highest precedence first:

1. --driver CLI flag (e.g., swamp model method run --driver docker)
2. Step-level driver field
3. Job-level driver field
4. Workflow-level driver field
5. Definition-level driver field
6. defaultDriver from .swamp.yaml
7. Built-in raw driver

defaultDriverConfig

Driver-specific configuration paired with defaultDriver.

The configuration object is used as-is. Driver configurations are not merged across precedence levels — when a higher-precedence layer specifies a driver, its configuration replaces this one entirely.

defaultDriver: docker
defaultDriverConfig:
  image: alpine:latest

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.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          driver-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",
    "driver-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/
    telemetry/
    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": "20260430.202457.0",
  "initializedAt": "2026-04-30T20:45:49.030Z",
  "skillsCopied": [
    "swamp-data",
    "swamp-data-query",
    "swamp-model",
    "swamp-repo",
    "swamp-report",
    "swamp-workflow",
    "swamp-extension-model",
    "swamp-extension-publish",
    "swamp-vault",
    "swamp-extension-vault",
    "swamp-extension-datastore",
    "swamp-extension-driver",
    "swamp-issue",
    "swamp-troubleshooting",
    "swamp-getting-started",
    "swamp-extension-quality"
  ],
  "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": "20260430.202457.0",
  "newVersion": "20260430.202457.0",
  "upgradedAt": "2026-04-30T20:45:49.925Z",
  "skillsUpdated": [
    "swamp-data",
    "swamp-data-query",
    "swamp-model",
    "swamp-repo",
    "swamp-report",
    "swamp-workflow",
    "swamp-extension-model",
    "swamp-extension-publish",
    "swamp-vault",
    "swamp-extension-vault",
    "swamp-extension-datastore",
    "swamp-extension-driver",
    "swamp-issue",
    "swamp-troubleshooting",
    "swamp-getting-started",
    "swamp-extension-quality"
  ],
  "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.

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
modelsDir: custom/models
workflowsDir: custom/workflows
vaultsDir: custom/vaults
driversDir: custom/drivers
datastoresDir: custom/datastores
reportsDir: custom/reports
trustedCollectives:
  - swamp
  - si
  - my-collective
trustMemberCollectives: true
defaultDriver: docker
defaultDriverConfig:
  image: alpine:latest
datastore:
  type: filesystem
  path: /data/swamp-store