Salt × AI · differential edge

Salt + AI — patterns that actually work.

AI writes plausible Salt YAML. Sometimes it runs. Here's how to make AI a real productivity multiplier on your Salt fleet — and how to spot when it's lying to you.

v1.0 · Updated 2026-05-09

The cheat sheet

01 Shines vs lies 02 Prompts that work 03 Paste-the-error 04 MCP for Salt 05 Pillar from prose 06 Failure modes 07 AI uplift
01 · The honest split

Where AI shines, where it lies.

Most "AI for Salt" content reads like a sales deck. It isn't. AI is excellent at four very specific things and terrible at four others. Knowing which is which is the whole game.

What it's good at

Use AI here. Save hours.

  • Scaffolding. Generating the first 80% of a state file from a clear description. Read it, fix the 20%, ship.
  • Reading errors. Paste a Salt traceback + the failing state. AI explains it faster than digging through `-l debug` output.
  • Pillar from prose. Translating "50 web servers, 3 envs, TLS varies" into structured pillar YAML.
  • Documenting your states. Generating human-readable runbooks from existing `.sls` files.
What it lies about

Verify everything here. No exceptions.

  • Module names. AI invents modules that sound right but don't exist in your Salt version.
  • Require chains. Wrong order, misspelled IDs, missing dependencies — looks plausible, doesn't compile.
  • Runtime state. AI doesn't know what's actually installed on your minion. It guesses.
  • Anything pre-2022. Trained on docs that include patterns Salt removed years ago.

The pattern: AI drafts → you read every line → run on one test minion → iterate. Never apply AI-generated states to production without reading them. AI is a smart junior, not a senior. Treat it that way.

02 · The prompt format

Prompts that generate working states.

The difference between AI-generated YAML that runs first try and AI-generated YAML that wastes your afternoon is almost entirely in the prompt. Here's the format.

The format that works

Good prompt
Salt minion version: 3006.4
Target OS: Ubuntu 22.04
Goal: install nginx, enable+start the service, allow ports 80/443 in ufw

Generate a Salt state file (.sls) using these modules only:
- pkg.installed
- service.running
- cmd.run

Include explicit `require:` chains so order is unambiguous.
No comments. YAML only.

Why it works: Version pinned (no 2019-era patterns), OS specified (right package names), goal is concrete, module list constrains the search space, explicit require: removes ordering guesswork.

The format that wastes your time

Bad prompt
Set up a webserver with Salt

Why it fails: No version → mixed-era YAML. No OS → wrong package names. No module constraint → AI picks weird modules. No `require:` instruction → implicit ordering. You'll spend 30 minutes debugging.

The "minimal first, then expand" pattern

For complex states, ask AI for the smallest possible working version first. Get it to apply cleanly on one test minion. Then ask it to expand — add the firewall rules, add the TLS, add the monitoring. Each iteration stays small enough that you can read every line.

Always pin the version. Salt's release cadence means modules and signatures shift. AI trained on Salt 3001 docs will happily hand you patterns that 3006+ rejects. One line at the top of your prompt — Salt minion version: 3006.x — saves you hours of debugging deprecated syntax.

03 · The fastest debug loop

Paste-the-error troubleshooting.

When a state fails, AI is faster than `-l debug` output for the first read. Not for the fix — for the diagnosis. This is the workflow.

STEP 01

Capture full debug

Run with -l debug. Copy the entire output, not just the red bit. AI uses the surrounding context.

STEP 02

Paste with context

Salt version, target OS, the failing state file, the full traceback. Four pieces. Always.

STEP 03

Ask the surgical question

"What's wrong, and what's the minimum change?" Not "fix this for me" — minimum change forces a focused diagnosis.

Common AI wins on Salt errors

Where AI still loses to a senior

If the failure is a multi-minion race condition, a state that only fails under load, or a Salt master config quirk that depends on your specific GPG/PKI setup — AI can't see your environment. It'll guess. A senior with shell access wins.

04 · The next level

MCP for Salt — give Claude shell access (carefully).

MCP is Anthropic's protocol for letting Claude call real tools — your tools, your environment. There's no official Salt MCP server. There should be. Here's the architecture we use.

The wire-up, in five lines

  • A small Python MCP server running on the Salt master (or a sidecar with API access)
  • Wraps salt-call locally — or hits the salt-master REST API if you have one
  • Read-only tools first: test.ping, grains.items, state.show_sls, cp.list_states
  • Mutating tools gated: anything that runs (state.apply, cmd.run) defaults to test=True and requires explicit confirmation
  • Every call logged — you want an audit trail when an LLM is targeting production

