HazelJS Installation

Install HazelJS for Agent OS (Meridian / hazel agent) or a framework HTTP app. This page covers prerequisites, packages, and troubleshooting.

Quick Reference

• Purpose: Install HazelJS and start an Agent OS or HTTP project.
• When to use: First install, adding packages, or troubleshooting.
• Key concepts: Primary path is Meridian. @hazeljs/​core (HTTP/DI), @hazeljs/​agent (Agent OS kernel), @hazeljs/​cli (hazel agent new). Optional: Skillgate, Gatekeeper, Agent VM, RAG, HCEL.
• Inputs: Node.js 18+, npm 9+.
• Outputs: Meridian or a running app on http://localhost:3000.
• Dependencies: Node.js 18+, TypeScript. @hazeljs/​core loads reflect-metadata — do not install or import it. class-validator / class-transformer only if you use DTO validation.
• Common patterns: Clone Meridian → store:sync → platform:sync → dev; or hazel agent new my-desk --template=agent-os; or npm install @hazeljs/​core for a one-file API.
• Common mistakes: Treating --template=ai-native as the Agent OS flagship; missing experimentalDecorators in tsconfig; installing or importing reflect-metadata in application code.

HazelJS Prerequisites

• Node.js — Version 18.x or later (node --version). Recommended: Node.js 20 LTS.
• npm — Version 9.x or later (npm --version)
• Git — Optional, for development (git --version)

HazelJS Installation Methods

Agent OS — Meridian (recommended)

git clone https://github.com/​hazel-js/​hazeljs-meridian-ops.git
cd hazeljs-meridian-ops
npm install
npm run store:sync
npm run platform:sync
npm run dev

Agent OS scaffold

npm install -g @hazeljs/​cli
hazel agent new my-desk --template=agent-os
cd my-desk && npm install && npm run dev

Framework HTTP app (secondary)

# Install the HazelJS CLI globally
npm install -g @hazeljs/​cli

# Skeleton API
hazel g app my-app
cd my-app
npm install
npm run dev

Or create a new HazelJS app with interactive prompts:

hazel new my-app -i

--template=ai-native scaffolds HCEL / RAG / Docker. It is not the Agent OS flagship (use Meridian for DNA / Store / Skillgate / HITL).

Install HazelJS Core in an Existing Project

npm install @hazeljs/​core

Install Specific HazelJS Packages

# Example: install core + AI + auth
npm install @hazeljs/​core @hazeljs/​ai @hazeljs/​auth

# Example: install core + caching + database
npm install @hazeljs/​core @hazeljs/​cache @hazeljs/​prisma

HazelJS Package Decision Guide

Use this table when you know the goal but not the package name. Each row includes @hazeljs/​core where it is required. Full list: Available Packages below.

