@hanzo/cloud

The typed JavaScript/TypeScript client for the Hanzo Cloud/v1/ platform API at api.hanzo.ai. Auth is Hanzo IAM-native: the client holds the IAM-issued Bearer JWT (or an API key) and sends it on every request.

Zero runtime dependencies. First-class services for agents, agent sessions, and machines, plus a fully-typed send() escape hatch that reaches every one of the 172 operations in the spec.

There is a companion Dart client, hanzoai, that mirrors this shape.

Where it sits

Three orthogonal, IAM-native clients — use them together:

Package	Surface
@hanzo/base	Base datastore — records, realtime, files
@hanzo/ai	Inference — chat completions, models
@hanzo/cloud	Platform control plane — agents, sessions, machines, and the full /v1/cloud/* surface

@hanzo/clouddoes not wrap or supersede @hanzo/ai. They are orthogonal: @hanzo/ai is the inference data plane (send a prompt, get a completion); @hanzo/cloud is the control plane (create an agent, run it, watch its sessions, provision the machine it runs on). An app that both configures agents and streams model output installs both.

Install

npm install @hanzo/cloud

import{HanzoCloud}from'@hanzo/cloud'constcloud=newHanzoCloud({token: process.env.HANZO_TOKEN})

token is a Hanzo IAM JWT (from hanzo.id) or an API key. The origin defaults to https://api.hanzo.ai.

Agents

constagent=awaitcloud.agents.create({name: 'researcher',model: 'zen-coder',instructions: 'You research and summarize.',tools: ['search','fetch'],})construn=awaitcloud.agents.run('researcher',{input: 'Summarize RFC 8628.'})console.log(run.status,run.output)constagents=awaitcloud.agents.list()constdetail=awaitcloud.agents.get('researcher')consthistory=awaitcloud.agents.runs('researcher',20)constmetrics=awaitcloud.agents.metrics('7D')

A one-shot agent runs when you POST to /run. A long-running agent additionally carries a 5-field cron schedule and is invoked by the scheduler:

awaitcloud.agents.create({name: 'nightly-digest',model: 'zen-coder',executionMode: 'long-running',schedule: '0 9 * * *',})

Agent sessions

A session is one live invocation. Sessions linked by parentSessionId form the subagent tree; rootSessionId is the shared key.

constsession=awaitcloud.sessions.register({agent: 'researcher'})awaitcloud.sessions.appendEvent(session.id,{kind: 'log',payload: {message: 'started'},})awaitcloud.sessions.pause(session.id)awaitcloud.sessions.resume(session.id)awaitcloud.sessions.message(session.id,{message: 'focus on section 3'})consttree=awaitcloud.sessions.tree(session.id)

Stream live session and event updates over SSE:

constctrl=newAbortController()forawait(constframeofcloud.sessions.stream({signal: ctrl.signal})){console.log(frame.type,frame.data)// 'session' | 'event'}

Machines

constmachines=awaitcloud.machines.list({pageSize: 50})constone=awaitcloud.machines.get('org/name')awaitcloud.machines.add({name: 'gpu-1',region: 'sfo3'})awaitcloud.machines.update('org/name',{size: 'xl'})

The full surface

Every /v1/cloud/* resource (nodes, pods, containers, providers, connections, stores, vectors, workflows, …) is reachable through the typed send() method. Pair it with the generated paths type for end-to-end safety:

importtype{paths}from'@hanzo/cloud'typeProviders=paths['/v1/cloud/get-providers']['get']['responses']['200']['content']['application/json']constproviders=awaitcloud.send<Providers>('/v1/cloud/get-providers')

The generated paths, components, and operations types are re-exported from the package root. They are produced from openapi.yaml (synced from the hanzo/openapi monorepo) via npm run codegen — the spec is the single source of truth.

Auth

cloud.setToken(jwt)// seed or replace the Bearer tokencloud.authStore.isValid// token present and, if a JWT, unexpiredcloud.signOut()// clear it

Errors are thrown as HanzoCloudError with .status and parsed .detail.

Develop

npm install
npm run codegen # regenerate src/generated/types.ts from openapi.yaml
npm run typecheck
npm run build
npm test

License

MIT © Hanzo AI, Inc. See LICENSE.