MANUAL
Guidance on how to thrive in the Swamp.
Swamp is an adaptive automation framework designed to be operated by AI agents. Start by reading How Swamp Works if you're just getting started.
Hello World
Install Swamp, initialize a repo, and run your first workflow
Tutorials →Publish Your First Extension
Build a TypeScript extension model, smoke-test it, score it against the quality rubric, walk it through every 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 →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, 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 →Reuse a Model with the Factory Pattern
Define one model with an inputs schema and call it multiple times from a workflow to create separately addressable resource instances.
How-to Guides →CEL Expressions
Complete reference for CEL expression syntax, context variables, operators, functions, and data queries in Swamp
Reference →Model Definitions
Complete YAML schema reference for Swamp model definitions — fields, types, defaults, constraints, and validation rules
Reference →model type describe
Reference for swamp model type describe: inspect model type schemas, methods, arguments, and output specs with full or compact JSON output
Reference →OpenTelemetry
Reference for OpenTelemetry configuration, span hierarchy, context propagation, and instrumentation points 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, encryption, and environment variable mounting
Reference →Data Outputs
Reference for Swamp data outputs: resource and file specs, lifetime, garbage collection, versioning, streaming, tags, sensitive fields, and CLI
Reference →Repository Configuration
Complete YAML schema reference for .swamp.yaml — every field, type, default, environment variable override, and validation rule
Reference →Data Querying
Reference for swamp data query: CEL predicates, DataRecord fields, --select projections, tag filtering, data.query() in expressions, and interactive TUI
Reference →Datastore Configuration
Reference for Swamp datastore backends, configuration fields, hydration strategies, environment variable overrides, sync behavior, distributed locking, and CLI commands
Reference →Namespace Commands
CLI reference for swamp datastore namespace commands — set, unset, migrate, and list namespace operations
Reference →Doctor
Reference for the swamp doctor subcommands — audit, extensions, install, secrets, vaults, and workflows. Flags, exit codes, and the text and JSON output shapes.
Reference →API Key Authentication
Reference for Swamp API key formats, authentication headers, credential storage, scoping rules, limits, and the full key lifecycle.
Reference →TLS and Proxies
Reference for Swamp TLS trust stores (DENO_TLS_CA_STORE, DENO_CERT, SSL_CERT_FILE) and swamp serve server-side TLS (--cert-file, --key-file)
Reference →Notifications
What triggers a Lab inbox notification, how mentions are parsed, the dedup and rate-limit rules, and scope caveats.
Reference →How Swamp Works
How models, workflows, vaults, extensions, skills, and data querying compose into agent-driven automation
Explanation →AI Agent Integration
Why Swamp is designed around AI agents, how the agent interface works, and what makes different tools effective with Swamp
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 →swamp serve
How swamp serve exposes a repository over WebSocket, why off-loopback binding requires TLS and authentication, and how admin materialization works
Explanation →