Why this matters

Without MCP, Claude generates Salt blindly. It guesses what's installed, guesses what your states look like, guesses what your grains return. With MCP and read-only tools wired up, Claude can ask — "what version is minion-foo running?", "what's in your existing nginx state?" — and write states that actually fit your environment.

It's the difference between a contractor who shows up, asks questions, and writes code that fits — and one who shows up, doesn't ask, and writes code that breaks.

Never expose cmd.run as an unconstrained tool. An LLM with arbitrary shell access is a vulnerability waiting to happen. Always: read-only by default, mutating tools require explicit per-call approval, every action logged. If you wouldn't give the tool to a junior on day one, don't give it to Claude either.

05 · The boring win

Pillar data from prose.

Pillar generation is where AI quietly saves the most time. Repetitive structure, predictable shape, low risk if you read the diff. This is the "use it every day" pattern.

Where it works

Where it doesn't

The secret-sanitizing trick: Before pasting any pillar to AI, search-and-replace your real values with <PLACEHOLDER> tokens. Get the AI's output back. Re-substitute the real values locally. Five seconds of work, zero secret leakage.

06 · The honest part

The "looks fine, doesn't run" problem.

AI-generated Salt that looks plausible but isn't is the single biggest time-sink. Real examples we've seen, and how to catch them in 30 seconds instead of 30 minutes.

1. Hallucinated modules

AI invents modules that sound like they should exist. They don't.

ensure_running:
  systemd.unit_running:    # NOT A REAL MODULE
    - name: nginx
Fix: Salt has service.running, not systemd.unit_running. Verify against the state module index before applying.

2. Wrong require chains

AI generates require: blocks that reference state IDs that don't exist or are misspelled. Salt fails the compile step with a confusing error.

Fix: Always run salt-call --local state.show_sls your.state first. It compiles without applying. Compile errors surface in seconds.

3. Deprecated patterns

AI trained on 2019 docs will suggest module signatures that worked then but were removed in 3006+. Especially common with pkg.installed arguments and old file.managed options.

Fix: Pin the version in your prompt. Salt minion version: 3006.x at the top of every prompt cuts this in half.

4. Jinja in the wrong render phase

AI references grains inside pillar files (which render before grains are available), or pillar values inside states without remembering the lookup syntax. Looks fine, fails at compile.

Fix: If a state breaks with "undefined variable", suspect render order before suspecting your data. Pillar renders first, states render second, grains exist throughout but pillar can't see them.

5. Confidently wrong with no source

The dangerous one. AI states something authoritatively that's just wrong. "Salt automatically retries failed states" — it doesn't, unless you wire it up. "onchanges is the same as watch" — they're different.

Fix: Cross-reference anything load-bearing against docs.saltproject.io. Your cheat sheet is also a sanity check — if AI suggests a flag that isn't on your cheat sheet, double-check it exists.

The 30-second sanity check that catches all five

# 1. Compile-only — catches typos, missing modules, bad requires
salt-call --local state.show_sls your.state

# 2. Dry-run — catches everything else, no changes made
salt 'minion-test' state.apply your.state test=True

# 3. Read the diff. Then apply for real.
salt 'minion-test' state.apply your.state
07 · The Saltify pattern

AI uplift — what we leave behind when we exit.

Most consultancies leave you with a working stack and a phone number. We leave you with a stack, a phone number, and a colleague that doesn't bill. This is what that means in practice.

The handover kit

Why this changes the math

AI replaces nobody. But it makes a senior engineer faster, and it makes a junior engineer competent. When we leave a client, the senior on their team stops needing us for routine state work — they handle it with AI uplift. They call us back for the architectural decisions, the blue/green cutovers, the things that need real judgment.

That's not "make yourself indispensable" consulting. That's the opposite. We're confident enough in our work to make ourselves less needed. Repeat business comes from solving the hard problems, not gatekeeping the easy ones.

Want this for your team? AI uplift is bundled with every Saltify engagement — blue/green build-outs, multi-master deployments, VCF Salt installs. We don't charge extra for the prompt library, the MCP server, or the runbook templates. Talk to us.

Built from production Saltify engagements + Anthropic's MCP spec. Patterns evolve as Salt and Claude both ship — last reviewed May 2026.