I want to...	Install
Run the Agent OS teaching app	Clone Meridian
Scaffold DNA / HITL / Skillgate	hazel agent new + @hazeljs/​agent
Build a basic HTTP API	@hazeljs/​core
Scaffold projects from the CLI	@hazeljs/​cli
Add LLM integration (OpenAI, Anthropic, etc.)	@hazeljs/​core @hazeljs/​ai
Build AI agents with tools	@hazeljs/​core @hazeljs/​ai @hazeljs/​agent
Reversible tools + speculative branches	@hazeljs/​agent-vm @hazeljs/​agent
Curate OpenAPI / REST → agent skills	@hazeljs/​skillgate @hazeljs/​agent (+ @hazeljs/​swagger for fromModule)
Authorize every tool call (fail-closed)	@hazeljs/​agent-gatekeeper (+ @hazeljs/​agent)
Add RAG / semantic search over documents	@hazeljs/​core @hazeljs/​ai @hazeljs/​rag
Regression-test agents with describeAgent	@hazeljs/​testing @hazeljs/​eval (+ @hazeljs/​agent)
Benchmark agent quality across commits	@hazeljs/​benchmark (+ @hazeljs/​agent / your scorer)
Full Agent OS lifecycle (policies, DNA, twin, Skillgate, Gatekeeper)	See Agent OS guide
Build agents and RAG with shared conversation memory	@hazeljs/​core @hazeljs/​ai @hazeljs/​agent @hazeljs/​rag (+ optional @hazeljs/​memory)
Versioned prompt templates (not inline strings)	@hazeljs/​core @hazeljs/​prompts (+ @hazeljs/​ai when calling LLMs)
Persistent memory store (Redis/Prisma) for agents or RAG	@hazeljs/​core @hazeljs/​memory
Block PII / prompt injection / unsafe LLM output	@hazeljs/​core @hazeljs/​guardrails (+ @hazeljs/​ai)
Regression-test RAG or agents (golden datasets, CI)	@hazeljs/​core @hazeljs/​eval (+ @hazeljs/​rag or @hazeljs/​agent; prefer @hazeljs/​testing for agent suites)
Trace LLM calls and agent steps (OpenTelemetry)	@hazeljs/​core @hazeljs/​observability (+ @hazeljs/​ai / @hazeljs/​agent)
Connect to MCP tool servers	@hazeljs/​core @hazeljs/​mcp (+ @hazeljs/​ai / @hazeljs/​agent)
ML models, feature store, batch inference	@hazeljs/​core @hazeljs/​ml (+ optional @hazeljs/​data)
Add authentication (JWT)	@hazeljs/​core @hazeljs/​auth
Add OAuth social login	@hazeljs/​core @hazeljs/​auth @hazeljs/​oauth
Fine-grained authorization (roles/abilities)	@hazeljs/​core @hazeljs/​casl (+ @hazeljs/​auth)
Audit log who did what	@hazeljs/​core @hazeljs/​audit
Add database (Prisma)	@hazeljs/​core @hazeljs/​prisma
Add database (TypeORM)	@hazeljs/​core @hazeljs/​typeorm
Add caching (Redis/memory)	@hazeljs/​core @hazeljs/​cache
Type-safe config / .env	@hazeljs/​core @hazeljs/​config
Shared Git-backed config (Spring Cloud Config style)	@hazeljs/​core @hazeljs/​config-server
Background jobs with Redis (BullMQ)	@hazeljs/​core @hazeljs/​queue
CPU-intensive work off the main thread	@hazeljs/​core @hazeljs/​worker
Scheduled recurring tasks (cron expressions)	@hazeljs/​core @hazeljs/​cron
Durable workflows (wait/resume, idempotency)	@hazeljs/​core @hazeljs/​flow
Run flows as a standalone HTTP service	@hazeljs/​core @hazeljs/​flow-runtime
Event streaming between microservices (Kafka)	@hazeljs/​core @hazeljs/​kafka
Google Cloud Pub/Sub messaging	@hazeljs/​core @hazeljs/​pubsub
WhatsApp / Telegram / Viber bots	@hazeljs/​core @hazeljs/​messaging (+ @hazeljs/​ai)
In-process pub/sub between modules	@hazeljs/​core @hazeljs/​event-emitter
Distributed saga / compensation across services	@hazeljs/​core @hazeljs/​saga
Distributed lock (only one instance runs a job)	@hazeljs/​core @hazeljs/​distributed-lock
Service discovery for microservices	@hazeljs/​core @hazeljs/​discovery
API gateway (versioning, canary routing)	@hazeljs/​core @hazeljs/​gateway
Circuit breaker, retry, rate limit	@hazeljs/​core @hazeljs/​resilience
Self-heal failing methods / pods (K8s restart, HPA boost)	@hazeljs/​core @hazeljs/​self-healing (+ optional @hazeljs/​ai @hazeljs/​ops-agent @hazeljs/​resilience)
Predict traffic and raise HPA before spikes	@hazeljs/​core @hazeljs/​predictive-scaling (+ optional @hazeljs/​self-healing)
Real-time WebSocket / SSE	@hazeljs/​core @hazeljs/​websocket
Realtime subscriptions (higher-level than raw WS)	@hazeljs/​core @hazeljs/​realtime
GraphQL API	@hazeljs/​core @hazeljs/​graphql
gRPC services	@hazeljs/​core @hazeljs/​grpc
OpenAPI / Swagger docs	@hazeljs/​core @hazeljs/​swagger
ETL / data pipelines	@hazeljs/​core @hazeljs/​data
Feature flags	@hazeljs/​core @hazeljs/​feature-toggle
i18n / translations	@hazeljs/​core @hazeljs/​i18n
Inspect routes, cron, agents at runtime	@hazeljs/​core @hazeljs/​inspector
Deploy serverless (AWS Lambda)	@hazeljs/​core @hazeljs/​serverless
Ops/incident triage (Jira, Slack)	@hazeljs/​core @hazeljs/​ops-agent (+ @hazeljs/​agent @hazeljs/​ai)
PDF documents to audio (TTS)	@hazeljs/​core @hazeljs/​pdf-to-audio (+ @hazeljs/​ai)
End-to-end support chat + RAG example	See Support Agent (uses core, rag, ai, memory patterns)

