hanzo-base

Hanzo Base is an open source Go backend that provides a complete application backend in a single binary.

Hanzo Base - Open Source Backend for Any App

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-platform.md, hanzo/hanzo-orm.md, hanzo/hanzo-database.md, hanzo/js-sdk.md

Overview

Hanzo Base is an open source Go backend that provides a complete application backend in a single binary. It includes embedded SQLite and PostgreSQL databases with realtime subscriptions, built-in file and user management, an Admin dashboard UI, REST and GraphQL APIs, CRDT-based collaboration, and a JavaScript plugin VM. Go module: github.com/hanzoai/base.

Why Hanzo Base?

Tech Stack

OSS Base

Repo: hanzoai/base. License: MIT.

When to use

Hard requirements

  1. Go 1.24+ for building from source
  2. Node 18+ for Admin UI development only
  3. No external database required (SQLite embedded); PostgreSQL optional via plugins

Quick reference

| Item | Value | |------|-------| | Go module | github.com/hanzoai/base | | Default port | 8080 (Docker), 8090 (dev) | | Admin UI | /_/ path on running instance | | Data dir | ./hz_data (default) | | Health check | GET /api/health | | JS SDK | @hanzoai/base | | React SDK | @hanzoai/base-react | | Docker image | ghcr.io/hanzoai/base | | License | MIT | | Repo | github.com/hanzoai/base |

One-file quickstart

Use as a Go library

package main

import (
 "log"

 "github.com/hanzoai/base"
 "github.com/hanzoai/base/core"
)

func main() {
 app := base.New()

 app.OnServe().BindFunc(func(se *core.ServeEvent) error {
 // registers new "GET /hello" route
 se.Router.GET("/hello", func(re *core.RequestEvent) error {
 return re.String(200, "Hello world!")
 })

 return se.Next()
 })

 if err := app.Start(); err != nil {
 log.Fatal(err)
 }
}

Then run:

go mod init myapp && go mod tidy
go run main.go serve

Run as standalone binary

# Download from releases or build from source
CGO_ENABLED=0 go build -o base ./examples/base
./base serve --http=0.0.0.0:8080 --dir=./hz_data

Docker

docker run -d \
 --name base \
 -p 8080:8080 \
 -v ./hz_data:/pb_data \
 ghcr.io/hanzoai/base \
 serve --http=0.0.0.0:8080 --dir=/pb_data

Core Concepts

Architecture

