Getting Started

Prerequisites

You need:

• Node.js 24 or newer
• npm, which Node.js includes
• A credential for the model your agent uses

The default scaffolded model routes through the Vercel AI Gateway. Set AI_GATEWAY_API_KEY, or link a Vercel project to use VERCEL_OIDC_TOKEN. To use a model provider directly, install its AI SDK provider package and set the provider's API key.

Choose a model, provider, and channel that meet your data-processing and compliance requirements.

Create a project

Run eve init with a project name:

npx eve@latest init my-agent

The command creates the project, installs dependencies, and initializes Git. After scaffolding, eve offers to start the development server or, if a supported coding agent is installed, to open the project in the coding agent.

To add eve to a project that already has a package.json, run this command from its root before you create any agent/ files:

npx eve@latest init .

eve adds the missing eve, ai, and zod dependencies without changing files the project already owns.

Customize initialization

To initialize the agent with a different AI Gateway model or reasoning effort, pass --model or --reasoning:

npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high

Run the agent

Choose Start eve dev after scaffolding, or run this from the project root:

npm run dev

This starts an interactive session where you can send messages to your agent.

Project layout

eve builds an agent by walking the filesystem under agent/. Each directory is an authored slot, and the slot a file lands in determines how eve loads it.

Naming from paths

eve derives names from file paths, so you do not configure them separately.

The root agent uses its package.json name, or its app directory name if none is set. A subagent uses its directory name.

Recommended layout

A minimal agent needs instructions.md; agent.ts is optional when the defaults are sufficient. Add other slots as the agent needs them:

my-agent/
├── package.json
├── tsconfig.json
├── agent/
│   ├── agent.ts
│   ├── instructions.md
│   ├── instrumentation.ts
│   ├── channels/
│   ├── connections/
│   ├── hooks/
│   ├── skills/
│   ├── lib/
│   ├── sandbox/
│   ├── tools/
│   ├── schedules/
│   └── subagents/
└── evals/

Evals live beside agent/, not inside it.

Agent files and directories

Each path under agent/ has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked Yes.

Files available in the sandbox

Files under agent/ define your agent; only files in agent/sandbox/workspace/ are copied to /workspace/ when a session starts.

Local subagents

A local subagent uses the same agent.ts shape as the root:

agent/subagents/researcher/
├── agent.ts
├── instructions.md
├── connections/
├── hooks/
├── skills/
├── lib/
├── sandbox/
├── tools/
└── subagents/

A subagent's agent.ts is required and must provide a description, while its instructions are optional. Connections, hooks, skills, shared code, sandboxes, tools, and nested subagents are supported. Channels and schedules remain root-only. See Subagents for inheritance and isolation behavior.

Flat layout

When the app root is also the agent root, eve supports this layout:

my-agent/
├── package.json
├── agent.ts
├── instructions.md
├── tools/
└── skills/

Prefer the nested layout because it keeps application files separate from the authored agent surface.

Debug file discovery

Run eve info when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under .eve/; see Observability and the CLI reference.

Install manually

If you do not want to use the scaffold, install the runtime dependencies:

npm install eve@latest ai zod

Declare Node.js 24 in package.json, then create agent/instructions.md and, when you need runtime configuration, agent/agent.ts.

Continue with the tutorial

The Tutorial builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result.

After the tutorial, continue with the task you need:

Read Execution Model and Durability for the mental model behind sessions, turns, durable steps, and parked work.