vercel__eve/docs/concepts/project-structure.mdx

---
title: "Project Structure"
description: "Start with one agent, keep application code beside it, and split into a workspace only when you need separately addressable agents."
---

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/`.

| When you need…                                                         | Structure                                        |
| ---------------------------------------------------------------------- | ------------------------------------------------ |
| One agent, with or without a browser app                               | `agent/` beside your application code            |
| A specialist that an agent delegates to                                | `agent/subagents/<name>/` inside that agent      |
| Several separately addressable agents sharing a package and deployment | `agents/<name>/agent/` in an eve agent workspace |
| Separate dependencies, versions, or release schedules                  | Separate agent packages or projects              |

Every root agent can have [declared subagents](/docs/subagents#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](/docs/skills) instead when you only need an optional procedure.

## One agent

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

```text
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](/docs/getting-started). The [Agent Files reference](/docs/reference/agent-files) lists supported paths. Keep agent-only helpers in `agent/lib/`; share reusable capabilities through [extensions](/docs/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](/docs/guides/frontend/overview#per-framework-integration).

## Several root agents

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

```text
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:

```bash
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](/docs/subagents#vercel-workspace-peers) 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](/docs/guides/deployment/self-hosting#run-workspace-members).

## 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](/docs/extensions#use-an-extension-in-a-workspace); delegate across deployments with [remote agents](/docs/guides/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`](/docs/guides/frontend/nextjs) 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.
- **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`](/docs/guides/deployment/vercel#compose-agents-with-other-vercel-services) to contribute the agents alongside the frontend service. For [self-hosting](/docs/guides/deployment/self-hosting#run-workspace-members), 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.

The generated Web Chat installer does not support agent workspaces. Create the frontend and its agent-selection UI yourself, using the [React chat example](/docs/guides/frontend/overview#basic-chat-react). Develop a peer Next.js frontend with `next dev` separately from the agents. For an authored Vercel service graph, use `vercel dev --local` to run the composition without linking a Vercel project.

For a single `agent/` project, `eve add channel/web` currently generates a root Next.js app using `eve/next`. `eve/vercel` currently requires an `agents/` workspace; it cannot compose a standalone root `agent/`.

## Add a second root agent

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

```bash
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](/docs/guides/frontend/nextjs#dev-vs-deploy-topology).
- 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:

```bash
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.