Project Structure

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

Every root agent can have declared subagents with their own prompts, tools, and sandboxes. These specialists have no separate channel endpoint and do not inherit the parent's authored capabilities. 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 capabilities through extensions.

For a generated Next.js chat UI, run eve add channel/web from the project root. 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. Their directory names identify them in the CLI and public routes. Members have no package.json of their own: adding one excludes that directory from eve workspace discovery. Unlike a package-manager workspace, this layout does not give members separate dependency or version boundaries.

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 the selected agent, not peer applications. Start other agents separately when needed; 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 capabilities through workspace extensions; delegate across deployments with remote agents.

Configure a web deployment

Choose how the frontend and agents run together independently of how many agents you have:

• Add agents to a Next.js application: use eve/next in next.config.ts. Next.js owns the application lifecycle; the integration starts agent processes and proxies requests locally, and contributes separate agent services on Vercel. 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 an organizational convention, not an eve filesystem slot. Deployment configuration owns peer services; eve discovers only the agents. Both Vercel integrations deploy the services together, not as independent releases.

Run eve add channel/web from a standalone agent or select a workspace agent with --agent <name>. The installer creates a Next.js frontend under apps/web/. Choose Vercel to configure separate Vercel services and run them with pnpm dev:all; you don't need to link a Vercel project to run them locally. Choose Other to let Next.js host the agents and run the application with pnpm dev:web. Use pnpm dev or pnpm dev:eve when you only want 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. Do not leave a root agent/ directory: eve treats a project with agent/ as single-agent even when agents/ also 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 alongside durable-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.