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: 20260407.173244.0
initializedAt: "2026-04-07T19:46:52.083Z"
repoId: 0aa50cbf-d8dd-42c4-9262-2a337b671c95
tool: 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.

tool

AI coding tool to configure skills and instructions for.

Controls which tool-specific files are created and maintained:

Setting tool to none skips skill copying, instructions file creation, and tool-specific .gitignore entries.

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 (e.g., .claude/ when tool is 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
}

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 tool is not none, tool-specific files are also created (e.g., CLAUDE.md and .claude/ for the claude tool).

Initialization

$ swamp repo init [path] [options]

Creates .swamp.yaml with swampVersion, initializedAt, repoId, tool, and gitignoreManaged set. Creates the directory structure, copies tool skills, and generates the instructions file.

$ swamp repo init --json

{
  "path": "/home/user/my-repo",
  "version": "20260407.173244.0",
  "initializedAt": "2026-04-07T19:47:38.422Z",
  "skillsCopied": [
    "swamp-data",
    "swamp-data-query",
    "swamp-model",
    "swamp-repo",
    "swamp-report",
    "swamp-workflow",
    "swamp-extension-model",
    "swamp-vault",
    "swamp-extension-vault",
    "swamp-extension-datastore",
    "swamp-extension-driver",
    "swamp-issue",
    "swamp-troubleshooting"
  ],
  "instructionsFileCreated": true,
  "settingsCreated": true,
  "gitignoreAction": "created",
  "tool": "claude"
}

Upgrade

$ swamp repo upgrade [path] [options]

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": "20260407.173244.0",
  "newVersion": "20260407.173244.0",
  "upgradedAt": "2026-04-07T19:47:42.032Z",
  "skillsUpdated": [
    "swamp-data",
    "swamp-data-query",
    "swamp-model",
    "swamp-repo",
    "swamp-report",
    "swamp-workflow",
    "swamp-extension-model",
    "swamp-vault",
    "swamp-extension-vault",
    "swamp-extension-datastore",
    "swamp-extension-driver",
    "swamp-issue",
    "swamp-troubleshooting"
  ],
  "instructionsUpdated": false,
  "settingsUpdated": false,
  "gitignoreAction": "unchanged",
  "tool": "claude"
}

Complete Example

A .swamp.yaml with all optional fields configured:

swampVersion: 20260407.173244.0
initializedAt: "2026-04-07T19:46:52.083Z"
upgradedAt: "2026-04-07T19:47:06.865Z"
repoId: 0aa50cbf-d8dd-42c4-9262-2a337b671c95
tool: claude
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
datastore:
  type: filesystem
  path: /data/swamp-store