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 builds to platform.hanzo.ai. That origin serves the Studio's browser UI, and paths it does not route fall through to its HTML shell with a 404. The one build door is api.hanzo.ai/v1/runner.

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