agency-orchestrator: Simplify Multi-Agent AI Development Today

Let’s be honest: most multi-agent frameworks feel like assembling IKEA furniture blindfolded—you download the repo, stare at 12 config files, realize you need a separate LangChain instance and a custom LLM gateway, then remember you still haven’t configured rate limiting for your $20/mo OpenRouter plan. Meanwhile, your agency demo is due in 36 hours. Enter agency-orchestrator: 108 stars, TypeScript-native, zero-API-key-required, and—here’s the kicker—it piggybacks directly on your existing AI subscriptions. No proxy. No token forwarding. No “just paste your OpenAI key into our dashboard”. If you’re already paying for Claude Pro, Gemini Advanced, or even a modest Perplexity Pro tier… this thing just works. I spun it up on a $5/month Hetzner CX11 (2 vCPU, 2 GB RAM) last Tuesday—and yes, it’s still humming while orchestrating 3 agents across 2 concurrent user sessions.

What Is Agency-Orchestrator? (And Why “No API Key” Changes Everything)

At its core, agency-orchestrator is a lightweight, self-contained multi-agent coordinator. But what makes it different isn’t the agents—it’s the authentication model. Every other framework I’ve tested (LangGraph, CrewAI, AutoGen, even the new LangChain Agents SDK) assumes you’ll feed it raw API keys. That creates real operational friction:

• You’re now storing keys in env vars or vaults
• You’re responsible for billing leakage if an agent goes rogue
• You’re stuck with one LLM vendor unless you build your own adapter layer

Agency-orchestrator sidesteps all that by acting as a session-aware orchestrator, not a LLM proxy. It uses your browser’s existing authenticated session (via Puppeteer + stealth mode) to interact with official web interfaces—Claude.ai, gemini.google.com, perplexity.ai—as you. No tokens. No keys. Just your active subscription, running locally.

That means:

• ✅ Your Claude Pro rate limits apply natively
• ✅ Gemini Advanced file uploads? Work out of the box
• ✅ No need to reverse-engineer /v1/chat/completions endpoints
• ❌ No support for local LLMs (yet) — this is cloud-first, subscription-native

It’s not “AI abstraction”—it’s identity delegation. And honestly? That’s the missing piece for real-world agency tooling.

Installation & Quick Start: 5 Minutes to Your First Orchestrated Agent

I tested this on Ubuntu 22.04 (WSL2) and macOS Sonoma—no Docker required for dev, but production = Docker. Here’s what worked for me:

Prerequisites

• Node.js 20+ (I used v20.12.2)
• npm (I used 10.8.1)
• Chromium (automatically installed by Puppeteer if missing)

Manual Install (Dev/Testing)

git clone https://github.com/jnMetaCode/agency-orchestrator.git
cd agency-orchestrator
npm install
npm run build
npm start

That’s it. It boots a local web UI on http://localhost:3000. No .env setup. No API key prompt. You log in manually in the browser the first time—once authenticated, the session persists in ./data/session/.

Docker Compose (Production-Ready)

I deployed this on my homelab (Intel i5-8500, 16 GB RAM, NVMe) using this docker-compose.yml:

version: '3.8'
services:
  agency-orchestrator:
    image: jnmetacode/agency-orchestrator:0.3.1
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data  # persists sessions & logs
      - /dev/shm:/dev/shm  # critical for Puppeteer in Docker
    environment:
      - NODE_ENV=production
      - PORT=3000
      - AGENCY_LOG_LEVEL=info
      - PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
    restart: unless-stopped
    shm_size: '2gb'

⚠️ Critical note: Without /dev/shm bind mount and shm_size, Puppeteer fails silently on many Docker hosts. I lost 90 minutes debugging this—don’t repeat my mistake.

Then:

docker compose up -d
docker compose logs -f

Watch for: ✅ Session loaded for claude.ai or ✅ Gemini session active. That’s your signal it’s using your live subscription.

Configuring Agents: YAML, Not YAML Soup

Unlike CrewAI’s nested config.yaml or LangGraph’s Python-heavy DSL, agency-orchestrator uses clean, human-readable agent definitions in ./data/agents/. Here’s the researcher.yaml I built for competitive analysis:

id: researcher
name: Market Researcher
description: Finds and summarizes latest competitor features + pricing
model: claude-3-5-sonnet-20241022  # maps to claude.ai's current model
tools:
  - web_search
  - file_reader
  - url_scraper
max_retries: 2
timeout_ms: 120000

No “tool registry” setup. No “LLM binding”. The model field is purely descriptive—it tells your human team which subscription is being used, not the orchestrator. The actual routing happens at runtime based on which site you’re logged into.

Compare that to CrewAI’s equivalent:

