openzoo 0.51.2 → 0.51.3

package/bin/openzoo.js

@@ -170,18 +170,21 @@ usage:
   npx openzoo balance    wallet balance on every rail — Solana (USDC/TOKEN/SOL),
                          Base (USDC/ETH), Robinhood Chain (USDG/memecoins/ETH)
   npx openzoo build [dir]     transmute a Vercel-shaped app (Next.js pages/api,
-                              app/**/route, Vite + api/*) into a Pinocchio Rust
-                              program + asset plan (--out .zoo-out --arch v0|v3)
-  npx openzoo deploy [dir]    deploy the program and the static frontend to
-                              Solana accounts (--cluster mainnet|devnet|localnet,
-                              --yes to accept the rent estimate; burner wallet)
-  npx openzoo serve <program> local gateway/explorer for a deployed site
-                              (--cluster, --port 4402); /api/* reads are free
+                              app/**/route, Vite + api/*) for Solana. Default
+                              --target shared: bytecode for the shared zoo-vm
+                              runtime, no Rust toolchain, a site is data accounts
+                              (~0.03-0.1 SOL). --target program: own Pinocchio
+                              program per site (--arch v0|v3, ~1 SOL+)
+  npx openzoo deploy [dir]    deploy the site to Solana accounts (--cluster mainnet,
+                              --runtime <zoo-vm id> or OPENZOO_VM_PROGRAM, --yes to
+                              accept the rent estimate; burner wallet)
+  npx openzoo serve [site]    local gateway/explorer for a deployed site (--runtime,
+                              --cluster, --port 4402); /api/* reads are free
                               simulations, writes are signed by the burner
+  npx openzoo runtime deploy  deploy the shared zoo-vm runtime once per cluster
   npx openzoo inspect [dir]   print the app in Vercel terms + eligibility report
   npx openzoo hub             hosted explorer for every transmuted site on the
                               cluster (what sites.openzoo.fun runs)
-  npx openzoo hub             hosted explorer for every transmuted site on the cluster
   npx openzoo address    print both funding addresses (Solana + EVM)
   npx openzoo help       this text
 
@@ -421,6 +424,7 @@ async function main() {
     case 'serve':
     case 'inspect':
     case 'hub':
+    case 'runtime':
     case 'transmute': {
       // VERCEL-SHAPED APP -> SOLANA MAINNET. `openzoo build|deploy|serve` hand
       // the argv to openzoo-transmute (a sibling npm package): it reads the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.51.2",
-  "description": "Local x402-paying proxy + MCP server for openzoo.fun \u2014 point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental. `openzoo build|deploy|serve|hub` transmute a Vercel-shaped app (Next.js / Vite + /api) into a Pinocchio program + asset accounts on Solana mainnet.",
+  "version": "0.51.3",
+  "description": "Local x402-paying proxy + MCP server for openzoo.fun \u2014 point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental. `openzoo build|deploy|serve|hub|runtime` transmute a Vercel-shaped app (Next.js / Vite + /api) into Solana accounts on the shared zoo-vm Pinocchio runtime (~0.05 SOL a site) or a dedicated program, mainnet.",
   "license": "MIT",
   "type": "module",
   "bin": {

package/transmute/README.md

@@ -63,17 +63,48 @@ Requirements: Node ≥ 18, and for `build`/`deploy` the Solana toolchain
 (`cargo build-sbf`): `sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"`.
 `build --skip-cargo` works without it (you get the crate and the cost sheet, no `.so`).
 
-## Quickstart
+## Quickstart (shared runtime — the default)
+
+A site does not need its own program. The `zoo-vm` runtime
+(`runtime/zoo-vm`, prebuilt at `prebuilt/zoo_vm.v0.so`) is deployed once per
+cluster; every site is then just data accounts under it — a 66-byte site
+account, its bytecode module (`/.zoo/code.bin`, ~1–2 KB for a handful of
+routes), its static files and its manifest. Rent for a small site is
+**≈0.03–0.1 SOL** instead of ≈1 SOL+ for a dedicated program.
 
 ```sh
 cd my-next-app                      # or a Vite repo with api/*.js, or a .vercel/output
 npx openzoo-transmute inspect       # the app in Vercel terms + eligibility report
-npx openzoo-transmute build         # → .zoo-out/.zoo/{crate,manifest.json,deploy/*.so}
-npx openzoo-transmute deploy --cluster devnet
-npx openzoo-transmute serve <programId> --cluster devnet
+npx openzoo-transmute build         # → .zoo-out/.zoo/{code.bin,manifest.json,…}; no cargo needed
+npx openzoo-transmute deploy --cluster mainnet --runtime <zoo-vm id> --yes
+npx openzoo-transmute serve         # site id + runtime read from .zoo/deploy.json
 open http://127.0.0.1:4402/         # explorer at /.zoo/, manifest at /.zoo/manifest.json
 ```
 
+The site id is the public key of `.zoo/site-keypair.json` (looks like a
+program id, costs nothing; keep it — redeploys update the same site). The hub
+serves it at `https://sites.openzoo.fun/s/<siteId>` once its
+`OPENZOO_VM_PROGRAM` points at the same runtime.
+
+Deploying the runtime itself (once, ≈2.2 SOL on mainnet for the 313 KB .so,
+upgradeable by the deployer's key):
+
+```sh
+npx openzoo-transmute runtime deploy --cluster mainnet --yes     # keypair → ./zoo-vm-keypair.json
+export OPENZOO_VM_PROGRAM=<printed id>
+```
+
+`--target program` keeps the original path: one Pinocchio program per site,
+compiled from the generated crate with `cargo build-sbf`.
+
+## Quickstart (dedicated program)
+
+```sh
+npx openzoo-transmute build --target program   # → .zoo-out/.zoo/{crate,manifest.json,deploy/*.so}
+npx openzoo-transmute deploy --cluster mainnet --yes
+npx openzoo-transmute serve <programId> --cluster mainnet
+```
+
 `inspect` prints one line per function with its route, style, runtime,
 `maxDuration`, `memory` and methods, marks each `✓`/`✗` and says why:
 
@@ -115,14 +146,16 @@ POST /api/counter            → 402 payment required   (gateway started without
 
 | command | what it does |
 |---|---|
-| `build [dir] [--out .zoo-out] [--name <crate>] [--arch v0\|v3] [--cluster <c>] [--skip-cargo] [--json]` | read the app (`lib/vercel.js`), transmute (`lib/compile/`), write `<out>/.zoo/{crate/, manifest.json, report.json, static-plan.json, build.json}`, run `cargo build-sbf --arch <arch>` → `.zoo/deploy/<name>.so`, print the cost sheet (`--cluster` only chooses the RPC whose rent parameters price it, default `localnet`; unreachable → the 6.96 SOL/MB rule). Default arch is `v0` (mainnet); `deploy` re-detects the cluster's SBPF version and rebuilds if needed. Exit code 2 when nothing was eligible |
-| `deploy [dir\|outDir] [--cluster mainnet\|devnet\|testnet\|localnet\|<url>] [--keypair <path>] [--yes] [--program <id>] [--concurrency 4] [--skip-assets] [--force] [--json]` | deploy or upgrade the program (keypair kept at `.zoo/program-keypair.json`, so redeploys upgrade in place), upload every static file (unchanged ones skipped by comparing bytes on chain), write `/.zoo/manifest.json`, record `.zoo/deploy.json` |
-| `serve [programId] [--cluster <c>] [--port 4402] [--host 127.0.0.1] [--keypair <path>\|--no-keypair] [--quiet]` | the local gateway; `programId` defaults to the `.zoo/deploy.json` under the current directory (or its `.zoo-out/`). Reads are simulated, writes are signed by the wallet; without a wallet (or with `--no-keypair`) writes answer 402. Without `--cluster`/`OPENZOO_CLUSTER` this command assumes `localnet`, unlike the others |
+| `build [dir] [--target shared\|program] [--runtime <id>] [--out .zoo-out] [--name <crate>] [--arch v0\|v3] [--cluster <c>] [--skip-cargo] [--json]` | `--target shared` (default): transmute to a `ZOOB` bytecode module at `<out>/.zoo/code.bin` for the shared runtime, no cargo, site-sized cost sheet. `--target program`: read the app (`lib/vercel.js`), transmute (`lib/compile/`), write `<out>/.zoo/{crate/, manifest.json, report.json, static-plan.json, build.json}`, run `cargo build-sbf --arch <arch>` → `.zoo/deploy/<name>.so`, print the cost sheet (`--cluster` only chooses the RPC whose rent parameters price it, default `localnet`; unreachable → the 6.96 SOL/MB rule). Default arch is `v0` (mainnet); `deploy` re-detects the cluster's SBPF version and rebuilds if needed. Exit code 2 when nothing was eligible |
+| `deploy [dir\|outDir] [--cluster mainnet\|devnet\|testnet\|localnet\|<url>] [--keypair <path>] [--yes] [--runtime <id>] [--program <id>] [--concurrency 4] [--skip-assets] [--force] [--json]` | shared build: create the site account under `--runtime` (or `OPENZOO_VM_PROGRAM`), upload `code.bin`, assets and manifest as PDAs namespaced by the site id (keypair at `.zoo/site-keypair.json`). Program build: deploy or upgrade the program (keypair kept at `.zoo/program-keypair.json`, so redeploys upgrade in place), upload every static file (unchanged ones skipped by comparing bytes on chain), write `/.zoo/manifest.json`, record `.zoo/deploy.json` |
+| `serve [siteId\|programId] [--runtime <id>] [--cluster <c>] [--port 4402] [--host 127.0.0.1] [--keypair <path>\|--no-keypair] [--quiet]` | the local gateway; with `--runtime` the positional is a site id on the shared runtime. It defaults to the `.zoo/deploy.json` under the current directory (or its `.zoo-out/`). Reads are simulated, writes are signed by the wallet; without a wallet (or with `--no-keypair`) writes answer 402. Without `--cluster`/`OPENZOO_CLUSTER` this command assumes `localnet`, unlike the others |
 | `inspect [dir] [--json]` | the Vercel model (functions, static files, routes, crons) plus the eligibility report |
-| `status <programId> [--cluster <c>] [--json]` | program account, authority, `maxDataLen`, deploy slot, and the on-chain manifest |
+| `status <siteId\|programId> [--runtime <id>] [--cluster <c>] [--json]` | program account, authority, `maxDataLen`, deploy slot, and the on-chain manifest; with `--runtime`, the site account and its manifest |
+| `runtime deploy [--cluster <c>] [--keypair <path>] [--yes] [--program-keypair zoo-vm-keypair.json] [--so <path>]` | deploy (or upgrade in place) the shared `zoo-vm` runtime: `prebuilt/zoo_vm.<arch>.so`, or built from `runtime/zoo-vm` when no prebuilt matches the cluster's SBPF version |
+| `runtime status <id> [--cluster <c>]` | the runtime program's account |
 | `help`, `--version` | |
 
-Environment: `OPENZOO_CLUSTER` (default `mainnet` for `deploy`/`status`, `localnet` for `serve`), `OPENZOO_RPC` (mainnet RPC
+Environment: `OPENZOO_VM_PROGRAM` (shared runtime id; default for `--runtime`), `OPENZOO_TARGET` (`shared`/`program`), `OPENZOO_CLUSTER` (default `mainnet` for `deploy`/`status`, `localnet` for `serve`), `OPENZOO_RPC` (mainnet RPC
 URL), `OPENZOO_KEYPAIR` / `OPENZOO_WALLET` (signer path), `OPENZOO_DEBUG=1`
 (stack traces). Signer discovery order (`lib/wallet.js`): `--keypair` →
 `OPENZOO_KEYPAIR` → `OPENZOO_WALLET` or `~/.openzoo/wallet.json` (the openzoo

package/transmute/lib/build.js

@@ -251,8 +251,10 @@ export async function build(root = '.', opts = {}) {
   log(`reading ${root} → ${deployment.source}${deployment.framework ? ` (${deployment.framework})` : ''}: ${deployment.functions.length} function(s), ${deployment.staticFiles.length} static file(s)`);
   for (const n of deployment.notes) { log(`note: ${n}`); notes.push(n); }
 
+  const target = opts.target === 'shared' ? 'shared' : 'program';
   const transmute = opts.transmute || await loadTransmute();
-  const result = await transmute(deployment, { name, runtimePath, arch: opts.arch, root, outDir });
+  const result = await transmute(deployment, { name, runtimePath, arch: opts.arch, root, outDir, target });
+  if (target === 'shared') return buildShared({ root, outDir, zooDir, deployment, name, result, notes, log, opts });
   if (!result || !result.crate || !result.crate['Cargo.toml'] || !result.crate['src/lib.rs']) throw new Error('transmute() returned no crate (expected {crate:{"Cargo.toml","src/lib.rs"}, manifest, report})');
   const manifest = { name, ...(result.manifest || {}) };
   if (!manifest.version) manifest.version = 1;
@@ -295,7 +297,7 @@ export async function build(root = '.', opts = {}) {
   const soSize = soPath ? fs.statSync(soPath).size : null;
   writeJson(path.join(zooDir, 'build.json'), {
     name, crateName, root, outDir, arch, soPath, soSize, soName: soNameFor(crateName), builtAt: new Date().toISOString(),
-    runtimePath, cargo: cargo ? { ok: cargo.ok, missing: !!cargo.missing } : { skipped: true },
+    runtimePath, cargo: cargo ? { ok: cargo.ok, missing: !!cargo.missing } : { skipped: true }, target: 'program',
   });
 
   // Cost sheet.
@@ -309,3 +311,71 @@ export async function build(root = '.', opts = {}) {
   log(`next: openzoo-transmute deploy ${path.relative(process.cwd(), outDir) || outDir} --cluster <localnet|devnet|mainnet>`);
   return { outDir, zooDir, crateDir, manifest, report, soPath, arch, costEstimate, deployment, notes, staticPlan };
 }
+
+// ---------------------------------------------------------------- shared runtime
+
+/** Bytes of the site account the shared runtime creates per site. */
+export const SITE_ACCOUNT_BYTES = 66;
+
+/** Rent for a shared-runtime site: site account + code asset + assets + manifest (no program). */
+export async function estimateSharedCost({ staticFiles = [], codeSize = 0, manifestBytes = 0, connection = null }) {
+  const est = await estimateCost({ staticFiles, soSize: null, manifestBytes, connection });
+  est.items = est.items.filter((i) => i.kind !== 'program');
+  const rent = async (n) => { if (connection) { try { return await connection.getMinimumBalanceForRentExemption(n); } catch {} } return (ACCOUNT_OVERHEAD_BYTES + n) * LAMPORTS_PER_BYTE; };
+  const codeBytes = accountBytesFor('asset', codeSize, 'application/x-zoo-bytecode');
+  const extra = [
+    { label: 'site account (shared runtime)', kind: 'site', bytes: SITE_ACCOUNT_BYTES, lamports: await rent(SITE_ACCOUNT_BYTES) },
+    { label: `/.zoo/code.bin (bytecode = ${codeSize.toLocaleString()} B)`, kind: 'asset', bytes: codeBytes, lamports: await rent(codeBytes) },
+  ];
+  for (const it of extra) it.sol = it.lamports / LAMPORTS_PER_SOL;
+  est.items = [...extra, ...est.items];
+  est.lamports += extra.reduce((n, i) => n + i.lamports, 0);
+  est.sol = est.lamports / LAMPORTS_PER_SOL;
+  est.feeLamports = 5000 * (2 + Math.ceil(codeSize / 900) + staticFiles.reduce((n, f) => n + 1 + Math.ceil(f.size / 900), 0) + 2);
+  est.feeSol = est.feeLamports / LAMPORTS_PER_SOL;
+  est.totalLamports = est.lamports + est.transientLamports + est.feeLamports;
+  est.totalSol = est.totalLamports / LAMPORTS_PER_SOL;
+  est.unknownProgram = false;
+  est.shared = true;
+  return est;
+}
+
+/** `build --target shared`: bytecode module instead of a crate; nothing to compile. */
+async function buildShared({ root, outDir, zooDir, deployment, name, result, notes, log, opts }) {
+  if (!result || !result.code || !result.code.length) throw new Error('transmute() returned no bytecode module for --target shared');
+  const manifest = { name, ...(result.manifest || {}), target: 'shared' };
+  if (!manifest.version) manifest.version = 1;
+  if (!manifest.framework) manifest.framework = deployment.framework;
+  if (!Array.isArray(manifest.routes)) manifest.routes = [];
+  if (!Array.isArray(manifest.static)) manifest.static = deployment.staticFiles.map((f) => ({ path: f.path, contentType: f.contentType, size: f.size }));
+  if (!manifest.config) manifest.config = deployment.config;
+  const runtime = opts.runtime || process.env.OPENZOO_VM_PROGRAM || null;
+  if (runtime) manifest.runtime = runtime;
+  const report = { eligible: [], ineligible: [], warnings: [], ...(result.report || {}) };
+
+  fs.rmSync(path.join(zooDir, 'crate'), { recursive: true, force: true });
+  fs.mkdirSync(zooDir, { recursive: true });
+  const codePath = path.join(zooDir, 'code.bin');
+  fs.writeFileSync(codePath, result.code);
+  const byPath = new Map(deployment.staticFiles.map((f) => [f.path, f]));
+  const staticPlan = manifest.static.map((s) => ({ ...s, file: byPath.get(s.path)?.file || s.file || null }));
+  writeJson(path.join(zooDir, 'manifest.json'), manifest);
+  writeJson(path.join(zooDir, 'report.json'), report);
+  writeJson(path.join(zooDir, 'static-plan.json'), staticPlan);
+  const codeSize = result.code.length;
+  writeJson(path.join(zooDir, 'build.json'), { name, root, outDir, target: 'shared', codePath, codeSize, runtime, builtAt: new Date().toISOString(), cargo: { skipped: true } });
+  log(`wrote ${path.relative(process.cwd(), zooDir) || zooDir}/{code.bin (${codeSize.toLocaleString()} B bytecode), manifest.json, report.json, static-plan.json}`);
+  log(`functions: ${report.eligible.length} eligible, ${report.ineligible.length} ineligible${report.warnings.length ? `, ${report.warnings.length} warning(s)` : ''}`);
+  for (const i of report.ineligible) log(`  ✗ ${i.name}: ${i.reason}${i.file ? ` (${path.relative(root, i.file)}${i.line ? ':' + i.line : ''})` : ''}`);
+  for (const w of report.warnings) log(`  ! ${typeof w === 'string' ? w : w.message || JSON.stringify(w)}`);
+  if (!runtime) { const n = 'no --runtime given: pass --runtime <zoo-vm program id> (or OPENZOO_VM_PROGRAM) at deploy time'; notes.push(n); log(`note: ${n}`); }
+
+  const connection = opts.connection !== undefined ? opts.connection : await probeConnection(opts.cluster || 'localnet');
+  const manifestBytes = Buffer.byteLength(JSON.stringify({ ...manifest, runtime: 'x'.repeat(44), site: 'x'.repeat(44), deployedAt: new Date().toISOString() }));
+  const costEstimate = await estimateSharedCost({ staticFiles: staticPlan, codeSize, manifestBytes, connection });
+  log('');
+  log(formatCostTable(costEstimate));
+  log('');
+  log(`next: openzoo-transmute deploy ${path.relative(process.cwd(), outDir) || outDir} --cluster mainnet${runtime ? '' : ' --runtime <id>'}`);
+  return { outDir, zooDir, crateDir: null, manifest, report, soPath: null, codePath, codeSize, arch: null, target: 'shared', costEstimate, deployment, notes, staticPlan };
+}

package/transmute/lib/cli.js

@@ -14,20 +14,25 @@ import path from 'node:path';
 import { PublicKey } from '@solana/web3.js';
 import { readDeployment } from './vercel.js';
 import { build } from './build.js';
-import { deploy, resolveOutDir, clusterLabel } from './deploy.js';
+import { deploy, deployRuntime, resolveOutDir, clusterLabel } from './deploy.js';
 import { startGateway, DEFAULT_PORT } from './gateway.js';
 import { startHub, DEFAULT_HUB_PORT } from './hub.js';
-import { connect, getProgramInfo, readManifest } from './solana.js';
+import { connect, getProgramInfo, getSiteInfo, readManifest } from './solana.js';
 import { loadWallet, rpcUrl } from './wallet.js';
 import { MANIFEST_PATH } from './wire.js';
 
 export const USAGE = `openzoo-transmute — Vercel app → Solana program + asset accounts
 
 usage:
-  openzoo-transmute build   [dir] [--out .zoo-out] [--name <crate>] [--arch v0|v3] [--cluster <c>] [--skip-cargo]
-  openzoo-transmute deploy  [dir|outDir] [--cluster mainnet|devnet|localnet|<url>] [--keypair <path>] [--yes] [--program <id>]
-                            [--concurrency 4] [--skip-assets] [--force] [--headroom 1.5]
-  openzoo-transmute serve   <programId> [--cluster <c>] [--port ${DEFAULT_PORT}] [--keypair <path>] [--host 127.0.0.1] [--quiet]
+  openzoo-transmute build   [dir] [--target shared|program] [--out .zoo-out] [--name <crate>] [--arch v0|v3] [--cluster <c>] [--skip-cargo]
+                            --target shared (default): bytecode for the shared zoo-vm runtime — a site is data accounts only (≈0.05–0.1 SOL)
+                            --target program: your own Pinocchio program per site (≈1 SOL+)
+  openzoo-transmute deploy  [dir|outDir] [--cluster mainnet|devnet|localnet|<url>] [--keypair <path>] [--yes] [--runtime <zoo-vm id>]
+                            [--program <id>] [--concurrency 4] [--skip-assets] [--force] [--headroom 1.5]
+  openzoo-transmute serve   <siteId|programId> [--runtime <zoo-vm id>] [--cluster <c>] [--port ${DEFAULT_PORT}] [--keypair <path>] [--host 127.0.0.1] [--quiet]
+  openzoo-transmute runtime deploy [--cluster <c>] [--keypair <path>] [--yes] [--program-keypair zoo-vm-keypair.json] [--so <path>]
+                            deploy (or upgrade) the shared zoo-vm runtime once per cluster
+  openzoo-transmute runtime status <zoo-vm id> [--cluster <c>]
   openzoo-transmute hub     [--cluster mainnet] [--port 8080] [--host 0.0.0.0] [--public-url <https://…>]
                             hosted explorer for EVERY program on the cluster (/s/<programId>), read-only
   openzoo-transmute inspect [dir]                 print the Vercel model + eligibility report
@@ -35,7 +40,7 @@ usage:
   openzoo-transmute help
 
 clusters: mainnet (default, needs --yes to deploy), devnet, testnet, localnet, or an RPC URL.
-env: OPENZOO_CLUSTER, OPENZOO_RPC (mainnet RPC), OPENZOO_KEYPAIR / OPENZOO_WALLET (signer).
+env: OPENZOO_CLUSTER, OPENZOO_RPC (mainnet RPC), OPENZOO_KEYPAIR / OPENZOO_WALLET (signer), OPENZOO_VM_PROGRAM (shared runtime id).
 `;
 
 /** `--k v`, `--k=v`, `--flag`, `--no-flag`; everything else is positional. */
@@ -114,26 +119,49 @@ async function tryTransmute(deployment) {
   }
 }
 
+export const DEFAULT_TARGET = 'shared';
+
+/** `--runtime` is the zoo-vm program id (shared) — or, for `--target program`, a zoo-host checkout path. */
+function runtimeFlag(f) {
+  const v = f.runtime;
+  if (typeof v !== 'string') return { runtime: process.env.OPENZOO_VM_PROGRAM || null, runtimePath: f.runtimePath || undefined };
+  if (fs.existsSync(v) && fs.existsSync(path.join(v, 'Cargo.toml'))) return { runtime: process.env.OPENZOO_VM_PROGRAM || null, runtimePath: v };
+  new PublicKey(v);
+  return { runtime: v, runtimePath: f.runtimePath || undefined };
+}
+
 async function cmdBuild(p, f, log) {
-  const r = await build(p[0] || '.', { out: f.out, name: f.name, arch: f.arch, cluster: f.cluster, runtimePath: f.runtime, skipCargo: !!f.skipCargo, log });
-  if (f.json) log(JSON.stringify({ outDir: r.outDir, soPath: r.soPath, arch: r.arch, report: r.report, costEstimate: { sol: r.costEstimate.sol, totalSol: r.costEstimate.totalSol, source: r.costEstimate.source } }, null, 2));
+  const target = f.target || process.env.OPENZOO_TARGET || DEFAULT_TARGET;
+  if (!['shared', 'program'].includes(target)) throw new Error(`--target must be shared or program (got ${target})`);
+  const { runtime, runtimePath } = runtimeFlag(f);
+  const r = await build(p[0] || '.', { out: f.out, name: f.name, arch: f.arch, cluster: f.cluster, target, runtime, runtimePath, skipCargo: !!f.skipCargo, log });
+  if (f.json) log(JSON.stringify({ outDir: r.outDir, target: r.target || 'program', soPath: r.soPath, codePath: r.codePath || null, codeSize: r.codeSize || null, arch: r.arch, report: r.report, costEstimate: { sol: r.costEstimate.sol, totalSol: r.costEstimate.totalSol, source: r.costEstimate.source } }, null, 2));
   return r.report.ineligible.length && !r.report.eligible.length && r.manifest.routes.length === 0 && r.deployment.functions.length ? 2 : 0;
 }
 
 async function cmdDeploy(p, f, log) {
-  const r = await deploy({ outDir: p[0] || '.', cluster: f.cluster, keypair: f.keypair, programId: f.program, yes: !!f.yes, concurrency: f.concurrency ? Number(f.concurrency) : undefined, skipAssets: !!f.skipAssets, force: !!f.force, log });
+  const { runtime } = runtimeFlag(f);
+  const r = await deploy({ outDir: p[0] || '.', cluster: f.cluster, keypair: f.keypair, programId: f.program, runtime, yes: !!f.yes, concurrency: f.concurrency ? Number(f.concurrency) : undefined, skipAssets: !!f.skipAssets, force: !!f.force, headroom: f.headroom, log });
   if (f.json) log(JSON.stringify(r, null, 2));
   return 0;
 }
 
 async function cmdServe(p, f, log) {
   let programId = p[0];
+  let { runtime } = runtimeFlag(f);
   if (!programId) {
     // Fall back to the last deploy in ./ or ./.zoo-out.
-    try { programId = JSON.parse(fs.readFileSync(path.join(resolveOutDir('.'), '.zoo', 'deploy.json'), 'utf8')).programId; } catch { /* none */ }
-    if (!programId) throw new Error('usage: serve <programId> (no .zoo/deploy.json found to infer it from)');
+    try {
+      const d = JSON.parse(fs.readFileSync(path.join(resolveOutDir('.'), '.zoo', 'deploy.json'), 'utf8'));
+      programId = d.target === 'shared' ? d.site : d.programId;
+      if (d.target === 'shared' && !runtime) runtime = d.runtime;
+    } catch { /* none */ }
+    if (!programId) throw new Error('usage: serve <siteId|programId> [--runtime <zoo-vm id>] (no .zoo/deploy.json found to infer it from)');
   }
   new PublicKey(programId); // validate
+  // Shared runtime: the positional is the site id, the program is zoo-vm.
+  let site = null;
+  if (runtime) { site = programId; programId = runtime; }
   let keypair = null, walletPath = null;
   if (f.keypair !== false) {
     try { const w = loadWallet({ keypair: typeof f.keypair === 'string' ? f.keypair : undefined }); keypair = w.keypair; walletPath = w.path; }
@@ -142,10 +170,10 @@ async function cmdServe(p, f, log) {
   const port = f.port != null ? Number(f.port) : DEFAULT_PORT;
   const host = f.host || '127.0.0.1';
   if (keypair && !/^(127\.0\.0\.1|localhost|::1|\[::1\])$/.test(host)) log(`warning: binding ${host} with a signer: anyone who can reach this gateway can send transactions paid by ${keypair.publicKey.toBase58()}; use --no-keypair unless that is intended`);
-  const gw = await startGateway({ programId, cluster: f.cluster, port, host, keypair, log, quiet: !!f.quiet });
+  const gw = await startGateway({ programId, site, cluster: f.cluster, port, host, keypair, log, quiet: !!f.quiet });
   const m = gw.state.manifest;
   log(`openzoo-transmute gateway → ${gw.url}/  (explorer ${gw.url}/.zoo/, manifest ${gw.url}${MANIFEST_PATH})`);
-  log(`program ${programId} on ${gw.state.cluster} · ${m.routes.length} function(s), ${m.static ? m.static.length : '?'} asset(s) · signer ${keypair ? keypair.publicKey.toBase58() + (walletPath ? ` (${walletPath})` : '') : 'none (reads only)'}`);
+  log(`${site ? `site ${site} on runtime ${programId}` : `program ${programId}`} on ${gw.state.cluster} · ${m.routes.length} function(s), ${m.static ? m.static.length : '?'} asset(s) · signer ${keypair ? keypair.publicKey.toBase58() + (walletPath ? ` (${walletPath})` : '') : 'none (reads only)'}`);
   for (const r of m.routes) log(`  ${(r.methods && r.methods.length ? r.methods.join('|') : 'ANY').padEnd(16)} ${r.routePath}`);
   const stop = () => gw.close().then(() => process.exit(0));
   process.once('SIGINT', stop);
@@ -165,10 +193,24 @@ async function cmdInspect(p, f, log) {
 }
 
 async function cmdStatus(p, f, log) {
-  if (!p[0]) throw new Error('usage: status <programId> [--cluster <c>]');
-  const programId = new PublicKey(p[0]);
+  if (!p[0]) throw new Error('usage: status <siteId|programId> [--runtime <zoo-vm id>] [--cluster <c>]');
+  const { runtime } = runtimeFlag(f);
   const rpc = rpcUrl(f.cluster);
   const connection = connect(rpc);
+  if (runtime) {
+    const site = new PublicKey(p[0]);
+    const [info, manifest] = await Promise.all([getSiteInfo(connection, new PublicKey(runtime), site), readManifest(connection, new PublicKey(runtime), site).catch(() => null)]);
+    const out = { site: site.toBase58(), runtime, cluster: clusterLabel(f.cluster), rpc: rpc.replace(/\?.*$/, ''), exists: info.exists, authority: info.authority ? info.authority.toBase58() : null, account: info.pda.toBase58(), manifest: manifest ? { name: manifest.name, routes: manifest.routes?.length ?? 0, static: manifest.static?.length ?? 0, deployedAt: manifest.deployedAt } : null };
+    if (f.json) { log(JSON.stringify(out, null, 2)); return info.exists ? 0 : 1; }
+    log(`site        ${out.site} on runtime ${runtime} (${out.cluster})`);
+    if (!info.exists) { log('status      NOT DEPLOYED'); return 1; }
+    log(`authority   ${out.authority}`);
+    log(`account     ${out.account}`);
+    if (manifest) { log(`manifest    ${manifest.name || ''} · ${out.manifest.routes} function(s), ${out.manifest.static} asset(s) · deployed ${manifest.deployedAt || '?'}`); for (const r of manifest.routes || []) log(`  ${(r.methods && r.methods.length ? r.methods.join('|') : 'ANY').padEnd(16)} ${r.routePath}`); }
+    else log(`manifest    none at ${MANIFEST_PATH}`);
+    return 0;
+  }
+  const programId = new PublicKey(p[0]);
   const [info, slot, manifest] = await Promise.all([getProgramInfo(connection, programId), connection.getSlot('confirmed'), readManifest(connection, programId).catch(() => null)]);
   const out = {
     programId: programId.toBase58(), cluster: clusterLabel(f.cluster), rpc: rpc.replace(/\?.*$/, ''), slot,
@@ -215,13 +257,27 @@ async function cmdHub(p, f, log) {
   return 0;
 }
 
+async function cmdRuntime(p, f, log) {
+  const sub = p[0];
+  if (sub === 'deploy') {
+    const r = await deployRuntime({ cluster: f.cluster, keypair: f.keypair, yes: !!f.yes, programKeypair: f.programKeypair, so: f.so, headroom: f.headroom, log });
+    if (f.json) log(JSON.stringify(r, null, 2));
+    return 0;
+  }
+  if (sub === 'status') {
+    if (!p[1]) throw new Error('usage: runtime status <zoo-vm id> [--cluster <c>]');
+    return cmdStatus([p[1]], { ...f, runtime: undefined }, log);
+  }
+  throw new Error('usage: runtime deploy|status');
+}
+
 export async function run(argv = process.argv.slice(2), io = {}) {
   const log = io.log ?? console.log;
   const error = io.error ?? console.error;
   const { cmd, positionals, flags } = parseArgs(argv);
   if (flags.version) { log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version); return 0; }
   if (flags.help || cmd === 'help' || cmd === '--help') { log(USAGE); return 0; }
-  const commands = { build: cmdBuild, deploy: cmdDeploy, serve: cmdServe, inspect: cmdInspect, status: cmdStatus, hub: cmdHub };
+  const commands = { build: cmdBuild, deploy: cmdDeploy, serve: cmdServe, inspect: cmdInspect, status: cmdStatus, hub: cmdHub, runtime: cmdRuntime };
   const fn = commands[cmd];
   if (!fn) { error(`unknown command: ${cmd}\n`); error(USAGE); process.exitCode = 1; return 1; }
   try {