# Server Primitives

## Server primitives for Vite apps and any host

ViteHub adds storage, queues, schedules, email, and other server APIs to Vite apps. Call them from routes, handlers, jobs, or workers. You don't need an Agent Definition.

Start with [Your first server primitive](https://vitehub.dev/docs/getting-started/first-server-primitive) for a runnable example. Read [Concepts](https://vitehub.dev/docs/getting-started/concepts) when you need to understand generated imports or host configuration. Read [Agents](https://vitehub.dev/docs/agents) only when a model needs access to one of these APIs.

- [First primitive](https://vitehub.dev/docs/getting-started/first-server-primitive) — Add KV to an app, register the Vite Integration, and call the Runtime Helper from server code.
- [Server model](https://vitehub.dev/docs/getting-started/concepts/vite-integrations-and-provider-output) — Learn how generated imports and host configuration keep application code independent from providers.
- [Runtime imports](https://vitehub.dev/docs/getting-started/concepts/runtime-helpers-and-stable-imports) — Call primitives through ViteHub-owned imports instead of generated files or provider SDK wiring.
- [Agents](https://vitehub.dev/docs/agents) — Give an Agent selected access to server APIs through Capabilities.

> **Note**

Server code calls runtime helpers directly. Agents receive only the abilities added through Capabilities. Read [Runtime helpers and stable imports](https://vitehub.dev/docs/getting-started/concepts/runtime-helpers-and-stable-imports) and [Capabilities API](https://vitehub.dev/docs/agents/capabilities) when you need those contracts.

## Pick the right primitive

| You need | Start with |
| --- | --- |
| Public, server, build-time, runtime, or secret environment values | [Env](https://vitehub.dev/docs/env) |
| Application users, sessions, Better Auth routing, or guarded app routes | [Auth](https://vitehub.dev/docs/auth) |
| Provider accounts that the app owns, with OAuth refresh, access rules, and call activity | [Connections](https://vitehub.dev/docs/connections) |
| Request budgets that must be consumed before expensive server work starts | [Rate Limit](https://vitehub.dev/docs/rate-limit) |
| Outbound transactional messages with provider-neutral delivery | [Email](https://vitehub.dev/docs/email) |
| Named outbound message destinations, such as Telegram or Teams, behind selected connectors | [Channels](https://vitehub.dev/docs/channels) |
| Small key-addressed values, settings, flags, cursors, or lightweight state | [KV](https://vitehub.dev/docs/kv) |
| Relational data, constraints, joins, migrations, or queryable history | [Database](https://vitehub.dev/docs/database) |
| Uploads, generated artifacts, binary files, or object metadata | [Blob](https://vitehub.dev/docs/blob) |
| Provider-backed browser sessions, screenshots, DOM inspection, or live handoff | [Browser](https://vitehub.dev/docs/browser) |
| Persistent file-tree state, snapshots, diffs, rules, or sessions | [Workspace](https://vitehub.dev/docs/workspace) |
| Collaborative Markdown editing, presence, and Workspace checkpoints | [Realtime](https://vitehub.dev/docs/realtime) |
| Read-only retrieval from files, globs, GitHub, markdown, MCP, or custom loaders | [Source](https://vitehub.dev/docs/source) |
| Parse, query, search, and serve content from Sources | [Content](https://vitehub.dev/docs/content) |
| Background delivery that returns before work finishes | [Queue](https://vitehub.dev/docs/queue) |
| Durable long-running work with provider-tracked run state | [Workflows](https://vitehub.dev/docs/workflows) |
| Static cron output or recurring runtime schedules | [Schedule](https://vitehub.dev/docs/schedule) |
| Isolated provider-managed execution | [Sandbox](https://vitehub.dev/docs/sandbox) |
| Controlled Unix-like command sessions | [Shell](https://vitehub.dev/docs/shell) |

## Use primitives from server code

Most primitives expose the same application import on every host. ViteHub connects that import to the selected provider during the build.

```ts [server/api/settings.put.ts]
import { kv } from 'vite-hub/kv'

export default defineEventHandler(async (event) => {
  const [error] = await kv.set('settings', await readBody(event))
  if (error) throw error
  return { ok: true }
})
```

The route doesn't need to know whether KV uses local files, Cloudflare, Vercel, or another driver.

## Definitions and generated output

Some primitives work directly after configuration. Env, KV, Blob, Source, and Shell can often be called from server code without a discovered Definition.

Other primitives need a Definition so ViteHub can discover runtime behavior or named work. Email composes one declaratively configured provider, while Auth uses a singleton Definition bound at runtime. Database schemas, Workspace Definitions, Queue Definitions, Workflow Definitions, Static Schedule Definitions, Sandbox Definitions, and Agent Definitions can also generate Runtime Registries or host-specific Provider Output. Rate Limit uses source-local handles with explicit stable IDs instead of location-derived Definitions.

| Need | Read |
| --- | --- |
| Understand portable Definitions and location-derived discovery | [Definitions and discovery](https://vitehub.dev/docs/getting-started/concepts/definitions-and-discovery) |
| Check where Definition files belong | [File conventions](https://vitehub.dev/docs/reference/file-conventions) |
| Inspect generated host artifacts | [Provider output](https://vitehub.dev/docs/reference/provider-output) |
| Configure package integrations and host settings | [Config options](https://vitehub.dev/docs/reference/config-options) |
| Use ViteHub's framework and host boundary | [Frameworks and hosts](https://vitehub.dev/docs/frameworks-hosts) |
| Emit Cloudflare bindings, routes, queues, workflows, crons, and workers | [Cloudflare](https://vitehub.dev/docs/frameworks-hosts/cloudflare) |
| Emit Vercel output for functions, queues, workflows, and runtime bindings | [Vercel](https://vitehub.dev/docs/frameworks-hosts/vercel) |
| Emit Deno Agent server output and Deno cron wake output | [Deno](https://vitehub.dev/docs/frameworks-hosts/deno) |
| Run the generated server output yourself | [Node/self-hosted](https://vitehub.dev/docs/frameworks-hosts/node-self-hosted) |

## Connect primitives to Agents

Capabilities expose controlled agent-facing access to primitives. A storage Capability can expose scoped read/edit tools, a Schedule Capability can manage allowed Runtime Schedules, and `workspaceShell()` can expose file inspection through Workspace and Shell boundaries.

Don't expose a server API to a model just because the app uses it. Add the relevant [Official Capability](https://vitehub.dev/docs/agents/capabilities/official) only when the Agent needs that ability. Configure its scope, write mode, and approvals for that task.

| Need | Read |
| --- | --- |
| Build the Agent that will receive the ability | [Agents](https://vitehub.dev/docs/agents) |
| Understand the agent-facing contribution model | [Capabilities overview](https://vitehub.dev/docs/agents/capabilities) |
| Pick from built-in Capability factories | [Official capabilities](https://vitehub.dev/docs/agents/capabilities/official) |
| Expose KV with scoped storage tools | [KV capability](https://vitehub.dev/docs/kv/agent-capability) |
| Expose Blob storage with scoped file tools | [Blob capability](https://vitehub.dev/docs/blob/agent-capability) |
| Expose relational data intentionally | [Database capability](https://vitehub.dev/docs/database/agent-capability) |
| Let an Agent send authorized plain-text email | [Email capability](https://vitehub.dev/docs/email/agent-capability) |
| Let an Agent send its result through a Channel | [Channels capability](https://vitehub.dev/docs/channels/agent-capability) |
| Consume a trusted budget before an Agent Invocation | [Rate Limit capability](https://vitehub.dev/docs/rate-limit/agent-capability) |
| Give an Agent headless browser evidence through an allowlisted command | [Browser capability](https://vitehub.dev/docs/browser/agent-capability) |
| Let an Agent manage allowed Runtime Schedules | [Schedule capability](https://vitehub.dev/docs/schedule/agent-capability) |
| Expose Workspace-backed inspection or mutation | [Workspace shell](https://vitehub.dev/docs/workspace/agent-capability) |
| Run isolated execution from an Agent boundary | [Sandbox capability](https://vitehub.dev/docs/sandbox/agent-capability) |

## Next steps

- [Build the first primitive](https://vitehub.dev/docs/getting-started/first-server-primitive)
- [Build the first Agent](https://vitehub.dev/docs/getting-started/first-agent)
- [Read the Concepts overview](https://vitehub.dev/docs/getting-started/concepts)