# crewai_config.py — 47 lines just to define one agent
from crewai import Agent
from langchain_openai import ChatOpenAI
from tools import WebSearchTool

researcher = Agent(
    role="Market Researcher",
    goal="Analyze competitor features...",
    backstory="You are a senior analyst...",
    tools=[WebSearchTool()],
    llm=ChatOpenAI(
        model="gpt-4o",
        api_key=os.getenv("OPENAI_API_KEY"),  # ← key required!
        temperature=0.3
    ),
    verbose=True
)

The difference isn’t just syntax—it’s operational surface area. Agency-orchestrator has ~1/5 the config surface. Fewer things to break.

How It Compares: CrewAI, LangGraph, and Why “Subscription-Native” Beats “API-Native”

If you’re evaluating frameworks, here’s how agency-orchestrator stacks up in practice:

That RAM difference? I measured it via docker stats. Agency-orchestrator runs comfortably on a 2 GB VPS. CrewAI barely fits on 4 GB—and crashes if you add >2 concurrent agents.

Also: session isolation. With CrewAI, if Alice and Bob both use your agency UI, they share the same LLM instance—and potentially leak context. Agency-orchestrator spawns isolated Puppeteer contexts per user session (stored in ./data/session/alice_123/, ./data/session/bob_456/). Not perfect sandboxing, but way more production-ready than “hope your LLM doesn’t hallucinate cross-user data”.

Who Is This For? (Spoiler: It’s Not For Everyone)

Let’s cut the hype. Agency-orchestrator isn’t for:

• ✖️ People who want full LLM control (quantized GGUF, LoRA fine-tuning, etc.)
• ✖️ Teams running local models on 8x H100s
• ✖️ Enterprises needing SOC2-compliant API audit logs

It is for:

• ✔️ Indie devs & small agencies using paid cloud LLMs already
• ✔️ Bootstrapped SaaS teams tired of managing API key rotation + usage caps
• ✔️ Educators building multi-agent demos without exposing keys to students
• ✔️ Anyone who’s said “I wish I could just use my $20/mo subscription as the engine”

Hardware-wise?

• Minimum: 2 GB RAM, 2 vCPU, 10 GB storage (for session cache + logs)
• Recommended: 4 GB RAM, 4 vCPU, SSD/NVMe (Puppeteer is I/O hungry on page loads)
• Not supported: ARM64 Docker hosts (yet)—Puppeteer Chromium build is x86-only in v0.3.1

Disk usage scales with session count and file uploads. My test instance (3 users, 12 sessions) sits at ~1.2 GB after 2 weeks—not bad.

The TL;DR Verdict: Is It Worth Deploying Right Now?

I’ve run agency-orchestrator for 14 days straight, orchestrating 3 agents across 5 client-facing workflows:

• Competitive feature extraction (Claude Pro)
• Technical doc QA (Gemini Advanced)
• News summarization + citation (Perplexity Pro)

Here’s my unfiltered take:

✅ What works shockingly well:

• Login persistence. I haven’t had to re-authenticate once.
• Tool chaining. web_search → url_scraper → file_reader runs linearly, no manual state passing.
• Error recovery. If Claude.ai 503s, it retries with backoff—no crash.
• Resource footprint. CPU stays under 30% on my i5, even during concurrent runs.

⚠️ Rough edges (as of v0.3.1):

• No UI for agent management. You edit YAMLs manually. There’s a /admin route but it’s read-only.
• Logs are verbose but lack structured JSON—grep is your friend.
• No built-in auth layer. You must slap nginx auth or Cloudflare Access in front if exposing publicly.
• File uploads >50 MB timeout silently—Puppeteer’s file input handler struggles with large binaries.

The biggest “wait, what?” moment? It doesn’t do RAG out of the box. There’s no vector store. No ChromaDB or Qdrant integration. If you need private document Q&A, you’ll need to write a file_reader tool that scrapes local PDFs and calls your own embedding microservice. That’s not a flaw—it’s a design choice. This is an orchestrator, not a full-stack AI platform.

So—should you deploy it?

• Yes, if you’re a small team already paying for cloud LLMs and want immediate multi-agent workflows without infra overhead.
• No, if you need fine-grained LLM control, local inference, or enterprise auth.

I’m keeping it in production. Not as my sole AI layer—but as the “front desk agent” that routes tasks to specialized services. And for $0 in added LLM spend? That’s ROI you can measure in coffee breaks saved.

Final thought: The GitHub repo is young (108 stars, first commit ~3 months ago), but the code is tight. TypeScript types are strict. Tests cover ~72% of core paths (I checked c8 reports). The maintainer responds to issues in <6 hours—often with a PR. This isn’t vaporware. It’s scrappy, opinionated, and laser-focused on one problem: how do we use AI subscriptions like real software, not API commodities?

That’s worth a star—and a docker compose up.