Hanzo PaaS

Hanzo PaaS is the control plane for shipping software on Hanzo infrastructure — Studio at platform.hanzo.ai, API at api.hanzo.ai/v1/platform. You register an application, point it at a Docker image or Git repo, attach a domain, and the platform builds, deploys, and operates it on your clusters — with deployment history, rolling updates, and drift detection. Authentication is delegated to Hanzo IAM with per-organization isolation.

platform.hanzo.ai is the Studio — a browser UI, not an API host. Every programmatic call goes to api.hanzo.ai/v1/platform/..., the same host and the same key as AI, KMS, and analytics.

The model

Hanzo PaaS organizes work into a simple hierarchy:

organization
  └── project
        └── environment            (e.g. production, staging)
              ├── application       (a Docker image or Git source → one workload)
              └── compose           (a multi-service docker-compose / stack unit)

State is stored in Hanzo Base (embedded SQLite, replicated to object storage) — there is no external database to run.

Authentication

Two credential types, both retrieved from Hanzo KMS — never hard-coded:

There is no x-api-key header and no second credential type — one bearer, one host.

Deploy

From the Studio

1. Sign in at platform.hanzo.ai with your Hanzo IAM account.
2. Create a project and an environment.
3. Add an application — choose a Docker image or connect a Git repository.
4. Attach a domain and deploy.

Get a bearer

The machine identity comes from Hanzo KMS; the exchange is the same one every Hanzo service uses.

TOKEN=$(curl -sS -X POST https://api.hanzo.ai/v1/kms/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r .accessToken)

Projects and apps

# List projects in the caller's org
curl -fsS https://api.hanzo.ai/v1/platform/projects \
  -H "Authorization: Bearer $TOKEN"

# Apps in a project
curl -fsS https://api.hanzo.ai/v1/platform/projects/$PROJECT/apps \
  -H "Authorization: Bearer $TOKEN"

Redeploy

curl -fsS -X POST \
  "https://api.hanzo.ai/v1/platform/projects/$PROJECT/apps/$APP/deploy" \
  -H "Authorization: Bearer $TOKEN"

Build an image

Builds run in-cluster on Hanzo's own BuildKit — never on a laptop, never on a third-party runner. One door:

curl -fsS -X POST https://api.hanzo.ai/v1/runner \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "https://github.com/hanzoai/docs",
    "sha": "'$SHA'",
    "image": "ghcr.io/hanzoai/docs:v1.4.0"
  }'
# → 202 {"buildJobId":"…","status":"queued","runnerPool":"…","image":"…","target":"…"}

repo must be a full https:// URL; image must push to a registry we own (ghcr.io/{hanzoai,luxfi,zooai}/*) whose namespace matches the caller's org. sha pins the commit — ref or branch are accepted, defaulting to main.

Do not post to platform.hanzo.ai/v1/* or platform.hanzo.ai/api/*. The first returns 500 Service token is not configured on the server; the second returns the Studio's HTML shell with a 404. Neither is an API.

Custom domains & TLS

Attach a hostname to an application; TLS is provisioned automatically (Let's Encrypt) and a DNS record is created:

Attach it in the Studio under the project's Domains tab, then point your DNS at the ingress IP shown there. Records themselves are managed through Hanzo DNS at api.hanzo.ai/v1/dns.

Self-hosting

git clone https://github.com/hanzoai/platform
cd platform
cp .env.example .env   # set IAM endpoint, service token, etc.
docker compose up -d

The platform runs as a Next.js application with an embedded SQLite database; for production it deploys to a cluster via the operator. It authenticates against Hanzo IAM using the hanzo-platform application.

API Reference

The /v1/platform control surface and /v1/runner builds

IAM bearers and the fabric build token

Create, deploy, redeploy, and operate applications

Register and manage clusters and node pools

Related Services

Identity and access management with multi-org SSO

Secrets and service tokens for deployments

The embedded data store behind the control plane

Object storage for build artifacts and backups