docs: present V8 · Open Edition — category-first IA, decentralized spine, API-ref separated (#36)

Ground docs.hanzo.ai in HIP-0127 (V8 · Open Edition). The spine: "the AI cloud
you can run yourself" — one unified binary, hanzo.network is the cloud, category-
first descent by the eight movements, API reference as its own separated surface.

- Sidebar (content/docs/meta.json): flat ~85-item dump with overlapping
  ad-hoc labels → the eight canonical movements from openapi/capabilities.yaml
  (Identity & Trust · Intelligence · Data · Streams · Observability · Commerce ·
  Platform · Applications), as icon-bearing separators (---[Icon]Name---). Files
  stay flat — no URL/back-link breakage. openapi/sdks/api removed from the root
  descent; they remain the dedicated top-nav surfaces.
- Top nav (components/layouts/shared.tsx): add Docs + Network; API and SDKs kept
  as separated surfaces.
- Landing (app/(home)/page.tsx): hero → decentralized spine; ecosystem grid →
  the eight movements (category-first); breadth stats bar + models/SDKs/MCP
  panels making the full surface visible. Every number traces to a source:
  67 caps / 8 movements (capabilities.yaml), 157 models (ai/conf/models.yaml),
  706 connectors (cloud/.../catalog.json), 6 SDK langs (openapi/CLAUDE.md).
- Docs home (content/docs/index.mdx): 69-services pitch → the run-it-yourself
  spine + the eight-movements grid.
- New content/docs/network.mdx: hanzo.network / self-host — one binary, BYO GPU
  or K8s, mine on any device (TEE/CC), free for public+OSS, the language seam is
  the wire not FFI.
- New content/docs/architecture/philosophy.mdx: the engineering pedagogy —
  one-and-one-way, decomplect, one contract → N SDKs → thin CLIs, ZAP-native.
- architecture/index.mdx: "ten categories" → the eight movements; link
  philosophy + network.

Content review only — do not merge yet.
This commit is contained in:
Hanzo Dev
2026-07-08 14:16:58 -07:00
committed by GitHub
parent 409e60c590
commit d87077cfb8
9 changed files with 573 additions and 204 deletions
+16
View File
@@ -10,6 +10,22 @@ at docs.hanzo.ai/docs/contributing/docs-architecture). Summary:
- **docs.hanzo.ai is the hub.** ONE Fumadocs build (`apps/docs`) → ONE CF Pages
project `hanzo-docs`. The federated per-section deploy is **retired** (stale
origins 530'd). Do not reintroduce per-section builds.
- **IA is category-first (V8 · Open Edition, HIP-0127).** The docs sidebar
(`content/docs/meta.json`) is grouped by the **eight movements** — Identity &
Trust · Intelligence · Data · Streams · Observability · Commerce · Platform ·
Applications — the exact taxonomy in `~/work/hanzo/openapi/capabilities.yaml`
(`domains`, 67 capabilities). Movements are icon-bearing separators
(`---[Icon]Name---`, resolved by `lucideIconsPlugin`), NOT folder moves —
files stay flat so URLs/openapi back-links don't break. **API reference and
SDKs are separated surfaces** (`/docs/openapi`, `/docs/sdks`) reached via the
top nav (`components/layouts/shared.tsx`), deliberately NOT in the root
sidebar descent. The landing (`app/(home)/page.tsx`) + docs home
(`content/docs/index.mdx`) lead with the decentralized spine ("the AI cloud
you can run yourself"); `content/docs/network.mdx` = self-host/hanzo.network,
`content/docs/architecture/philosophy.mdx` = the engineering pedagogy. Landing
breadth stats trace to real sources: 67/8 (`capabilities.yaml`), 157 models
(`ai/conf/models.yaml`), 706 connectors (`cloud/clients/automations/catalog/
catalog.json`), 6 SDK langs (`openapi/CLAUDE.md`). Count from data, never invent.
- **One canonical home per doc.** Content enters the single build via exactly one
of three orthogonal mechanisms, chosen by *kind*:
1. **Authored** (first-party prose) → MDX under `content/docs/<section>/`.
+175 -113
View File
@@ -1,21 +1,19 @@
import Link from 'next/link';
import {
Activity,
ArrowRight,
Bot,
Cloud,
Code2,
Database,
FileJson2,
Globe,
HardDrive,
MessageCircle,
Monitor,
Search,
LayoutGrid,
Package,
Server,
Shield,
ShoppingCart,
Sparkles,
Terminal,
Workflow,
Zap,
} from 'lucide-react';
import { Button } from '@/components/ui/button';
import { Badge } from '@/components/ui/badge';
@@ -29,122 +27,93 @@ import {
} from '@/components/ui/card';
import { CodeBlock } from '@/components/code-block';
/* -- Ecosystem grid -- big clickable squares -------------------------------- */
/* -- The eight movements -- category-first, mirrors the console shell -------- */
const ecosystem = [
const movements = [
{
name: 'Hanzo Cloud',
desc: 'LLM gateway for 200+ models. Load balancing, caching, and observability.',
icon: Cloud,
href: '/docs/services/cloud',
tag: 'AI',
},
{
name: 'Hanzo Chat',
desc: 'Multi-model AI chat with MCP tools, file uploads, and 14 Zen models.',
icon: MessageCircle,
href: '/docs/chat',
tag: 'AI',
},
{
name: 'Hanzo Dev',
desc: 'AI coding agent with IDE integration, debugging, and MCP tools.',
icon: Terminal,
href: '/docs/dev',
tag: 'AI',
},
{
name: 'Hanzo Bot',
desc: '743+ skills, 35+ channel adapters. Deploy AI bots anywhere.',
icon: Bot,
href: '/docs/services/bot',
tag: 'AI',
},
{
name: 'Hanzo Flow',
desc: 'Visual workflow automation. Drag-and-drop AI pipelines.',
icon: Workflow,
href: '/docs/services/flow',
tag: 'Automation',
},
{
name: 'Hanzo Platform',
desc: 'PaaS with git push deploy. Docker containers, SSL, scaling.',
icon: Globe,
href: '/docs/services/paas',
tag: 'Infra',
},
{
name: 'Hanzo Console',
desc: 'Observability dashboard. Tracing, evals, and cost tracking.',
icon: Monitor,
href: '/docs/services/console',
tag: 'Ops',
},
{
name: 'Hanzo Space',
desc: 'S3-compatible object storage with CDN and versioning.',
icon: HardDrive,
href: '/docs/services/s3',
tag: 'Infra',
},
{
name: 'Hanzo Search',
desc: 'AI-powered search with generative UI and RAG.',
icon: Search,
href: '/docs/services/search',
tag: 'AI',
},
{
name: 'Hanzo Guard',
desc: 'AI safety, PII detection, and content moderation.',
name: 'Identity & Trust',
desc: 'Who you are, what you may touch, where secrets live. IAM, AuthZ, KMS, MPC, Zero-Trust.',
icon: Shield,
href: '/docs/services/guard',
tag: 'Security',
href: '/docs/iam',
tag: 'Identity',
},
{
name: 'Hanzo IAM',
desc: 'Identity, SSO, OAuth2, SAML. Unified auth for everything.',
name: 'Intelligence',
desc: 'The mind of the cloud. Models, agents, MCP, embeddings, prompts, GPUs, functions.',
icon: Sparkles,
href: '/docs/llm',
tag: 'Intelligence',
},
{
name: 'Data',
desc: 'The stores everything writes to. SQL, Vector, KV, Search, Object, Base, DocDB.',
icon: Database,
href: '/docs/services/iam',
href: '/docs/sql',
tag: 'Data',
},
{
name: 'Streams',
desc: 'Messaging, durable tasks, async orchestration. PubSub, Tasks, Pipelines, Crawl.',
icon: Workflow,
href: '/docs/pubsub',
tag: 'Streams',
},
{
name: 'Observability',
desc: 'See everything. Telemetry, metrics, logs, traces, sessions, evals, analytics.',
icon: Activity,
href: '/docs/o11y',
tag: 'Observe',
},
{
name: 'Commerce',
desc: 'The economy. Meter, price, bill, reward. Commerce, Billing, Marketplace, Referrals.',
icon: ShoppingCart,
href: '/docs/commerce',
tag: 'Commerce',
},
{
name: 'Platform',
desc: 'The cloud fabric. Deploy, provision, route, host. Gateway, Machines, Edge, Registry.',
icon: Server,
href: '/docs/gateway',
tag: 'Platform',
},
{
name: 'Zen',
desc: '44 frontier models, 4B to 1T+. Open weights on HuggingFace.',
icon: Sparkles,
href: 'https://zenlm.org',
tag: 'Models',
external: true,
name: 'Applications',
desc: 'The user-facing surfaces. Chat, Studio, Dev, Integrations, Apps.',
icon: LayoutGrid,
href: '/docs/chat',
tag: 'Apps',
},
];
/* -- Developer quick links -------------------------------------------------- */
const devLinks = [
{
name: 'The Network',
desc: 'Run the whole cloud yourself',
href: '/docs/network',
icon: Globe,
},
{
name: 'SDKs',
desc: 'Python, TypeScript, Go, Rust, C',
desc: 'Python, TypeScript, Go, Rust',
href: '/docs/sdks',
icon: Code2,
},
{
name: 'API Reference',
desc: 'OpenAPI specs for all 33 services',
desc: 'REST for every capability',
href: '/docs/openapi',
icon: FileJson2,
},
{
name: 'MCP + ZAP',
desc: '260+ tools + zero-copy RPC protocol',
href: '/docs/mcp',
icon: Terminal,
},
{
name: 'Extensions',
desc: 'IDE, browser, and desktop extensions',
href: '/docs/projects/hanzoai/extension',
icon: Zap,
name: 'Architecture',
desc: 'One binary, one contract',
href: '/docs/architecture',
icon: Package,
},
];
@@ -162,15 +131,16 @@ export default function Page() {
className="relative mb-8 rounded-full border-white/10 bg-white/[0.03] px-4 py-2 text-sm text-[#a3a3a3] backdrop-blur font-normal"
>
<span className="h-1.5 w-1.5 rounded-full bg-white mr-2" />
One API &middot; 33 Services &middot; 200+ Models
One binary &middot; One contract &middot; 67 capabilities
</Badge>
<h1 className="relative text-5xl md:text-6xl lg:text-7xl font-bold tracking-tight leading-[1.05]">
<span className="text-white">Hanzo AI Cloud</span>
<span className="text-white">The AI cloud you<br className="hidden sm:block" /> can run yourself</span>
</h1>
<p className="relative mt-5 max-w-xl text-[#737373] text-lg md:text-xl leading-relaxed">
AI infrastructure for developers.
Build, deploy, and scale intelligent applications.
The same open-source binary we run in production 67 capabilities across
eight movements. Run it on your own machine, GPU, or cluster.
The network is the cloud.
</p>
{/* -- Install command -- the main CTA ------------------------------ */}
@@ -199,17 +169,33 @@ export default function Page() {
<div className="relative flex flex-row items-center gap-3 mt-8 flex-wrap justify-center">
<Button asChild size="lg" className="rounded-full bg-white px-7 text-black hover:bg-neutral-200">
<Link href="/docs/services">
<Link href="/docs/getting-started">
Get Started
<ArrowRight className="size-4 ml-1" />
</Link>
</Button>
<Button asChild variant="outline" size="lg" className="rounded-full border-white/15 px-7 text-white hover:bg-white/5 bg-transparent">
<Link href="/docs/openapi">
API Reference
<Link href="/docs/network">
Run it yourself
</Link>
</Button>
</div>
{/* -- Breadth stats bar -------------------------------------------- */}
<div className="relative mt-14 grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 gap-px w-full max-w-4xl rounded-2xl overflow-hidden border border-white/[0.08] bg-white/[0.04]">
{[
{ n: '67', label: 'Capabilities' },
{ n: '8', label: 'Movements' },
{ n: '157', label: 'Models' },
{ n: '706', label: 'MCP connectors' },
{ n: '6', label: 'SDK languages' },
].map((s) => (
<div key={s.label} className="bg-[#0a0a0a] px-5 py-5 text-center">
<div className="text-2xl font-bold text-white tabular-nums">{s.n}</div>
<div className="mt-1 text-[11px] uppercase tracking-wider text-[#525252]">{s.label}</div>
</div>
))}
</div>
</section>
<div className="mx-auto w-full max-w-[1400px] px-6 md:px-12 space-y-24">
@@ -220,7 +206,7 @@ export default function Page() {
Quick Start
</h2>
<p className="text-[#737373] text-sm mb-8">
Install the CLI, log in, and start using every Hanzo service from your terminal.
Install the CLI, log in, and reach every capability from your terminal.
</p>
<div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
<CodeBlock
@@ -257,16 +243,16 @@ print(response.choices[0].message.content)`}
</div>
</section>
{/* -- Ecosystem -- big clickable cards ----------------------------- */}
{/* -- The eight movements -- category-first ------------------------ */}
<section>
<h2 className="text-3xl font-bold tracking-tight mb-3">
Ecosystem
The eight movements
</h2>
<p className="text-[#737373] text-sm mb-8">
Everything you need to build with AI. Click any card to jump to its docs.
Every capability is named by its route and lives in exactly one movement. Click any to descend.
</p>
<div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3">
{ecosystem.map((item) => {
{movements.map((item) => {
const isExternal = !!(item as { external?: boolean }).external;
const linkProps = isExternal
? { target: '_blank' as const, rel: 'noreferrer noopener' }
@@ -333,6 +319,82 @@ print(response.choices[0].message.content)`}
</div>
</section>
{/* -- Models & providers ------------------------------------------ */}
<section>
<h2 className="text-3xl font-bold tracking-tight mb-3">
Every model, one API
</h2>
<p className="text-[#737373] text-sm mb-8">
157 models across every major provider call any of them with one credential, one request shape.
</p>
<div className="grid grid-cols-2 sm:grid-cols-4 md:grid-cols-8 gap-3">
{[
{ name: 'Zen', spec: 'Open weights' },
{ name: 'OpenAI', spec: 'GPT' },
{ name: 'Anthropic', spec: 'Claude' },
{ name: 'Qwen', spec: 'Open' },
{ name: 'Llama', spec: 'Open' },
{ name: 'DeepSeek', spec: 'Open' },
{ name: 'Mistral', spec: 'Open' },
{ name: 'Gemma', spec: 'Open' },
].map((p) => (
<Card key={p.name} className="border-white/[0.06] bg-white/[0.02] shadow-none py-0 gap-0 rounded-lg">
<CardContent className="px-4 py-3 text-center">
<div className="text-xs font-semibold text-white mb-1">{p.name}</div>
<div className="text-[10px] text-[#525252]">{p.spec}</div>
</CardContent>
</Card>
))}
</div>
</section>
{/* -- SDKs + connectors ------------------------------------------- */}
<div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
<Card className="border-white/[0.08] bg-white/[0.02] shadow-none py-0 gap-0 rounded-2xl overflow-hidden">
<CardContent className="p-8">
<div className="flex items-center gap-3 mb-2">
<Code2 className="size-5 text-[#a3a3a3]" />
<CardTitle className="text-xl font-bold tracking-tight">SDKs in every language</CardTitle>
</div>
<CardDescription className="text-xs text-[#525252] mb-6">
Generated from one contract the same <code className="font-mono">/v1</code> surface, typed for your stack.
</CardDescription>
<div className="flex flex-wrap gap-2">
{['Python', 'TypeScript', 'Go', 'Rust', 'C++', 'Dart'].map((l) => (
<span key={l} className="rounded-full border border-white/10 bg-white/[0.03] px-3 py-1.5 text-xs text-[#a3a3a3]">
{l}
</span>
))}
</div>
<Link href="/docs/sdks" className="mt-6 inline-flex items-center gap-1 text-xs font-medium text-[#525252] hover:text-white transition-colors">
SDK reference <ArrowRight className="size-3" />
</Link>
</CardContent>
</Card>
<Card className="border-white/[0.08] bg-white/[0.02] shadow-none py-0 gap-0 rounded-2xl overflow-hidden">
<CardContent className="p-8">
<div className="flex items-center gap-3 mb-2">
<Workflow className="size-5 text-[#a3a3a3]" />
<CardTitle className="text-xl font-bold tracking-tight">706 tools, one MCP surface</CardTitle>
</div>
<CardDescription className="text-xs text-[#525252] mb-6">
706 connectors Slack, GitHub, Notion, Stripe, and more exposed as MCP tools any agent can call.
</CardDescription>
<div className="flex flex-wrap gap-2">
{['Slack', 'GitHub', 'Notion', 'Stripe', 'Google', 'Linear', '+700 more'].map((c) => (
<span key={c} className="rounded-full border border-white/10 bg-white/[0.03] px-3 py-1.5 text-xs text-[#a3a3a3]">
{c}
</span>
))}
</div>
<Link href="/docs/mcp" className="mt-6 inline-flex items-center gap-1 text-xs font-medium text-[#525252] hover:text-white transition-colors">
MCP tools <ArrowRight className="size-3" />
</Link>
</CardContent>
</Card>
</div>
{/* -- What the CLI can do ----------------------------------------- */}
<Card className="border-white/[0.08] bg-white/[0.02] shadow-none py-0 gap-0 rounded-2xl overflow-hidden">
<CardContent className="p-8 md:p-10">
@@ -344,17 +406,17 @@ print(response.choices[0].message.content)`}
<CardTitle className="text-2xl font-bold tracking-tight">
The <code className="font-mono">hanzo</code> CLI
</CardTitle>
<CardDescription className="text-xs text-[#525252] mt-0.5">One tool for everything</CardDescription>
<CardDescription className="text-xs text-[#525252] mt-0.5">A ~15 MB Rust client for any live cloud prod, laptop, or self-host</CardDescription>
</div>
</div>
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
{[
{ cmd: 'hanzo chat', desc: 'Chat with any model interactively' },
{ cmd: 'hanzo models list', desc: 'Browse 200+ available models' },
{ cmd: 'hanzo models list', desc: 'Browse every available model' },
{ cmd: 'hanzo keys create', desc: 'Create and manage API keys' },
{ cmd: 'hanzo deploy', desc: 'Deploy apps with git push' },
{ cmd: 'hanzo logs', desc: 'Stream logs from any service' },
{ cmd: 'hanzo spaces', desc: 'Manage S3-compatible storage' },
{ cmd: 'hanzo storage', desc: 'Manage S3-compatible storage' },
{ cmd: 'hanzo secrets', desc: 'Manage secrets and env vars' },
{ cmd: 'hanzo bot', desc: 'Deploy and manage AI bots' },
{ cmd: 'hanzo flow', desc: 'Run workflow automations' },
@@ -445,7 +507,7 @@ print(response.choices[0].message.content)`}
</a>
</Button>
<Button asChild variant="outline" size="lg" className="rounded-full border-white/15 px-8 text-white hover:bg-white/5 bg-transparent">
<Link href="/docs/services">
<Link href="/docs">
Browse Documentation
</Link>
</Button>
+7 -2
View File
@@ -3,8 +3,13 @@ import { HanzoDocsIcon } from '@/app/layout.client';
export const linkItems: LinkItemType[] = [
{
text: 'Platform',
url: '/docs/services',
text: 'Docs',
url: '/docs',
active: 'nested-url',
},
{
text: 'Network',
url: '/docs/network',
active: 'nested-url',
},
{
+17 -2
View File
@@ -6,11 +6,24 @@ index: true
# Architecture
This section explains how Hanzo Cloud is put together — what runs today, and where the platform is headed. We keep the two clearly separated: the product pages elsewhere in these docs describe shipped behavior, while the platform direction here is design work being ratified through the [Hanzo Improvement Proposals (HIPs)](https://hips.hanzo.ai).
This section explains how Hanzo Cloud is put together — what runs today, and where the platform is headed. We keep the two clearly separated: the product pages elsewhere in these docs describe shipped behavior, while the platform direction here is design work being ratified through the [Hanzo Improvement Proposals (HIPs)](https://hips.hanzo.ai). For the principles behind it all, see [Engineering Philosophy](/docs/architecture/philosophy).
## Today
Hanzo Cloud is **one Go binary**. A single API key at `api.hanzo.ai` reaches every service — AI inference, identity, secrets, storage, commerce, and more — because those services are **native subsystems compiled into that one binary**, each served under `/v1` and mapped to [hanzoai/openapi](https://github.com/hanzoai/openapi). Ingress and routing are native subsystems too, so the binary is its own front door rather than sitting behind a separate gateway or ingress tier. The catalog is grouped into ten categories — AI, Compute, Data, Network, Security, Observe, Platform, Web3, Apps, and Commerce; see [Platform & Services](/docs/services) for the full list. This single-binary consolidation is the unified cloud binary (HIP-0106), already substantially shipped.
Hanzo Cloud is **one Go binary**. A single API key at `api.hanzo.ai` reaches every capability — AI inference, identity, secrets, storage, commerce, and more — because those capabilities are **native subsystems compiled into that one binary** (`cloud`, `CGO_ENABLED=0`, static), each served under `/v1/<capability>` and mapped to [hanzoai/openapi](https://github.com/hanzoai/openapi). Ingress and routing are native subsystems too, so the binary is its own front door rather than sitting behind a separate gateway or ingress tier. This single-binary consolidation is the unified cloud binary (HIP-0106), already substantially shipped — and it is the same binary that powers [the network you can run yourself](/docs/network).
The 67 capabilities are grouped into the **eight movements** of the capability manifest:
<Cards>
<Card title="Identity & Trust" href="/docs/iam" description="Who you are, what you may touch, where secrets live." />
<Card title="Intelligence" href="/docs/llm" description="Models, agents, evaluation — the mind of the cloud." />
<Card title="Data" href="/docs/sql" description="The stores every capability writes to and reads from." />
<Card title="Streams" href="/docs/pubsub" description="Messaging, durable tasks, async orchestration." />
<Card title="Observability" href="/docs/o11y" description="See everything — telemetry, analytics, usage." />
<Card title="Commerce" href="/docs/commerce" description="The economy — meter, price, bill, reward." />
<Card title="Platform" href="/docs/gateway" description="The cloud fabric — deploy, provision, route, host." />
<Card title="Applications" href="/docs/chat" description="The user-facing surfaces built on all of the above." />
</Cards>
A few products still run as standalone applications on their own domains — for example [Sign](/docs/services/sign) (`esign.hanzo.ai`), [Dataroom](/docs/services/dataroom) (`dataroom.hanzo.ai`), and [Cap Table](/docs/services/captable) (`captable.hanzo.ai`) — authenticating through Hanzo IAM. These are the remaining standalone apps, being absorbed into the one runtime rather than the intended end state.
@@ -19,6 +32,8 @@ A few products still run as standalone applications on their own domains — for
The platform is converging on one model for running these services: a **consensus-backed plugin platform**, where each service is a *plugin* registered into a single cloud runtime, and a small consensus control plane decides where each plugin's writers live. This is a design direction — specified as a draft proposal, not yet a shipped runtime.
<Cards>
<Card title="Engineering Philosophy" href="/docs/architecture/philosophy" description="The principles behind V8: one and one way, decomplect, the language seam is the wire not FFI." />
<Card title="The Network" href="/docs/network" description="The AI cloud you can run yourself — one binary, BYO GPU, the network is the cloud." />
<Card title="Consensus-Backed Plugin Platform" href="/docs/architecture/plugin-platform" description="The HIP-0125 direction: plugins as the unit, consensus over placement, ZAP-native authoring." />
<Card title="ZAP Protocol" href="/docs/zap" description="Zero-Copy App Proto — the high-performance transport plugins default to." />
<Card title="Hanzo Improvement Proposals" href="https://hips.hanzo.ai" description="Where platform architecture is specified and ratified." />
@@ -4,6 +4,7 @@
"icon": "Blocks",
"pages": [
"index",
"philosophy",
"plugin-platform"
]
}
@@ -0,0 +1,127 @@
---
title: Engineering Philosophy
description: The principles behind Hanzo V8 — one and one way, decomplect, ZAP-native, the language seam is the wire not FFI, one contract to N SDKs to thin CLIs.
icon: Compass
---
import { Cards, Card } from '@hanzo/docs-ui/components/card'
import { Callout } from '@hanzo/docs-ui/components/callout'
# Engineering Philosophy
Hanzo **V8 · Open Edition** is composed from a small set of decisions applied
everywhere, so that no consumer ever needs to know or care which part is Go and
which is Rust. This page is the *why* — the design pedagogy. The canonical,
normative version lives in **[HIP-0127](https://hips.hanzo.ai)**.
<Callout type="info">
One rule ties the whole platform together: **one contract, many bindings, thin
clients, and a wire — never FFI — between languages.**
</Callout>
## One and one way
There is exactly one way to do everything, by construction. A capability is
**one name = one `/v1/<name>` = one self-contained spec** — no `svc` suffix, no
singular/plural twins, no facade. The [capability manifest](https://hips.hanzo.ai)
(`capabilities.yaml`) is the single registry: every spec must appear there
exactly once, in exactly one of the [eight movements](/docs). The build *fails*
on an orphan spec, an unlisted spec, or a name in two places. Orthogonality is a
build invariant, not a hope.
The same rule governs distribution: one contract, one client core per stack, one
distribution harness. Every SDK and CLI is **derived** from the contract — none
is hand-forked.
## Decomplect — values, not places
Following Rich Hickey: a capability is named by its **value** (its `/v1` route),
not by its **place** (which repo, language, or pod implements it). We *decomplect*
— unbraid — the things that naive designs fuse together.
<Cards>
<Card title="Values, not places" description="A capability is its route, not its host. Callers bind to /v1/<name>, never to a machine, a process, or a language." />
<Card title="One concern per binary" description="The Go/Rust boundary is a value boundary (ZAP frames), not a place boundary (FFI in one address space). Each box does one thing." />
<Card title="Easy ≠ simple" description="FFI is easy — one repo, one process — but complects two toolchains. The wire seam is simpler: independent, composable, language-free at the edge." />
<Card title="Compose, don't inherit" description="Capabilities are composed over a uniform wire, not extended through shared implementation. Orthogonal and independently complete." />
</Cards>
## One binary, one contract
The application cloud is **one Go binary** (`cloud`, `CGO_ENABLED=0`, static),
embedding the platform's subsystems and mounting them behind a single public
surface: **`/v1/<capability>` over HTTP + ZAP**. That is the ONE contract every
consumer speaks. Capabilities are grouped into the eight movements of the
manifest; each is one name, one route, one spec.
Keeping it pure Go with no cgo is what preserves the single static binary — the
thing that makes [*"run the whole cloud anywhere"*](/docs/network) true.
## The language seam is the wire, never FFI
Hanzo is Go **and** Rust. The cloud is Go; the [engine](/docs/services/engine),
the [`dev`](/docs/dev) agent, and the ML kernels are Rust. They compose over
**[ZAP](/docs/zap)** — network or local socket — each a clean single-language
binary. Go `cloud` and the Rust components **never link each other's code**; they
exchange ZAP frames whose schema lives beside the product that implements it.
Two naive urges, both rejected:
<Cards>
<Card title="Don't fuse over FFI" description="cgo/uniffi in one process destroys the CGO_ENABLED=0 static binary and complects two toolchains. Rejected." />
<Card title="Don't split orgs by language" description="No hanzo-go / hanzo-rs. That leaks an implementation detail into the org and forces users to know which half a capability lives in. Rejected." />
</Cards>
Everything canonical lives under **`hanzoai/<product>`** — organized by
capability, not by language. Users never know which language answered, because
the org is product-first and the wire is uniform — **not** because the languages
are fused.
## One contract → N SDKs → thin CLIs
Distribution is a single derivation tree. The one contract generates the language
bindings and the wire types; the clients are thin frontends over a shared core.
```
hanzo.yaml the ONE contract — /v1 over HTTP + ZAP
│ generate ↓
go-sdk · rust-sdk · js-sdk language bindings (derived)
zap-spec the ZAP wire types
hanzo-client (Rust: ZAP bridge + hanzo.id auth + rust-sdk)
├── hanzo — the control CLI → @hanzo/cli
└── dev — the coding agent → @hanzo/dev
```
- **The CLI is a client, never the server.** It speaks ZAP (or its SDK) to a
*live* cloud — production, a laptop, or a self-host — and never imports the
cloud. That coupling is the trap that bloats a client to hundreds of megabytes.
- **One client core, two thin frontends.** [`hanzo`](/docs/cli) (the control CLI)
and [`dev`](/docs/dev) (the coding agent) share one Rust `hanzo-client`: one
auth stack, one ZAP client, one SDK. The result is a ~15 MB binary — small
enough to ship over npm.
- **One harness, many channels.** Per-platform prebuilt binaries on GitHub
Releases fan out to `@hanzo/cli` / `@hanzo/dev` (npm), `hanzo.sh` (`curl | sh`),
Homebrew, and `go install`. One binary per tool, N channels.
<Callout type="info">
`.zap` and OpenAPI are two transports of the **same** `/v1` contract — both
derived from the per-service spec, never hand-maintained separately. One
contract → HTTP + ZAP + SDKs, all generated.
</Callout>
## Deploy: native PaaS, no second deployer
Deploys go through the native PaaS (`hanzoai/platform`), which merge-patches the
operator's `Service` resource; the operator reconciles the rollout. **No second
deployer.** It is driven by the [`hanzo` CLI](/docs/cli) or the platform UI — the
same one contract, all the way to production.
## Read the specs
<Cards>
<Card title="Architecture" href="/docs/architecture" description="How Hanzo Cloud is built today and the direction it is converging on." />
<Card title="The Network" href="/docs/network" description="The AI cloud you can run yourself — one binary, BYO GPU, the network is the cloud." />
<Card title="ZAP Protocol" href="/docs/zap" description="Zero-Copy App Proto — the wire the Go and Rust halves speak." />
<Card title="Hanzo Improvement Proposals" href="https://hips.hanzo.ai" description="HIP-0127 and the specs it ties together: the unified binary, ZAP, the SDKs, the CLI." />
</Cards>
+38 -33
View File
@@ -1,58 +1,63 @@
---
title: Documentation
description: Comprehensive documentation for the Hanzo AI platform — 69 services covering AI, automation, identity, infrastructure, and operations.
description: The AI cloud you can run yourself. 67 capabilities across eight movements, one contract at api.hanzo.ai — and the same open-source binary you can run on your own machine, GPU, or cluster.
---
import { Cards, Card } from '@hanzo/docs-ui/components/card'
import { Rocket, Code, Package, Cloud, MessageSquare, Cpu, Smartphone, Search, GitBranch, Shield, Lock, Globe, Server, Container, Database } from 'lucide-react'
import { Callout } from '@hanzo/docs-ui/components/callout'
import { Rocket, Code, Package, Globe, Shield, Sparkles, Database, Workflow, Activity, ShoppingCart, Server, LayoutGrid } from 'lucide-react'
# Hanzo Documentation
# The AI cloud you can run yourself
Hanzo is a full-stack AI infrastructure company (Techstars '17). One API key gives access to 69 services covering AI, automation, identity, infrastructure, and operations — all at `api.hanzo.ai`.
Hanzo is **one open-source binary** that serves the whole cloud — 67 capabilities
across [eight movements](#the-eight-movements), one contract at `api.hanzo.ai`.
The same binary that answers in production is the one you run on your own machine,
GPU, or cluster. [**The network is the cloud.**](/docs/network)
## Quick Links
```bash
curl hanzo.sh | sh
```
<Cards>
<Card icon={<Rocket />} title="Run Your Org" href="/docs/run-your-org" description="Signup → brain → bot → team in under 10 minutes" />
<Card icon={<Code />} title="API Reference" href="/docs/openapi" description="OpenAPI docs for every endpoint" />
<Card icon={<Package />} title="SDKs" href="/docs/sdks" description="Python, TypeScript, Go, Rust clients" />
<Card icon={<GitBranch />} title="Open Source" href="/docs/projects" description="150+ open source projects" />
<Card icon={<Rocket />} title="Get Started" href="/docs/getting-started" description="Account, API key, first call — under five minutes." />
<Card icon={<Globe />} title="The Network" href="/docs/network" description="Run the whole cloud yourself. BYO GPU or K8s, mine on any device." />
<Card icon={<Code />} title="API Reference" href="/docs/openapi" description="REST for every capability, generated from OpenAPI." />
<Card icon={<Package />} title="SDKs" href="/docs/sdks" description="Python, TypeScript, Go, Rust — derived from one contract." />
</Cards>
## Products
## The eight movements
Every capability is named by its route — `/v1/<capability>` — and lives in exactly
one movement. This is the whole platform, category-first.
<Cards>
<Card icon={<Cloud />} title="Hanzo Cloud" href="/docs/services/cloud" description="Unified LLM gateway — 100+ models, one API" />
<Card icon={<MessageSquare />} title="Hanzo Chat" href="/docs/services/chat" description="AI chat with Zen models, MCP and ZAP tools" />
<Card icon={<Database />} title="Hanzo Brain" href="/docs/services/brain" description="Five-runtime brain.db substrate every Hanzo product shares" />
<Card icon={<Container />} title="Hanzo Agents" href="/docs/services/agents" description="88 specialist agents, 15 orchestrators, hanzo-mcp native" />
<Card icon={<Cpu />} title="Hanzo Engine" href="/docs/services/engine" description="GPU inference engine — Rust, CUDA, Metal" />
<Card icon={<Smartphone />} title="Hanzo Edge" href="/docs/services/edge" description="On-device AI — run models locally anywhere" />
<Card icon={<Search />} title="Hanzo Search" href="/docs/services/search" description="Sub-50ms hybrid search in Rust" />
<Card icon={<GitBranch />} title="Hanzo Flow" href="/docs/services/flow" description="Visual AI workflow builder" />
<Card icon={<Shield />} title="Identity & Trust" href="/docs/iam" description="Who you are, what you may touch, where secrets live. IAM, AuthZ, KMS, MPC, Zero-Trust." />
<Card icon={<Sparkles />} title="Intelligence" href="/docs/llm" description="The mind of the cloud. Models, agents, MCP, embeddings, prompts, GPUs, functions." />
<Card icon={<Database />} title="Data" href="/docs/sql" description="The stores everything writes to. SQL, Vector, KV, Search, Object, Base, DocDB." />
<Card icon={<Workflow />} title="Streams" href="/docs/pubsub" description="Messaging, durable tasks, async orchestration. PubSub, Tasks, Pipelines, Crawl." />
<Card icon={<Activity />} title="Observability" href="/docs/o11y" description="See everything. Telemetry, metrics, logs, traces, sessions, evals, analytics." />
<Card icon={<ShoppingCart />} title="Commerce" href="/docs/commerce" description="The economy. Meter, price, bill, reward. Commerce, Billing, Marketplace, Referrals." />
<Card icon={<Server />} title="Platform" href="/docs/gateway" description="The cloud fabric. Deploy, provision, route, host. Gateway, Machines, Edge, Registry." />
<Card icon={<LayoutGrid />} title="Applications" href="/docs/chat" description="The user-facing surfaces. Chat, Studio, Dev, Integrations, Apps." />
</Cards>
## Security & Commerce
## Build with it
<Cards>
<Card icon={<Shield />} title="Hanzo Guard" href="/docs/services/guard" description="AI safety — PII redaction, injection detection, content filtering" />
<Card icon={<Lock />} title="Hanzo KMS" href="/docs/services/kms" description="Secrets management and encryption key operations" />
<Card icon={<Globe />} title="Hanzo Commerce" href="/docs/services/commerce" description="Headless commerce — products, orders, subscriptions, payments" />
<Card icon={<Server />} title="Hanzo MPC" href="/docs/services/mpc" description="Multi-party computation for threshold signatures and key management" />
<Card icon={<Package />} title="The hanzo CLI" href="/docs/cli" description="One ~15 MB Rust binary that talks to any live cloud — prod, laptop, or self-host." />
<Card icon={<Sparkles />} title="Zen Models" href="https://zenlm.org" description="Frontier open-weight models, 4B edge to 1T+ reasoning. On HuggingFace." />
<Card icon={<Code />} title="ZAP Protocol" href="/docs/zap" description="Zero-Copy App Proto — the wire the Go and Rust halves speak." />
<Card icon={<Rocket />} title="Architecture & Philosophy" href="/docs/architecture" description="One binary, one contract, the ZAP wire — the engineering principles behind V8." />
</Cards>
## Infrastructure
<Cards>
<Card icon={<Globe />} title="Gateway" href="/docs/services/gateway" description="API gateway and LLM proxy" />
<Card icon={<Server />} title="Ingress" href="/docs/services/ingress" description="L7 reverse proxy with auto TLS" />
<Card icon={<Container />} title="PaaS" href="/docs/services/paas" description="Kubernetes PaaS with GitOps deploy" />
<Card icon={<Database />} title="DB" href="/docs/services/db" description="Serverless PostgreSQL with pgvector" />
</Cards>
<Callout type="info">
This is **V8 · Open Edition**, specified in [HIP-0127](https://hips.hanzo.ai):
one contract, many bindings, thin clients, and a wire — never FFI — between
languages. See [Engineering Philosophy](/docs/architecture/philosophy) for the *why*.
</Callout>
## Resources
- [GitHub](https://github.com/hanzoai) — Source code and open-source projects
- [hanzo.industries](https://hanzo.industries) — Company overview and research
- [hanzo.ai](https://hanzo.ai) — Platform and API access
- [console.hanzo.ai](https://console.hanzo.ai) — Dashboard and API keys
- [hips.hanzo.ai](https://hips.hanzo.ai) — Hanzo Improvement Proposals
+47 -54
View File
@@ -1,93 +1,86 @@
{
"pages": [
"---Getting Started---",
"---[Rocket]Start Here---",
"index",
"getting-started",
"startups",
"deploy",
"network",
"run-your-org",
"startups",
"---[Shield]Identity & Trust---",
"iam",
"authz",
"kms",
"mpc",
"zero-trust",
"authentication",
"api-keys",
"organizations",
"---Platform & Services---",
"services",
"api",
"openapi",
"sdks",
"gateway",
"console",
"integrations",
"apps",
"---Products---",
"studio",
"ai-studio",
"chat",
"---[Sparkles]Intelligence---",
"llm",
"mcp",
"dev",
"usage",
"zap",
"agents",
"mcp",
"ai-studio",
"prompts",
"embeddings",
"marketplace",
"---Cloud: Data---",
"gpus",
"functions",
"---[Database]Data---",
"sql",
"vector",
"kv",
"search",
"datastore",
"docdb",
"storage",
"base",
"datastore",
"docdb",
"memory",
"---Cloud: Compute & Deploy---",
"gpus",
"machines",
"edge",
"functions",
"---[Workflow]Streams---",
"pubsub",
"tasks",
"pipelines",
"registry",
"networks",
"blockchain",
"---Observability---",
"crawl",
"---[Activity]Observability---",
"o11y",
"metrics",
"logs",
"traces",
"sessions",
"dashboards",
"---Evaluation---",
"datasets",
"experiments",
"scores",
"score-configs",
"annotation-queues",
"---Security & Identity---",
"iam",
"kms",
"authz",
"mpc",
"zero-trust",
"zt",
"---Commerce & Billing---",
"---[ShoppingCart]Commerce---",
"commerce",
"billing",
"marketplace",
"referrals",
"---Proof of AI---",
"---[Server]Platform---",
"gateway",
"deploy",
"machines",
"edge",
"networks",
"registry",
"console",
"blockchain",
"proof-of-ai",
"---Architecture---",
"architecture",
"---Infrastructure---",
"tasks",
"pubsub",
"crawl",
"---Skills Reference---",
"---[LayoutGrid]Applications---",
"chat",
"dev",
"integrations",
"apps",
"---[Terminal]Build---",
"cli",
"zap",
"skills",
"---Research---",
"usage",
"organizations",
"---[BookOpen]Reference---",
"architecture",
"services",
"research",
"---Open Source---",
"projects",
"---Contributing---",
"contributing"
]
}
+145
View File
@@ -0,0 +1,145 @@
---
title: The Network
description: The AI cloud you can run yourself. hanzo.network is hanzod nodes that spawn the same unified cloud binary we run in production — OSS AI cloud in one binary, BYO GPU or K8s, mine on any device, free for public and open-source workloads.
icon: Globe
---
import { Cards, Card } from '@hanzo/docs-ui/components/card'
import { Callout } from '@hanzo/docs-ui/components/callout'
import { Steps, Step } from '@hanzo/docs-base-ui/components/steps'
# The AI cloud you can run yourself
Hanzo is **one Go binary**. The `cloud` binary — `CGO_ENABLED=0`, statically
linked — embeds the whole platform: all 67 capabilities across the eight
movements, mounted as subsystems, served behind one contract at
`/v1/<capability>`. The same binary that answers `api.hanzo.ai` in production is
the binary you run on your laptop with one command.
`hanzo.network` is what happens when you point that binary at a chain instead of
a single host. It is a network of **`hanzod` nodes** that spawn and power that
same unified `cloud` binary. **The network is the cloud** — not a hosted service
you rent, but a substrate anyone can join and run.
```bash
curl hanzo.sh | sh
```
<Callout type="info">
This is the story specified in **[HIP-0127 — V8 · Open Edition](https://hips.hanzo.ai)**:
one binary, one contract, a network that is the cloud. Nothing here is a hosted
tier you are locked into — every capability is the same open-source binary,
whether it runs on our nodes or yours.
</Callout>
## One binary, everywhere
The naive way to ship a cloud is dozens of services, each its own image, each its
own deploy. Hanzo rejects that. The application cloud is **one static Go binary**
with no cgo, no cross-toolchain build, no runtime dependencies — which is exactly
what makes *"`curl | sh`, run the whole cloud anywhere"* true.
<Cards>
<Card title="On your machine" description="One binary, no dependencies. Runs the entire cloud locally for development or a single-tenant deployment." />
<Card title="On your GPU or K8s" description="Bring your own accelerator or cluster. The binary uses what you give it — no vendor hardware lock-in." />
<Card title="On the network" description="hanzod nodes spawn the same binary and coordinate over the chain. Join as a provider or a consumer." />
</Cards>
Because the surface is one uniform contract — `/v1/<capability>` over **HTTP +
[ZAP](/docs/zap)** — a consumer never needs to know or care *which* node, *which*
process, or *which* language answered. The route is the identity.
## GitHub for compute
Public and open-source workloads run **free on public nodes**. Think of it as
GitHub for compute: your open work is hosted at no cost on the shared network,
the same way open source is hosted for free today. Private and metered workloads
are market-priced.
<Cards>
<Card title="Public + OSS → free" description="Open-source and public workloads run at no cost on public hanzod nodes. Openness is the pricing tier." />
<Card title="Private → market-priced" description="Private workloads are metered and priced by the market of providers — you pay for what you use, to whoever runs it." />
</Cards>
## Mine on any device
Any device can be a provider. A `hanzod` node contributes its compute to the
network and is paid at market price for the work it does. Confidential workloads
run inside **NVIDIA TEE / Confidential Compute** enclaves, so a provider serves
work it cannot see and a consumer runs work a host cannot inspect.
<Cards>
<Card title="Any device" description="Laptop, workstation, server, or datacenter GPU — if it runs the binary, it can mine." />
<Card title="Confidential by default" description="NVIDIA TEE/CC enclaves keep provider and consumer mutually blind. Trust the math, not the operator." />
<Card title="Market-priced" description="Providers are paid the going rate for the compute they contribute. The network clears the price." />
</Cards>
## The language seam is a wire, never FFI
Hanzo is Go **and** Rust: the cloud is Go, while the [engine](/docs/services/engine),
the [`dev`](/docs/dev) agent, and the ML kernels are Rust. They compose over
**[ZAP](/docs/zap)** — a network or local socket — never over FFI. Each stays a
clean single-language binary; they exchange ZAP frames, they never link each
other's code.
This is deliberate. FFI (cgo/uniffi) is *easy* — one process — but it *complects*
two toolchains and destroys the single static binary. The wire seam is *simpler*:
independent, composable, language-free at the boundary. **Don't fuse — bridge.**
See [Architecture & Philosophy](/docs/architecture) for the full reasoning.
## Run it yourself
<Steps>
<Step>
### Install the binary
```bash
curl hanzo.sh | sh
```
One command installs the [`hanzo` CLI](/docs/cli) — a ~15 MB Rust binary that
speaks to any live cloud, whether it is production, your laptop, or a self-host.
</Step>
<Step>
### Log in
```bash
hanzo login
```
Authenticate with [Hanzo IAM](/docs/iam) — the same identity works against every
cloud, everywhere.
</Step>
<Step>
### Use every capability
```bash
hanzo chat "Explain the network" # Intelligence
hanzo deploy ./my-app # Platform
hanzo secrets set API_KEY=… # Identity & Trust
```
The CLI is a **client, never the server** — it never imports the cloud. It talks
ZAP (or its SDK) to a live cloud. Point it at prod, your laptop binary, or a
customer self-host; the commands are identical.
</Step>
</Steps>
## Learn more
<Cards>
<Card title="Architecture & Philosophy" href="/docs/architecture" description="One binary, one contract, the ZAP wire — the engineering principles behind the network." />
<Card title="The hanzo CLI" href="/docs/cli" description="Install, log in, and drive every capability from one Rust binary." />
<Card title="ZAP Protocol" href="/docs/zap" description="Zero-Copy App Proto — the wire the Go and Rust halves speak." />
<Card title="HIP-0127" href="https://hips.hanzo.ai" description="V8 · Open Edition — the canonical specification for this model." />
</Cards>