Scira: a self-hostable agentic search engine built on the Vercel AI SDK

The problem Scira targets: research that cites its sources

A general chat model answers from weights. For research, that is the wrong substrate, because you cannot click through to check the claim. Scira's stated purpose is narrower than "search engine": the README describes it as an agentic research platform that plans, retrieves and cites. The audience is someone who wants the Perplexity-shaped interaction (ask, get a grounded answer, click a citation) but wants to own the retrieval pipeline, swap the models, and add tools that no hosted product exposes.

The repository backs that up. The top level holds an app/ directory, an ai/ directory, lib/, drizzle/ migrations, create_indexes.sql and reindex_tables.sql, a Dockerfile and a docker-compose.yml. That is the layout of a deployable product, not a library. If you want a search API to call from your own service, this is the wrong shape of project.

How the agent plans, retrieves and cites

The README gives a three-step loop: you ask, the agent breaks the question into sub-tasks and searches live sources, then it returns an answer with inline citations. The mechanism underneath is the Vercel AI SDK. The package.json depends on @ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/google, @ai-sdk/xai, @ai-sdk/mistral, @ai-sdk/groq, @ai-sdk/cohere, @ai-sdk/gateway, @ai-sdk/mcp and @ai-sdk/openai-compatible, so model routing is per-provider rather than a single vendor lock.

Retrieval is deliberately multi-vendor. The README lists web search as "multi-query parallel web search with deduplication using Exa, Firecrawl, Parallel, and Tavily", and the .env.example carries TAVILY_API_KEY, EXA_API_KEY and FIRECRAWL_API_KEY separately. State lives in Postgres (DATABASE_URL, drizzle.config.ts, the SQL files) and Redis (REDIS_URL), with Upstash named for serverless Redis and rate limiting. Uploaded files are embedded with Cohere and reranked, per the file query search entry.

The design consequence is that Scira is a router, not a crawler. It owns planning, tool selection, citation assembly and the UI. Everything factual comes from a paid third party. That is a reasonable trade, but it means your answer quality is bounded by whichever search vendors you fund, and your bill scales with the number of tools a single question triggers.

Installing Scira and running a first query

The repository ships a Dockerfile and a docker-compose.yml, so the container path is the shortest documented route. The compose file defines one service, scira.app, built from the Dockerfile, publishing port 3000 and setting NODE_ENV=production, PORT=3000 and HOSTNAME=0.0.0.0.

services:
  scira.app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - HOSTNAME=0.0.0.0
    restart: unless-stopped

Before building, copy .env.example to .env. The Dockerfile copies .env into the builder stage, so the build reads it. Note what that file asks for: XAI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DATABASE_URL, REDIS_URL, BETTER_AUTH_SECRET, TAVILY_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY and roughly two dozen more. A minimal run still needs a model key, a database URL and an auth secret.

cp .env.example .env
# fill in at least one model key, DATABASE_URL, REDIS_URL, BETTER_AUTH_SECRET
docker compose up --build

The image is multi-stage: node:22-alpine as the base, a deps stage that enables corepack and installs with pnpm, a builder stage that runs npm run build, and a runner stage that copies .next/standalone and .next/static and drops to a non-root nextjs user. Expect the build to take a while, since it installs the full dependency tree. When it finishes, the app answers on http://localhost:3000.

If you prefer to run it outside Docker, the package.json scripts are dev, build, start, lint, typecheck (tsgo --noEmit) and fix. The README's own instructions point at scira.ai to try the hosted version, so the self-host path is inferred from the repository files rather than spelled out in prose.

npm run dev
npm run typecheck

Where Scira gets expensive and where it fails

The first limitation is credential surface. The .env.example is the honest inventory: AI keys for xAI, OpenAI, Anthropic, Groq, Inception and Google; Daytona for the code sandbox; database and Redis URLs; a blob token; Better Auth secrets plus GitHub, Google and Twitter OAuth clients; Tavily, Exa, Firecrawl and Notte; Cloudflare account and token; TMDB, an ElevenLabs key, Spotify client credentials; Google Maps, Mapbox and Tripadvisor; OpenWeather and Aviation Stack; Supermemory, Smithery and an MCP credentials encryption key. Each one is a separate account, quota and failure mode. A question that fans out across web search, a code interpreter and a stock chart touches several of them at once.

The second is that several features are gated. The README marks Connectors, Memory, Voice and XQL as Pro. Those are product tiers on the hosted service, and the README does not describe how the equivalent entitlement is enforced in a self-hosted build. Treat that as an open question to answer in the code before you plan around those modes.

The third is operational: the Dockerfile copies .env into the image at build time. That is convenient for a build that needs configuration, and it also means secrets baked into an image layer. The README does not document a rollback procedure, a migration story for the drizzle/ directory, or what happens to scheduled Lookouts when the process restarts. If you need a single static binary, a small dependency tree, or a system that works without external search vendors, Scira is the wrong tool.

Scira compared with Perplexity

The obvious comparison is Perplexity, and the difference is not answer quality, which neither project documents, but where the pipeline lives. Perplexity is a hosted product: you get its crawler, its index, its model routing and its rate limits, and you cannot swap any of them. Scira is a client of other people's indexes. Its web search entry names Exa, Firecrawl, Parallel and Tavily, and its answers are assembled from whatever those APIs return.

That inverts the cost model. With Perplexity you pay a subscription and someone else absorbs retrieval cost. With Scira you pay each vendor directly, per call, and a deep multi-step query can hit several. In exchange you get to change the plan prompt, add a tool, point the model selector at a different provider through @ai-sdk/openai-compatible, or run the whole thing on infrastructure you control, which the AGPL-3.0 licence permits as long as you honour its network-use terms.

The practical read: if you want a research product and not a research stack, the hosted service is the lower-effort choice. If you want the retrieval pipeline to be a file in your repository, Scira is the one that gives you that.

Licence, maintenance and the upgrade bill

Scira is AGPL-3.0. The practical implication for a self-hoster is that if you modify it and let users interact with it over a network, the licence's source-disclosure obligation is the thing to read, not the permissive-licence assumption people often carry over from MIT projects. This is a description of the licence, not legal advice; if you plan to run a modified Scira as a service, have someone who knows the AGPL look at your setup.

The maintenance picture from the repository: it is not archived, and the last push was on 2026-08-12. The dependency list is broad and pinned with carets, covering a dozen AI SDK providers, AWS S3 clients, Dodo Payments, Better Auth, Daytona and others. Each of those moves independently. Upgrading means reconciling the AI SDK provider versions against each other, re-running the drizzle migrations, and re-checking the SQL index files. That is ongoing work, not a one-time install. If your team cannot absorb a dependency churn cycle across a dozen providers, the hosted version is the honest answer.

Editorial conclusion

Adopt Scira if you want a working, citable research interface you can fork and point at your own model keys, and you are willing to supply Postgres, Redis, blob storage and roughly thirty third-party API credentials. Skip it if you need a single-binary deployment or a small, auditable codebase: the tool surface is wide and the README does not document rollback or migration paths. Before committing, run the Dockerfile build with a populated .env and confirm which of the env keys your chosen modes actually require, since the README lists modes and tools but not the per-mode key mapping.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. zaidmukaddam/scira on GitHub