--- title: Getting Started description: Create an eve project, configure a model, understand its filesystem layout, and run your first agent. --- # Getting Started ## Prerequisites You need: * Node.js 24 or newer * npm, which Node.js includes * A credential for the model your agent uses The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`. To use a model provider directly, install its AI SDK provider package and set the provider's API key. Choose a model, provider, and channel that meet your data-processing and compliance requirements. ## Create a project Run `eve init` with a project name: ```bash npx eve@latest init my-agent ``` The command creates the project, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding. Pass an AI Gateway model ID or reasoning effort when you do not want the defaults: ```bash npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high ``` To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files: ```bash npx eve@latest init . ``` eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns. ## Run the agent If the development server is not already running, start it from the project root: ```bash npm run dev ``` The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command. ## Project layout eve builds an agent by walking the filesystem under `agent/`. Each directory is an authored slot, and the slot a file lands in determines how eve loads it. ### Naming from paths Identity comes from the path. You never write a `name` or `id` field on a `define*` call. | Path | Resolves to | | ------------------------------------- | --------------------- | | `agent/tools/get_weather.ts` | tool `get_weather` | | `agent/connections/linear.ts` | connection `linear` | | `agent/skills/summarize.md` | skill `summarize` | | `agent/subagents/researcher/agent.ts` | subagent `researcher` | The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory. ### Recommended layout A minimal agent needs `instructions.md`; `agent.ts` is optional when the defaults are sufficient. Add other slots as the agent needs them: ```text my-agent/ ├── package.json ├── tsconfig.json ├── agent/ │ ├── agent.ts │ ├── instructions.md │ ├── instrumentation.ts │ ├── channels/ │ ├── connections/ │ ├── hooks/ │ ├── skills/ │ ├── lib/ │ ├── sandbox/ │ ├── tools/ │ ├── schedules/ │ └── subagents/ └── evals/ ``` Evals live beside `agent/`, not inside it. ### Authored slots The Subagents column states whether a local subagent (`subagents//`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots. | Path | Description | Subagents | Notes | | ------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config). | | `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents. | | `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only. | | `channels/` | HTTP and messaging entry points | No | Root-only. | | `connections/` | External MCP and OpenAPI services | Yes | One connection per file; its name comes from the filename. | | `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only. Recursive directories are supported. | | `skills/` | On-demand procedures and capability packs | Yes | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. | | `lib/` | Shared authored helper code | Yes | Import-only; not mounted into the workspace. | | `sandbox.ts` or `sandbox/sandbox.ts` | The agent's single sandbox | Yes | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. | | `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/` when a session starts. | | `tools/` | Typed executable integrations | Yes | Module-backed only. | | `schedules/` | Recurring jobs | No | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only. | | `subagents/` | Specialist child agents | Yes | Each child is a local package under `subagents//`. Nested subagents are supported. | ### Runtime files and source files eve does not mount the whole authored tree into the runtime sandbox. Files under `agent/sandbox/workspace/**` land in `/workspace/` when a session starts. Skill package files land outside the workspace under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback when `$HOME` is unavailable. Everything in `lib/` remains import-only source code. ### Local subagents A local subagent uses the same `agent.ts` shape as the root: ```text agent/subagents/researcher/ ├── agent.ts ├── instructions.md ├── connections/ ├── hooks/ ├── skills/ ├── lib/ ├── sandbox/ ├── tools/ └── subagents/ ``` A subagent's `agent.ts` is required and must provide a description, while its instructions are optional. Connections, hooks, skills, shared code, sandboxes, tools, and nested subagents are supported. Channels and schedules remain root-only. See [Subagents](./subagents) for inheritance and isolation behavior. ### Flat layout When the app root is also the agent root, eve supports this layout: ```text my-agent/ ├── package.json ├── agent.ts ├── instructions.md ├── tools/ └── skills/ ``` Prefer the nested layout because it keeps application files separate from the authored agent surface. ### Debug file discovery Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Observability](./guides/instrumentation) and the [CLI](./reference/cli) reference. ## Install manually If you do not want to use the scaffold, install the runtime dependencies: ```bash npm install eve@latest ai zod ``` Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`. ## Continue with the tutorial The [Tutorial](/docs/tutorial/first-agent) builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result. After the tutorial, continue with the task you need: | Goal | Read | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Give the model an action it can call | [Tools](/docs/tools) | | Connect an MCP server or OpenAPI service | [Connections](/docs/connections) | | Reach users through Slack, Discord, or another platform | [Channels](/docs/channels/overview) | | Build a browser interface | [Frontend Frameworks](/docs/guides/frontend/overview) | | Test agent behavior | [Evals](/docs/evals/overview) | | Secure and deploy the agent | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment/overview) | Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability) for the mental model behind sessions, turns, durable steps, and parked work. --- 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)