Project Structure

An eve project starts with one root agent in agent/. A root agent accepts requests through its own HTTP API or channels, and can have many tools, skills, and subagents. Keep browser application files outside agent/.

Declared subagents have their own prompts, tools, and sandboxes, but no channel endpoint. They don't inherit the parent's tools, connections, or skills. Use a skill instead when you only need an optional procedure.

One agent

Use this layout for a standalone agent or an agent inside a web application:

project/
├── package.json
├── agent/
│   ├── instructions.md
│   ├── tools/
│   └── subagents/
├── evals/
├── app/                    # optional Next.js browser application
└── next.config.ts          # optional Next.js integration

Create the agent with Getting Started. The Agent Files reference lists supported paths. Keep agent-only helpers in agent/lib/. Share reusable tools, skills, and connections through extensions.

For a generated chat UI, run eve add channel/web from the project root and choose Next.js or TanStack Start. For an existing browser app, follow your framework integration guide.

Several root agents

Use an eve agent workspace when, for example, clients need to address support and research separately:

project/
├── package.json
├── agents/
│   ├── support/
│   │   ├── agent/
│   │   └── evals/
│   └── research/
│       ├── agent/
│       └── evals/
└── apps/                   # optional peer applications, not eve workspace members
    └── web/

Members share the root package, dependencies, scripts, and Vercel deployment, so they have no separate dependency or version boundaries. Their directory names identify them in the CLI and public routes. A member with its own package.json is excluded from eve workspace discovery.

Create a workspace, then select an agent to run:

npx eve@latest init operations --agents support,research
cd operations
npx eve dev --agent support

Run agent commands such as dev, info, and eval from agents/<name>/, or pass --agent <name> from the workspace root. eve dev --agent support runs only that agent, not other agents or peer applications; local workspace-peer calls require an explicit transport.

On Vercel, run eve link and eve deploy from the root; deployment includes all members. No frontend is required. For self-hosting, build and run each member separately.

Independent releases

Use separate packages or projects when agents need independent dependencies or releases, even within the same monorepo. These are not eve agent-workspace members. Share tools, skills, and connections through workspace extensions; delegate across deployments with remote agents.

Configure a web deployment

Either setup works with one agent or a workspace:

• Add agents to a Next.js application: use eve/next in next.config.ts. Next.js runs the application. Locally, the integration starts the agents and forwards requests to them. On Vercel, it adds the agents as separate services. A root Next.js app can sit beside either agent/ or agents/; workspace members are discovered automatically. A peer app such as apps/web/ can select its eve project with eveRoot: "../..".
• Add a frontend to an agent workspace: keep the frontend as a peer application, for example under apps/web/. On Vercel, use eve/vercel in root vercel.ts to contribute the agents alongside the frontend service. For self-hosting, run the services with your process manager and configure a reverse proxy. The frontend does not need eve/next.

apps/web/ is a convention, not a directory eve reads. Your deployment configuration defines peer services, and eve finds only the agents. Both Vercel integrations deploy the services together, not as independent releases.

Run eve add channel/web from a standalone agent, or pass --agent <name> in a workspace, to create a Next.js or TanStack Start frontend under apps/web/. The installer then asks how to host it:

Use pnpm dev or pnpm dev:eve for one agent and the eve terminal UI.

Add a second root agent

To convert a single-agent project into a workspace, move the original agent from the project root:

mkdir -p agents/support
mv agent agents/support/agent

Move its evals/ directory, if present, to agents/support/evals/. Keep package.json, dependencies, environment files, and any browser application at the project root. Don't leave a root agent/ directory, because eve treats a project with agent/ as single-agent even when agents/ exists.

Before adding the next agent:

• Update tsconfig.json to include agents/**/*.ts, preserving any application includes. Update moved-file imports and path aliases, including scaffolded package.json#imports entries that point at ./agent/* or ./evals/*.
• Update scripts that assume one agent. Use --agent support for agent-scoped commands; build an agent-only Vercel workspace with root eve build. For a Next.js app, keep the framework scripts and follow its build instructions.
• Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent eveRoot override to enable workspace discovery, and select support in the client hook. Store the agent name with any saved session links.

Then add the second agent and check discovery:

npx eve init research
npx eve info --agent support
npx eve info --agent research

Run the moved agent's evals with npx eve eval --agent support. Add later agents with npx eve init <name> from the workspace root.