┌──────────────────────────────────────────────┐
│ Hanzo Base Binary │
├──────────────┬───────────────┬───────────────┤
│ REST API │ Realtime WS │ Admin UI │
│ /api/* │ /api/realtime│ /_/ │
├──────────────┴───────────────┴───────────────┤
│ core.App │
│ ┌─────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Records │ │ Auth │ │ File Storage │ │
│ │ (CRUD) │ │ (OAuth2) │ │ (S3/local) │ │
│ └─────────┘ └──────────┘ └───────────────┘ │
├──────────────────────────────────────────────┤
│ SQLite (default) │ PostgreSQL (cloudsql) │
└──────────────────────────────────────────────┘

Directory Structure

base/
 base.go # Main Base struct, implements core.App
 core/ # Core app logic, records, collections, events, router
 apis/ # HTTP API handlers (records, auth, collections, realtime, batch, etc.)
 cmd/ # CLI commands (serve, superuser)
 crdt/ # CRDT types (document, text, sync)
 forms/ # Form validation (record upsert, email, S3 test)
 migrations/ # Database migration scripts
 mails/ # Email templates
 plugins/
 jsvm/ # JavaScript VM (Goja) for hooks and migrations
 migratecmd/ # Migration CLI command
 cloudsql/ # Serverless PostgreSQL (per-tenant)
 functions/ # OpenFaaS serverless functions
 platform/ # Multi-tenant IAM + KMS integration
 scheduler/ # Cron/scheduled tasks
 ghupdate/ # GitHub self-update
 zap/ # ZAP binary protocol transport (port 9652)
 sdk/
 base-js/ # @hanzoai/base TypeScript SDK
 base-react/ # @hanzoai/base-react React hooks
 tools/ # Internal utility packages
 archive/ # Archive utilities
 auth/ # Auth helpers
 cron/ # Cron scheduler
 dbutils/ # Database utilities
 filesystem/ # File system abstraction
 hook/ # Event hook system
 inflector/ # String inflection
 list/ # List utilities
 logger/ # Structured logging
 mailer/ # Email sending
 osutils/ # OS utilities
 picker/ # Data picker
 router/ # HTTP router
 routine/ # Goroutine helpers
 search/ # Search utilities
 security/ # Security helpers
 store/ # In-memory store
 subscriptions/ # Realtime subscriptions
 template/ # Template engine
 tokenizer/ # Token utilities
 types/ # Custom types
 ui/ # Admin dashboard (Svelte 4 + Vite 5)
 examples/base/ # Standalone example with all plugins
 tests/ # Integration tests
 docs/ # Documentation

Plugin System

Plugins extend Base via hooks on the core.App interface:

| Plugin | Purpose | |--------|---------| | jsvm | JavaScript hooks and migrations via Goja VM | | migratecmd | Database migration CLI commands | | cloudsql | Serverless PostgreSQL per-tenant provisioning | | functions | OpenFaaS serverless function integration | | platform | Multi-tenant IAM (hanzo.id) + KMS (kms.hanzo.ai) | | scheduler | Cron-based scheduled tasks | | ghupdate | GitHub self-update for releases | | zap | Binary protocol transport on port 9652 |

CLI Commands

./base serve # Start the HTTP server
./base serve --dev # Dev mode (verbose logging, SQL output)
./base serve --http=0.0.0.0:8080
./base serve --dir=./hz_data
./base superuser create # Create a superuser
./base superuser upsert # Create or update a superuser

Global Flags

--dir Data directory (default: ./hz_data)
--dev Enable dev mode
--encryptionEnv Env var name for 32-char encryption key
--queryTimeout Default SELECT query timeout in seconds

Auth Methods

Base supports multiple authentication methods out of the box:

Realtime

WebSocket-based realtime subscriptions at /api/realtime:

CRDT

The crdt/ package provides conflict-free replicated data types:

Development

Build and test

# Run tests
go test ./...
make test

# Lint
golangci-lint run -c ./golangci.yml ./...
make lint

# Build standalone binary
cd examples/base
CGO_ENABLED=0 go build

# Generate JS types for JSVM plugin
make jstypes

# Test coverage report
make test-report

Admin UI development

cd ui
npm install
npm run dev # Dev server at localhost:3000
npm run build # Production build to ui/dist/

The Admin UI expects the backend at http://localhost:8090 by default. Override with HZ_BACKEND_URL in ui/.env.development.local.

Docker build

# Multi-stage build (from repo Dockerfile)
FROM golang:1.26-alpine AS builder
WORKDIR /build
COPY . .
CGO_ENABLED=0 go build \
 -ldflags="-s -w -X github.com/hanzoai/base.Version=$(git describe --tags)" \
 -o /build/base ./examples/base/main.go

FROM alpine:3.21
COPY --from=builder /build/base /app/base
EXPOSE 8080
ENTRYPOINT ["/app/base"]
CMD ["serve", "--http=0.0.0.0:8080", "--dir=/pb_data"]

SDK Clients

JavaScript SDK (@hanzoai/base)

import { BaseClient } from '@hanzoai/base';

const client = new BaseClient('http://localhost:8080');

// Reactive queries, query deduplication, optimistic updates
// Exports: core, react hooks, crdt

Exports:

React SDK (@hanzoai/base-react)

import { useBaseQuery } from '@hanzoai/base-react';

// Reactive queries, optimistic mutations, realtime, CRDT collaboration

Official external SDKs

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Port 8090 already in use | Another Base instance running | Kill process or use --http=:8091 | | SQLite build errors | CGO required by default | Use CGO_ENABLED=0 for pure Go SQLite | | Admin UI not loading | UI dist not embedded | Run cd ui && npm run build first | | JS hooks not executing | Wrong hooks directory | Use --hooksDir=./hz_hooks flag | | Modernc version mismatch | Dependency conflict | Check modernc_versions_check.go logs |

Related Skills

Last Updated: 2026-05-12 Category: Hanzo Ecosystem Related: backend, baas, go, realtime, crdt, auth, admin Prerequisites: Go 1.24+, basic REST API knowledge