HazelJSOperate agents like production systems.
Define · Run · Decide · Govern · Survive — Agent OS for TypeScript
Frameworks build agents. HazelJS operates them.
Architecture
Define & Deploy
1/5Run
2/5Decide
3/5Govern
4/5Survive
5/5TypeScript / Node.js Backend
Define → Run → Decide → Govern → Survive
Agents are easy to prototype but difficult to operate reliably. Production agents need durable execution, governed capabilities, policy enforcement, approval flows, observability, testing, and safe rollout workflows. HazelJS Agent OS brings these primitives together in one TypeScript-native platform — not a bare-metal operating system.
01
Prompt loops, tool calling, and model adapters get you to a demo.
02
Durable runs, governed skills, Gatekeeper authorization, DNA packaging, HITL, and deployment lifecycle keep agents alive in production.
03
Runtime, governance, kernel, and control plane — not a glue stack of Nest + LangGraph + workers + a vendor console.
New to the term? Read What is an Agent OS? or explore Agent OS.
Operate agents like production systems. Agent OS gives them the lifecycle primitives demos never need — and real traffic always does.
Agent explores wrong plan and leaks side effects
Effect-typed tools (@Reversible, @Irreversible) + speculative branches — commit winner, compensate losers.
Need to undo an agent run after a bad outcome
Transactional undo replays @Compensate handlers newest-first with quarantine on failure.
You know the mission, not the agent roster
Deploy mission + genes + constitution. Agents spawn, specialize, and terminate from environment signals under resource limits.
Agent crashes mid-run
Runs survive process restarts with checkpointed state.
LLM invents free-form actions from a prompt
Closed-set choose (retry | rollback | escalate). Confidence informs policy — Gatekeeper still authorizes.
Agent wants to perform risky actions
Default-deny authorization before every tool call, with governed skills and human approval.
Prompt / model / skill behavior changes
Version identity, model, skills, and policy like packages.
Need safe rollout and testing
Test agent behavior before it reaches production traffic.
Need debugging and visibility
Trace plan → execute → critique with full run history.
Multiple workers / concurrency control
Coordinate workers safely without lost or double work.
Need resilient stateful execution
Runs, HITL, leases, state, and recovery as OS primitives.
Packages nest inside a few operating jobs — not a tall laundry list of peers. Drill into docs when you need the detail.
DNA · Store · Apply
Version identity, prompt, skills, and policies as DNA. Declare desired state with Store/Apply — tools stay in TypeScript.
Runtime · Agent VM · Organism
Agent Runtime executes the loop. Agent VM classifies effects and enables speculation/undo. Organism self-organizes specialists from a mission and environment signals.
Decision Runtime · Confidence · Policy
Bounded closed-set judgment before side effects. Evidence, judge, critic, and confidence inform policy — never authorize. Default provider is native hazel-agent, not an external-model wrapper.
Skillgate · Gatekeeper
Skillgate curates which APIs become capabilities. Gatekeeper authorizes each tool call — default deny, approvals, rewrite.
Durable kernel
Durable runs, crash-safe HITL, leases, state, and recovery — so agents outlive process restarts.
Built on your TypeScript / Node.js backend. Local first. Kubernetes optional — never the product.
Decision Runtime
LLMs reason. Decision Runtime judges. Policies route. Gatekeeper authorizes. Confidence never means permission — so rollback, refund, and escalate stay bounded and auditable.
The decision path
State
Typed input
Evidence
Extract signals
Decide
Closed choices
Confidence
Informs policy
Policy
Allow · review
Gatekeeper
Authorize
Why it matters
01
choices: […] as const. Invalid model verbs are rejected before anything runs.
02
Evidence → candidates → judge → critic → confidence. Optional LLM stages still fall back to heuristics — never to “allow”.
03
Policy can allow eligibility. Gatekeeper still decides. High confidence denied is a feature, not a bug.
04
Shadow-compare providers, trend outcomes, fit ECE — never auto-inject history into prompts.
import { createDecisionRuntime } from '@hazeljs/decision';
const decisions = createDecisionRuntime({ gatekeeper });
const result = await decisions.decide({
objective: 'Choose the safest remediation',
state: { errorRate: 0.38, failedHealthChecks: 8 },
choices: ['retry', 'rollback', 'escalate', 'ignore'] as const,
risk: 'high',
execute: true,
});
// result.decision is typed — Gatekeeper still gates side effectsPair with Skillgate (which APIs become skills) and Gatekeeper (may this tool run now).
From definition to production — a clear operating loop, not a one-shot prompt script.
Define with Agent DNA
Deploy through control plane workflows
Run with durable runtime
Decide with Decision Runtime, then Gatekeeper + Skillgate
Observe with Inspector
Evolve safely with tests and digital twins
A Kubernetes-like mental model for AI agents — apply desired state, run, inspect, and read logs.
$ hazel agent apply support-agent.yaml
$ hazel agent run support-agent
$ hazel agent inspect support-agent
$ hazel agent logs support-agentapiVersion: hazeljs.ai/v1
kind: Agent
metadata:
name: support-agent
spec:
dna:
version: 1.2.0
runtime:
replicas: 3
skills:
- orders.read
- refunds.create
policy:
refunds.create:
approval: required
budget:
maxCostPerRun: 0.05One repo that teaches DNA vs tools, Store vs platform vs run, Skillgate, router, and HITL. Copy the pattern into your product.
01
store:sync
Publish DNA packages + lockfile
02
platform:sync
Apply Definitions / Deployments
03
npm run dev
Chat with real @Tool handlers
terminal
cd hazeljs-meridian-ops && npm i && npm run store:sync && npm run platform:sync && npm run devLocal Store is enough to start. Hosted registry (promote/share packages) is an optional Team SKU — never required for local correctness.
Pick a challenge, ship a public TypeScript agent, then submit it with the form on /build.
Q4 2026 · Oct 1, 2026 – Dec 31, 2026 · 0/20 projects · 0/10 builders
Advanced
Investigate alerts, inspect system context, recommend remediation, request approval, and execute recovery actions.
Intermediate
Review pull requests, analyze changes, enforce policy, and recommend or execute approved actions.
Intermediate
Investigate orders, evaluate refund policy, request approval when needed, and execute refunds safely.
Advanced
Inspect cloud infrastructure, diagnose problems, suggest fixes, and execute governed operational actions.
Starter
Collect sources, build knowledge, synthesize findings, and maintain durable research context.
Intermediate
Use MCP tools as governed capabilities while enforcing identity, policy, approvals, and execution boundaries.
NestJS gives you APIs. LangChain gives you loops. HazelJS is the open-source Agent OS — durable process, DNA packaging, Skillgate, and local apply inside the same TypeScript backend.
Great APIs — AI agents are still an add-on.
NestJS structures backends well. Shipping durable agents still means bolting on LangChain, state stores, and approval workflows yourself.
Run durable agents with @hazeljs/agent. Decide with @hazeljs/decision. Authorize with Gatekeeper. Speculate with Agent VM. Self-organize with Organism. Clone Meridian to learn the full path; add Skillgate when REST becomes tools.
Runtime stack
Agent OS kernel, Decision Runtime, Gatekeeper, Agent VM, and Organism — the primitives you operate with. Decide first (closed set + policy), then authorize with Gatekeeper before side effects.
Runtime + durable lifecycle
Durable runs, HITL, leases, policies, and DNA overlay — the Agent OS kernel inside your TypeScript DI app.
Install
npm install @hazeljs/agentAgent OS example
const result = await runtime.execute('support-desk', goal, {
loop: { maxIterations: 4, successScore: 90 },
contract: { fallbackAgent: 'safe-desk' },
});Bounded judgment before side effects
Closed-set choose with confidence and policy. Native hazel-agent pipeline — not an external-model wrapper. Gatekeeper still authorizes every execute.
Install
npm install @hazeljs/decision @hazeljs/agentDecision example
const result = await decisions.decide({
objective: 'Choose the safest remediation',
state: incident,
choices: ['retry', 'rollback', 'escalate', 'ignore'] as const,
risk: 'high',
});Authorize every tool call
Deterministic authorization before protected tool execution. Agents propose. Gatekeeper decides — default deny, not a prompt guardrail.
Install
npm install @hazeljs/agent-gatekeeperGatekeeper example
await gatekeeper.execute({
context,
tool: fromFunction('stripe.refund', refund),
});Effect types & speculation
Effect-typed tools with transactional undo and speculative multi-branch execution. Commit the winning plan; compensate losers automatically.
Install
npm install @hazeljs/agent-vm @hazeljs/agentReversible tool + compensation
@Reversible({ compensate: 'holdSeat' })
@Tool({ name: 'holdSeat' })
async holdSeat(input) { return { holdId: store.hold(input.flightId) }; }
@Compensate('holdSeat')
async releaseHold(effect) { store.release(effect.output.holdId); }Mission-defined societies
Deploy a mission, not an agent topology. Ephemeral specialists spawn from environment signals under constitution, budgets, and survival pressure.
Install
npm install @hazeljs/organism @hazeljs/agent @hazeljs/coreOrganism example
const registry = new OrganismHostRegistry();
const host = await registry.getOrCreate(id, () =>
createOpsOrganism({ id, mission, genes, repository })
);
await host.start();Learn the path
Primary path — clone and learn
See the full Agent OS in one repo — DNA, Store, Skillgate, HITL, and local apply. Copy the pattern into your product.
Install
npm run store:sync && npm run platform:sync && npm run devTour path
# DNA ≠ tools · Store ≠ platform ≠ run
# apply does not restart Node — overlay on bootGovernance boundary
Turn selected REST endpoints into governed agent capabilities. Reads by default. Writes need approval.
Install
npm install @hazeljs/skillgate @hazeljs/agentSkillgate example
const gate = Skillgate.fromOpenApi(spec, {
include: { tags: ['agent'] },
});
gate.register(registry, 'api-concierge');Proof that HazelJS packages ship real products. Zynli is multi-tenant AI support (RAG, flows, billing) — supporting ecosystem, not the Agent OS teaching path. For DNA, HITL, Skillgate, and apply, clone Meridian.
Zynli.AI
Live in productionMulti-tenant AI support — RAG, flows, billing, and real-time handoff. Built by HumanBee AB.
01
Visitors get KB-grounded answers first; low-confidence turns escalate to live agents with full context.
02
Intent routing runs order tracking, ticket creation, and custom HTTP actions — HazelJS stack patterns in production.
03
Multi-tenant workspaces, subscriptions, real-time Socket.IO, and an embeddable React widget — shipped, not a demo repo.
HazelJS stack in production
Try the support widget on this page — it runs on the same HazelJS RAG stack as Zynli.
// KB → guided flow → ticket bot → LLM → human handoff
await askRag(question, tenantId, { sessionId });
await matchVisitorIntent(tenantId, message);
await tryExecuteVisitorFlow({ conversationId, tenantId, ... });Flagship: Meridian (DNA, Store, Skillgate, HITL). Smaller: hazel agent new. HCEL / ai-native templates are not the Agent OS path.
git clone https://github.com/hazel-js/hazeljs-meridian-ops.gitcd hazeljs-meridian-ops && npm i && npm run store:sync && npm run platform:sync && npm run devMeridian — store:sync → platform:sync → dev. Real @Tool handlers + HITL.
// 1. Setup DI
// 2. Configure OpenAI Adapter
// 3. Setup LangChain Chain
// 4. Manually pipe input to RAG
// 5. Manually pipe RAG output to Agent
// 6. Handle tool failures manually
// 7. Write 50 lines of boilerplate...
async execute(input) {
const docs = await this.rag.search(input);
const prompt = this.template.fill(input, docs);
const agent = new AgentExecutor({ ... });
return agent.call({ prompt });
}// 1. Just call the chain.
// Context flows implicitly.
async execute(input) {
return await this.ai.hazel
.prompt(template)
.rag('docs')
.agent('specialist')
.execute(input);
}Deep dives on Agent OS, agent lifecycle, Skillgate, DNA, and what we are shipping next.
Git-backed configuration, automatic recovery, and proactive Kubernetes HPA — a deep dive into @hazeljs/config-server, @hazeljs/self-healing, and @hazeljs/predictive-scaling, and how they compose into one operations stack.
Read more →
Agent OS is the production lifecycle for AI-native TypeScript agents inside a Node backend — durable runs, Skillgate, policies, DNA — not a bare-metal OS.
Read more →
Curate OpenAPI / REST into agent tools with HITL defaults, then register on Agent OS or export to MCP. Opt-in by design.
Read more →Get help from developers shipping production AI agents. Share patterns, debug runs, and shape the Agent OS roadmap.
Connect with students and researchers building on HazelJS at your institution.
Ask questions, share agent patterns, and get feedback from builders in the trenches.
Shape the roadmap, test new packages, and get direct access to the core team.
Clone Meridian to see Agent DNA, Store, Skillgate, and HITL in one TypeScript backend. Then keep @hazeljs/agent in your app. Apache 2.0.
Later
Today: run Agent OS locally in your Node app. Cloud registry and managed deploy are optional Team SKUs — never required to ship agents.
Correct without Cloud or Kubernetes
Promote DNA packages when you are ready
Optional — not the product
Coming later — not required now
Join 9+ developers for early access to HazelJS.Cloud
Our official consulting partner helps teams architect, implement, and ship HazelJS Agent OS in production — faster.
Need help shipping AI agents, RAG pipelines, or production backends on HazelJS? HumanBee is the official consulting partner for architecture, hands-on implementation, and team enablement.