eve/docs/channels/eve.mdx

Filesystem-first framework for durable backend AI agents that run anywhere.

---
title: "eve"
description: "The default HTTP API for an agent, covering session routes, auth, and customization."
---

The eve channel is the framework's default HTTP API. It's what the terminal UI, [`useEveAgent`](../guides/frontend/overview), `curl`, and any SDK client talk to when they start sessions, send messages, and stream events. `eveChannel()` mounts the canonical session routes under `/eve/v1/session*`, and they are enabled by default even when `agent/channels/eve.ts` does not exist.

Reach for it when something needs HTTP access to your agent, including local tooling, a browser frontend, the terminal UI, or another API client. Most apps never write this file. Add `agent/channels/eve.ts` only to override the defaults, usually the route auth policy.

```ts title="agent/channels/eve.ts"
import { eveChannel } from "eve/channels/eve";
import { localDev, vercelOidc } from "eve/channels/auth";

export default eveChannel({
  auth: [localDev(), vercelOidc()],
});
```

## Routes

The channel exposes routes that create sessions, send follow-ups, and stream events:

- `GET /eve/v1/health`
- `POST /eve/v1/session` (start a session)
- `POST /eve/v1/session/:sessionId` (send a follow-up)
- `GET /eve/v1/session/:sessionId/stream` (stream events, NDJSON)

Start a session with a minimal body. The response returns `sessionId` and the `continuationToken` you reuse for follow-ups:

```bash
curl -X POST https://<deployment>/eve/v1/session \
  -H "Content-Type: application/json" \
  -d '{"message":"What is the weather in Paris?"}'
# {"continuationToken":"eve:7f3c...","ok":true,"sessionId":"ses_01h..."}
```

Stream that session's events as newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:

```bash
curl -N https://<deployment>/eve/v1/session/ses_01h.../stream
# {"type":"turn.started",...}
# {"type":"text.delta","delta":"It is "}
# {"type":"message.completed",...}
```

See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the full request and stream flow, including the complete event set.

## Authentication

The `auth` option decides who can call these routes. The built-in helpers cover development and trusted infrastructure:

- `localDev()` accepts requests during local development.
- `vercelOidc()` lets the local CLI reach a deployed agent, and lets other internal deployments from your team call it.

Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth (Clerk, Auth.js, your own OIDC/JWT verification, an API-key verifier, or any custom `AuthFn`). Vercel OIDC is optional; use it only when Vercel-issued deployment tokens are part of your trust model.

`eve init` scaffolds an `agent/channels/eve.ts` with a production placeholder so you replace it before going live. The generated channel allows Vercel OIDC and localhost, and includes `placeholderAuth()`, which returns a setup-focused 401 in production until you swap it for real auth. Delete the file and eve falls back to `[localDev(), vercelOidc()]`, which still does not admit browser users in production.

For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).

## Customization

Use `onMessage` to add request-specific context before the agent sees the user message, and `events` to observe stream events from sessions this channel created:

```ts title="agent/channels/eve.ts"
import { eveChannel, defaultEveAuth } from "eve/channels/eve";
import { localDev, vercelOidc } from "eve/channels/auth";

export default eveChannel({
  auth: [localDev(), vercelOidc()],
  onMessage(ctx, message) {
    const callerId = ctx.eve.caller?.principalId ?? "anonymous";
    return {
      auth: defaultEveAuth(ctx),
      context: [`HTTP caller ${callerId} sent: ${message}`],
    };
  },
  events: {
    "message.completed"(eventData, channel, ctx) {
      console.log("eve response completed", {
        continuationToken: channel.continuationToken,
        sessionId: ctx.session.id,
      });
    },
  },
});
```

## Clients

The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.

For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript SDK](../guides/client/overview). It wraps the session routes, continuation token, stream cursor, and reconnect loop.

## What to read next

- [Frontend](../guides/frontend/overview): drive the eve channel from browser UI with `useEveAgent`
- [TypeScript SDK](../guides/client/overview): call the eve channel from TypeScript
- [Auth & route protection](../guides/auth-and-route-protection): the route auth policy
- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the routes this channel exposes