Skip to main content
Anvil is distributed as a single npm package. This page covers everything you need to go from a blank directory to a correctly configured Anvil project.

​
Requirements

Before installing, make sure your environment meets these requirements:
  • Node.js ≥ 20 — Anvil relies on the native Request, Response, Headers, and ReadableStream APIs that ship with Node 20.
  • ESM project — Anvil is ESM-only. Your package.json must declare "type": "module".
  • npm, yarn, or pnpm — any of the three major package managers work.

​
Install the package

npm install anvil zod
zod is a direct dependency of your route and tool schemas — install it alongside Anvil.

​
Configure package.json

Add "type": "module" to enable ESM, then add the Anvil CLI commands as scripts:
package.json
{
  "name": "my-api",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "anvil dev",
    "build": "anvil build",
    "start": "anvil start",
    "lint": "anvil lint"
  },
  "dependencies": {
    "anvil": "latest",
    "zod": "latest"
  }
}
If you omit "type": "module", Node treats your files as CommonJS and imports from anvil fail with a syntax error. ESM is required.

​
Minimal project structure

Anvil expects your route handlers to live under server/routes/. Everything else is up to you. 
my-api/
├── server/
│   └── routes/
│       └── get.ts       ← GET / (your first route)
├── package.json
└── tsconfig.json        ← optional, but recommended
A minimal tsconfig.json for an Anvil project:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true
  }
}

​
Optional peer dependencies

Anvil’s core routing and middleware work with no extra packages. The AI provider integrations and persistence adapters are optional peer dependencies, loaded lazily — install only what you use.

Anthropic (Claude)

Required if you use AnthropicDriver in an agent route or LLM client.
npm install @anthropic-ai/sdk

OpenAI (GPT / o-series)

Required if you use OpenAIDriver.
npm install openai

Google Gemini

Required if you use GeminiDriver.
npm install @google/generative-ai

SQLite persistence

Required for SqliteStateStore, SqliteTraceStore, or SqliteVectorStore — persistent traces, checkpoints, memory, and vectors across restarts.
npm install better-sqlite3
If you try to use a driver or store whose peer dependency is not installed, Anvil throws a clear error at the call site pointing you to the missing package and the in-memory alternative — it will not silently fail.

​
CLI commands reference

Once installed, the anvil binary is available in your node_modules/.bin/. Running it through npm run (or your package manager equivalent) is the recommended approach.
CommandWhat it does
anvil devStarts the dev server on port 3000 with watch mode. TypeScript routes are loaded on the fly via jiti.
anvil buildScans server/routes/, generates .gen/routes.ts, and bundles dist/server.mjs for production.
anvil startRuns the production bundle. Requires anvil build first.
anvil lintValidates all routes: checks paramsSchema keys match folder params, verifies MCP-exposed schemas convert cleanly to JSON Schema. Add --strict to fail on warnings.
anvil mcpServes MCP-exposed routes and server/tools/ over Streamable HTTP on port 3100. Pass --stdio for Claude Desktop and similar local clients.
anvil eval <file>Runs a defineEvalSuite test file against an agent route; exits non-zero if any case fails.
anvil replay <traceId>Re-runs a captured agent trace with mocked model responses and recorded tool outputs — no live model calls.

​
Verify the installation

Create a minimal route and start the dev server to confirm everything is working:
server/routes/get.ts
export default function handler() {
  return { status: 'ok' };
}

npm run dev
# [anvil] dev server listening on http://localhost:3000

curl http://localhost:3000/
# {"status":"ok"}
If you see the JSON response, your installation is complete.

​
Scaffold instead of hand-writing

Once installed, npx anvil init writes package.json (scripts + dependencies), tsconfig.json, .gitignore, and a starter route for you — pick a basic API, MCP server, or agent route template. See anvil init.

​
Next steps

Quickstart

Build a route, expose it as an MCP tool, and add a streaming agent — in one walkthrough.

File-Based Routing

The full routing convention: verbs, groups, catch-alls, and the route manifest.