Similar packages — quick picks: Queue vs Worker vs Cron · Flow vs Flow Runtime · Kafka vs Pub/Sub vs Messaging · RAG vs Agentic RAG · Memory in RAG vs @hazeljs/​memory

Available Packages

Install any package with npm:

npm install @hazeljs/​core @hazeljs/​ai

Browse full documentation from the docs sidebar or each package page linked in the table above.

Building HazelJS from Source

Build HazelJS from source if you want to contribute, customize, or use the latest development version.

# Step 1: Clone the repository
git clone https://github.com/​hazel-js/​hazeljs.git

# Step 2: Navigate to the project directory
cd hazeljs

# Step 3: Install dependencies
npm install

# Step 4: Build the project
npm run build

# Step 5: Link the CLI (optional)
npm link

Verifying HazelJS Installation

After installation, verify that HazelJS is installed correctly:

# Check CLI version
hazel --version
# Should display your installed CLI version

# Check available commands
hazel --help

Creating Your First HazelJS Project

Agent OS: clone Meridian or hazel agent new my-desk --template=agent-os.

HTTP skeleton:

hazel new my-app -i
cd my-app
npm run dev

Manual HazelJS Project Setup

If you prefer to set up manually without the HazelJS CLI:

1. Initialize a new project:

mkdir my-app && cd my-app
npm init -y
npm install @hazeljs/​core class-validator class-transformer
npm install -D typescript @types/​node ts-node-dev

2. Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "declaration": true,
    "outDir": ".​/dist",
    "rootDir": ".​/src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "resolveJsonModule": true,
    "moduleResolution": "node"
  },
  "include": ["src/​**/​*"],
  "exclude": ["node_modules", "dist"]
}

Important: experimentalDecorators must be true. emitDecoratorMetadata is optional for most apps. Do not install or import reflect-metadata; @hazeljs/​core loads it automatically.

3. Create src/​main.ts:

import { HazelApp, HazelModule, Controller, Get } from '@hazeljs/​core';

@Controller('hello')
class HelloController {
  @Get()
  hello() {
    return { message: 'Hello, World!' };
  }
}

@HazelModule({
  controllers: [HelloController],
})
class AppModule {}

async function bootstrap() {
  const app = new HazelApp(AppModule);
  await app.listen(3000);
  console.log('Application is running on http://localhost:3000');
}

bootstrap();

4. Add scripts to package.json:

{
  "scripts": {
    "dev": "ts-node-dev --respawn src/​main.ts",
    "build": "tsc",
    "start": "node dist/​main.js"
  }
}

5. Run:

npm run dev

Visit http://localhost:3000/​hello — you should see {"message":"Hello, World!"}.

HazelJS Environment Variables

Create a .env file in your HazelJS project root:

PORT=3000
NODE_ENV=development
DATABASE_URL=postgresql:/​/​user:password@localhost:5432/​mydb
JWT_SECRET=your-secret-key

HazelJS Project Structure

A typical HazelJS project follows this structure:

my-app/​
├── src/​
│   ├── user/​
│   │   ├── dto/​
│   │   │   └── create-user.dto.ts
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   └── user.module.ts
│   ├── app.module.ts
│   └── main.ts
├── .env
├── package.json
└── tsconfig.json

HazelJS Installation Troubleshooting

Permission Errors (npm install -g)

If you encounter permission errors when installing globally:

sudo npm install -g @hazeljs/​cli

Or configure npm to use a different directory for global packages.

Command Not Found

If the hazel command is not found:

• Verify npm global bin directory is in your PATH
• Restart your terminal after installation
• Check installation with: npm list -g @hazeljs/​cli

Version Conflicts

If you have multiple Node.js versions installed:

nvm use 20

Use nvm or n to manage Node.js versions.

Decorators Not Working

Ensure experimentalDecorators is true in your tsconfig.json. You do not need to install or import reflect-metadata — @hazeljs/​core already does that.

Validation Not Working

Install the required peer dependencies:

npm install class-validator class-transformer

Use @Body(DtoClass) decorator with your DTO class for automatic validation.

Related Pages

• Introduction — Agent OS overview
• Agent OS guide — DNA, HITL, Skillgate, local apply
• CLI — hazel agent new and generators
• Core Package — HTTP / DI pipeline
• Concepts & Glossary — Decorators and terms

Next Concepts to Learn

• Meridian — Flagship teaching app
• Agent Package — Kernel APIs
• Skillgate — OpenAPI → skills
• Testing Package — describeAgent CI
• Controllers Guide — REST beside agents