Safety Guardrails — Aspire Agent Rules

Purpose: Detailed explanation of why each guardrail exists, what goes wrong when violated, and how to recover.

Why These Rules Exist

Issue #15801 documented 5 specific failures when AI agents work in Aspire projects without guidance. Every rule below directly prevents one or more of these failures.

Rule 1: ALWAYS aspire start — NEVER dotnet run

Why dotnet run Is Dangerous for AppHosts

The AppHost project is an orchestrator, not a regular .NET app. Running it with dotnet run:

• Bypasses the Aspire CLI orchestration layer — resources don't get managed lifecycle
• No dashboard — the Aspire developer dashboard won't launch
• No backchannel — aspire wait, aspire logs, aspire describe won't work
• No resource management — can't operate on individual resources
• Port conflicts — resources start without coordinated port allocation
• No cleanup — orphaned processes when the host exits

Correct Pattern

# ✅ Start the Aspire app
aspire start

# ✅ Verify it's running
aspire ps

aspire run vs aspire start

For AI agents, always use aspire start — it runs in the background and returns control to the agent.

Recovery If dotnet run Was Used

# Kill the dotnet process manually (find PID first)
# Then start correctly:
aspire start

Rule 2: ALWAYS aspire wait — NEVER curl Polling

Why curl Polling Is Wrong

Aspire tracks resource readiness internally through health checks, dependency graphs, and startup ordering. Manual HTTP polling:

• Doesn't know the correct port — Aspire assigns ports dynamically
• Doesn't respect dependency ordering — a resource may respond to HTTP before its dependencies are ready
• Creates false negatives — health endpoint may not exist or may return 503 during startup
• Wastes time — retry loops with arbitrary delays vs. event-driven readiness

Correct Pattern

# ✅ Wait for a specific resource
aspire wait apiservice

# ✅ Wait with extended timeout for slow resources
aspire wait postgres --timeout 120

# ✅ Wait then interact
aspire wait apiservice && curl $(aspire describe apiservice --format Json | jq -r '.endpoints[0].url')

Machine-Readable Output

Always use --format Json when parsing output programmatically:

# ✅ Get resource endpoints as JSON
aspire describe --format Json

# ❌ Never scrape text output
aspire describe | grep "http"  # fragile, format may change

Rule 3: Prefer Resource Commands / Watch — NEVER dotnet build With Aspire Running

Why dotnet build Causes File-Lock Errors

When Aspire is running, it holds file locks on:

• Output assemblies (.dll, .pdb) of managed resources
• Build intermediates in obj/ directories
• NuGet package caches being read by running processes

Running dotnet build while Aspire holds these locks produces:

error MSB3491: Could not write to output file 'bin/Debug/net10.0/MyService.dll'
error CS2012: Cannot open 'obj/Debug/net10.0/MyService.dll' for writing

The agent then concludes the project is "un-buildable" — a false conclusion.

Recovery If dotnet build Was Used and Locks Hit

When you see MSB3491 / CS2012 / "file in use" / "another process is using":

# ✅ Single correct recovery
aspire stop              # release all Aspire-held locks

# Then EITHER use a resource-scoped command if Aspire is still up + one resource changed:
aspire resource <name> rebuild
# OR:
aspire start             # if AppHost code changed or Aspire was fully stopped

🔒 aspire stop is the ONLY first step. Do not pkill dotnet, do not delete
bin//obj/, do not "reboot to release the lock", and do not tell the user the
project has a permanent build failure. The cause is always the same — Aspire is
holding the output files — and the fix is always aspire stop.

What Changed Determines the Action

Rule 4: Use aspire stop For Cleanup — NEVER Leave Unwanted Processes Running

Why Cleanup Matters

Aspire orchestrates multiple processes (your services, databases, message brokers, etc.). Leaving them running causes:

• Port conflicts — next aspire start fails because ports are occupied
• File locks — can't build or modify service code
• Resource consumption — databases, Redis, etc. consuming memory
• Stale state — old code running while you've made changes
• Orphaned containers — Docker containers left running

Correct Pattern

# ✅ Stop when cleanup is requested or the user did not ask to keep it running
aspire stop

# ✅ Verify everything stopped
aspire ps  # should show no running resources

Recovery from Orphaned Processes

# Check if anything is still running
aspire ps

# If aspire ps shows nothing but ports are blocked:
# The previous instance may have crashed. Start fresh:
aspire start  # will clean up orphaned state

Rule 5: ALWAYS --format Json for Machine-Readable Output

Why JSON Output Matters for Agents

Text output is formatted for humans and may change between versions. JSON output is:

• Stable — structured contract unlikely to break
• Parseable — jq, Python, or any JSON parser works
• Complete — includes fields not shown in text output

Examples

# ✅ Machine-readable resource list
aspire ps --format Json

# ✅ Get specific resource details
aspire describe apiservice --format Json

# ✅ Parse with jq
aspire describe --format Json | jq '.resources[] | select(.state == "Running")'

⚠️ Known JSON Output Issues

Hidden Resources and --include-hidden

aspire ps, aspire describe, and other CLI commands **filter out resources marked as hidden in the AppHost** (proxies, helper containers, migration jobs, etc.). This filtering is correct for normal workflows — agents and humans see only the resources they care about, not the implementation scaffolding.

Use --include-hidden when:

# ✅ Normal flow — filtered (correct for most tasks)
aspire ps --format Json

# ✅ Debugging / completeness — include hidden resources
aspire ps --include-hidden --format Json
aspire describe --include-hidden --format Json

If a user reports "I can't see my proxy / migration / helper container," reach for --include-hidden before assuming the AppHost is misconfigured.

Rule 6: ALWAYS --non-interactive for Agent Commands

Why It Matters

AI agents run in non-interactive terminals. Some Aspire CLI commands may prompt for confirmation or input. Always pass --non-interactive to prevent hangs:

# ✅ Agent-safe commands
aspire start --non-interactive
aspire deploy --non-interactive
aspire agent init --non-interactive

⚠️ Known issue: aspire agent init --non-interactive is broken in some versions (#16264, #15071). If it fails, instruct the user to run it from a standard terminal.

Recovery Patterns Summary