Hypha

An event-backed TypeScript framework that turns LLM agents into governed, durable, auditable production systems via DomainPacks.

Stars
★ 452
Last updated
5d ago
License
Apache-2.0
Primary language
TypeScript

At a glance

How it runs
Self-hosted serviceFrameworkLibrary / SDK
Works with
Universal · cross-platformOpenAI API
Cost
Free software; you pay for model usage
Setup effort
High · needs real infrastructure
You'll need
Node.js 22npmMongoDBRedisOpenAI API key (or another model provider)Shell / CLINetwork accessLocal filesystemMCP Server
Typical use
Platform teams that need internal domain agents (e.g. finance reconciliation or legal review) to be replayable and auditable
Not a fit if
  • Solo developers who want zero-infrastructure setup without MongoDB and Redis
  • Teams that only need a thin LLM script and no event-sourced recovery
  • Small teams unwilling to own policy, approval, and cache-consistency runtime duties
Website
codesoul-co.github.io/Hypha ↗ set on GitHub
Maintenance
Commits in the last 30 dayslast commit 2026-11-15latest release v1.0.1 (2026-08-14)

What does this agent do, and when should you use it?

Hypha is an open-source TypeScript framework split into an Agent Core and a Production Harness. The Core handles ReAct reasoning, planning, tool selection, Memory access and model/context orchestration; the Harness turns those decisions into bounded, event-backed execution with FSM control, policy and approval, checkpoints, recovery, replay and audit. Product behavior is declared in a DomainPack (YAML, JSON or TypeScript) rather than hard-coded, so one runtime can be instantiated as coding, finance, legal or research agents. State is derived from Events and content-addressed Artifacts, and every cache layer is a disposable projection that can never authorize a side effect, skip policy, or advance the FSM. It ships as 15 version-aligned @codesoul-co/hypha-* npm packages alongside an Express API server and an example CLI, under Apache-2.0 for source code.

On startup the Express server composes the canonical Event authority and durable execution graph; session-command, ReAct continuation, timer, recovery and reconciliation workers run an initial sweep before readiness. A DomainPack is loaded into a DomainPackRegistry via LocalDomainPackLoader and compiled with compileDomainPackToHarnessedSystem into fsmProcess, harnessedSystem, agentPatch, bindings, sessionInitialization, dependencySnapshot and processHash. The trusted composition layer must then register Skills, bind Tool contracts to local, HTTP, plugin, execution or MCP adapters, approve exact MCP capability revisions, and persist the dependency snapshot alongside Run events. Execution follows DomainPack → validated bindings → framework-owned Harness FSM → bounded ReAct quantum → governed Tool/MCP/Memory/Execution activity → Event, receipt and Artifact evidence → projection, continuation, recovery, replay and evaluation. The HTTP API exposes /api/v1/chat and /chat/stream, /runtime/runs/:runId with events, replay, audit and regression projections, /tools, /tool-approvals, /mcp, /memory, /skills and /workflows, plus OpenAPI 3.1 generated from the mounted Express routes; the CLI offers login, chat --stream, tools, skills and workflows. Caching is layered into Serving, Thinking, WorkCache, Tool/Execution, Memory/Context and Prefix/KV, configured through HYPHA_SERVING_CACHE and HYPHA_WORKCACHE with memory, sqlite or redis stores.

  1. Platform teams that need internal domain agents (e.g. finance reconciliation or legal review) to be replayable and auditable
  2. SaaS vendors running several vertical agents on one runtime and swapping only the DomainPack
  3. Compliance-sensitive teams whose tool calls require approval, policy and durable Event/Artifact evidence
  4. Workflow owners needing long-running tasks with checkpoints, bounded recovery and human review
  5. Application developers who want to customize prompts, skills and workflows through DomainPacks instead of patching the core
  6. Infrastructure teams deploying agents on a private or local stack and reusing Redis/SQLite caches to cut cost

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
  • docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine
Environment variables
HYPHA_OWNER_PASSWORD JWT_SECRET HYPHA_LLM_DEFAULT_MODEL OPENAI_API_KEY HYPHA_MEMORY_CONFIG_PATH
Config files
.env.example .env config.yaml
Runtime
Node.js 22
Install notes cover
Docker

How do you install or deploy this agent?

You need Node.js 22 or newer, npm, MongoDB and Redis, and at least one configured model provider or reachable local model endpoint.

git clone https://github.com/CodeSoul-co/Hypha.git
cd Hypha
npm ci
cp .env.example .env

Optionally run disposable local MongoDB and Redis containers:

docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine

Configure identity and a model provider in .env; keep credentials out of config.yaml and source control:

[email protected]
HYPHA_OWNER_PASSWORD=replace-with-a-private-password
JWT_SECRET=replace-with-at-least-32-random-characters

HYPHA_LLM_DEFAULT_PROVIDER=openai
HYPHA_LLM_DEFAULT_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-provider-key

Build once and start the compiled server in a production environment:

npm run lint
npm run typecheck
npm run build
npm test
NODE_ENV=production npm start

Note that npm run test:release intentionally fails when real Memory or Execution services and credentials are unavailable.

How do you use this agent?

Start the dev server and check liveness plus the traffic gate:

npm run dev
curl -fsS http://127.0.0.1:3000/api/v1/health
curl -fsS http://127.0.0.1:3000/api/v1/ready

Log in and issue a streamed chat with the example CLI:

npm run cli -- login --email [email protected]
npm run cli -- chat "Explain the active runtime" --stream
npm run cli -- tools
npm run cli -- skills
npm run cli -- workflows

Load and compile a DomainPack as a library, then register the compiled system in your composition layer:

import {
  applyDomainAgentPatch,
  compileDomainPackToHarnessedSystem,
  DomainPackRegistry,
  LocalDomainPackLoader,
} from '@codesoul-co/hypha-domain';

const registry = new DomainPackRegistry();

await new LocalDomainPackLoader({
  directories: ['configs/domain-packs'],
}).loadInto(registry);

const domainPack = registry.get('domain.minimal', '0.0.0');
if (!domainPack) throw new Error('DomainPack not found');

const compiled = compileDomainPackToHarnessedSystem(domainPack, {
  agentRef: { id: 'agent.default', version: '1.0.0' },
  taskSchemaId: 'task.minimal',
  workflowId: 'workflow.minimal',
  sessionProfileId: 'session.local',
  memoryProfileId: 'memory.local',
});

const agent = applyDomainAgentPatch(
  {
    id: 'agent.default',
    version: '1.0.0',
    name: 'Default Agent',
    modelAlias: 'default-chat',
  },
  compiled.agentPatch
);

Narrow capabilities per workflow state, for example read-only tools plus a required skill:

states:
  - id: Research
    goal: Collect bounded evidence.
    allowedTools: [common.search]
    allowedSkills: [skill.context-enrichment]
    requiredSkills: [skill.context-enrichment]
    allowedMCPProfiles: [mcp.local]
    permissionScopes: [search.query]
    policyRefs: [policy.readonly]
    timeoutPolicy:
      timeoutMs: 30000
      onTimeout: fail
    retryPolicy:
      maxAttempts: 2

To turn on reuse, set HYPHA_SERVING_CACHE=memory|sqlite|redis and HYPHA_WORKCACHE=off|memory|sqlite|redis, and point HYPHA_MEMORY_CONFIG_PATH at a validated Memory profile set.

What are this agent's strengths and limitations?

Pros
  • Clear Core/Harness split with concrete components for FSM execution, checkpoints, recovery, replay and audit rather than prompt-level discipline
  • DomainPack is a documented product boundary: compilation yields fsmProcess, bindings and dependencySnapshot so one runtime hosts many domain agents
  • Cache layering with an explicit 'reuse without authority' invariant, including tests that cache on and off must preserve source-of-truth semantics
  • Governed tool and MCP invocation with version approval, plus per-state allowedTools, requiredSkills, timeouts and policies
  • Published as 15 version-aligned npm packages with an Express HTTP API, generated OpenAPI 3.1 and a working example CLI
Limitations
  • Requires your own MongoDB and Redis, and the production checklist adds TLS, backups and retention, which is heavier than a single library
  • Wide configuration surface across DomainPack, config.yaml, tools.yaml, memory-profiles.yaml and many env vars; misconfiguration can fail readiness
  • Release acceptance expects real Memory and Execution providers and fails by design without credentials, so verification costs real setup
  • Brand assets are excluded from Apache-2.0, so forks and third-party products must rebrand
  • Only an OpenAI model example is shown in the quickstart; other providers need your own configuration and verification

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
Hypha This agent 55 · Major gaps Self-hosted serviceFree + model costs ★ 452 5d ago TypeScript OpenAI API
RocketRide 84 · Good — ★ 20k today Python —
Swarm 47 · Major gaps Agent plugin / skillFree ★ 754 6mo ago TypeScript Claude Code
Kun Workspace 57 · Major gaps Desktop appFree + model costs ★ 6.4k 5d ago TypeScript ChatGPT · Codex · OpenAI API · Claude API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
55/ 100 5-point scale 2.8 / 5
Trust 18/29
Reliability 8/14
Adaptability 10/18
Convention 10/18
Effectiveness 6/13
Verifiability 3/8
Why each dimension lost points
Trust18 / 29 · 3.1/5

