# 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

```mermaid
flowchart LR
  App[Rust, iOS, or Android application] --> Runtime[VifuRuntime]
  Runtime --> ProviderA[In-process provider]
  Runtime --> ProviderB[HTTP provider]
  Runtime <--> Store[(Host store or snapshot)]
```

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

```mermaid
flowchart LR
  Client[Web, native, or engine client] -->|Project API| Server[Vifu Server]
  Console[Operations Console] --> Server
  Server <--> DB[(PostgreSQL)]
  Server <--> GatewayA[Agent Gateway A]
  Server <--> GatewayB[Agent Gateway B]
  GatewayA --> ProviderA[Agent Providers]
  GatewayB --> ProviderB[Agent Providers]
```

- **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

1. The client sends a project key and an Agent identifier.
2. Vifu Server checks the key's project and permissions.
3. The Server builds the selected Runtime provider, Agent, and endpoint
   contract.
4. Runtime invokes the configured provider directly or through Agent Gateway.
5. 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

```mermaid
sequenceDiagram
  participant Client as Application client
  participant Server as Vifu Server
  participant Extension as Runtime extension
  participant Gateway as Agent Gateway
  Client->>Server: JSON-RPC request
  Server->>Extension: Forward project request
  Extension->>Server: Request an exposed Agent
  Server->>Gateway: Invoke provider
  Gateway-->>Server: Agent result
  Server-->>Extension: Agent result
  Extension-->>Server: JSON-RPC response
  Server-->>Client: JSON-RPC response
```

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](/docs/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](/docs/technical-direction) for work that is not yet
part of the supported contract.