Vifu Runtime
Vifu Runtime is the hosted environment that loads your browser game and connects it to Vifu Cloud.
How It Fits Together
| Layer | Vifu provides | Your game provides |
|---|---|---|
| CLI | manifest validation, build orchestration, deploy, publish, diagnostics | source code, build command, manifest |
| Manifest | public V1 feature declaration | game name, entry file, build output, requested features |
| Web Shell | SSR project pages, metadata, auth/session context, host bridge, creator/project routing | public project identity and player-facing metadata |
| Runtime Gateway | isolated runtime origin, /play, CSP, executable bundle delivery, runtime session files | HTML, JavaScript, WASM, CSS, images, and other deployed bundle assets |
| Web Runtime | iframe embedding, sandbox, SDK bridge, lifecycle events | rendering, input, rules, safe state, declared game-owned tools |
| SDK | AI, resources, save state, runtime tools | safe state, tool handlers, game-owned serialization |
| Cloud | auth, AI provider routing, quota, runtime assets, game state | player-facing game data and release intent |
AI Runtime Model
For most games, start with vifu.ai.generateText(...). The host/session owns which Mind is active, so the game can request text or tool-backed actions without hardcoding a provider or persona.
Use Runtime Agents when the game has multiple independent AI participants that must keep separate tools, instructions, and run state.
Vifu separates the intelligence from the runtime entity using it:
| Term | Meaning |
|---|---|
| Mind | Intelligence, persona, model, or provider. |
| Agent | Runtime participant with its own tools and runs. |
| Companion | Agent kind for a user-facing partner, bubble, voice, or surface. |
| NPC/Tutor/Director | Other agent kinds for games, learning, and interactive scenes. |
| Tool | Callable runtime ability available to one AI turn or Agent. |
Use vifu.tool(...), vifu.agent(...), and vifu.run(...) when an NPC, tutor, companion, narrator, or game object needs an isolated tool registry and run session. Do not create agents just to make a single AI call.
Production Origins
Vifu keeps the trusted shell, untrusted runtime, and backend API on separate origins:
| Origin | Owner | Responsibility |
|---|---|---|
https://vifu.ai | Web shell Worker | SSR/BFF pages, login-aware shell, host bridge, creator/project URLs |
https://runtime.vifu.ai | Runtime Gateway Worker | /play, runtime HTML, executable runtime bundle assets, runtime session file URLs |
https://api.consenger.com | API Gateway and API Workers | launch resolution, auth, private checks, AI, credits, game state, runtime data/media |
Development uses https://runtime-dev.vifu.ai for the runtime gateway and https://api-dev.consenger.com for API calls.
Runtime Flow
- You run
vifu deploy. - The CLI validates
manifest.json. - The CLI builds and scans the static artifact.
- Vifu uploads the artifact and creates or updates the game.
- The public project page on
vifu.ai/{owner}/{project}server-resolves the game and public launch payload. - The web shell embeds
play_url, which points atruntime.vifu.ai/play. - Runtime Gateway serves the entry HTML and rewrites executable bundle asset URLs to the runtime origin.
- Runtime data and media are fetched from Vifu API endpoints for now; they will move behind Runtime Gateway when network egress is tightened further.
- The SDK bridge connects the game to Vifu platform capabilities declared by the manifest.
Important Boundary
The runtime does not make arbitrary browser code trusted. Vifu-hosted community games run as untrusted iframe code on the runtime origin. The security model is layered:
- the web shell owns route resolution, metadata, session context, and the host bridge
- the runtime gateway owns
/play, CSP, runtime HTML, executable bundle assets, and runtime session files - the API owns authorization, private checks, AI, credits, game state, and backend-owned runtime data/media
- iframe sandboxing and CSP harden browser execution, but backend authorization remains the business security boundary
Use the SDK for platform access; do not construct backend URLs or send raw host messages.