---
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.
url: "https://eve.dev/docs/concepts/project-structure"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

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

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

[Declared subagents](/docs/subagents#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](/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 tools, skills, and connections 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#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, 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:

```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 only that agent, not other agents or peer applications; 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-hosted-operations#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 tools, skills, and connections 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

Either setup works with one agent or a workspace:

- **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) 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`](/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-hosted-operations#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 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:

| Choice                            | Result                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------------- |
| **Vercel services**               | Separate Vercel services, run locally with `pnpm dev:all` without linking a Vercel project. |
| **Next.js** or **TanStack Start** | The frontend hosts the agent; run the application with `pnpm dev:web`.                      |

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:

```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. 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](/docs/guides/frontend/nextjs#run-build-and-deploy).
- 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:

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

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)