The platform.hanzo.ai control plane — deploy and operate applications, containers, and custom domains across your clusters, with IAM-native multi-org access.

Hanzo PaaS

API reference · Hanzo Platform API → — every endpoint, generated from the OpenAPI spec.

Hanzo PaaS (platform.hanzo.ai) is the control plane for shipping software on Hanzo infrastructure. 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.


Studio	`https://platform.hanzo.ai`
Canonical API	`https://platform.hanzo.ai/v1`
Build pipeline API	`https://platform.hanzo.ai/api` (tRPC + OpenAPI)
Auth	Hanzo IAM (interactive) · API key / service token (machine)
Source	github.com/hanzoai/platform

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)

Object	What it is
project	A grouping of related services, owned by an organization
environment	An isolated slice of a project (production, staging, preview)
application	A single deployable unit. Its `appName` is the name of the live workload it drives. `sourceType` is one of `docker`, `git`, `github`, `gitlab`, `bitbucket`, `gitea`, or `drop`; `deployTarget` is `local`, `cloud`, or `k8s`
deployment	One build/deploy run, with status and start/finish timestamps
domain	A hostname mapped to an application or compose service, with automatic TLS

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:

Credential	Header	Use
API key	`x-api-key: <key>`	Machine access to the build-pipeline API (`/api/`). Org-scoped; issued under Settings → API Keys*
Service token	`Authorization: Bearer <token>`	The canonical `/v1` container surface (redeploy, observe)
IAM token	`Authorization: Bearer <iam-jwt>`	Interactive / user access, via Hanzo IAM SSO

Deploy

From the Studio

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

Redeploy a running container (canonical `/v1`)

The canonical, machine-driven redeploy performs a zero-downtime rolling restart of the live workload — it re-pulls the image and recreates pods. It takes a service token and no body:

# Service token comes from KMS — never inline a real value
TOKEN=$(curl -sS -X POST https://kms.hanzo.ai/v1/kms/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r .accessToken)
PAAS_TOKEN=$(curl -sS "https://kms.hanzo.ai/v1/kms/orgs/hanzo/secrets/paas/SERVICE_TOKEN?env=production" \
  -H "Authorization: Bearer $TOKEN" | jq -r .secret.value)

curl -fsS -X POST \
  "https://platform.hanzo.ai/v1/org/$ORG_ID/project/$PROJECT_ID/env/$ENV_ID/container/$APP_ID/redeploy" \
  -H "Authorization: Bearer $PAAS_TOKEN"
# → {"ok":true}

Build and deploy (pipeline `/api`)

To register a new app and run a build through the deployment pipeline, use the OpenAPI surface with an API key. Procedures are <router>.<procedure>:

# 1. Register the application (does not deploy)
curl -fsS -X POST https://platform.hanzo.ai/api/application.create \
  -H "x-api-key: $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web", "environmentId": "'$ENV_ID'" }'

# 2. Attach a Docker image source, then deploy
curl -fsS -X POST https://platform.hanzo.ai/api/application.deploy \
  -H "x-api-key: $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "applicationId": "'$APP_ID'" }'

# Rebuild an existing application
curl -fsS -X POST https://platform.hanzo.ai/api/application.redeploy \
  -H "x-api-key: $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "applicationId": "'$APP_ID'", "title": "ship v1.3.0" }'

application.deploy and application.redeploy enqueue a build job; application.start, application.stop, and application.reload manage the running workload. See the Containers API for the full procedure set.

Observe & drift

The platform continuously reconciles three views of every app and computes drift:

Tag	Meaning
`declared`	The version your operator/manifest declares
`running`	The image actually live in the cluster
`latest`	The newest released version available

# List apps with drift, scoped to an org
curl -fsS "https://platform.hanzo.ai/v1/apps?org=hanzo&drift=true" \
  -H "Authorization: Bearer $PLATFORM_SERVICE_TOKEN"

{
  "apps": [
    { "org": "hanzo", "app": "docs", "env": "production",
      "declared_tag": "v1.4.0", "running_tag": "v1.3.0", "latest_tag": "v1.4.0",
      "health": "yellow", "drift": ["un-rolled"] }
  ],
  "summary": { "total": 1, "byDrift": { "un-rolled": 1 } }
}

Drift is never stored — it is recomputed from declared/running/latest each time. POST /v1/apps/sync refreshes the observed columns from the cluster and release feeds.

Custom domains & TLS

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

curl -fsS -X POST https://platform.hanzo.ai/api/domain.create \
  -H "x-api-key: $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "'$APP_ID'",
    "host": "app.example.com",
    "https": true,
    "certificateType": "letsencrypt"
  }'

Point your DNS at the platform ingress IP shown on the project's Domains tab.

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 control surface and the /api build pipeline

API keys, service tokens, and IAM tokens

Create, deploy, redeploy, and operate applications

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

Hanzo PaaS

On this page