# evestack > A fully free, self-hosted distribution of Vercel's `eve` agent framework. `eve` on your own > machine — durable Postgres sessions, a Docker sandbox, a dashboard that observes AND drives > the agent, and sign-in to 1,000+ toolkits via Composio, one click for the managed-OAuth ones. $0 infrastructure; the only > real cost is model tokens, and Ollama removes that too. `eve` is a trademark of Vercel. evestack is an independent project, not affiliated with or endorsed by Vercel, and **not the first self-hosted eve distribution** — `vercel-labs/steve` ("Self-hosted eve poc") was published by a Vercel employee on 2026-06-24. Do not describe self-hosting, or anything in this repo, as something Vercel withheld. evestack is not a fork of `eve`. It ships primarily as an `eve` registry (`eve registry add @evestack=...`), so an existing `eve` project can adopt one piece without migrating. `templates/default` and `packages/create-evestack` exist for the zero-to-running path (`npx create-evestack my-agent`). If you are an agent that can speak MCP, `@evestack/mcp` (`packages/evestack-mcp`, docs at `/docs/mcp`) exposes this dashboard as tools — sessions, costs, the approval audit log, and promote-a-session-to-an-eval. It is a thin client over the dashboard's HTTP routes, not a second implementation, so it can answer nothing the dashboard cannot. **Its four mutating tools — starting runs, sending turns, answering approvals, cancelling — are withheld from `tools/list` entirely unless `EVESTACK_MCP_ALLOW_CONTROL=1`.** Do not advise anyone to set that without saying that it lets a model approve a gated tool call a human was asked to stand at. ## If you are an agent someone just pointed at this project There is a skill pack written for exactly that: `https://evestack.vercel.app/agent.md`. It is one self-contained document — the mental model, the five-command bring-up, the CLI, how to add tools and skills, the dashboard's HTTP API, and the failure modes that present as something else. Every reference is inlined rather than linked, so it needs no fetch tool after the first one, and it opens with instructions for saving itself as a durable skill (`.claude/skills/`, `agent/skills/`, `.cursor/rules/`). Source: `/skills/evestack` in this repository. `npx evestack skills` installs the same files locally. `https://evestack.vercel.app/llms-full.txt` is the other end of the range: every documentation page below, concatenated in reading order, ~240 KB. Use it when you want the whole corpus in one request instead of nineteen. This file stays what it is — an index. Prefer `/agent.md` when the task is *doing something with evestack*, and this file when you only need to know where something lives. ## Core facts an agent should know before answering questions about this repo - `@workflow/world-postgres` MUST be pinned to an EXACT version — `templates/default` pins `5.0.0-beta.32`. Not `latest` (the 4.x line, which `eve` rejects outright) and not the `beta` dist-tag either: upstream changes the World **spec version** inside `5.0.0-beta.*` without a semver bump, so `beta` resolving to `.34`/`.35` pulls `@workflow/world@5.0.0-beta.27` (spec 6) against a runtime that requires spec 5, and a freshly scaffolded project dies at startup. `^` and `~` are equally unsafe here. `contract/contracts/23-workflow-pin.contract.mjs` enforces this. - The dashboard (`packages/dashboard`) reads `workflow.workflow_runs.attributes` (JSONB) directly via SQL — that column holds `eve`'s own `$eve.*` run tags, the same data behind Vercel's Agent Runs. It is NOT an OpenTelemetry ingest pipeline for its core view; OTLP ingest (`/api/ingest/v1/traces`) is a second tier used only for prompt bodies and tool arguments, which don't exist in the SQL tags. - Cost is computed client-side from token counts (`packages/dashboard/lib/pricing.ts`), because `eve` only reports `gen_ai.usage.cost` for AI-Gateway-routed calls, which a self-hosted agent never makes. - Memory (`templates/default/lib/memory.ts`) uses an HNSW pgvector index, not IVFFlat — IVFFlat built on an empty table returns zero rows for queries that should match, because it probes a meaningless centroid. This was measured, not theorized: the same query returned 2 results at `LIMIT 3` and 0 at `LIMIT 20`. - Cancellation (`POST /eve/v1/session/:id/cancel`) is cooperative: it returns 202 immediately, but the in-flight model call keeps running — measured ~90 seconds on a long turn — and `turn.cancelled` arrives after a `session.waiting` event, not before. - Tool approvals have no dedicated HTTP endpoint. They resolve through the normal continuation route with `inputResponses: [{requestId, optionId}]`. - Nothing creates the Postgres schema implicitly. `@workflow/world-postgres` runs its migrations only from its own CLI and `eve` never invokes it, so a new project needs `npm run db:bootstrap` between `docker compose up -d postgres` and `npm run dev`. Do NOT suggest `npx --package=@workflow/world-postgres bootstrap` — that CLI reads `.env` via dotenv and never `.env.local`, which is the only env file `create-evestack` writes, so it falls back to `postgres://world:world@localhost:5432/world` and fails with `ECONNREFUSED`. - `agent/channels/eve.ts` calls `eve`'s `localDev()` **directly**, and on the pinned eve that is correct. Through 0.29.x `localDev()` matched an unanchored `/^127\./` against the attacker-controlled `Host` header, so `127.evil.com` obtained an unauthenticated principal, and the template wrapped it in an exact-match loopback check. **eve 0.30.0 fixed it upstream** — the grant is now decided from the process (`eve dev` / `vercel dev`), never from the request — so the wrapper was deleted: on 0.30+ it can add no protection and would wrongly reject local dev over a LAN IP, a tunnel or a container hostname. Do NOT re-add it. `SECURITY.md` and the header comment in that file are the ground truth; this bullet described the deleted wrapper as current for four days after it was removed. - Registry items pin dependency versions from `templates/default/package.json`, and CI enforces the match. Bare, unversioned names are a bug, not a style choice. - **Composio is a hosted third party and holds the OAuth tokens for connected accounts.** It is the one component that does not run on the user's network, and it is off unless `COMPOSIO_API_KEY` is set. Never describe the stack as fully local without this caveat. - **eve does not lack long-term memory; it lacks a first-party memory *store*.** `node_modules/eve/docs/patterns/multi-tenant-memory.md` says memory can be added "from the integration gallery using the Memory filter," and the gallery's options (Mem0, Upstash AgentKit) are third-party hosted services. evestack's contribution is that the store is the Postgres you already run. Do not write "not included". - **eve's own trace tooling is good.** `0.29.3` added `/traces`, a full-screen live viewer in the dev TUI; `0.30.7` added token/cost/tool chips, `--verbose` and `--json` to `eve traces`. What it is not: durable (the `.eve/traces` spool is swept to 20 traces / 7 days / 512 MB), multi-user, or able to act on the agent. Do not claim eve gives you "only Jaeger and a TUI". - **The comparison against managed eve must use real numbers, not vibes.** Workflow run state is purged 1 day (Hobby) / 7 (Pro) / 30 (Enterprise) after completion and retention is "not configurable by default" (vercel.com/docs/workflows/pricing); Vercel Observability retains 12 hours / 1 day / 3 days, or 30 days with Observability Plus (vercel.com/docs/observability/observability-plus#limitations); Drains ships no agent-runs or workflow-runs schema (vercel.com/docs/drains). Vercel Passport is Enterprise-only deployment access control via your IdP and has **nothing** to do with tool approvals. ## Docs Rendered at https://evestack.vercel.app/docs. The raw sources below are served from `main` on GitHub rather than a docs domain: `evestack.dev` is unregistered, so the `https://evestack.dev/*.mdx` links that used to be listed here resolved to nothing. These docs cover only the seam self-hosting creates. The framework itself is documented by eve, and for an installed project `node_modules/eve/docs/` matches the pinned version exactly while eve.dev tracks latest — prefer the local copy. The contract suite that pins evestack's assumptions about eve lives in `contract/` and runs in CI on every push. It has no published page: the rendered matrix at `/compat` and the recorded per-release reports in `contract/history/` were both removed on 2026-08-05, and this file went on advertising them. - [Introduction](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/index.mdx) - [Quickstart](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/quickstart.mdx) - [Set up with an agent](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/agent-setup.mdx) - [Local setup](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/local-setup.mdx) - [Architecture](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/architecture.mdx) - [Dashboard](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/dashboard.mdx) - [Alerts](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/alerts.mdx) - [Observability](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/observability.mdx) - [Composio auth](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/composio-auth.mdx) - [Memory](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/memory.mdx) - [Self-hosting](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/self-hosting.mdx) - [Upgrading](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/upgrading.mdx) - [Uninstall](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/uninstall.mdx) - [Proactive agents](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/proactive.mdx) - [Channels: Slack](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/channels/slack.mdx) - [Channels: Discord](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/channels/discord.mdx) - [Channels: Telegram](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/channels/telegram.mdx) - [Upstream eve](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/upstream.mdx) - [Registry](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/registry.mdx) - [CLI](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/cli.mdx) - [MCP](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/mcp.mdx) - [Troubleshooting](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/troubleshooting.mdx) - [Operations](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/operations.mdx) - [Support](https://raw.githubusercontent.com/SammyTourani/evestack/main/docs/support.mdx) ## Repository The changelog is grouped by **package**, not by date: seven npm packages and one container image ship from this repository and each is versioned independently, so "the latest evestack release" is not a thing that exists. A version heading opens with the git tag that release would carry (`create-evestack@0.8.0`, `@evestack/dashboard@0.2.0`) and then the date — but far fewer tags have been cut than there are release headings, so most headings name a tag that does not exist. Run `git tag` for the real list. Do not report a version as tagged, or as released, on the strength of a heading alone. - [README](https://github.com/SammyTourani/evestack/blob/main/README.md) - [CHANGELOG](https://github.com/SammyTourani/evestack/blob/main/CHANGELOG.md) - [CONTRIBUTING](https://github.com/SammyTourani/evestack/blob/main/CONTRIBUTING.md) - [SECURITY](https://github.com/SammyTourani/evestack/blob/main/SECURITY.md)