Don't Panic — Introduction to Swamp

Swamp is what happens when an agent solves a useful operational problem and somebody has the good sense to keep the solution. Instead of preserving a heroic chat transcript and hoping it remembers the plot next Tuesday, Swamp keeps model definitions and workflows as files in Git. The machine-specific results of each run live separately in its data layer, which is less romantic but much more useful when something has failed.

The important split is between a model type, reusable TypeScript behavior, and a model definition, YAML that configures that behavior for one target. The type knows how to check an endpoint or call a service. Definitions name the endpoints, accounts, and timeouts. That means one repair to the behavior can reach several definitions, rather than breeding a small colony of nearly identical scripts. It also means a definition is reviewable without requiring everyone to become the author of the integration.

Then come workflows, directed graphs of jobs and steps. Work without dependencies can run in parallel, because waiting decoratively is still waiting. Dependencies say both what must finish and which outcome lets the next action begin. Use succeeded when a deployment must stop after a failed check. Use completed when a report or cleanup needs to appear precisely because the check failed. This distinction is the difference between an incident report and an unusually quiet afternoon.

The other durable part is data. A method writes a resource when later work needs structured, queryable facts, and it can write a file when the artifact itself matters. CEL expressions read those named outputs instead of making a downstream step guess at a temporary file. Retention has limits, so run history is evidence you can inspect and recreate, not an accidental infinite archive. Put secrets in a vault at runtime; putting a token in a definition is merely a very efficient way to make a future cleanup task.

Start with the Slides for the map, then use the Cheatsheet when the names, lifetimes, conditions, and commands begin to blur together. The Practice Reference builds a typed HTTP check and shows the boundaries in action. The exercise makes a failed check prove why succeeded and completed are different. The Reference tab is the route into the manual once this compact machinery has acquired a real system to operate.