Machines
Package visor is the compute you rent from Hanzo: machines, GPUs and clusters — launch one, resize it, tear it down.
Package visor is the compute you rent from Hanzo: machines, GPUs and clusters — launch one, resize it, tear it down.
| Base URL | https://api.hanzo.ai |
| Operations | 8 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
machines
GET /v1/machines/{id}/agent
Returns the agent binding of one of the caller org's machines, or 404 when the machine runs no bot runtime.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral… |
PUT /v1/machines/{id}/agent
Binds a cloud Agent to one of the caller org's machines: the machine is recorded as running that Agent's @hanzo/bot runtime. The owning org is the validated tenant, never a client field.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine to bind, from the URL path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
agentName | string | — | AgentName is the cloud Agent (/v1/agents) the machine will run. |
botVersion | string | — | BotVersion pins the @hanzo/bot runtime version; empty takes the default. |
id | string | — | ID is the machine to bind, from the URL path. |
DELETE /v1/machines/{id}/agent
Detaches the agent runtime from one of the caller org's machines. The machine stays — this halts the bot, it does not terminate the compute. Answers 204.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral… |
GET /v1/machines/{id}
Returns one of the caller org's machines by its org-scoped name. Visor keys the lookup by owner/name, so an id belonging to another tenant resolves to not-found rather than another org's machine.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral… |
DELETE /v1/machines/{id}
Terminates one of the caller org's machines. Visor takes the machine identity as owner+name, and the owner is the validated principal, so a caller can only ever terminate its own tenant's machine. Answers 204.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral… |
GET /v1/machines/agents
Returns every agent↔machine binding in the caller's org — which machines are running which cloud Agent, with vm's own reconciled status.
GET /v1/machines
Returns every machine the caller's org has — Visor's registry, the
live DigitalOcean droplets and the DOKS worker nodes (deduped into one union),
plus the BYO machines that dialed in via hanzo link (provider "byo").
A source Visor cannot answer for is logged and skipped, never an error: one wedged upstream must not hide the machines the other sources can see.
POST /v1/machines
Launch a metered machine for your org, or price one first with dryRun
Provisions a machine owned by the caller's org and answers 201 with the machine. Send dryRun: true to get a PRICE QUOTE instead: 200 with the upstream quote passed through verbatim, nothing launched and nothing spent. Two response shapes on one address is the rule to know, and it is why this is not a typed op.
Metering is not this plane's: the launch fronts the compute provider's resell endpoint, which owns the balance gate and the per-hour meter, and cloud only forwards the tenant. Ownership is the validated principal's org and is never read from the body, so a launch always lands in the caller's OWN tenant and the machine it creates is only ever visible to that tenant. Fails closed: a validated principal is required (403 without one) and size (or its instanceType alias) is required (400).
How is this guide?