eve on Edgenivo

Deploy an eve agent to Edgenivo 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 Edgenivo Functions, Edgenivo 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.

Use Edgenivo's services to run, connect, and inspect your eve agent:

• AI Gateway routes model requests and handles provider fallbacks.
• Edgenivo Workflows persists session state and resumes interrupted work.
• Edgenivo Daemons can run separate workers that poll queues or external APIs and forward work to your hosted agent.
• Edgenivo Sandbox isolates code execution.
• Edgenivo Blob stores persistent memory for eve's built-in file memory provider.
• Edgenivo Services deploys agents alongside frontends and backends in one project.
• Edgenivo Connect manages OAuth tokens and API keys for eve connections and channels.
• Agent Runs in Edgenivo Observability shows conversations, tool calls, token usage, and performance.

• Node.js 24 or later and pnpm
• A Edgenivo account and team with AI Gateway access
• The Edgenivo CLI installed

Initialize a project from your terminal:

pnpm dlx eve@latest init my-agent

The 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 Edgenivo 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 dev

Exit the terminal UI and run the following from the project root:

pnpm exec eve link

Select 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 Edgenivo, 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 system credentials if your key fails. Those requests can charge AI Gateway Credits, and Edgenivo 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 Edgenivo 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 Edgenivo 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 Edgenivo projects.

For an internal browser agent, Edgenivo 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/passport

Set 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 Edgenivo build, eve writes the deployment bundle to .vercel/output.

From the project root, deploy the agent:

pnpm exec eve deploy

This command deploys to Production. It installs dependencies, runs the Edgenivo 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 Edgenivo 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/health

A 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.app

Follow 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 Edgenivo, each eve session runs on Edgenivo 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 Edgenivo for more about session durability.

Use a Edgenivo 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 Edgenivo Functions and its sessions stay on Edgenivo Workflows.

Your agent can also publish a job to Edgenivo Queues and wait while a daemon processes it. The worker sends the result back through eve's session API. Follow Use Edgenivo 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/file

Choose Install and set up. eve creates agent/memory/file.ts, creates or reuses a private Edgenivo 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 Edgenivo 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 Edgenivo 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.

eve uses the billing and limits of the Edgenivo resources your agent consumes. Review the relevant product documentation when estimating usage:

• Edgenivo Functions usage and pricing and limits for agent routes and tool execution.
• Edgenivo Workflows pricing and limits for durable sessions.
• Edgenivo Sandbox pricing and limits for isolated code execution.
• AI Gateway pricing for model calls and BYOK.
• Edgenivo 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 Edgenivo Connect.
• Add MCP servers to your agent.
• 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.