Shannon AI: a Go multi-agent orchestration framework you run yourself

What Shannon AI is for, and who should run it

Shannon AI is a multi-agent orchestration framework aimed at teams that want agent workflows in their own infrastructure rather than behind someone else's API. The repository describes it as production-oriented, and the feature list reads like a list of operational complaints: agents that fail without explanation, costs that grow without a ceiling, no visibility into what a run did, and code execution that needs isolating. The README frames each of those as a named solution, from Temporal workflows for replay to hard token budgets per task or agent with automatic model fallback.

The audience is narrow but clear. You need Docker and Docker Compose, and you need an API key for at least one LLM provider. The project supports OpenAI, Anthropic, Google, DeepSeek, xAI, Qwen and local models through Ollama, and it also accepts any OpenAI-compatible endpoint. If your team already operates PostgreSQL, Redis and Temporal, the marginal cost of adding Shannon is mostly configuration. If you have never run Temporal, the architecture diagram is the honest description of what you are signing up for: a Gateway in Go, an Orchestrator in Go, an Agent Core in Rust and an LLM service in Python, with four backing stores underneath. That is a platform, not a library.

How the Gateway, Orchestrator and Agent Core split the work

The architecture is a pipeline with explicit handoffs. A client request reaches the Gateway on port 8080, which handles REST, authentication through JWT or API key, and rate limiting. The Orchestrator on port 50052 takes over for task decomposition and budget management, and it is the layer that runs Temporal workflows. The Agent Core on port 50051 is written in Rust and acts as an enforcement gateway: WASI sandboxing, token counting and a circuit breaker live here. The LLM service on port 8000 handles provider abstraction, MCP tools and the agent loop, while a separate Playwright service on port 8002 does browser automation.

The interesting design choice is that enforcement sits in Rust rather than in the Python agent loop. Token counts and sandbox boundaries are checked below the layer that talks to providers, so a misbehaving agent loop cannot simply ignore the budget. The trade-off is that any new capability has to be threaded through four languages. The README's own table of execution strategies shows how much routing logic the Orchestrator carries: complexity below 0.3 goes to a single-agent Simple path, multi-step tasks default to a DAG with fan-out and fan-in, and ReAct, Research, Exploratory, Browser Use, Domain Analysis and Swarm are selected by task characteristics. Research mode is documented as using tiered models for cost optimization, with a stated 50-70% reduction. The README states that figure; it is not something this article measured.

Installing Shannon AI with the one-command script

The README gives a single install command that downloads configuration, prompts for API keys, pulls Docker images and starts services. It assumes Docker and Docker Compose are already present.

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash

You will be prompted for at least one provider key. The README lists OPENAI_API_KEY and ANTHROPIC_API_KEY as the common choices, and notes that any OpenAI-compatible endpoint works. Two optional keys improve web tasks: SERPAPI_API_KEY for search and FIRECRAWL_API_KEY for fetching.

If you prefer to work from a clone, the Makefile defines a two-step path. `make setup` runs `setup-env` and `proto-local`, which copies .env.example to .env and symlinks it into deploy/compose. The Makefile itself prints the remaining steps: add API keys, run ./scripts/setup_python_wasi.sh for Python code execution, then start services.

make setup
make dev
make smoke

`make dev` brings up the stack without browser automation and prints the Temporal UI address, which the Makefile gives as http://localhost:8088. `make dev-browser` adds Playwright and Chromium, and the Makefile notes that variant is roughly 3.4GB. `make smoke` is the check that the setup works. If the symlink is missing, `make check-env` fails with an explicit message telling you to run `make setup-env`.

Your first Shannon AI task through the REST API

Once the stack is up, the Gateway is the entry point. The README's first example submits a task and then streams its events.

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the capital of France?", "session_id": "demo"}'

curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=<task_id>"

The first call returns a task identifier; you substitute it for `<task_id>` in the second call, which holds the connection open and emits server-sent events. That streaming endpoint is the practical way to watch a run, and it pairs with the replay tooling in the Makefile (`replay`, `replay-export`, `ci-replay`) for inspecting an execution afterwards.

If you would rather not hand-roll HTTP, the project publishes a Python SDK. The README shows the install and a short client session.

pip install shannon-sdk

from shannon import ShannonClient

with ShannonClient(base_url="http://localhost:8080") as client:
    handle = client.submit_task("What is the capital of France?", session_id="demo")
    result = client.wait(handle.task_id)
    print(result.result)

There is also an OpenAI-compatible surface. Setting OPENAI_API_BASE to http://localhost:8080/v1 is documented as letting existing OpenAI client code run unchanged. That is the lowest-friction way to point an existing script at Shannon.

Forcing research and swarm strategies on a task

