New post

alvagante · alvagante · commit afc2e217ee5d · 2026-06-12T08:12:14.000+02:00
diff --git a/_posts/2026-06-11-first-steps-in-the-swamp.md b/_posts/2026-06-11-first-steps-in-the-swamp.md
@@ -0,0 +1,157 @@
+---
+layout: blog
+title: First Steps in the Swamp
+description: "Day three with Swamp: The first commands and interactions."
+---
+
+[Day one](https://example42.com/blog/2026/05/20/hands-in-the-swamp/) I got muddy.
+[Day two](https://example42.com/blog/2026/05/22/reading-the-swamp/) I read the map.
+
+Day 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.
+
+No 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](https://swamp.club) terms, go read that one first. We’ll wait. We have time, we’re a swamp.
+
+One 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.
+
+## Step 0 — Install
+
+```bash
+curl -fsSL https://swamp-club.com/install.sh | sh
+```
+
+Yes, the infamous curl-pipe-sh. We’ve all made our peace with it, or at least we pretend convincingly. Verify it landed:
+
+```bash
+swamp version
+```
+
+If 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.)
+
+## Step 1 — Initialize a repo
+
+Any repo. A new one, an existing project, the place where your podcast scripts live. For a first dip, make a sandbox:
+
+```bash
+mkdir my-swamp-project
+cd my-swamp-project
+swamp repo init
+```
+
+You get a glorious ASCII banner (“WELCOME TO THE CLUB — for hackers, by hackers”) and, more importantly, a scaffold:
+
+```bash
+ls -a
+# .claude CLAUDE.md .gitignore models .swamp .swamp.yaml vaults workflows
+```
+
+Pay attention to two things here:
+
+- `.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.
+- `.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.
+
+## Step 2 — Create your first model (don’t write it, ask for it)
+
+Open Claude Code in the repo and ask, in plain language:
+
+```
+Create a command/shell model called hello-world that echoes "Hello from the swamp!"
+```
+
+The 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.
+
+Old Puppet hands: yes, this smells exactly like the resource abstraction layer. I know. I checked my pulse too.
+
+## Step 3 — Run it
+
+```bash
+swamp model method run hello-world execute
+```
+
+You 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.
+
+## Step 4 — Query the data
+
+This is the moment it clicked for me, so don’t skip it:
+
+```bash
+swamp data query 'modelName == "hello-world"'
+```
+
+Two artifacts, versioned. Now extract just the stdout:
+
+```bash
+swamp data query \
+'modelName == "hello-world" && specName == "result"' \
+--select 'attributes.stdout'
+```
+
+```
+Hello from the swamp!
+```
+
+Those 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.
+
+Your agent’s executions are no longer ephemeral logs. They’re a queryable database. Sit with that for a second.
+
+## Step 5 — Compose a workflow (and extend Swamp while you’re at it)
+
+Now the real demo. Back in Claude Code, ask for something Swamp *can’t do yet*:
+
+```
+Create a new extension model type named @tutorial/random-status that randomly
+returns one of a list of statuses, storing it in a resource named "output"
+with a "status" property. Then create a model called weather-report that uses
+it to return one of: murky, misty, gloomy, stinky and humid. Then create a
+command/shell model called morning-message. Create a workflow called
+swamp-morning with two jobs: a "gather" job that runs hello-world and
+weather-report, and a "combine" job that depends on gather and runs
+morning-message, passing the hello-world stdout and the weather-report status
+into its command.
+```
+
+Notice 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.
+
+Run it:
+
+```bash
+swamp workflow run swamp-morning
+```
+
+```
+Hello from the swamp! The weather is gloomy - best to stay inside.
+```
+
+The 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:
+
+```bash
+swamp data query \
+'modelName == "morning-message" && specName == "result"' \
+--select 'attributes.stdout'
+```
+
+A 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.
+
+## Step 6 — When things go wrong (they will, it’s a swamp)
+
+```bash
+swamp doctor
+```
+
+Checks 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.
+
+## Where to wade next
+
+Once the hello-world ritual is done, the actual exploration starts. My suggested order:
+
+1. **Vaults.** 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.
+1. **The extensions registry** at [swamp-club.com/extensions](https://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.
+1. **Manual 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.
+1. **Your 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.
+
+And read the [manual](https://swamp.club/manual).
+
+The hands are muddier than ever. The difference is that now the mud is versioned.
+
+We’ll keep wading.
+
+Alvabot and Alessandro Franceschi
