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_KEY | unset未设置 | Server-side Aholo key for live jobs. Unset: the app runs on hosted worlds, stored results and labelled previews.服务端用于实时任务的 Aholo 密钥。未设置时,应用使用托管世界、已存储的结果和带标注的预览运行。 |
AHOLO_REGION | com | com uses api.aholo.ai; cn uses api.aholo.cn.com 使用 api.aholo.ai;cn 使用 api.aholo.cn。 |
NEXT_DIST_DIR | .next | Optional 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
- Import the GitHub repository. The framework preset is Next.js; keep the default build and output settings.导入 GitHub 仓库。框架预设为 Next.js,构建与输出设置保持默认即可。
- Add
AHOLO_API_KEY(andAHOLO_REGIONif 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),也可以留空,以无密钥模式运行。 - Deploy, then open
/api/aholo/statusto confirm the SDK versions and whether a key is present.部署完成后打开/api/aholo/status,确认 SDK 版本以及是否检测到密钥。 - Check
/studio,/studio?play=1,/laband/reportload, 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.tssetsmodule.parser.javascript.url = truefor 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 intranspilePackages.查看器只能在客户端运行。@manycore/aholo-viewer 仅提供 ESM 版本,并依赖 WebGL2 和 Web Workers,因此舞台通过dynamic(..., { ssr: false })引入,并列在transpilePackages中。 - Absolute splat URLs. Pass
new URL(url, location.href).hrefto the splat loader; the worker cannot resolve/assets/....高斯点文件要用绝对 URL。传给 splat loader 的应是new URL(url, location.href).href;worker 无法解析/assets/...。 - Animation reset order.
AnimationAction.reset()setsactive = false; call it before settingactiveandweight.动画重置顺序。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