Files
skills/public/app-port.html
zeekayandHanzo Dev dc9194a5ac Say what runs locally, with a start command that works
skill.md described only the hosted cloud. An outside adopter's agents
vendored it and had to note that its paid-cloud commands did not apply,
and the local lines it did carry did not work: `hanzo up cloud` forwards
to `hanzo host serve`, which needs a cloud binary it does not build, and
`brew install hanzoai/tap/hanzo` installs CLI 1.9.57 against 8.5.158.

"On your own machine" gives one start command each for Base, the cloud,
zip, the MCP server and the engine, each run against current main or the
published package, and lists what only the hosted cloud has. cloud-host
starts from the command that runs and says what `hanzo host serve`,
`hanzo host start` and `hanzo up` expect. app-port and the Go coursework
point at the same commands instead of an invented compose file; llms.txt
opens with the entry, and the site's lede no longer promises a complete
local copy.

Two README commands fail on main, so these pages do not use them: the
cloud's `make dev` stops with `cek: this build cannot encrypt a store`,
and Base's `go install .../examples/base@latest` is refused for its
replace directive.

public/ is regenerated with HIPs from hanzoai/hips main (0eedbe1). The
last build read a working tree, so it served uncommitted HIP edits and
six HIPs that are not on main (1191-1195, 1329); those leave the index,
and their pages stay where they were.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 10:36:35 -07:00

