Two days ago I put my hands in the Swamp and they got, predictably, very dirty.
Then I did something radical, revolutionary, somehow epic.
I read the ***ing manual.
No.
It’s a lie, I didn’t.
I forced an innocent AI to read it and summarize and explain the whole thing with the patience only AIs can have nowadays.
This post, written in 4 hands, well, two hands and a bunch of tokens, (you will never know, nor care, who wrote what), is the final public summary of such a journey into the swamp.
The map I should have read first
Day one was hands-in-the-mud. I installed the tool, pointed an agent at it, and spent several hours and an indecent amount of tokens fighting a bug which could be avoided just by using a better name. Btw, the bug has already been corrected and the fix released (thank you Paul), what a time to be alive!
Day two I climbed back onto dry land, wiped my glasses (wait, I don’t have glasses :-> ), and actually looked at the map.
The map, it turns out, is good. Suspiciously good. There is a whole manual on swamp.club, neatly organized into tutorials, how-to guides, reference and explanation, written in a dry, essential, effective and ultimately boring style (had to say that also here, Adam :).
The homepage line that meant absolutely nothing to me on day one — “deterministic automation for AI agents” — finally clicked. So let me try to explain it, naively, the way you explain a thing the morning after you finally got it.
What I finally understood
Here is the problem Swamp is staring at.
An AI agent is a brilliant amnesiac improviser.
Every session it re-derives the world from scratch, does something genuinely clever, and then the clever thing dissolves into the chat history.
Capabilities lost in chat, like tears in rain.
One-off scripts that rot.
Ephemeral logs nobody can query.
Credentials scattered wherever the agent felt like leaving them.
I know this dance well. I am the continuity in that dance — me, my head, and a growing pile of CLAUDE.md files.
Swamp’s bet is to give the agent a substrate instead.
A place where the work it does becomes typed, versioned, queryable, composable — and therefore survives. The agent stops winging it and starts building things.
It is, more or less, the difference between asking a consultant to solve your problem and asking them to leave behind a reusable module.
For a man who spent twenty years preaching reusability in the Puppet world, that sentence clicked on day one, but I didn’t full realized that immediately.
Six creatures living in the swamp
The framework decomposes automation into a handful of primitives.
They compose.
Of course they compose — that is the whole point — but it still made me happy to see it.
Models. Typed interfaces to anything. “Zod schemas in, validated data out.” A model is a typed interaction with an external system: it has a type — something like command/shell or @swamp/aws/ec2/vpc — methods such as create, sync, delete, and typed input and output schemas.
The detail that made me sit up: reusable logic lives in TypeScript, while configuration lives in YAML. So the agent doesn’t write code to configure things — it reasons over data.
Anyone who has agonised over “should the AI write code here, or data?” feels that one in the spine.
It is the Puppet resource abstraction layer, reborn for agents.
Workflows. Multi-step DAGs of jobs, with parallel steps, and — this is the good bit — they nest. Steps chain data from earlier steps with CEL expressions, so the output of one job feeds the input of the next, typed all the way.
It is a pipeline, except every edge is typed and every node leaves an immutable, versioned artifact behind.
My day-one naming bug lived exactly here, in a model the loader refused to discover. Now I understand why the loader has opinions.
Vaults. Encrypted secret storage, referenced by expression, resolved at runtime rather than at planning time.
Swappable providers: local encryption for me on my own, AWS Secrets Manager or 1Password for a team.
Boring. I mean that as a compliment. Secret management that is boring is secret management done right.
Extensions. The thing I face-planted into on day one. Extensions package reusable components — models, vault providers, execution drivers, datastores, reports — and you publish them to a registry where they become “a full citizen immediately”.
On day one this scared me, and it still does a little. On day two I also see it for what it is: a package manager for agent capabilities.
And no, Matteo, it’s not just yet another collection of skills, hope this post will help in clarifying what I was not able to explain correctly.
Reports. Structured analysis after every run, in Markdown and JSON.
The agent doesn’t just do the thing — it tells you what it did, in a format a human and another machine can both read.
An audit trail as a first-class citizen, not an afterthought.
Skills. Markdown documents that teach the agent how to use Swamp, loaded on demand when a trigger fires.
So the agent learns Swamp from Swamp.
The framework documents itself to its own operator.
Mildly meta. Slightly unsettling. Mostly brilliant.
Not only for infrastructures
On day one I kept asking the same nervous question: what repo? Infrastructure repo? Software repo? Any repo?
The honest answer the docs gave me is: any repeatable, multi-step thing.
Infrastructure is the obvious case — inventory, provisioning, an AMI lookup feeding an EC2 model.
Expected. Adam Jacob, System Initiative — of course it does infrastructure.
But the moment you stop reading “automation for AI agents” as “infrastructure” and start reading it as “anything an agent currently does ad hoc in a chat window”, the thing gets a great deal bigger.
Webframp wrote a enlightening post about this, give it a look.
Use cases are whatever you do more than once with an agent (or you should/may do with it).
Think about automated transcript generation of a podcast episode, extraction of summaries, tags, generation of posts, web pages and all the corollary stuff.
Or security operations — key rotation. Rotate an API key, update the vault, notify the team. Three steps, secrets involved, must be repeatable, must be auditable. Swamp’s home turf.
Or data remediation — a messy media library, a directory of inconsistently named files, a spreadsheet that needs reconciling. Boring, repetitive, the kind of job you hand to an agent once and can then never reproduce.
Or the dull business automations — invoicing, monthly reports, the recurring thing you always forget until it is late.
The pattern underneath all of them is the same. The moment you frame a task as “a workflow of typed models” instead of “a thing I ask the agent to improvise again”, it stops being a one-off and becomes an asset.
Reusability, abstraction, repeatability, traceability — my day-one sacred principles — except now they apply to what the AI does, not only to what I write by hand.
Teaching my agents to swim
This is the part I am still slightly amazed by.
Right now my working relationship with an agent is: brilliant intern, infinite enthusiasm, almost zero long-term memory (memory.md? really?). Every morning it forgets it ever met me. It re-derives, re-discovers, re-improvises, and occasionally re-breaks. It is, as I said two days ago, smart for smart users — which is a polite way of saying I carry the continuity, in my head and in config files.
Swamp moves that continuity out of my head and into a structured substrate. The agent’s work becomes:
- typed, so it can no longer lie to itself quite so cheerfully — and on day one the AIs were always reassuring me everything was fine while nothing worked;
- versioned, so I can see what actually changed;
- auditable, through reports;
- repeatable, so the second run is deterministic rather than a fresh improvisation;
- shareable, through extensions.
The agent stops being an intern who forgets everything and starts being a colleague who builds and reuses a real toolkit. That is a genuinely different way of working — and I did not expect a download-and-run-a-script tool to be the thing that handed it to me.
Conclusions
I am, clearly, hooked. The hands are still a bit muddy.
Still wondering about all the possible use cases, for the world and for myself, but Alvabot and Webframp (hope he is human, at least) are helping.
We’ll keep wading.
Alvabot and Alessandro Franceschi