Strategy routing is automatic, but the README exposes overrides through the task context. A research task sets force_research and a research_strategy, and a swarm task sets force_swarm.

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Compare renewable energy adoption in EU vs US",
    "context": {"force_research": true, "research_strategy": "deep"}
  }'

The swarm variant uses the same field pattern with force_swarm set to true. The README describes the Swarm strategy as a lead-orchestrated multi-agent team with convergence detection, which is the part worth understanding before you rely on it: a lead agent coordinates and the run ends when convergence is detected, so the stopping condition is model-driven rather than a fixed step count.

Skills are a lighter-weight extension point. The README shows listing them and attaching one to a task by name.

curl http://localhost:8080/api/v1/skills
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "Review the auth module", "skill": "code-review", "session_id": "review-123"}'

Custom skills go in config/skills/user/, a directory the README notes is gitignored and may need creating. The skills documentation is linked as docs/skills-system.md.

Where Shannon AI is the wrong choice

The strongest limitation is stated in the project's own .env.example, not in a caveat buried elsewhere: OPENAI_API_KEY is required for memory features, because text embeddings come from OpenAI. Without it, the file says, semantic search and agent memory are disabled and agents operate in stateless mode. Shannon will still run. So a team that standardizes on Anthropic or a local Ollama model for cost or data-residency reasons gets a working orchestrator with a degraded memory layer unless they also hold an OpenAI key. That is a real architectural coupling, and it sits awkwardly next to the README's vendor lock-in row, which lists OpenAI, Anthropic, Google, DeepSeek, xAI and Ollama as interchangeable.

The second constraint is operational weight. Four services, PostgreSQL, Temporal and Redis, plus an optional Playwright image around 3.4GB, is not something you drop into a laptop and forget. The README does link platform-specific guides for Ubuntu, Rocky Linux and Windows, which suggests the maintainers know first-run setup varies by OS. The README does not document rollback or downgrade between releases, so if you need a supported upgrade path you should verify it yourself before depending on it. Finally, if your problem is a single prompt-response call, none of this machinery earns its keep; the Simple strategy exists, but you are still running the full stack to reach it.

Shannon AI compared with a plain workflow engine

The closest alternative is not another agent framework but a general workflow engine such as Temporal used directly, or an orchestration library like LangGraph. The difference in approach matters. With a workflow engine alone you write your own agent loop, your own token accounting and your own sandbox, and you get durable execution without opinions about LLM providers. Shannon AI ships those opinions: the enforcement gateway in Rust, the tiered model selection in Research mode, the WASI sandbox, OPA policies and the multi-tenant isolation described in the README. You trade flexibility at the edges for a working default at the center.

LangGraph-style libraries sit at the opposite end. They are embedded in your Python process, so there is no Gateway, no Temporal and no separate ports to manage. The cost is that durability, replay and budget enforcement become your responsibility. Shannon's Makefile targets for replay and CI replay are the concrete expression of that difference: the project treats a past execution as an artifact you can re-run, which is hard to replicate on top of an in-process library without building the same persistence layer. If you already have Temporal and a strong opinion about your agent loop, you will find Shannon's Orchestrator duplicating decisions you have made. If you do not, it is a substantial head start.

Licence, maintenance and what upgrades cost

Shannon AI is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The repository includes a LICENSE file at the top level. This is a permissive licence with no copyleft obligation and no source-disclosure requirement for your own code. It says nothing about the licences of the backing services you will run alongside it, and Temporal, PostgreSQL and Redis each carry their own terms, so a deployment review should cover the whole stack rather than just this repository. Nothing here is legal advice.

The maintenance picture is current rather than historical. The repository is not archived, and the last push was on 2026-09-05, which is recent. The latest release listed is v0.5.1 from 2026-06-02, with v0.5.0 the same day and v0.4.1 on 2026-04-04. That cadence suggests active work between releases, though the gap between the June release and the September push means main has moved ahead of the tagged version.

Upgrade cost is where the multi-language split shows up. There are Go, Rust and Python components plus protobuf definitions under protos/, and the Makefile includes proto and proto-local targets, so a source build involves regenerating protocol code before the services will talk to each other. Container-based installs avoid that, but you inherit image pulls. The Makefile also carries coverage targets for Go and Python separately, which reflects the same split.

Editorial conclusion

Shannon AI fits teams that already run Docker and Temporal-style infrastructure and want replayable, budgeted agent runs they host themselves. It does not fit anyone who wants a managed endpoint or a single-binary tool, since the stack spans four services plus PostgreSQL, Temporal and Redis. Before adopting, check that your machine has room for the images (the browser variant is around 3.4GB), that your provider keys are set, and that your use case survives the caveat in .env.example: without OPENAI_API_KEY, semantic search and agent memory are disabled.

Frequently asked questions

Official sources

1. Kocoro-lab/Shannon on GitHub
2. License: MIT
3. Project website
4. README
5. Releases