An outside adopter built a product on this stack in a day and lost most of their time to one gap: nothing documents how to run the cloud locally. They wrote four launcher scripts, each minting a master key by hand, and shipped every service unauthenticated on loopback to reach where one existing command already gets you. That command is `hanzo host serve`. It binds a unix socket rather than a port, and loopback where it binds one at all — safer than what they built to replace it, and mentioned in no README. `hanzo up` is the heavier path: k3s in a microVM with the cloud deployed into it, for when the cluster shape is what you are testing. The page states the port that actually matters. 3690 is what `local` means to `hanzo network`; the 8080 in the cloud README is the container's, and a URL built from one while the other runs is a connection to nothing. Their commit history contains exactly that fix. It also says what does not work locally, rather than leaving it to be found one command at a time: KMS needs an IAM principal and there is no IAM on a laptop, so the in-process client that skips the guard makes local a different code path from deployed. And it records the at-rest encryption report as unreproduced, because it is — a boot log claiming encryption is not evidence, and the page says to read the file header instead. A "do not rebuild these" table names the six things they wrote from scratch because they could not find ours, and admits the one that genuinely does not exist: a single-box self-host guide. Their two practices worth copying are in here too — a positive control on any exposure test, and recording what was executed separately from what was only written. The manifest gains a self-hosted section, so an agent pasted the URL learns what differs locally before it discovers it the hard way. Co-authored-by: Hanzo Dev <[email protected]>
3.4 KiB
hip, title, author, type, category, capability, status, implementation-go, created, requires
| hip | title | author | type | category | capability | status | implementation-go | created | requires |
|---|---|---|---|---|---|---|---|---|---|
| 1192 | Space — Drives Folders and File Storage | Hanzo AI | Standards Track | Infrastructure | space | Final | shipped | 2026-09-10 | HIP-0026, HIP-0106, HIP-0139 |
HIP-1192: Space — Drives Folders and File Storage
Abstract
/v1/space is the canonical capability for space within the Hanzo Cloud platform.
Package space is where work lives: drives, folders and the files in them.
The implementation is hanzoai/cloud apps/space and plugin/space (HIP-0106, HIP-0139).
All operations are native, composable, and authenticated against Hanzo IAM (HIP-0026).
Motivation
Before this specification, space operations lacked a unified canonical surface or were scattered across disparate endpoints. Under HIP-0139 (§1), every cloud capability maps 1:1 with exactly one plugin binary, one address prefix, one client class, and one authoritative specification. This eliminates duplicate implementations and ensures strict physical isolation, predictable billing, and orthogonal composability across the estate.
Specification
The key words MUST, MUST NOT, and SHOULD are to be interpreted as in RFC 2119.
§1 Addresses and Operations
The space capability answers exclusively under its assigned route prefixes:
| Method | Path | Summary |
|---|---|---|
GET |
/v1/space/health |
Health reports whether this deployment can serve spaces, drives and files. |
GET |
/v1/space/spaces |
Lists the caller org's own spaces. |
POST |
/v1/space/spaces |
Makes a new space for the caller's org and answers 201 with it. |
GET |
/v1/space/{space}/drives |
Lists a space's drives. |
POST |
/v1/space/{space}/drives |
Makes a new drive in a space and answers 201 with it. |
DELETE |
/v1/space/{space}/drives/{drive} |
Removes an EMPTY drive and answers 204. |
GET |
/v1/space/{space}/drives/{drive}/files |
Lists one folder level of a drive. |
GET |
/v1/space/{space}/drives/{drive}/files/{wildcard1} |
Mints a URL the caller downloads the file from DIRECTLY. |
PUT |
/v1/space/{space}/drives/{drive}/files/{wildcard1} |
Mints a URL the caller uploads the file to DIRECTLY. |
DELETE |
/v1/space/{space}/drives/{drive}/files/{wildcard1} |
Removes one file and answers 204. |
§2 Storage and Physical Isolation
Data is isolated physically per organization using cloud.OrgDB:
{DataDir}/orgs/{org}/space.db. Isolation is strictly enforced at the filesystem and OS level;
no cross-tenant queries are permitted. Where temporal or timeseries data is captured, postings
are signed and immutably appended.
§3 Authentication and Principal
Every request reaching /v1/space MUST present a valid Hanzo IAM bearer token (HIP-0026, HIP-0111).
Anonymous requests are rejected at the edge gateway before invoking the plugin. The executing
principal is extracted from the token and bound to the request context.
Security Considerations
- Physical Separation: Each tenant retains an isolated SQLite database file.
- Replay & Channel Binding: Direct dials and internal RPCs enforce channel binding over ZAP native transport.
- Audit Trails: All state-modifying actions emit immutable audit events to the centralized event plane (HIP-1190).
References
- HIP-0026: Identity & Access Management Standard
- HIP-0106: Hanzo Plugin Contract
- HIP-0139: Capability Standard