eve on Vercel
Deploy an eve agent to Vercel to run conversations that persist across interruptions and wait for tools or human input. eve compiles your agent's files into an application that uses Vercel Functions, Vercel Workflows, and AI Gateway.
To decide whether you need eve's built-in sessions and channels or an agent loop within your app, see Choosing between eve, AI SDK agents, and WorkflowAgent.
To start from a working agent instead of an empty project, deploy a template for a business agent or a personal agent.
Build a working eve agent for my project's use case, verify it locally, and prepare it for deployment on Vercel. Use https://vercel.com/docs/frameworks/agents/eve.md as the framework setup reference. 1. Define the outcome. Inspect the project and its repository instructions. Identify the task the agent should perform, the tools or data it needs, and one representative input with an expected result. Ask me about requirements you can't determine from the project before implementing them. 2. Prepare the environment. Check the guide's prerequisites and my Vercel setup. Check whether the Vercel Plugin is installed in your coding tool. If it's missing, install it using the tool-specific instructions at https://vercel.com/docs/agent-resources/vercel-plugin.md. 3. Implement the agent. Create or extend the eve project with instructions for my use case, an AI Gateway model, and the tools needed to complete the task. Reuse existing code and conventions, preserve unrelated work, and keep optional integrations out of scope unless the task needs them. 4. Verify the outcome. Run the agent with the representative input and compare its response and tool results with the expected outcome. Run relevant existing project checks and fix failures introduced by your changes. A server starting or a model returning text alone doesn't establish that the task works. 5. Prepare deployment. Follow the guide's eve-specific linking and deployment requirements. Identify the environment variables, storage, and connections this implementation needs, and provide the commands to deploy it. Keep this task scoped to implementation, local verification, and deployment preparation. Finish with a concise handoff: the implementation, commands you actually ran and their results, an example input and observed output, and the remaining deployment steps. If credentials, tools, or services block a check, mark it as unverified, explain what's missing, and give the command to rerun it.
Use Vercel's services to run, connect, and inspect your eve agent:
- AI Gateway routes model requests and handles provider fallbacks.
- Vercel Workflows persists session state and resumes interrupted work.
- Vercel Daemons can run separate workers that poll queues or external APIs and forward work to your hosted agent.
- Vercel Sandbox isolates code execution.
- Vercel Blob stores persistent memory for eve's built-in file memory provider.
- Vercel Services deploys agents alongside frontends and backends in one project.
- Vercel Connect manages OAuth tokens and API keys for eve connections and channels.
- Agent Runs in Vercel Observability shows conversations, tool calls, token usage, and performance.
- Node.js 24 or later and pnpm
- A Vercel account and team with AI Gateway access
- The Vercel CLI installed
Initialize a project from your terminal:
pnpm dlx eve@latest init my-agentThe command creates my-agent, installs dependencies, initializes Git, and opens eve's terminal UI. If no model connection is available, eve opens /login. Choose your Vercel account, complete the browser sign-in, and select the team to use for AI Gateway requests.
To add eve to an existing app with a package.json, run pnpm dlx eve@latest init . from its root before creating any agent/ files.
Send a message such as Explain what you can help me with in two sentences. The agent should respond in the terminal. Use /login again if you need to change the account, team, or credentials.
The project keeps the agent's model configuration in agent/agent.ts. Edit agent/instructions.md to change its behavior:
You help developers plan small software projects.
Ask for missing requirements before suggesting an implementation.
Keep answers concise and include a concrete next step.eve reloads changes during development. Send another message to check that the agent follows your instructions. To reopen the terminal UI after exiting, run:
cd my-agent
pnpm devExit the terminal UI and run the following from the project root:
pnpm exec eve linkSelect or create a project in the team you want to deploy to. The command links the directory and pulls the project's environment variables.
The model string in agent/agent.ts routes requests through AI Gateway. On Vercel, eve authenticates with the project's OpenID Connect (OIDC) identity, so you don't need to copy your local login credentials or add a provider API key. Local model connections and deployed model access are separate.
Add any secrets your tools or direct model providers require to the project's environment variables before deploying.
To use API credits from an eligible ChatGPT or Claude subscription, claim the credits in your provider organization and add that organization's key to AI Gateway Bring Your Own Key (BYOK). Your deployed eve agent continues to authenticate to AI Gateway with OIDC.
Follow the ChatGPT credits walkthrough or Claude credits walkthrough to check eligibility and claim credits. In agent/agent.ts, choose a model from the credited provider and set modelOptions.providerOptions.gateway.only to ['openai'] or ['anthropic']. Apply the same routing to separately configured subagent or compaction models.
Deploy and send a message, then verify the provider and credential source in AI Gateway Logs. The provider filter doesn't prevent fallback to Vercel's provider keys if your key fails. Those requests can charge AI Gateway Credits, and Vercel infrastructure charges still apply. See provider credits and billing.
Model access authenticates the agent to AI Gateway. Route authentication controls who can send messages to your agent.
For the terminal UI and callers using this Vercel project's OIDC identity, configure the built-in HTTP channel:
import { localDev, vercelOidc } from 'eve/channels/auth';
import { eveChannel } from 'eve/channels/eve';
export default eveChannel({
auth: [vercelOidc(), localDev()],
});
vercelOidc() verifies Vercel bearer tokens and accepts tokens from the current project by default. localDev() permits local development requests and doesn't authenticate production callers. Requests that neither helper accepts receive a 401 response.
These helpers don't verify your application's browser session cookies. Before adding a browser interface, add an authenticator for your application's users. Use the subjects option on vercelOidc() to explicitly permit callers from other Vercel projects.
For an internal browser agent, Vercel Passport authenticates visitors with your identity provider before requests reach the deployment. Passport requires an Enterprise plan. Set up Passport for the environment serving your browser UI and agent, then install the helper:
pnpm add @vercel/passportSet PASSPORT_AUDIENCE in your project's environment variables to the expected Passport audience for this deployment. During setup, read a verified identity after signing in and use its identity.payload.aud value. Pin that value in configuration; don't take the expected audience from each incoming request. Keep VERCEL_PROJECT_ID and VERCEL_ENV available so the helper also verifies the project and environment.
Replace agent/channels/eve.ts with this visitor-only policy:
import { getIdentity } from '@vercel/passport';
import type { AuthFn } from 'eve/channels/auth';
import { eveChannel } from 'eve/channels/eve';
const passportAuth: AuthFn<Request> = async (request) => {
try {
const audience = process.env.PASSPORT_AUDIENCE;
if (!audience) return null;
const identity = await getIdentity(request, {
development: false,
verifyOptions: { audience },
});
if (!identity?.verified || !identity.payload.iss) return null;
return {
authenticator: 'passport',
principalType: 'user',
issuer: identity.payload.iss,
principalId: identity.subject,
attributes: {},
};
} catch {
return null;
}
};
export default eveChannel({ auth: passportAuth });
This policy rejects missing, invalid, and unverified development identities. It keeps the verified issuer and subject as the visitor's identity, so byPrincipal memory stays consistent across conversations. Email addresses and browser-supplied user IDs don't determine the memory scope.
Redeploy, sign in through the browser, and save a preference. Start another conversation as the same visitor to check recall, then sign in as a different visitor and confirm their memory is separate. This policy requires a Passport session; the terminal UI's project OIDC login alone doesn't satisfy it. It also doesn't link Passport users to Slack or Discord accounts. See verified account linking before sharing memory across channels.
Keep the scaffold's build script, which runs eve build. During a hosted Vercel build, eve writes the deployment bundle to .vercel/output.
From the project root, deploy the agent:
pnpm exec eve deployThis command deploys to Production. It installs dependencies, runs the Vercel deployment, and displays build logs. After the deployment completes, use the resulting URL to check the agent.
For subsequent deployments, you can also connect the project to Git. To deploy an agent alongside a frontend or backend in the same project, see eve with Vercel Services.
For the service-caller setup without Deployment Protection, replace your_agent.vercel.app with the deployment's domain and check the built-in health route:
curl --fail https://your_agent.vercel.app/eve/v1/healthA successful health response confirms that the service is reachable. The health route doesn't check model access or session permissions. Connect the terminal UI and send a message to verify both:
pnpm exec eve remote connect --url https://your_agent.vercel.appFollow any authentication prompts and confirm that the agent responds. For Deployment Protection, set VERCEL_AUTOMATION_BYPASS_SECRET locally before connecting. Direct health requests need the automation bypass header too. A protection bypass doesn't replace eve's route authentication or provide a Passport visitor identity.
For the Passport setup, sign in through the browser, visit /eve/v1/health on the protected deployment, and send a message through your browser interface. Passport protects the health route before requests reach eve, so an unauthenticated curl request can return a sign-in redirect instead of a health response.
Open Agent Runs in the project dashboard to inspect conversations, tool calls, and token usage. For existing projects, check trace sampling if no runs appear. Use runtime logs to investigate failed requests.
Follow Trace and debug eve agent runs to investigate an incorrect answer, configure trace exports, and test the fix with a regression eval.
On Vercel, each eve session runs on Vercel Workflows. eve checkpoints progress between steps and resumes pending work after interruptions. Waiting for approval or user input suspends the workflow until that input arrives. You don't need to add a workflow wrapper or configure a separate database or queue.
Completed steps reuse their recorded results, but an interrupted step can execute again. Make tool actions that send emails, create records, or charge customers idempotent so a retry doesn't repeat the external action. See Running eve Agents Durably on Vercel for more about session durability.
Use a Vercel Daemon when a separate worker needs to poll a queue or external API continuously, then send work to your hosted eve agent. The daemon runs the ingestion loop; eve's HTTP endpoints stay on Vercel Functions and its sessions stay on Vercel Workflows.
Your agent can also publish a job to Vercel Queues and wait while a daemon processes it. The worker sends the result back through eve's session API. Follow Use Vercel Daemons with eve agents for both patterns, including authentication, retries, and shutdown handling.
Authenticate worker calls with an explicit service-caller policy and the daemon's OIDC identity. The visitor-only Passport policy above doesn't admit workers. Keep background credentials separate from visitors' Passport sessions.
Use eve's fileMemory() provider to retain selected facts and preferences across conversations. From the linked project, install file memory:
pnpm exec eve add memory/fileChoose Install and set up. eve creates agent/memory/file.ts, creates or reuses a private Vercel Blob store, and connects it to the project with OIDC. The generated memory definition scopes each document to the authenticated caller.
Redeploy with pnpm exec eve deploy to use the new storage configuration. Ask the agent to remember a preference, confirm that it calls its memory save tool, then start another conversation with the same identity to check recall.
During eve dev, the default memory backend keeps data in the development process and loses it on restart. For setup details and a deployable example, see Store eve agent memory.
Use Vercel Drives when an agent needs datasets or working files that persist independently of its sandbox. For concurrent sessions reading the same dataset, mount a read-only drive snapshot.
First, create a drive named agent-data in iad1, in the same Vercel project as your agent. Mount it read-write in a separate sandbox, write your dataset, and stop that sandbox. The drive must contain at least one file before you can mount a snapshot.
Add this sandbox definition to mount the prepared dataset at /data:
import { defineSandbox } from 'eve/sandbox';
import { VercelSandbox } from 'eve/sandbox/vercel';
export const environment = VercelSandbox.environment({ region: 'iad1' });
export default defineSandbox(() =>
environment.open({
mounts: {
'/data': { drive: 'agent-data', mode: 'snapshot' },
},
}),
);
Keep the sandbox and drive in the same region, and keep mounts outside eve's managed /workspace directory. Add the dataset paths to agent/instructions.md, redeploy, and start a new session to read them. Each snapshot shows the drive's contents when mounted; existing mounts don't receive later writes.
For mutable workspaces, use mode: 'read-write' and coordinate access. A drive supports only one active read-write mount, while each eve session has its own sandbox. See Mounting a drive for access modes and sharing constraints.
A business agent is an eve agent that handles recurring work for a team, such as drafting marketing content or answering questions about company data. Employees send requests from a tool they already use, like Slack. You choose which systems the agent can reach and which actions wait for a person's approval.
Deploy one of these templates to start with a working business agent:
| Template | What the agent does | Works with | Safeguards |
|---|---|---|---|
| eve Marketing Team | A lead agent routes each request to one of five specialists, which draft blog posts, social posts, and email campaigns. | Slack, Notion, Typefully, and Resend | Sends, deletes, and scheduled posts wait for approval. |
| eve Data Analyst | Answers questions about your business from a Postgres database, with charts, tables, and the SQL it ran. | Slack and Postgres | Queries are read-only, and expensive queries wait for approval. |
The eve Marketing Team template deploys a lead agent and five specialists: a product marketer, a content marketer, a social media coordinator, a search engine optimization (SEO) specialist, and an email specialist. You brief the lead in Slack. The lead routes the request to a specialist and returns a link to the result: a blog draft in Notion, social posts in Typefully, or an email campaign in Resend.
Each specialist is an eve subagent with its own instructions, skills, and connections. To add a specialist, add a directory under agent/subagents/. Every specialist reads the same brand context document, which keeps product claims consistent across blog posts, social posts, and email.
The template sets an approval policy on actions you can't undo. Sending a Resend campaign, deleting a Typefully draft, or scheduling a post pauses until someone approves it in Slack. Saving a draft needs no approval. Notion and Resend sign in each person through Vercel Connect, so the agent acts with that person's permissions.
To understand the architecture, setup steps, and approval gates, read How do I build an AI marketing team?. For a code walkthrough, follow Run a marketing team from Slack with eve.
The eve Data Analyst template deploys an agent that answers questions about your business from a Postgres database. Ask "What was our monthly recurring revenue last month?" in Slack. The agent replies with the number, the exact period, and the time zone, and adds a chart or table when one helps.
The eve Data Analyst agent can read your database but can't change it:
- Every query runs in a read-only transaction with a time limit.
- Each person queries through a Postgres role, so your database permissions decide what that person can see.
- Expensive queries wait for approval from the person who asked.
- Each answer includes the SQL queries the agent ran.
Metric definitions live in agent/skills/metric-definitions.md, so terms like "churn" follow your team's rules. The template needs Postgres 14 or later. It can load demo data, so you can test the agent before you connect your own tables.
Start with a recurring task where a colleague can check the agent's work before anyone acts on it. Give the agent a narrow set of sources, and use read-only access where possible.
7 internal AI agents teams can build describes seven internal agents, with the access boundaries, review points, and pilot measurements for each one. Four of the seven have an eve template you can deploy:
- Content drafts from approved sources: eve Content Agent
- Data analysis with inspectable queries: eve Data Analyst
- Evidence for incident response: eve Incident Response Agent
- Software changes for engineering review: eve Software Factory
Before more employees rely on a business agent, name an owner. Then decide who can use the agent, what data it reads, what it can change, and what it can spend. How do you govern AI apps and agents built by employees? explains each decision and the evidence to check before a wider rollout.
Use these Vercel and eve features to enforce each decision:
| Decision | How to enforce it for an eve agent |
|---|---|
| Who can use the agent | Configure who can call the agent in agent/channels/eve.ts. On Enterprise plans, Vercel Passport signs browser users in through your identity provider. |
| What data the agent reads | Add only the connections the task needs. Vercel Connect manages each connection's OAuth tokens and API keys. |
| What the agent can change | Set an approval policy on tools that send, delete, or publish. eve runs a tool call without approval unless you set a policy. |
| What the agent can spend | Set a project budget with AI Gateway budgets, and configure Spend Management for your team. |
| What the agent did | Review conversations, tool calls, and token usage in Agent Runs. |
A personal agent is an eve agent that works for one person. You deploy it to your own Vercel project, so you control its instructions, model, tools, and memory.
Deploy one of these templates to start with a working personal agent:
| Template | Interface | What the agent does | Sign-in |
|---|---|---|---|
| eve Personal Agent | Nuxt web chat, Slack, and iMessage | Shares one memory across every interface, and answers questions about your GitHub and Linear work. | Email and password accounts |
| eve TanStack Agent | TanStack Start web chat | Searches the web, reads pages, and presents answers as cards, sortable tables, and metrics. | One shared password |
Choose the eve Personal Agent template for an assistant that remembers your context across web chat, Slack, and iMessage. Choose the eve TanStack Agent template for a web chat that renders answers with your own React components.
The eve Personal Agent template deploys a Nuxt web app and an eve agent as two Vercel Services from one repository. The web chat keeps your threads across sessions. Link your Slack account to reach the same agent from direct messages, or add your phone number to text the agent over iMessage.
The eve Personal Agent template gives you control over what the agent remembers:
- Memory has five categories: work context, personal context, active focus, instructions and preferences, and project history.
- The agent proposes each new memory as an approval card in chat, and you approve or skip it.
- You can edit or delete any memory entry from your profile.
- An import flow brings in the context you've built up in ChatGPT or Claude.
Connect GitHub and Linear through Vercel Connect to ask about repositories, pull requests, issues, and cycles. Actions that write to GitHub wait for your approval. To change the agent's name, instructions, model, or tools, follow the template's customization guide.
The eve TanStack Agent template connects an eve agent to a TanStack Start React frontend. Both deploy together in one Vercel project through Vercel Services. The included agent searches the web, reads pages, and asks follow-up questions when it needs more information.
json-render turns the agent's structured responses into React components you define, such as result cards, sortable tables, and metrics. Each conversation has a URL, so you can return to a session after you reload the page.
The template protects the chat with one shared password, which you set in the EVE_ACCESS_PASSWORD environment variable. Before you share the agent with other people, add an authenticator for your application's users. See Build an agent chat with eve for more about the template.
To build a personal agent without a template, create an agent and deploy it. Then add file memory with Vercel Blob so the agent keeps your preferences across conversations. To reach the agent from Slack and other chat platforms, connect it to Chat SDK.
eve uses the billing and limits of the Vercel resources your agent consumes. Review the relevant product documentation when estimating usage:
- Vercel Functions usage and pricing and limits for agent routes and tool execution.
- Vercel Workflows pricing and limits for durable sessions.
- Vercel Sandbox pricing and limits for isolated code execution.
- AI Gateway pricing for model calls and BYOK.
- Vercel Blob usage and pricing for persistent file memory.
- Tracing usage and pricing for indexed Agent Runs spans.
Use Agent Runs to inspect a representative task's model and tool calls, and configure Spend Management for your team.
- Build a software factory that investigates issues, checks changes, and prepares draft pull requests.
- Connect eve to external services with Vercel Connect.
- Add MCP servers to your agent.
- Give your agent GitHub tools that request tokens from a GitHub connector and ask for approval before each write.
- Answer from your content by connecting your agent to Sanity Context, which reads from Sanity datasets, websites, and files.
- Bring your agent to chat platforms with Chat SDK.
- Configure OpenTelemetry to control trace content and export destinations.
- Explore eve's execution model for sessions, turns, and durability.
Was this helpful?