An AI research assistant that shows its working. Ask a question and a durable backend agent searches the web, reads sources, and answers with inline citations — with every search, page read and delegated sub-agent rendered as a live step rather than a spinner.
Self-hosted, and each user brings their own AI Gateway key, so research is billed to them rather than to whoever runs the deployment.
Documentation · Architecture · Self-hosting
- eve — durable backend agent framework
- Next.js 16 + React 19 + shadcn/ui (Base UI) + Tailwind v4
- Streamdown — streaming markdown
- better-auth — Vercel (default) + Google + GitHub + email/password
- Neon Postgres + Drizzle ORM
- Vercel AI Gateway for models and
reranking — no per-provider keys. Default model
xai/grok-4.20-reasoning, compaction ongoogle/gemini-3.5-flash; seelib/models.tsandagent/agent.ts.
Two processes that behave like one. withEve() in next.config.ts rewrites
/eve/v1/* to the agent, so from the browser there is a single origin and no
CORS.
Browser ──────▶ Next.js :3000 ──────▶ Postgres
│
│ /eve/v1/* (rewrite)
▼
eve agent :4274 ────▶ Postgres
└──────────────▶ AI Gateway
On Vercel both deploy as one project. Everywhere else you start both yourself —
next build does not build the agent.
| Path | What lives there |
|---|---|
agent/ |
Everything the model can see or do: tools, skills, instructions, subagents, schedules |
agent/channels/eve.ts |
The agent's HTTP channel and its ordered auth chain |
app/(app)/ |
The authenticated shell — chat, projects, lookouts, settings, MCP |
app/api/ |
REST endpoints the UI calls directly |
app/docs/ |
The documentation site, built with Fumadocs |
components/timeline/ |
The research transcript |
lib/ |
Database, auth, retrieval, model catalog, event parsing |
proxy.ts |
Next 16's renamed middleware |
You need Bun, a Neon database, and a Vercel AI Gateway key.
bun install
cp .env.example .env.localFill in AI_GATEWAY_API_KEY, DATABASE_URL and BETTER_AUTH_SECRET — the only
hard requirements — and set ALLOW_SHARED_GATEWAY_KEY=true for local
development. Then:
bun run db:setup # creates the pgvector extension, once per database
bun run db:push # applies the schema
bun run dev # starts Next.js and the agent togetherEverything else degrades gracefully when unset: Exa, Firecrawl, Resend, Blob storage and the OAuth providers. See the environment matrix for what each one buys you.
Vercel, Docker and a plain VPS are all covered in
the self-hosting docs, including the
parts that bite — the two-process model, the NODE_ENV requirement on the agent
process, and why the Docker image has to be linux/amd64.
Set DEMO_MODE=true to serve a landing page instead of the app; that is what
miniscira.com runs.
See CONTRIBUTING.md, and SECURITY.md for
reporting a vulnerability. AGENTS.md documents the invariants that aren't
visible from the code alone — worth reading before changing the agent channel,
the event parser, or the lookout scheduler.