least_privilege: README and tool-mcp-security.md require tool/MCP/file/execution writes to pass policy, approval, idempotency and harness boundaries, and DomainPacks need explicit registration before gaining runtime authority — a documented least-privilege design (2). user_confirmation: docs state write/irreversible capabilities require explicit policy and may require approval, but the sample shows no concrete approval UI or default-deny logic, only documentation assertions (2). data_flow_transparency: README describes Event/Artifact/receipt as source of truth and cache as non-authoritative, with clear layering (2). sensitive_data_handling: the security guide requires credentials outside ToolSpec/DomainPack, forbids auth headers or sensitive paths in events, and mandates auditPolicy.redactPaths; tests verify DLQ records are redacted. However the framework ships no secret manager, leaving that to deployment (2). dependency_security: package.json has an npm audit script and CI runs npm run audit and test:audit-policy, with some pinned versions; but the dependency surface is large and no audit results are provided, so absence of known vulnerabilities cannot be confirmed (2). external_effects: the security guide distinguishes none/read/write/external_effect/irreversible and requires idempotency or receipt reconciliation; known limitations note interrupted writes become conflict without a reconciler (2). rollback: checkpoint, recovery, replay, legacy migration rollback modules and a RecoveryTree exist, but no end-to-end rollback drill is shown in the sample (2). source_attribution: README cites benchmark results without reproducible scripts or data links; the Skill asks for source preservation but framework-level provenance evidence is limited (1).

Reliability8 / 14 · 2.9/5

self_consistency: README architecture matches core/adapters exports, the CLI thin-client positioning, and test assertions such as /ready failing closed (2). dependency_availability: engines require Node>=22, README lists MongoDB/Redis and a model provider as prerequisites, and CI uses mongo:7/redis:7 services; however local adapters depend on the better-sqlite3 native module whose cross-platform availability is not verified in the sample (2). failure_messages: the CLI catches errors and prints code: message, and /ready returns structured component status; but no runtime error taxonomy or user-facing recovery guidance is visible (1).

Adaptability10 / 18 · 2.8/5

audience_and_scenarios: README targets developers of production-grade LLM agent applications and gives a DomainPack integration path plus a release-agent example (2). capability_boundaries: docs state DomainPack is the product integration boundary, product logic must not enter core/kernel, and cache cannot authorize side effects (2). trigger_precision: the sample Skill uses only an always trigger; no conditional triggers or conflict resolution rules are shown (1). environment_fit: supports local SQLite/file, Docker, remote HTTP, PostgreSQL and S3 adapters, covering a broad range of environments (2).

Convention10 / 18 · 2.8/5

information_architecture: README is clearly layered and docs include guides/adr/reference, a sound structure (2). install_notes: Quick start gives Node version, npm ci, .env configuration, docker commands for Mongo/Redis, and health-check commands (2). naming_stability: package names @codesoul-co/hypha-* and version 1.0.1 are consistent, and the CLI version is fixed (2). examples_and_faq: only one release-agent example and a Skill sample exist; no FAQ or broader scenario examples (1). known_limitations: docs/reference/tool-mcp-known-limitations.md lists concrete limits on storage, cache, cancellation, secret management and API-key auth (2). license: the repository root contains the full Apache-2.0 LICENSE and package.json declares it consistently (3). versioning_changelog: README links the v1.0.1 release and UPGRADING.md, but no CHANGELOG content is in the sample (1). maintenance_responsibility: the publisher is unverified and README gives no maintainers, support channel or SLA (1).

Effectiveness6 / 13 · 2.3/5

output_usability: the framework provides a CLI, REST API, DomainPack compiler outputs and structured output contracts usable directly to build agent products (2). marginal_value: its differentiation is the harness/cache/recovery layer, but the README benchmark beats direct model calls by only about one percentage point, so marginal value evidence is weak (1). cost_benefit: the cache and reuse plane claims API-cost savings, but no verifiable cost data is provided and deployment adds MongoDB/Redis operational cost (1).

Verifiability3 / 8 · 1.9/5

