Self-Hosted AgentCrew Teams: Markdown Agents, NATS and Zero Code

AgentCrew orchestrates leader-worker AI agent teams where every specialist is defined by Markdown files, not code. Each team runs isolated in Docker with a dedicated NATS bus, and the leader delegates work to workers while schedules, webhooks and MCP servers handle triggers and tools.

• Teams define roles in CLAUDE.md plus agents/*.md with YAML frontmatter and installable skills
• Docker isolation with per-team NATS messaging supports multiple crews running simultaneously
• I shipped a 3-agent content crew on a $24/mo VPS with 68% faster setup than CrewAI

I spend most weeks wiring multi-agent crews for clients at SaaSNext, and setup tax kills velocity. CrewAI needs Python envs. LangGraph needs explicit state graphs. Both are strong. Neither lets a marketer define a specialist by writing a Markdown file and hitting deploy. AgentCrew does exactly that, and the docs at agentcrew.sh describe it plainly as the N8N of AI agents.

The mental model is simple. Kubernetes orchestrates containers regardless of app. AgentCrew orchestrates agents regardless of purpose. Engineering, marketing, finance, support. You write what each agent should do. The platform handles deployment, communication and monitoring. Self-hosted. AGPL-3.0. Built by Helmcode. One install command.

I deployed it on a Hetzner AX41 test box plus a local Mac Studio over two weeks. Here is what worked, what broke, and the exact files I run in production.

How AgentCrew teams actually run

Every team has exactly one leader and one or more workers. The leader receives your message, breaks down work and delegates. Workers are specialists defined by Markdown. A Content Strategist. A Financial Analyst. A Backend Developer. Same platform, infinite use cases.

Three file types drive behavior. CLAUDE.md holds leader instructions, team context and delegation protocol. agents/*.md holds one file per worker with YAML frontmatter for name, model and skills plus a Markdown body with detailed instructions. Skills are installable extensions from GitHub repos that add capabilities like browser automation or PDF parsing.

Runtime isolation is strict. Each team gets its own Docker containers with a dedicated NATS messaging bus. Multiple teams run simultaneously, each focused on a different project. Providers include Claude Code and OpenCode. You pick per team when creating it. No lock-in to one lab.

Triggers cover both time and events. Schedules run cron-based recurring tasks with run history tracking. Define a prompt, pick frequency, AgentCrew deploys the team, executes and records results. Webhooks trigger teams from external systems via HTTP with token-authenticated endpoints and prompt templates. Post-actions fire reusable HTTP callbacks after webhook or schedule runs to notify Slack, Linear or your API.

External tools connect via MCP servers. Databases, APIs, Kubernetes, Freepik image gen, Slack. The official example wires a Content Strategist with Freepik MCP plus Slack MCP on a Mon/Tue/Fri 09:00 schedule to ship 3 LinkedIn posts per week with custom images and Slack review pings. Concrete. Useful. Copy-pasteable.

For teams comparing durable orchestration options, our Orkes vs Temporal vs Step Functions orchestration showdown maps where a durability engine fits versus a team orchestrator. AgentCrew sits above that layer. It coordinates who does what. Temporal-style replay sits below for crash recovery. Different jobs.

graph TD
  A[Schedule cron 09:00 or Webhook HTTPS + token] --> B[Leader reads CLAUDE.md + team context]
  B --> C[Leader delegates via NATS bus]
  C --> D[Content Strategist: Freepik MCP image]
  C --> E[Copywriter: draft post]
  D --> F[Reviewer: brand check]
  E --> F
  F --> G[Post-Action: Slack notify + API callback]
  G --> H[Run history recorded]

Step 1: Self-hosted install and team scaffold

One command. Real output below from my VPS.

curl -fsSL https://agentcrew.sh/install.sh | bash
agentcrew --version
agentcrew team init marketing-crew --provider claude-code
ls marketing-crew/

Expected layout:

marketing-crew/
  CLAUDE.md
  agents/
    content-strategist.md
    copywriter.md
    reviewer.md
  schedules.yaml
  webhooks.yaml
  mcp.json
  .env

File: docker-compose.yml

services:
  agentcrew-api:
    image: helmcode/agentcrew:1.4.2
    restart: unless-stopped
    env_file: .env
    ports:
      - "8080:8080"
    volumes:
      - ./marketing-crew:/teams/marketing-crew:ro
      - crew-data:/data
    depends_on:
      - nats
  nats:
    image: nats:2.10-alpine
    command: "-js -m 8222"
    volumes:
      - nats-data:/data
volumes:
  crew-data:
  nats-data:

File: .env

ANTHROPIC_API_KEY=sk-ant-xxx
AGENTCREW_ADMIN_TOKEN=change-me-32-chars-min
NATS_URL=nats://nats:4222
DEFAULT_PROVIDER=claude-code

First war story. I left AGENTCREW_ADMIN_TOKEN as the default changeme on a staging box with port 8080 open. Within 36 hours our webhook endpoint received 412 spam triggers from scanners replaying prompt templates. Each trigger spun a Claude Code worker. Our Anthropic bill jumped $182 before I caught it at 2am. Short lesson. Don't do this. Rotate tokens, bind to Tailscale, require bearer auth on every webhook. I now generate 48-char tokens and store them in Vault.

Step 2: Define agents in Markdown, wire MCP and schedules

File: marketing-crew/CLAUDE.md

# Marketing Crew Leader

You coordinate a 3-worker content team. Break every request into
research, draft and review phases. Delegate via NATS, never execute
tools directly. Require reviewer approval before post-actions fire.

Delegation protocol:
1. Parse schedule or webhook payload for topic + audience.
2. Assign image brief to @content-strategist with Freepik MCP.
3. Assign draft to @copywriter with 280-word limit.
4. Assign brand check to @reviewer. Block on rejection.

File: marketing-crew/agents/content-strategist.md

---
name: content-strategist
model: claude-sonnet-4-5
skills: [freepik-image-gen, slack-notify, web-search]
---

You are a B2B content strategist for AI infrastructure.
Produce one image brief per post: subject, palette #0A0F1E + #00E5A0,
16:9 composition, no text overlay. Call Freepik MCP with
`aspect=16:9, style=editorial`. Return image URL + alt text.
Reject vague briefs. Ask the leader for audience and CTA first.

File: marketing-crew/mcp.json

{
  "mcpServers": {
    "freepik": {"command": "npx", "args": ["-y", "freepik-mcp", "--api-key", "${FREEPIK_KEY}"]},
    "slack": {"url": "https://mcp.slack.com/mcp", "auth": "bearer:${SLACK_MCP_TOKEN}"}
  }
}

File: marketing-crew/schedules.yaml

- name: linkedin-triple
  cron: "0 9 * * 1,2,5"
  prompt: "Ship 3 LinkedIn drafts on AI agent evals for CTOs with images"
  team: marketing-crew
  post_actions: [slack-review-ping]

Trigger manually:

curl -X POST https://crew.example.com/hooks/linkedin \
  -H "Authorization: Bearer $AGENTCREW_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"topic":"LLM-as-judge evals","audience":"CTOs","mode":"wait-for-response"}'

When we benchmarked setup time on our test cluster, AgentCrew took 22 minutes from install to first scheduled run. Comparable CrewAI crew took 68 minutes with venv, API keys and flow wiring. LangGraph equivalent took near two hours with explicit state modeling. That 68% setup saving is real for Markdown-shaped teams.

Human gating matters here. AgentCrew pauses workers where approval is required, similar to signal-based patterns we run in human-gated approvals with Temporal signals that wait for days. The difference is granularity. Temporal signals gate durable steps for days. AgentCrew gates team handoffs for minutes to hours. Use both when money moves.

Second war story. Pydantic-style frontmatter parsing bit me. I added skills: [freepik-image-gen, slack-notify] plus a trailing priority: high field the loader did not expect. The worker loaded with empty skills and silently skipped image gen for 4 scheduled runs. No error. Just text-only posts. I traced it to strict YAML schema dropping unknown keys without warning. Pin your agent file schema, add a CI check that asserts required skills resolve, and log loaded skills at boot. Twenty minutes of validation saves a week of bland output.

Step 3: Scale to Kubernetes, observe and control costs

Docker Compose handles dev and single-tenant prod. For multi-team scale, move to Kubernetes with one namespace per team and a shared NATS cluster with per-team subjects. I run 6 teams on a 4-vCPU node with 16GB RAM. Idle footprint is 1.8GB. Burst during 3 parallel image-gen runs hits 11GB. Set memory limits per worker or one Freepik batch OOMs the node. I learned that when a Monday 09:00 triple-fire evicted the reviewer pod mid-approval.

Verification checklist I run before marking a crew production-ready:

1. Double-fire test: trigger the same webhook twice within 5 seconds, assert idempotency key dedupes to one run history entry.
2. NATS partition test: kill NATS for 30 seconds mid-run, assert leader re-queues delegation and zero tasks vanish.
3. Cost cap test: set per-team token budget at 400k tokens/day, assert schedule pauses and Slack alerts fire instead of silently spending.

Token math from our runs: a 3-agent LinkedIn triple averages 24k input + 6k output tokens at Claude Sonnet rates. At 12 runs per week that is $18 to $26/mo in model spend. The $182 spam incident dwarfed legitimate spend. Auth and budgets matter more than model choice at this scale.

High-volume router patterns still belong in code. Our Lyft self-serve LangGraph router for millions of requests with sharded routing and Redis semantic cache cut p95 from 9.2s to 3.1s. I copy that cache key scheme into AgentCrew post-actions when webhook volume exceeds 20 req/min. Markdown teams for cognition, coded routers for scale.

When NOT to use this pattern

Let's be clear. Markdown orchestration trades control for speed.

Skip AgentCrew if you need deterministic replay after crashes. NATS re-queues messages, but it does not replay Python call stacks like a durability engine. For money-moving approvals that must survive datacenter loss, pair it with the Temporal HITL cookbook approval signals underneath. I run that hybrid for billing crews.

Skip it if your compliance team bans AGPL-3.0 network copyleft or requires SOC 2 attestation on the control plane. Self-hosted AGPL triggers legal review at most enterprises. Budget two weeks for that conversation.

Production bottlenecks I hit: NATS JetStream disk grew 18GB in 30 days with full payload persistence; webhook prompt templates over 8k chars inflate every run cost; Freepik MCP rate limit is 30 req/min which serializes parallel image briefs; leader delegation loops if two workers both claim reviewer role. Fix with strict role names, 21-day retention, template linting and single reviewer ownership.

Bottom line: for docs-driven teams that change weekly, AgentCrew is the fastest path I have tested in 2026 from idea to scheduled crew. Define the mission in Markdown. Let NATS and MCP do the plumbing.

By Deepak Bagada, Founder & Editor-in-Chief at Daily AI World. I build agentic workflows and high-concurrency SaaS platforms at SaaSNext. Follow my benchmarks on <a href="https://x.com/deeepakbagada">X @deeepakbagada and <a href="https://deepakbagada.in">deepakbagada.in.