Mycelium

The reliability layer for AI agents.

Mycelium checks tool calls before execution, controls retries and run limits, and records outcomes for recovery. It is for agents that send messages, charge payments, write data, or change external systems. Only calls routed through Mycelium are protected; each control must be configured and wired into the application.

Python applications use the runtime directly. Other languages connect through the experimental HTTP/JSON sidecar. The Python API follows semantic versioning; the v1alpha1 sidecar protocol is not yet a stable production contract.

Early design-partner use: a live outbound-email workflow recorded 25 ledgered sends and 0 duplicates in its first week. This is a limited observation from one workflow, not a general production guarantee or a public customer reference.

What it protects

Risk	What Mycelium does
Invalid or unsafe tool calls	Validates arguments, paths, destinations, and tool allowlists before execution
Expired or missing authority	Re-checks scope, destructive grants, current facts, and time-bound permissions
Duplicate or uncertain effects	Coordinates retries and concurrent workers, returns stored outcomes, and reconciles ambiguous attempts
Runaway agents	Stops repeated action loops and enforces time, step, token, and cost budgets
Stale context	Validates message, history, and state before the next action
False completion	Refuses “done” while required work remains open
Missing evidence	Records durable outcomes and optional signed receipts

Works with your stack

The engine requires Python 3.10+. Python applications use YAML, mycelium run, decorators, or the manual API, with integrations for LangGraph and CrewAI. TypeScript, Go, and other HTTP clients connect to a self-hosted sidecar running the same Python engine.

The application asks the sidecar whether an action may run, reports when the provider call may have started, and records its result. The sidecar owns action identity, claims, leases, fencing, state transitions, and recovery decisions. Clients do not reimplement those safety rules.

Published experimental clients:

npm install @mycelium-labs/sidecar-client@experimental
go get github.com/mycelium-labs/mycelium/clients/go@v0.1.1

Every other language can use the same authenticated OpenAPI contract directly. The sidecar supports a trusted loopback development profile and an explicitly selected shared PostgreSQL profile for multiple sidecars. See the protocol overview, TypeScript client, Go client, and local cross-language conformance suite.

How it works

1. The model proposes a tool call.
2. Mycelium applies the checks configured for that tool and run.
3. It either runs the tool, returns a stored result, waits, reconciles an uncertain outcome, or stops safely.
4. It records the decision and outcome for recovery and audit.

See the SDK reference for configuration details and the failure and threat model for exact guarantees and limits.

Quickstart

pip install mycelium-runtime
mycelium demo
mycelium init
mycelium run --config mycelium.yaml -- python -m my_app

mycelium init creates a starter configuration for one tool. Point it at your callable, describe whether the tool reads or changes external state, and enable the controls your workflow needs. Use SQLite for a durable single-process setup, or Redis/Postgres for multiple workers.

Prefer agent-assisted setup:

mycelium skills install

Then ask your coding agent: “Set up Mycelium in this project.” The bundled mycelium-setup skill inventories tools, updates the configuration, wires the runtime boundary, and runs Doctor and Verify.

For an unchanged sequential function whose consequential calls are already ledgered, ask the same skill to make it recoverable with Mycelium. It can add one outer composite decorator after verifying the actual callable boundaries, durable storage, and a stable host-owned operation ID. See the composite recovery guide for the supported syntax and the fail-closed behavior for opaque calls, definition drift, ambiguous child outcomes, and lost parent authority. The decorator does not discover hidden direct provider calls or make arbitrary Python control flow recoverable. It is a Python-runtime feature backed by file, SQLite, Redis, or PostgreSQL composite-control storage, not an endpoint in the language-neutral sidecar.

For non-Python applications, run the local sidecar and use the TypeScript, Go, or OpenAPI client:

mycelium sidecar serve --config /absolute/path/sidecar.yaml

See the non-Python setup for the protocol reference, or follow the self-hosting guide for complete local and shared PostgreSQL setup. Only calls routed through Mycelium are protected. See the full SDK reference for framework integrations, storage, configuration, and manual APIs.

Docs

• Handbook: https://mycelium-labs.github.io/ (website repo)
• Try in 5 minutes: https://mycelium-labs.github.io/try.html
• Sandbox demo: mycelium-labs/mycelium-labs.github.io/sandbox
• Full API reference: sdk/README.md
• Durable composite recovery: supported API and limits
• Language-neutral protocol: sdk/docs/spec/README.md
• Self-host the sidecar: local and shared PostgreSQL setup
• Experimental clients: TypeScript · Go
• Doctor vs Verify: mycelium doctor inspects configuration; mycelium verify runs synthetic failure scenarios. Neither proves a real provider is correct.
• Release policy & checklist: sdk/docs/RELEASE.md
• Security policy & private reporting: SECURITY.md
• PyPI: https://pypi.org/project/mycelium-runtime/

License

MIT. See LICENSE.

Maintainer

Mycelium is maintained by Nandana Dileep.