# Build with the Vifu Agent Runtime

Vifu is a small, fast, stateful, and portable runtime for agents.

Connect applications to agents from local or remote providers through one
runtime for stable APIs, durable state, access control, routing, and traces.

## Choose where to start

| Your goal | Start here |
| --- | --- |
| Run Vifu for the first time | [Run Vifu locally](/docs/self-hosting/local) |
| Work on the runtime source | [Run Vifu locally](/docs/self-hosting/local) |
| Embed the Rust runtime | [Embed the runtime](https://github.com/vifudotdev/vifu/blob/main/docs/runtime-embedding.md) |
| Add product behavior | [Vifu plugins](/docs/runtime-extensions) |
| Connect an Agent or model | [Agent Providers](/docs/agent-providers) |
| Understand the public runtime API | [Core runtime design](/docs/core-runtime-design) |
| Understand hosted and self-hosted authority | [Dashboard architecture](/docs/dashboard-architecture) |

## The runtime stack

An application can host one project directly:

```mermaid
flowchart LR
  App[Rust, iOS, or Android application] --> Runtime[VifuRuntime]
  Runtime --> Provider[Local or remote provider]
```

The service deployment operates many projects:

```mermaid
flowchart LR
  Client[Web, native, or engine client] -->|HTTP or WebSocket| Server[Vifu Server]
  Server <--> DB[(PostgreSQL)]
  Server <--> Gateway[Vifu Agent Gateway]
  Server --> ProviderA[Provider]
  Gateway --> ProviderB[Remote provider]
  Console[Operations Console] --> Server
```

- **VifuRuntime** owns the providers, Agents, endpoints, sessions, state, and
  effects for one embedded application.
- **Vifu Server** owns project APIs, authorization, runtime sessions, and
  persistence across multiple projects.
- **Vifu Agent Gateway** is an optional Server transport that connects provider
  resources from another machine and reports the Agents they expose.
- **PostgreSQL** stores durable project and runtime data.
- **Operations Console** manages projects, Agents, providers, keys,
  connections, and traces.

Agent Gateway connects to a running Vifu Server. An embedded application
registers provider implementations directly with `VifuRuntime`.

## Start the local release

Download and extract the archive for your platform from the
[latest release](https://github.com/vifudotdev/vifu/releases/latest), then run:

```bash
./vifu
```

Vifu creates its local Runtime profile and opens the live TUI. Press `B` to
open the embedded Dashboard at the same Server address, normally
`http://127.0.0.1:6790`. Confirm the Runtime independently:

```bash
curl --fail --silent http://127.0.0.1:6790/health
```

The Console guides project, provider, Agent, and key setup. Read
[Self-hosting](/docs/self-hosting) before exposing the deployment on a network.

## Call a project endpoint

Create a project key in the Console, then call an Agent through the
OpenAI-compatible endpoint:

```bash
curl http://127.0.0.1:6790/my-project/v1/chat/completions \
  --header "Authorization: Bearer $VIFU_PROJECT_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "guide",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

The project endpoint remains stable while provider configuration changes.
Provider credentials remain inside the Vifu deployment.

Read [Core runtime design](/docs/core-runtime-design) for the execution
boundary and [Dashboard architecture](/docs/dashboard-architecture) for hosted
and self-hosted authority.

## Related agent runtimes

These open-source projects solve adjacent parts of the agent runtime stack. The
comparison describes each project's primary model, not an exhaustive feature
checklist.

| Project | Primary model | How Vifu differs |
| --- | --- | --- |
| [ADK-Rust](https://github.com/zavora-ai/adk-rust) | Rust framework and execution runtime for defining agents, tools, workflows, sessions, memory, and servers | Vifu centers the project-level contract through which applications access agents exposed by local or remote providers |
| [Google Agent Development Kit](https://github.com/google/adk-python) | Code-first framework for building, evaluating, orchestrating, and deploying agent systems | Vifu centers stable project endpoints, provider connections, access, durable state, and traces at the application boundary |
| [LangGraph](https://github.com/langchain-ai/langgraph) | Graph orchestration framework and runtime for long-running, stateful agents and workflows | Vifu organizes agents and access around a project rather than a workflow graph |
| [Cloudflare Agents SDK](https://github.com/cloudflare/agents) | Cloudflare-hosted runtime for durable agent instances, state, sessions, connections, and scheduling | Vifu keeps the application contract portable across agents running on local or remote providers |

**Vifu does not replace agent providers. It gives applications a stable,
stateful runtime contract for accessing agents across local and remote
providers.**