410 lines
32 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>app-port</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/app-port.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/app-port">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/app-port.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>app-port</h1><p class="lede">Port an existing application onto the Hanzo stack — Hanzo Base and Hanzo Cloud OSS for the backend, ZAP for transport, @hanzo/ui and @hanzo/gui for the interface — and move its Python or JavaScript runtime into Go, Rust or C++. Use when adopting a Next.js, Node, Django, Flask, FastAPI, Rails or Spring app; when a service still speaks WebSockets; when a deployment still needs an interpreter beside the binary; or when asked to modernise, migrate or absorb an app somebody else&#x27;s stack currently runs.</p><h1>Migrate to Native Code: Go, Rust &amp; C++ with Hanzo Base</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related Skills</strong>: <code>hanzo/hanzo-base.md</code>, <code>hanzo/hanzo-cloud.md</code>, <code>hanzo/hanzo-stack.md</code>, <code>hanzo/hanzo-zap.md</code>, <code>hanzo/hanzo-analytics.md</code>, <code>hanzo/go-sdk.md</code></p>
<h2>Overview</h2>
<p>Modernizing your stack means moving away from interpreted, slow runtimes. Hanzo enforces an unapologetic architectural standard across its entire ecosystem: <strong>native compiled code only — in C++, Rust, and Go.</strong> No multi-gigabyte <code>node_modules</code>, no Python GIL or virtualenv fragility, and no bloated Next.js SSR servers.</p>
<p>Hanzo&#x27;s parts are open source and run on your own machine; <code>skill.md</code> gives the command that starts each. You can run locally, extend the cloud with new <code>/v1/*</code> subsystems, and build on <strong>Hanzo Base</strong> (<code>github.com/hanzoai/base</code>) with native realtime Server-Sent Events (SSE), analytics, and insights.</p>
<pre><code>┌─────────────────────────────────────────────────────────────────────────────┐
│ THE HANZO NATIVE STACK │
│ │
│ REPLACE SLOW INTERPRETED RUNTIMES: │
│ ❌ Python (GIL, .venv fragility, slow inference loops) │
│ ❌ Next.js / Node (node_modules bloat, SSR cold starts, high memory) │
│ ❌ Rails / Django / Spring (heavy runtime overhead, fragile microservices) │
│ │
│ WITH COMPILED NATIVE CODE ONLY: │
│ ⚡ Go: Control plane, Hanzo Base, Hanzo Cloud, ZAP transport, IAM, KMS │
│ ⚡ Rust: Inference engine, EVM execution (reth), payment switch, dev CLI │
│ ⚡ C++: Hardware tensor kernels, CUDA, Metal &amp; Apple Neural Engine (ANE) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ RUN IT ON YOUR OWN MACHINE │ │
│ │ - Base, Cloud, zip, MCP server, Engine: checkout or package │ │
│ │ - start commands: skill.md, section On your own machine │ │
│ │ - sign-in, billing and hosted models: api.hanzo.ai │ │
│ └──────────────────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────┴─────────────────────┐ │
│ ▼ ▼ │
│ EXTEND WITH NEW /v1/* SUBSYSTEMS HANZO BASE REALTIME BACKEND │
│ - Host + plugin architecture (HIP-0106) - Single Go binary (CGO=0) │
│ - Route in manifest/apps.go - Embedded SQLite / Postgres │
│ - Zero-overhead ZAP transport (HIP-0114) - Native Realtime SSE streams │
│ - Built-in Analytics &amp; Insights│
│ │ │
│ ▼ │
│ BUILD AGAINST HANZO AI CLOUD │
│ - api.hanzo.ai/v1 │
│ - Zen Models (qwen3+ only) │
│ - Hanzo AI (Techstars &#x27;17) │
└─────────────────────────────────────────────────────────────────────────────┘</code></pre>
<hr>
<h2>Why Native Code Only?</h2>
<p>| Metric | Legacy Interpreted (Python / Next.js / Node) | Hanzo Native (Go / Rust / C++) | |---|---|---| | <strong>Binary &amp; Footprint</strong> | Multi-GB <code>node_modules</code> or <code>.venv</code> | <strong>Single static executable (<code>CGO_ENABLED=0</code>)</strong> | | <strong>Cold Start</strong> | 1.5s – 8s | <strong>&lt; 15ms instant startup</strong> | | <strong>Idle Memory</strong> | 200MB – 800MB+ per process | <strong>15MB – 35MB</strong> | | <strong>Concurrency</strong> | Single-threaded event loop or GIL | <strong>Goroutines (Go) &amp; async Tokio (Rust)</strong> | | <strong>Transport</strong> | JSON over HTTP/1.1 or bulky gRPC | <strong>ZAP transport: zero-copy binary/JSON</strong> | | <strong>Realtime</strong> | Heavy WebSockets or external pusher SaaS | <strong>Native SSE (Server-Sent Events) &amp; CRDTs</strong> | | <strong>Observability</strong> | External agent daemons &amp; heavy SDKs | <strong>Native telemetry, ClickHouse/sqlite columns</strong> |</p>
<hr>
<h3>Measure it on the app in front of you</h3>
<p>Two claims worth making to whoever is paying for the work, and one way to check each on the app in front of you rather than taking it from here.</p>
<p><strong>Fewer moving parts at runtime.</strong> The before is an interpreter, the application on top of it, a process supervisor, and usually a second container for the other language. The after is one binary. Measure it: resident memory at idle and under the same load, and the count of processes and images the deployment needs. Take both readings on the same machine with the same traffic, because a number from somebody else&#x27;s benchmark is a number about their hardware.</p>
<p><strong>Concurrency stops costing a process.</strong> A Python application serves concurrent requests by forking workers, and every worker is another copy of the interpreter and its heap; a Node application gets one loop and adds processes to use more cores. Goroutines are neither. The reading that shows this is memory against concurrency: hold the request rate and raise the concurrency, and watch whether the footprint follows.</p>
<p>State these as what they are. The mechanism is certain — one process is fewer processes — and the size of the win is a property of the app, so measure it rather than quoting a multiplier.</p>
<h3>The part that matters most</h3>
<p>A developer can run the whole thing on the computer they already own.</p>
<p>That is not a performance note. When the development environment is one binary and a local cloud, working on the project does not require renting somebody else&#x27;s computer, a cluster to be provisioned, a seat on a plan, or a network connection good enough to stream a workspace. Someone on a modest laptop, on a bad connection, in a country where the card required to sign up is hard to get, can do the same work as someone on a funded team.</p>
<p>Stacks that can only be run in a data centre quietly decide who gets to contribute. This one does not, and keeping it that way is a design constraint rather than a side effect — if a change means the app can no longer be run locally in full, that is a cost to weigh and usually a reason to choose differently.</p>
<h2>The Core Triad: Go, Rust, C++</h2>
<p>Across Hanzo, every layer uses the right native tool:</p>
<ol><li><strong>Go (Control Plane, Cloud &amp; Base Backend)</strong>:</li></ol>
<ul><li><strong>Hanzo Base (<code>github.com/hanzoai/base</code>)</strong>: Single-binary Go backend with embedded SQLite (<code>modernc.org/sqlite</code>) and PostgreSQL (<code>pgx/v5</code>).</li><li><strong>Hanzo Cloud (<code>github.com/hanzoai/cloud</code>)</strong>: One light host binary, zero runtime microservice sprawl, routing 140+ subsystems over ZAP transport.</li><li><strong>IAM &amp; KMS</strong>: Embedded identity (<code>hanzo.id</code>) and secrets management (<code>kms.hanzo.ai</code>).</li></ul>
<ol><li><strong>Rust (High-Performance Compute &amp; System Execution)</strong>:</li></ol>
<ul><li><strong>Hanzo Engine (<code>hanzoai/engine</code>)</strong>: Native inference and embedding runtime.</li><li><strong>Hanzo EVM (<code>hanzoai/reth</code>)</strong>: Blockchain execution engine.</li><li><strong>Hanzo Payments (<code>hanzoai/payments</code>)</strong>: Sub-millisecond payment orchestration switch.</li><li><strong>Hanzo Dev CLI (<code>hanzoai/dev</code>)</strong>: Native developer CLI and TUI.</li></ul>
<ol><li><strong>C++ / Metal / CUDA (Hardware Acceleration)</strong>:</li></ol>
<ul><li>Optimized tensor kernels for Apple Silicon (Metal/ANE) and NVIDIA GPUs (CUDA).</li></ul>
<hr>
<h2>The order, and why it is this order</h2>
<p>Each step leaves the app working. Do not start the next until the current one is deployed.</p>
<p><strong>Stand it up unchanged, inside our binary.</strong> JavaScript through goja, Python through gpython, both in-process. Nothing is rewritten. What this buys is the deployment: one Go binary, no Node beside it, no Python beside it, no second base image. It is also the step that proves the surface — every route the old runtime served is now served by ours, and a diff of responses says whether that is true.</p>
<p><strong>Move the transport to ZAP.</strong> Same messages, same handlers, new wire. A service still speaking WebSockets at this point is a service that will still be speaking them a year from now.</p>
<p><strong>Port the interface to <code>@hanzo/ui</code> on <code>@hanzo/gui</code>.</strong> This is a visual port and it has its own skill — use <code>ui-port-parity</code>, which treats the existing interface as an executable visual contract and converges screen by screen with measurement rather than by eye. Do not attempt it by inspection.</p>
<p><strong>Port the handlers to Go, one at a time.</strong> The embedded runtime is the fallback for everything not yet ported, so a handler moves when it is ready and the rest keep running. A route is done when its Go implementation answers byte-identically to the embedded one, and that is a test, not a judgement.</p>
<p><strong>Delete the embedded runtime.</strong> When no route falls through to it. Not before, and not &quot;temporarily kept&quot; — an interpreter nobody needs is an interpreter nobody maintains and a dependency that still ships.</p>
<h2>ZAP, not WebSockets</h2>
<p>A service that still opens a WebSocket has not been ported, however much of its code is now Go. WebSockets are the thing being replaced, not a transport to keep beside ZAP: two transports means two reconnect policies, two auth paths and two sets of framing bugs, and the one carrying production traffic ends up being whichever the last change touched.</p>
<p>Port the transport as its own step, with the message shapes unchanged, so a failure is attributable to the transport rather than to everything at once.</p>
<hr>
<h2>Step 1: Run the Stack Locally</h2>
<p>Start the parts you are porting onto with the commands in <code>skill.md</code>, under <em>On your own machine</em> (<code>curl hanzoskills.com/skill.md</code>). Base and the cloud start from a checkout with no account, and the same section lists what needs the hosted cloud.</p>
<hr>
<h2>Step 2: Build with Hanzo Base &amp; Native Realtime SSE</h2>
<p>Replace Next.js API routes and Python FastAPI backends with <strong>Hanzo Base</strong> (<code>github.com/hanzoai/base</code>). It provides native Server-Sent Events (SSE) out of the box for real-time AI completion streaming, chat, and event broadcasting without third-party services:</p>
<pre><code class="lang-go">package main
import (
&quot;fmt&quot;
&quot;log&quot;
&quot;net/http&quot;
&quot;github.com/hanzoai/base&quot;
&quot;github.com/hanzoai/base/core&quot;
)
func main() {
app := base.New()
// 1. Native Realtime SSE Completion Stream
app.OnServe().BindFunc(func(se *core.ServeEvent) error {
se.Router.GET(&quot;/v1/stream/events&quot;, func(re *core.RequestEvent) error {
w := re.Response
r := re.Request
// Set SSE Headers
w.Header().Set(&quot;Content-Type&quot;, &quot;text/event-stream&quot;)
w.Header().Set(&quot;Cache-Control&quot;, &quot;no-cache&quot;)
w.Header().Set(&quot;Connection&quot;, &quot;keep-alive&quot;)
flusher, ok := w.(http.Flusher)
if !ok {
return re.String(500, &quot;Streaming unsupported&quot;)
}
// Stream events natively
for i := 1; i &lt;= 5; i++ {
fmt.Fprintf(w, &quot;data: {\&quot;event\&quot;: \&quot;ping\&quot;, \&quot;seq\&quot;: %d}\n\n&quot;, i)
flusher.Flush()
}
return nil
})
// 2. Realtime Event Hook Broadcast
app.OnRecordAfterCreateSuccess(&quot;messages&quot;).BindFunc(func(e *core.RecordEvent) error {
// Automatically broadcast to SSE subscribers
app.SubscriptionsBroker().Broadcast(map[string]any{
&quot;action&quot;: &quot;create&quot;,
&quot;record&quot;: e.Record,
}, &quot;messages&quot;)
return e.Next()
})
return se.Next()
})
if err := app.Start(); err != nil {
log.Fatalf(&quot;Failed to start Hanzo Base: %v&quot;, err)
}
}</code></pre>
<hr>
<h2>Step 3: Native Analytics &amp; Insights</h2>
<p>Stop embedding client-side tracker scripts or heavy telemetry agents. Hanzo Base includes native privacy-first event tracking and analytics logging:</p>
<pre><code class="lang-go">app.OnServe().BindFunc(func(se *core.ServeEvent) error {
// Middleware: Log native request analytics directly to embedded storage
se.Router.Bind(func(re *core.RequestEvent) error {
start := time.Now()
err := re.Next()
duration := time.Since(start)
// Record analytics event
go func(path string, status int, dur time.Duration) {
collection, _ := app.FindCollectionByNameOrId(&quot;analytics_events&quot;)
if collection != nil {
record := core.NewRecord(collection)
record.Set(&quot;path&quot;, path)
record.Set(&quot;status&quot;, status)
record.Set(&quot;duration_ms&quot;, dur.Milliseconds())
record.Set(&quot;timestamp&quot;, time.Now().UTC())
_ = app.Save(record)
}
}(re.Request.URL.Path, re.Response.Status(), duration)
return err
})
return se.Next()
})</code></pre>
<hr>
<h2>Step 4: Extend with New <code>/v1/*</code> Subsystems</h2>
<p>Hanzo Cloud uses a clean host + plugin architecture (HIP-0106). Every service registers under <code>/v1/&lt;name&gt;</code>:</p>
<ol><li>Create your subsystem under <code>apps/&lt;name&gt;</code> or as an embedded Go router plugin.</li><li>Declare the routing prefix in <code>manifest/apps.go</code>:</li></ol>
<p> ``<code>go var Apps = []App{ {Name: &quot;iam&quot;, Prefix: &quot;/v1/iam&quot;}, {Name: &quot;kms&quot;, Prefix: &quot;/v1/kms&quot;}, {Name: &quot;analytics&quot;, Prefix: &quot;/v1/analytics&quot;}, {Name: &quot;myfeature&quot;, Prefix: &quot;/v1/myfeature&quot;}, // Your new subsystem! {Name: &quot;ai&quot;, Prefix: &quot;/v1&quot;}, // AI gateway catch-all } </code>``</p>
<ol><li>Transport between subsystems uses <strong>ZAP transport</strong> (HIP-0114) — typed Go interfaces in-process, zero-copy RPC across VM boundaries.</li></ol>
<hr>
<h2>Step 5: Build Against the Full Hanzo AI Cloud</h2>
<p>Once your native Go backend is running locally, connect seamlessly to production at <code>api.hanzo.ai</code>:</p>
<pre><code class="lang-bash"># Call the unified AI Gateway (HIP-0004)
curl -s https://api.hanzo.ai/v1/chat/completions \
-H &quot;Authorization: Bearer $(hanzo auth token)&quot; \
-H &#x27;content-type: application/json&#x27; \
-d &#x27;{
&quot;model&quot;: &quot;zen&quot;,
&quot;messages&quot;: [{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Modernize my architecture&quot;}],
&quot;stream&quot;: true
}&#x27;</code></pre>
<ul><li><strong>Models</strong>: Frontier open-weight foundation models and Zen (<code>qwen3+</code> only).</li><li><strong>Identity</strong>: Hanzo IAM (<code>hanzo.id</code>).</li><li><strong>Secrets</strong>: Hanzo KMS (<code>kms.hanzo.ai</code>).</li><li><strong>Company</strong>: Hanzo AI is Techstars &#x27;17.</li></ul>
<hr>
<h2>What not to do</h2>
<p><strong>Do not run the old and new implementations side by side in production and compare.</strong> It doubles the failure surface and the comparison is never clean, because the two see different requests. Compare against captured traffic instead.</p>
<p><strong>Do not port tests last.</strong> The embedded runtime is the oracle: a Go handler is correct when it answers the way the interpreted one did, and that is only checkable while the interpreted one still exists.</p>
<p><strong>Do not keep a second component library &quot;for the parts we haven&#x27;t got to&quot;.</strong> Two libraries is two type ramps, two spacing scales and two sets of focus styles, and the screens between them read as a seam.</p>
<p><strong>Do not preserve an API shape nobody uses</strong> just because it was there. Check the callers first; a port is the cheapest moment to drop a surface, and the most expensive moment to carry one forward.</p>
<h2>The Native Migration Checklist</h2>
<ul><li>[ ] Eliminate Node.js / Next.js / Python interpreter dependencies.</li><li>[ ] Scaffold single-binary Go backend with <code>github.com/hanzoai/base</code>.</li><li>[ ] Configure <code>compose.yml</code> for local multi-service testing.</li><li>[ ] Stream completions &amp; live state via native Server-Sent Events (SSE).</li><li>[ ] Enable native analytics &amp; insights with embedded collection logging.</li><li>[ ] Extend the cloud by mounting new <code>/v1/*</code> endpoints over ZAP transport.</li><li>[ ] Build single static executable with <code>CGO_ENABLED=0</code>.</li><li>[ ] Connect to <code>api.hanzo.ai</code> using Zen (<code>qwen3+</code>) models.</li><li>[ ] Deploy with <code>git push</code> to <code>git.hanzo.ai</code>.</li></ul>
<h2>Telling whether it worked</h2>
<ul><li>One binary, no interpreter in the image, no runtime beside it.</li><li>No WebSocket endpoints.</li><li>Every component from <code>@hanzo/ui</code>; the ramp from <code>@hanzo/design</code>.</li><li>The appearance knobs move the interface, checked by reading a component&#x27;s</li></ul>
<p> computed colour after setting one — a panel that does nothing is a common and invisible failure.</p>
<ul><li>Handlers are goroutines.</li><li>The interface converges under <code>ui-port-parity</code>&#x27;s gates, not under review.</li></ul>
<h2>The interface half</h2>
<p>This skill covers the backend, the transport and the runtime. Porting the interface is its own problem with its own failure modes — an agent comparing two screens by eye will declare a match a person rejects at a glance — and it has its own skill: <strong><code>ui-port</code></strong>. Use it rather than reimplementing the measurement.</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/app-port.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>