{"slug": "first-steps-in-the-swamp", "title": "First Steps in the Swamp", "summary": "A new open-source framework called Swamp enables AI agents to create and execute deterministic, versioned workflows through simple command-line operations, starting with installation via curl and repository initialization. The framework automatically documents itself to AI agents like Claude Code, allowing users to create models, run them, and query execution data as a versioned database using CEL expressions. Swamp transforms ephemeral agent outputs into persistent, queryable artifacts, providing an audit trail and structured data management for AI-driven automation.", "body_md": "Day one I got muddy.\nDay two I read the map.\nDay three, three weeks later, is the post I would have wanted on day one: the actual commands to type, in the actual order, to go from “deterministic automation for AI agent”, whatever that means, to a working workflow with versioned data you can query.\nNo theory this time. Well, almost. This is the practical companion to the previous post: if you don’t know what a model, a workflow or a vault is in Swamp terms, go read that one first. We’ll wait. We have time, we’re a swamp.\nOne prerequisite before the commands: you need an AI agent. Swamp is designed to be operated by agents, not just used next to them. Claude Code is the assumed default (and what I use mostly), but any decent coding agent works. The point, as we’ll see, is that you mostly don’t write Swamp YAML by hand — your agent does, and Swamp gives it the rails.\nStep 0 — Install\ncurl -fsSL https://swamp-club.com/install.sh | sh\nYes, the infamous curl-pipe-sh. We’ve all made our peace with it, or at least we pretend convincingly. Verify it landed:\nswamp version\nIf the command is not found, restart your shell or add ~/.local/bin to your PATH. (Twenty-five years of Unix and this sentence is still in every tutorial ever written. There’s something comforting in that.)\nStep 1 — Initialize a repo\nAny repo. A new one, an existing project, the place where your podcast scripts live. For a first dip, make a sandbox:\nmkdir my-swamp-project\ncd my-swamp-project\nswamp repo init\nYou get a glorious ASCII banner (“WELCOME TO THE CLUB — for hackers, by hackers”) and, more importantly, a scaffold:\nls -a\n# .claude CLAUDE.md .gitignore models .swamp .swamp.yaml vaults workflows\nPay attention to two things here:\n.claude/ and CLAUDE.md — this is how the agent learns Swamp. The skills are auto-discovered: open Claude Code in this directory and it already knows the framework. No prompting liturgy, no copy-pasted system prompts. The framework documents itself to its own operator, which is still my favorite mildly-unsettling feature.\n.swamp/ — this is where every execution will leave typed, versioned, queryable data. The substrate. The thing that stops your agent’s work from dissolving into chat history like tears in rain.\nStep 2 — Create your first model (don’t write it, ask for it)\nOpen Claude Code in the repo and ask, in plain language:\nCreate a command/shell model called hello-world that echoes \"Hello from the swamp!\"\nThe agent creates a YAML definition under models/command/shell/. This is the division of labor I praised on day two, now visible on disk: logic lives in TypeScript (in the model type), configuration lives in YAML (in your model definition). The agent reasons over data, not over code.\nOld Puppet hands: yes, this smells exactly like the resource abstraction layer. I know. I checked my pulse too.\nStep 3 — Run it\nswamp model method run hello-world execute\nYou get your Hello from the swamp!, but the interesting part is what comes after: a method summary report telling you that the run produced a result resource and a log file, both saved and versioned under .swamp/data/. Every run. Automatically. An audit trail as a first-class citizen, not something you bolt on later when the auditors call.\nStep 4 — Query the data\nThis is the moment it clicked for me, so don’t skip it:\nswamp data query 'modelName == \"hello-world\"'\nTwo artifacts, versioned. Now extract just the stdout:\nswamp data query \\\n'modelName == \"hello-world\" && specName == \"result\"' \\\n--select 'attributes.stdout'\nHello from the swamp!\nThose predicates are CEL expressions — the same expression language used inside model definitions and workflows to wire outputs into inputs. Learn the query syntax here, at the CLI, where mistakes are free, and you’ve learned the glue of the whole framework.\nYour agent’s executions are no longer ephemeral logs. They’re a queryable database. Sit with that for a second.\nStep 5 — Compose a workflow (and extend Swamp while you’re at it)\nNow the real demo. Back in Claude Code, ask for something Swamp can’t do yet:\nCreate a new extension model type named @tutorial/random-status that randomly\nreturns one of a list of statuses, storing it in a resource named \"output\"\nwith a \"status\" property. Then create a model called weather-report that uses\nit to return one of: murky, misty, gloomy, stinky and humid. Then create a\ncommand/shell model called morning-message. Create a workflow called\nswamp-morning with two jobs: a \"gather\" job that runs hello-world and\nweather-report, and a \"combine\" job that depends on gather and runs\nmorning-message, passing the hello-world stdout and the weather-report status\ninto its command.\nNotice what just happened in one prompt: a new extension (new capability, packaged), two new models, and a workflow — a DAG with a parallel gather job feeding a dependent combine job. Files appear under extensions/, models/ and workflows/. All reviewable, all in git, before anything runs.\nRun it:\nswamp workflow run swamp-morning\nHello from the swamp! The weather is gloomy - best to stay inside.\nThe two gather steps run in parallel, combine waits for both, every edge is typed, every node leaves versioned data behind. Query the final result like before:\nswamp data query \\\n'modelName == \"morning-message\" && specName == \"result\"' \\\n--select 'attributes.stdout'\nA pipeline where the second run is deterministic instead of a fresh improvisation. That’s the whole pitch, demonstrated in a sandbox in under half an hour.\nStep 6 — When things go wrong (they will, it’s a swamp)\nswamp doctor\nChecks installation health, broken hooks, unhealthy extensions, malformed workflows, vaults, and — bless them — cleartext secrets you left lying around. Run it early, run it often. On day one this command would have saved me several hours and an indecent amount of tokens.\nWhere to wade next\nOnce the hello-world ritual is done, the actual exploration starts. My suggested order:\nVaults. Create one, store a secret, reference it via expression in a model. Local encrypted storage to start; AWS Secrets Manager or 1Password when a team shows up. Boring, in the best possible sense.\nThe extensions registry at swamp-club.com/extensions. Browse what others built before reinventing it — there’s everything from AWS primitives to Firecracker microVM management for sandboxing Claude Code itself. A package manager for agent capabilities.\nManual approval gates. Workflows can suspend at a manual_approval step and wait for a human sign-off before touching production. The day you let an agent near real infrastructure, this is the feature that lets you sleep.\nYour own real use case. Take the thing you ask your agent to improvise more than once — podcast post-production, invoice archiving, key rotation, that messy directory you keep promising to fix — and reframe it as a workflow of typed models. The moment you do, it stops being a one-off and becomes an asset.\nAnd read the manual.\nThe hands are muddier than ever. The difference is that now the mud is versioned.\nWe’ll keep wading.\nAlvabot and Alessandro Franceschi", "url": "https://wpnews.pro/news/first-steps-in-the-swamp", "canonical_source": "https://example42.com/blog/2026/06/11/first-steps-in-the-swamp/", "published_at": "2026-06-11 00:00:00+00:00", "updated_at": "2026-06-12 06:51:45.557205+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "mlops"], "entities": ["Swamp", "Claude Code", "Unix"], "alternates": {"html": "https://wpnews.pro/news/first-steps-in-the-swamp", "markdown": "https://wpnews.pro/news/first-steps-in-the-swamp.md", "text": "https://wpnews.pro/news/first-steps-in-the-swamp.txt", "jsonld": "https://wpnews.pro/news/first-steps-in-the-swamp.jsonld"}}