MANUAL
Guidance on how to thrive in the Swamp.
Swamp is an adaptive automation framework designed to be operated by AI agents. New here? Pick a path:
Run swamp start after installing: it signs you in, sets up a workspace and hands your first task to an AI agent. Already in a repo of your own? Ask your agent to "get started with Swamp".
Automating a specific service? Browse integrations for AWS, GitHub, Kubernetes, Cloudflare and more.
Your First Automation
Build an endpoint health monitor with typed checks, parallel execution, a summary workflow, and queryable version history — all in about fifteen minutes.
Tutorials →Working with Data
Create two behaviors, wire them with a data.latest() expression, orchestrate them in a workflow, then query and inspect the versioned data in The Swamp.
Tutorials →Storing Secrets
Store an API token in the default encrypted vault, annotate it with metadata, reference it from a behavior using vault.get(), and see it redacted in all output.
Tutorials →Publish Your First Extension
Build a TypeScript behavior extension, smoke-test it, score it against the quality rubric, take it through each publishing gate, and install it in another repo.
Tutorials →Remote Execution
Mint a token, start the orchestrator, connect a worker, and run a placed workflow step end-to-end
Tutorials →Install Swamp
Install the Swamp CLI on macOS, Linux or Windows with the official install script, verify the installation, fix PATH issues if the command is not found, and move Swamp's home directory with SWAMP_HOME when Windows application control blocks it.
How-to Guides →Start a Task with swamp start
Use swamp start to sign in, create or import a workspace, describe a task and hand it to an AI agent, then come back to your tasks and resume the agent.
How-to Guides →Collaborate in the Swamp
Promote a local Swamp repo to a shared datastore, migrate vaults to a cloud backend, and onboard teammates so they can run behaviors and workflows together
How-to Guides →Set Up Extension Trust
Control which collectives can supply extensions in your Swamp repository — list trusted collectives, add or remove entries, and enable membership auto-trust
How-to Guides →Set Up Webhooks
Trigger Swamp workflows from external services — configure GitHub, Linear, Stripe, Jira, and generic webhook endpoints on swamp serve with secret validation
How-to Guides →Set Up Shell Completions
Generate and install tab-completion scripts for Swamp CLI commands in bash, zsh, fish, or PowerShell 7 to autocomplete subcommands, flags, and behavior names
How-to Guides →Set Up OpenTelemetry
Export traces from Swamp behavior and workflow runs — enable console tracing for local debugging, send spans to a collector, and configure vendor headers
How-to Guides →Run Workflows on a Schedule
Add a cron trigger to a Swamp workflow so swamp serve executes it automatically — configure the schedule, validate, and disable scheduling when needed
How-to Guides →Use the Audit Timeline
Review what commands were run in a Swamp repository — filter the audit timeline by time window or session, show all commands, and verify audit hook health
How-to Guides →File Issues from the CLI
Search, view, and file bug reports, feature requests, and security reports on swamp-club from the terminal — post comments, close, reopen, and edit issues
How-to Guides →Inspect Repo Activity
See a summary of recent behavior runs, workflow executions, and data changes in a Swamp repository — filter by time window, cap output, and check remotely
How-to Guides →Remote Execution
Monitor the worker pool, query worker state, troubleshoot enrollment failures, deploy workers, and upgrade the fleet
How-to Guides →Set Up TLS for swamp serve
Configure swamp serve with TLS using direct certificate files or a reverse proxy like Caddy, for encrypted WebSocket and HTTP connections
How-to Guides →Set Up Background Autoupdating
Enable opt-in background autoupdating so Swamp stays current without manual intervention, using platform-native scheduling (launchd on macOS, systemd or cron on Linux).
How-to Guides →Authenticate with API Keys
Log in with the Swamp CLI, create personal API keys, generate collective tokens for CI/CD, and manage credentials for programmatic access.
How-to Guides →Troubleshoot Your Swamp Repo
Diagnose and fix problems with swamp doctor — installation health, broken audit hooks, unhealthy extensions, datastore health, namespace contamination, malformed workflows, cleartext secrets, and missing vaults.
How-to Guides →Gate a Workflow with Manual Approval
Pause a workflow at a manual_approval step so a human signs off before production runs — check pending gates, approve or reject with a reason, and resume.
How-to Guides →Cancel a Stuck Run
Stop a running workflow or behavior method run with swamp workflow cancel, swamp behavior cancel or Ctrl+C, and recover a run a force exit left running
How-to Guides →Reuse a Behavior with the Factory Pattern
Define one behavior with an inputs schema and call it several times from a workflow to create separately addressable resource instances of the same type.
How-to Guides →Verify Infrastructure with Assert Steps
Add assert steps to a workflow to validate collected state, control CI exit codes with severity thresholds, and generate JUnit XML for test reporters.
How-to Guides →Make Workflows Idempotent
Add guard expressions to workflow steps so re-runs skip completed work, and retry or resume failed runs without repeating irreversible side effects
How-to Guides →Authenticate to AWS with SSO
Sign in with an AWS SSO profile and use it for a Swamp S3 datastore or Secrets Manager vault, including config file paths, session expiry, and setup timeouts
How-to Guides →Turn Off Usage Telemetry
Stop Swamp recording and sending usage telemetry — for yourself in every repository, for a whole team, for CI and containers, or for a single command.
How-to Guides →CEL Expressions
Complete reference for CEL expression syntax, context variables, operators, functions, and data queries in Swamp
Reference →Behavior Definitions
Complete YAML schema reference for Swamp behavior definitions — fields, types, defaults, constraints, validation rules, and the swamp behavior commands
Reference →OpenTelemetry
Reference for OpenTelemetry tracing and log export configuration, span hierarchy, context propagation, and instrumentation in Swamp
Reference →Workflows
Complete YAML schema reference for Swamp workflows — jobs, steps, tasks, dependencies, triggers, forEach iteration, and execution ordering
Reference →Vaults
Complete reference for Swamp vaults — types, creation, key storage, retrieval, annotations, refresh hooks, CEL integration, audit trail, and encryption
Reference →Data
Reference for Swamp data: resource and file specs, lifetime, garbage collection, versioning, streaming, tags, sensitive fields, querying, and CLI
Reference →Repository Configuration
Complete YAML schema reference for .swamp.yaml — every field, type, default, environment variable override, and validation rule
Reference →Datastore Configuration
Reference for Swamp datastore backends, configuration fields, hydration strategies, environment variable overrides, sync behavior, distributed locking, and CLI commands
Reference →Doctor
Reference for the swamp doctor subcommands — audit, datastores, extensions, install, secrets, vaults, and workflows. Flags, exit codes, and the text and JSON output shapes.
Reference →Swamp Account Requirement
Which Swamp commands need a swamp-club.com account, which are exempt, what blocks a run, and how verification, signin tokens, offline use and revocation work.
Reference →API Key Authentication
Reference for Swamp API key formats, authentication headers, credential storage, scoping rules, limits, and the full key lifecycle.
Reference →Collective API
Reference for the Swamp collective REST API: endpoints, scopes, status codes, and the OpenAPI document that describes them.
Reference →TLS and Proxies
Reference for Swamp TLS trust stores (DENO_TLS_CA_STORE, DENO_CERT, SSL_CERT_FILE, --ca-cert / SWAMP_CA_CERT) and swamp serve server-side TLS
Reference →Okta SAML SSO
Reference for configuring Okta as a SAML identity provider for Swamp SSO, including application setup, attribute mapping, and connection testing
Reference →Operational Commands
Reference for swamp run history, swamp run doctor, swamp run gc, swamp audit, swamp summarise, swamp telemetry stats, and swamp source — flags, output, and examples
Reference →Issue Commands
Reference for swamp issue search, swamp issue get, swamp issue bug, swamp issue feature, swamp issue security, and swamp issue ripple
Reference →Invite Commands
Reference for swamp invite link — flags, output, and referral link behaviour
Reference →Subscription Commands
Reference for swamp subscription status and swamp subscription start: collective standings, the call to action, flags, SWAMP_CLUB_URL and JSON output.
Reference →Workspace Commands
Reference for swamp workspace create, import, list, get and remove: the workspace registry, workspace naming rules, JSON output and every error code.
Reference →CLI Output
Reference for Swamp CLI output modes — log-mode default, SWAMP_CLI_OUTPUT_JSON, --json, and the distinction from --log
Reference →Usage Telemetry
Reference for Swamp usage telemetry: every opt-out and its scope, the telemetry.collection setting, the telemetry.yaml file, the spool, and endpoint delivery.
Reference →Usage Telemetry Events
Reference for Swamp usage telemetry events: the cli_invocation envelope field by field, how events are sent, what the ingest service stores, and redaction.
Reference →Notifications
What triggers a Lab inbox notification, how mentions are parsed, the dedup and rate-limit rules, and scope caveats.
Reference →Glossary
Definitions of terms used throughout the Swamp documentation — behaviors, workflows, vaults, extensions, and the foundational concepts that connect them
Reference →How Swamp Works
How Swamp decomposes automation into behaviors, workflows, vaults, extensions, skills, and a queryable data layer — and how the primitives compose together
Explanation →Behaviors, Types, and Methods
Why Swamp separates behavior types from definitions, how the method execution lifecycle works, and the tradeoffs of auto-creation versus explicit definitions
Explanation →The Data Layer
Why Swamp uses versioned, immutable data as the composition mechanism between behaviors, and how querying, provenance, and redaction shape cross-behavior work
Explanation →The Workflow Execution Model
Why Swamp workflows are DAGs rather than scripts, how dependency resolution enables maximum parallelism, and why forEach is a first-class workflow primitive
Explanation →Extension Trust and the Supply Chain
Why Swamp requires explicit trust for third-party extensions, how dependency auditing protects the supply chain, and what the Verified by Swamp badge means
Explanation →AI Agent Integration
How AI coding agents drive Swamp: why the CLI, file formats and schemas are built for an agent to operate, the agent interface's three layers, and tool fit.
Explanation →About the Extension Scorecard
What the extension quality score measures, why it exists, where it appears, and why Verified by Swamp is a separate badge rather than a scored factor
Explanation →About the Extension Publishing Lifecycle
Why publishing an extension is a gated sequence rather than a single upload — what each gate protects, how authoring hands off to publishing, and where supply-chain trust fits.
Explanation →Background Autoupdating
Why Swamp uses platform-native scheduling for background updates, how the update lifecycle works, and design decisions around opt-in behavior and CI environments.
Explanation →API Key Scoping
Why Swamp has two types of API keys, how personal keys differ from collective tokens, and when to use each for CLI workflows and CI/CD.
Explanation →Understanding Workflow Suspension
Why Swamp workflows suspend at a manual_approval gate, how run state persists to disk and resume rebuilds it, and why approval and resume are separate.
Explanation →Giga-Swamp and Namespaces
Why giga-swamp exists, how namespaces provide provenance without isolation, and the design decisions behind shared datastores
Explanation →Remote Execution
How the orchestrator-worker model distributes step execution across machines while keeping credentials, data, and definitions centralized
Explanation →Worker Fleets
Why Swamp groups workers into fleets, how fleet tokens replace per-machine provisioning, and the design trade-offs behind elastic queueing and drain policies
Explanation →swamp serve
How swamp serve exposes a repository as a remote API, why OAuth uses the device grant flow, how collective-based admission works, and admin access
Explanation →The Audit System
Why Swamp records commands and CLI invocations, how audit hooks bridge each AI tool, what the timeline omits, and how vault read-access auditing differs
Explanation →Datastore Architecture
How the datastore unifies runtime data behind a single persistence layer, why lazy hydration is the default for remote backends, and how locking works.
Explanation →Data Lifetimes
Why Swamp offers five data lifetimes, when to choose each one, and how the tradeoffs between durability, storage cost, and query visibility shape pipeline design
Explanation →The Run Tracker
Why the run tracker uses a local SQLite database with heartbeat-based liveness detection, and what it records about in-flight behavior and workflow executions
Explanation →Configuration Layers
Why Swamp's four configuration sources — repo, user, environment, and CLI — have the precedence they do, and when each layer is the right place for a setting
Explanation →About Usage Telemetry
Why Swamp usage telemetry keeps names and redacts content, why redaction is an allowlist of named argument slots, and why every opt-out stands on its own.
Explanation →About Extension Licenses
Why an extension license has two parts on the Swamp registry, an SPDX name in the manifest and a LICENSE file, and why a license is optional but scored.
Explanation →