Vifu core runtime design
Status: Available. This page describes behavior implemented in the open-source Vifu runtime today.
Vifu uses one project-centered invocation model in two shapes. An application
can embed VifuRuntime and call it directly, or use Vifu Server for stable
project APIs, authorization, database persistence, and traces. The application
continues to own its interface and interaction design.
Running components
Embedded
One embedded Runtime represents one application or project. It registers providers, Agents, and named endpoints dynamically, keeps independent session state, and supports async or non-blocking start/poll/cancel invocation.
Service
- VifuRuntime supplies the provider, Agent, endpoint, session, timeout, cancellation, and result semantics used by embedded hosts and Server.
- Vifu Server authorizes project requests, resolves Agents, and stores projects, keys, provider configuration, and traces.
- Vifu Agent Gateway is an optional remote provider transport. It connects to Server; several Gateways can serve the same deployment.
- PostgreSQL keeps operational state across Server restarts.
- Operations Console configures and inspects the same APIs used by other clients.
How an Agent request runs
- The client sends a project key and an Agent identifier.
- Vifu Server checks the key's project and permissions.
- The Server builds the selected Runtime provider, Agent, and endpoint contract.
- Runtime invokes the configured provider directly or through Agent Gateway.
- Vifu Server returns the result and records the trace.
Changing the provider or Gateway does not require the client to change its project URL.
Public project APIs
| API | Current purpose |
|---|---|
/{project-slug}/v1/models | List Agents exposed by the project. |
/{project-slug}/v1/chat/completions | Call an Agent with an OpenAI-compatible request. |
/{project-slug}/v1/audio/speech | Generate speech through a configured capability. |
/{project-slug}/v1/audio/transcriptions | Transcribe audio through a configured capability. |
/{project-slug}/v1/realtime | Open the project's realtime connection. |
/{project-slug}/v1/rpc | Reach an attached application runtime extension. |
The RPC route is available only when an operator has attached a runtime extension to that project. Vifu does not invent the extension's application language or editor format.
Runtime extension boundary
Runtime extensions use ordinary HTTP and JSON-RPC. Vifu Server remains the authority for project identity, exposed Agents, launch channels, and traces. Read Runtime extensions for this boundary.
Embedded Runtime API
The public vifu-runtime crate provides VifuRuntime, AgentProvider, dynamic
Agent and endpoint registration, session state, host-provided storage, portable
snapshots, async invocation, and a start/poll/cancel game-loop API. The mobile
UniFFI surface exposes the same shape to iOS and Android hosts.
The lower-level API provides headless command, event, effect, state, and
snapshot primitives with a standard Bevy Plugin extension point. An
application can combine both levels and define its own behavior.
The crate is not a built-in story language, visual editor, or published release format. Those application-specific concepts belong to the plugin or external runtime that implements them.
Read Technical direction for work that is not yet part of the supported contract.