Documentation•Reference

Run Your First Autonomous Agent Locally

Time: ~5 minutes. Requirements: Node 18+, npm.

HazelJS Agent OS runs autonomous agents like local services. hazel apply starts a background node (hazeld) that hosts AgentOS. Closing the terminal does not stop your agents.

1. Install the CLI

npm install -g @hazeljs/​cli

This installs both hazel and hazeld.

2. Create a minimal agent

hazel new agent hello-bot
cd hello-bot
npm install

You get an order-support desk agent: agent.yaml (DNA) + agent.ts (lookup_order + HITL issue_refund) + package.json — no Kubernetes manifests.

3. Apply (starts hazeld if needed)

hazel apply agent.yaml

Expected:

✓ Agent "hello_bot" applied
  Status: Running (hosted by hazeld)
  Survives terminal close — daemon keeps the Agent OS node alive.

You are back at the shell prompt. The Agent OS node keeps running.

4. Inspect

hazel inspect hello_bot
hazel ps
hazel doctor

Status: Running means the agent is registered in the live node — not just written to disk.

5. Close the terminal

Quit the shell or close the window. Open a new one:

cd hello-bot
hazel inspect hello_bot

Still Running. That is the product: local agents as durable services.

Optional: approvals & secrets

hazel approvals
hazel approve <taskId>
hazel secret set OPENAI_API_KEY '…'   # value is not echoed back

Foreground vs daemon

CommandLifetime
hazel applyEnsures hazeld, applies DNA, returns
hazel devForeground AgentOS — dies with the TTY
hazeldLong-lived node (also started by apply)

Production local checklist

Single-user laptop / workstation — stable. Not multi-tenant auth on the socket.

  1. hazel doctor must exit 0 (daemon reachable, store writable).
  2. Prefer hazel apply over hazel dev for anything that must survive logout.
  3. Secrets: hazel secret set NAME value — values are never echoed. DNA env: { X: { secret: NAME } } resolves only inside hazeld.
  4. HITL: kill/restart preserves WaitingApproval; resume with hazel approve (never silent tool re-entry).
  5. Reboot (optional): install hazeld via HostServiceManager (launchd / systemd user / Windows task).
  6. hazel ui — thin status page on 127.0.0.1 bound to the control socket.

In-repo proof: examples/​local-agent-os (npm run demo).

Next: context desk (CAG + RAG + KAG + Memory)

Keep the default scaffold lean. When you want the multi-layer context story on the same local Agent OS path:

hazel new agent my-desk --template=context
cd my-desk && npm install
npm run demo              # offline planner — logs which sources ran
hazel apply agent.yaml    # HITL refunds still pause for hazel approve

In-repo proof: examples/​support-desk-context (npm run demo · npm run demo:hitl).

Deeper package-only labs (not Agent OS apply): Meridian example:rag · example:cag · example:kag · example:context — see RAG vs CAG vs KAG and @hazeljs/context.

Next

  • Agent OS guide — DNA, HITL, Skillgate, Gatekeeper
  • Meridian showcase — hazeljs-meridian-ops
  • Portability notes — Kubernetes / Cloud are optional; local node is the default