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

Run `eve add channel/web` from a standalone agent or select a workspace agent with `--agent <name>`. The installer asks which framework to use and creates a Next.js or TanStack Start frontend under `apps/web/`. Choose **Vercel services** 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 **Next.js** or **TanStack Start** to let the frontend host the agent 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:

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