Developers
build tools
Tools are versioned capabilities with clear inputs and outputs: Python, or any command. Built once, reused everywhere.
Version 1.2.0: now with agent tools (MCP)
Take your AI workflows backfrom the providers.
Azathoth is an open-source engine that runs AI workflows as durable, versioned specifications, and improves them only from evidence. You own the workflow. Every change is proven before it ships.
pip install azathoth-ai
The bet
Models answer prompts. The engine does the rest.
In most AI systems, the model drives: it decides what to do next, calls tools, and talks to the user. That makes it hard to see what happened, harder to swap models, and impossible to measure.
Azathoth flips that. The engine holds the full context, runs the tools itself, and gives each model only what its step needs. Models never act as agents and never change the workflow.
So every step is observable, swappable and measurable, and that is what makes evidence-driven optimization possible.
How it works
Six stages. One record of everything.
Each stage is kept separate: a specification never mixes with its evidence, and nothing but promotion grants production authority. Every value a step saw can be traced to the step that produced it.
- 01
Compose
Workflows are plain documents of steps and tools. No application code.
- 02
Run
The engine runs every step itself and records exactly what each model saw.
- 03
Benchmark
Score the workflow against your real cases for quality, speed and cost.
- 04
Optimize
Try cheaper compatible models, step by step. Evidence picks the winner.
- 05
Promote
Deliberately make the winner the production version, with an audit record.
- 06
Invoke
Production runs exactly what was promoted, whether the call comes from the CLI, a queue, or an AI agent.
Every stage writes to one append-only evidence store
Who does what
AI work moves out of application code and into operations.
Domain experts
compose workflows
Experts and analysts assemble workflows from those tools as plain JSON documents, then test them, without writing code.
Platform teams
run the show
Run, benchmark, optimize, promote and operate everything from the command line, like any other production service.
What ships in 1.2.0
Ready to run today.
Everything below is in the current release, open source and installable now.
New in 1.2.0
Agents (MCP)
- Promoted workflows served as MCP tools
- OAuth 2.1 resource server with a scope per tool
- Every invocation audited with its caller
- Progress notifications as each step finishes
Composition
- Steps that run in parallel, with results recorded in a fixed order
- Routing on conditions, so each case goes to the right specialist
- Retries, fallbacks and failure policies per step
- Workflows that call, loop over, and fan out to other workflows
Models
- Hundreds of models through OpenRouter, plus Amazon Bedrock
- An approved model list your organization controls
- Mix models step by step: the cheap one where it's enough
- Explicit failover to named substitutes if a model goes offline
Evaluation
- Benchmarks built from real cases, versioned like code
- Four ways to score: exact, normalized, schema, or AI judge
- Thumbs-up and thumbs-down feedback on real runs
- Failed runs score zero, so broken never looks cheap
Optimization
- Searches for strictly cheaper models that hold quality
- Keeps today's version in every round for a fair comparison
- Every experiment saved for inspection
- Never deploys on its own. Promotion is always explicit
Production
- A versioned JSON job interface: one request in, one result out
- Idempotent invocations, so retries never double-run
- Interrupted runs resume where they stopped
- Files of any size, split and processed in parallel
Operations
- Every operation available from bash
- Append-only history; revert by re-importing
- SQLite on a laptop, PostgreSQL in production
- OpenTelemetry tracing that never carries content
First-class on AWS
A better home for AI workflows than Step Functions.
Azathoth works with Amazon Bedrock models, an SQS queue worker, S3 inputs and PostgreSQL, and adds what Step Functions doesn't have: model choice, benchmarking and optimization.
A CloudFormation template for AWS Fargate is included, with job queues, an encrypted evidence bucket, least-privilege access and autoscaling workers.
End-to-end AWS validation of the template is in progress.
- Amazon Bedrock
- SQS worker
- S3 inputs
- PostgreSQL
New in 1.2.0 · Agents (MCP)
Give agents your workflows, not your keys.
azathoth-mcp serves your promoted workflows as tools for AI clients: Claude Desktop, your IDE, or your own agents. It's Azathoth's promotion rule, extended to agents. Nothing runs that wasn't promoted. Nothing is exposed that wasn't listed.
- 01
Only promoted workflows run
Each call runs the active production revision. The server won't start if a listed workflow hasn't been promoted, and re-promoting takes effect without a restart.
- 02
Only what you list is exposed
You choose each workflow, its tool name and the description the model sees. There is no "run anything" tool, and promotion and optimization are never offered.
- 03
One scope per tool
Tokens come from your own identity provider, and a caller sees only the tools its token allows.
- 04
Every call recorded with its caller
Each invocation records who called and how. One lookup shows the input, the outcome and every step of the run.
- 05
Retries never double-run
Repeating a call with the same idempotency key returns the recorded result, and interrupted calls resume where they stopped.
Local · stdio
One person, one client
For a single local client such as Claude Desktop. It uses the same environment as the CLI, and the guide covers setup on macOS and Windows.
Team · Streamable HTTP
One shared server, behind your identity provider
Usually on PostgreSQL, in front of Entra ID, Okta, Cognito or Keycloak. It accepts only signed, unexpired tokens issued for this server and never issues tokens itself. Without an identity provider, it only listens on the local machine.
pip install azathoth-mcpazathoth-mcp serveCallers pass inline values only. The server never reads files or references on a caller's behalf.
The difference
Measurement, versioning and deployment are part of the architecture.
| Azathoth | The typical alternative |
|---|---|
| The engine owns the flow; models only answer prompts | The model drives the loop as an agent |
| Agents see only the tools an operator listed, scoped per caller, with every call audited | Agents get broad API keys or an ungoverned MCP server |
| Workflows composed as documents from tools | Workflows written as application code |
| Every step recorded: model, tokens, cost, attempts | Logs, if someone added them |
| Benchmarks, judges and optimization built in | Separate evaluation tools, bolted on |
| Changes proven on a benchmark before promotion | Prompt and model swaps go straight to production |
| Mix models per step, with explicit failover | One provider per app; an outage means downtime |
| Interrupted runs resume from a journal | Restart from scratch |
| Same engine on a laptop and on AWS | Separate stories for development and the cloud |
Examples that ship
See it work.
Real, runnable workflows come in the box, from small learning examples to a workflow that writes other workflows.
Code review
Three reviewers run at once (security, correctness, readability), and a lead reviewer steps in only when there are findings.
Ticket triage
Each ticket is routed to exactly one of four specialists, policy-checked, and escalated to a stronger model when confidence is low.
Novel writer
Plans, outlines and writes a book, each chapter through its own edit-and-verify loop until the story ends.
Workflow writer
A workflow that writes, and validates, new Azathoth workflows.
Large files
Counts words across a file of any size in S3 by splitting it and processing the pieces in parallel.
The basics
Prompts, sentiment, redundant producers, loops and maps: small examples to learn from.
The operating rule
Configure explicitly. Execute empirically. Optimize without hidden deployment. Promote deliberately. Invoke exactly what production state says to invoke.
Coming next
Where Azathoth is headed.
Planned, not yet released. Follow along on GitHub.
Coming
PDF and multimodal input
Planned for 1.3, starting with PDFs.
Coming
MCP server in the AWS template
Run the agent server from the same CloudFormation stack as the workers.
Coming
Cthulhu
A paid optimizer that improves prompts, structure and escalation, not just model choice.
Coming
A visual interface
Compose and test workflows without the command line.
Get started
Install in one line.
Built in public, solo, from August 1, 2026 to 1.2.0in just over three months, with more than a hundred architecture decision records and every provider faked in tests.
pip install azathoth-aipip install azathoth-mcpReleased together, always at the same version.
- Optional extras
[postgres][bedrock][worker][otel]- Container
ghcr.io/eldritchinc/azathoth:1.2.0amd64 and arm64, cosign-signed; includes the CLI, queue worker and MCP server- Platforms
- macOS, Linux, Windows · Python up to 3.13
- Storage
- SQLite by default, PostgreSQL 15+
Want a hand?