claim_traceability: the README benchmark table cites main@ef33263 but provides no dataset, scripts or raw results, so it cannot be traced (1). cross_source_corroboration: test files and CI workflows partially corroborate claims about /ready, command idempotency and zero-skipped MCP tests, but benchmark and cache-benefit claims have no cross-source evidence (1). fact_inference_separation: architecture descriptions and performance claims are interleaved without clear separation of fact from inference (1).

Risks and how to mitigate them
  • Publisher identity is not verified by FollowAgents; maintenance responsibility and support channels are unclear, so evaluate before production adoption.
  • README benchmark results lack reproducible scripts and raw data and should not be used as a selection basis.
  • The framework ships no secret manager; credentials and audit redaction must be configured by the deployer.
  • Local adapters depend on the better-sqlite3 native module whose cross-platform availability is not verified in the sample.
  • The API-key authentication path is not enabled; deployments must not advertise X-API-Key request authentication.
Evidence confidence: Low Reviewed Nov 17, 2026 Reviewed revision a28e190d4037
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/hypha.svg)](https://followagents.com/en/agents/hypha)
<a href="https://followagents.com/en/agents/hypha"><img src="https://followagents.com/badge/hypha.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v1.0.1 Hypha npm release 1.0.1
    Release notes excerpt
    Patch release of the @codesoul-co/hypha-* npm line. Fixes since the 1.0.0 publication: - @codesoul-co/hypha-skills now ships the framework built-in skills (context-enrichment, intent-classification) in its tarball and exposes resolveBuiltinSkillsDirectory() (#22). The 1.0.0 tarball could not load built-in skills for npm consumers. - Repository gates: npm audit findings (js-yaml, nanoid) resolved (#23). All 15 packages are published at 1.0.1 with exact-version internal dependencies.
    View on GitHub ↗
  2. v1.0.0 Hypha v1.0.0
    Release notes excerpt
    Hypha v1.0.0 is the initial stable release of the ReAct + FSM agent-system framework. Highlights: - Application-defined FSM runs from validated FSMProcessSpec values or compiled DomainPack workflows. - FSM topology analysis and governed manual state transitions with policy, revision, lease, fencing, idempotency, terminal events, and replay evidence. - Production harness, DomainPack, provider-neutral memory, storage, tools, skills, MCP, inference, local adapters, serving cache, and testing packages. - OpenAPI 3.1 route inventory and a standalone release consumer example. …
    View on GitHub ↗

FAQ

Can a cache hit let a tool write, or skip an approval?
No. Caches are disposable projections: a hit cannot authorize a side effect, skip Policy or Approval, fabricate a receipt, advance the FSM, or replace Event and Artifact evidence, and cache-enabled and cache-disabled runs must keep identical source-of-truth semantics.
Does a DomainPack file become live just by sitting on disk?
No. The trusted composition layer must load and compile it, resolve model aliases and prompt references, register Skills, bind Tool adapters, approve exact MCP capability revisions, and persist processHash and dependencySnapshot with the Run's Event evidence.
Can a custom FSM topology bypass the harness phases?
Workflow-only Runs may use a validated application-owned FSMProcessSpec, but ReAct Runs keep the framework-owned Harness FSM so a product graph cannot skip reasoning, policy, activity, observation, verification, memory or recovery; manual transitions also require exact process identity, expected State and Run revision, an idempotency key and a reason.
What has to be running for the server to accept traffic?
Node.js 22+, npm, MongoDB and Redis, and at least one model provider or local endpoint; /api/v1/ready reports failure until storage, the selected model provider, Memory, the canonical runtime graph and required workers are ready.
Is commercial use allowed?
Source code is Apache-2.0, permitting commercial use, modification, distribution and private use; the Hypha name, logo and wordmark are not covered by that license, so third-party products must use their own primary branding.
Is Hypha free?
The software is free, but Hypha calls an AI model, and you pay that model provider for usage (or run a local model).
Is Hypha open source?
Yes. The source code is on GitHub (CodeSoul-co/Hypha) under the Apache-2.0 licence.
Is Hypha safe to use?
FollowAgents' FARS review (Nov 17, 2026) scored Hypha 18/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Hypha still maintained?
Yes. The latest commit on GitHub is from 2026-11-15, within the last 30 days. The latest release is v1.0.1 (2026-08-14).
Who makes Hypha?
Hypha is published on GitHub by the account CodeSoul-co. FollowAgents has not verified which person or company is behind that account.
What is Hypha's official website?
The project's GitHub repository lists https://codesoul-co.github.io/Hypha/ as its website. That link is set by the repository owner; the source code itself is on GitHub (CodeSoul-co/Hypha).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts