Self-hosting & deployment自托管与部署

One Next.js app, no database, one optional secret. Holorra runs anywhere Node 20 runs. Without a key it is fully explorable; with AHOLO_API_KEY set, the server can start live jobs too.一个 Next.js 应用,无需数据库,只有一个可选的密钥。能运行 Node 20 的地方就能运行 Holorra。没有密钥也能完整体验;设置 AHOLO_API_KEY 后,服务端还能发起实时任务。

Run it locally本地运行

terminal
git clone https://github.com/mrnetwork0001/Holorra.git
cd Holorra
npm install
cp .env.example .env.local      # optional: add AHOLO_API_KEY
npm run verify:aholo            # SDK exports + CDN asset check
npm run build && npm start      # http://localhost:3000
Use a production build, not next dev. In dev mode React Fast Refresh instruments the viewer's splat worker and the stage fails with $RefreshReg$ is not defined.请使用生产构建,不要用 next dev。开发模式下,React Fast Refresh 会向查看器的 splat worker 注入代码,舞台随即报错 $RefreshReg$ is not defined。

Environment环境变量

Variable变量Default默认值What it does作用
AHOLO_API_KEYunset未设置Server-side Aholo key for live jobs. Unset: the app runs on hosted worlds, stored results and labelled previews.服务端用于实时任务的 Aholo 密钥。未设置时,应用使用托管世界、已存储的结果和带标注的预览运行。
AHOLO_REGIONcomcom uses api.aholo.ai; cn uses api.aholo.cn.com 使用 api.aholo.ai;cn 使用 api.aholo.cn。
NEXT_DIST_DIR.nextOptional build folder name, for side-by-side builds on one machine.可选的构建目录名,用于在同一台机器上并存多个构建。

Visitors can still bring their own key in the studio header; it is sent per request and overrides the server key for that request only.访客仍可以在创作台顶栏填入自己的密钥;它随每次请求发送,只在该次请求中覆盖服务端密钥。

Deploy on Vercel部署到 Vercel

  1. Import the GitHub repository. The framework preset is Next.js; keep the default build and output settings.导入 GitHub 仓库。框架预设为 Next.js,构建与输出设置保持默认即可。
  2. Add AHOLO_API_KEY (and AHOLO_REGION if you use the CN region) under Environment Variables, or leave it empty to run in no-key mode.在 Environment Variables 中添加 AHOLO_API_KEY(使用 CN 区域时再加上 AHOLO_REGION),也可以留空,以无密钥模式运行。
  3. Deploy, then open /api/aholo/status to confirm the SDK versions and whether a key is present.部署完成后打开 /api/aholo/status,确认 SDK 版本以及是否检测到密钥。
  4. Check /studio, /studio?play=1, /lab and /report load, and that a world streams in.检查 /studio、/studio?play=1、/lab 和 /report 能正常加载,并确认有世界成功流式加载进来。

The mirrored results in public/assets total about 135 MB (the largest file is 22 MB) and are served as static files. Hosted worlds stream from Manycore's CDN, not from your deployment.public/assets 中镜像的结果共约 135 MB(最大的文件 22 MB),以静态文件形式提供。托管世界从 Manycore 的 CDN 流式加载,不经过你的部署。

Things that will bite you容易踩的坑

  • Worker URLs. Next.js rewrites new URL(..., import.meta.url) to relative URLs, which break the viewer's blob-module workers and leave every splat load hanging. next.config.ts sets module.parser.javascript.url = true for client builds to keep them absolute.Worker URL。Next.js 会把 new URL(..., import.meta.url) 改写为相对 URL,这会破坏查看器基于 blob 模块的 worker,让每次高斯点加载都一直挂起。next.config.ts 在客户端构建中设置了 module.parser.javascript.url = true,以保持绝对 URL。
  • Client-only viewer. @manycore/aholo-viewer is ESM-only and needs WebGL2 and Web Workers, so the stage is imported with dynamic(..., { ssr: false }) and listed in transpilePackages.查看器只能在客户端运行。@manycore/aholo-viewer 仅提供 ESM 版本,并依赖 WebGL2 和 Web Workers,因此舞台通过 dynamic(..., { ssr: false }) 引入,并列在 transpilePackages 中。
  • Absolute splat URLs. Pass new URL(url, location.href).href to the splat loader; the worker cannot resolve /assets/....高斯点文件要用绝对 URL。传给 splat loader 的应是 new URL(url, location.href).href;worker 无法解析 /assets/...。
  • Animation reset order. AnimationAction.reset() sets active = false; call it before setting active and weight.动画重置顺序。AnimationAction.reset() 会设置 active = false,所以要先调用它,再设置 active 和 weight。
  • Up axes. Aholo worlds are −Y up, glTF is +Y up, SpatialGen output is +Z up. See Worlds & the stage.朝上的坐标轴。Aholo 世界以 −Y 为上,glTF 以 +Y 为上,SpatialGen 输出以 +Z 为上。见世界与舞台。

Repository map仓库结构

src/app/                 routes: / (landing), /studio, /lab, /report, /mcp, /docs
src/app/api/aholo/       server routes: lux3d, world, tasks, asset, director, status
src/components/stage/    AholoHybridStage: the WebGL2 stage, play mode, drop-ins
src/components/docks/    creation dock, inspector, camera-path timeline
src/components/lab/      GLB and URDF viewers for /lab
src/config/              world presets, actors, props, clip library, real results
src/lib/                 SDK clients, URDF assembly, voxel collision, LuxReal export
public/assets/           mirrored Lux3D and SpatialGen results
docs/                    architecture, SDK reference, design system, report PDF
.mcp.json                Aholo MCP server for Claude Code / Cursor