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. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.

Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:

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

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.

Run the agent

If the development server is not already running, start it from the project root:

npm run dev

The TUI sends messages to your agent. Stop the server with Ctrl+C when you need your shell for another command.

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

Identity comes from the path. You never write a name or id field on a define* call.

The root agent takes its name from the enclosing package.json name, falling back to the app-root directory name when package.json has no name. A subagent takes its name from its directory.

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.

Authored slots

The Subagents column states whether a local subagent (subagents/<id>/) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots.

Runtime files and source files

eve does not mount the whole authored tree into the runtime sandbox. Files under agent/sandbox/workspace/** land in /workspace/ when a session starts.

Skill package files land outside the workspace under $HOME/.agents/skills/, with /workspace/skills/ as a fallback when $HOME is unavailable. Everything in lib/ remains import-only source code.

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.