Knowledge Agent Template: A Vercel-Hosted AI Agent That Searches Files Instead of Vectors

What Problem This Solves and Who It Is For

Most knowledge base agents require a chunking pipeline, an embedding model, and a vector database. Knowledge Agent Template removes all three. Agents search by running grep, find, and cat inside isolated sandboxes, which means results are exact matches rather than approximate semantic neighbors. There is no embedding model to configure, no index to rebuild when files change, and no vector infrastructure to operate.

The template targets teams that want to build a file-system-based AI agent and deploy it quickly on Vercel. The README describes the use cases as a web chat app, a GitHub Issues bot, and a Discord bot, all served from one codebase. Planned additions mentioned in the README include Slack and Linear adapters. Adding a new platform requires writing a single adapter file, as stated in the README's customization guide.

Sources are pluggable: the README names GitHub repositories, YouTube transcripts, and custom APIs as examples. Any source that can be represented as files in a sandbox becomes searchable without any configuration beyond writing a source adapter. The deterministic nature of file-based search also makes results easier to audit than approximate vector retrieval: you can see exactly which file and which line matched the query.

Architecture: Sandboxes, Source Adapters, and a Complexity Router

The monorepo is organized into three packages. The @savoir/sdk package exposes AI SDK compatible bash and bash_batch tools that agents call to search files. The @savoir/agent package is the agent core: router, prompts, tools, and types. The apps/app package is a unified Nuxt application that hosts the web chat UI, the API, and the bot adapters.

Sandboxes are pooled across users and conversations. When a chat starts, it connects to an already-running sandbox instead of spinning up a new one, which the README states achieves startup in under 100ms. If none is available, a pre-built snapshot starts one in 1 to 3 seconds. Because sandboxes are shared, agents reach them through a parsed command policy that allows only read-only commands. Nothing can write a file or spawn an arbitrary process.

A complexity router classifies every incoming question from trivial to complex and routes it to the appropriate model. The README describes the routing as automatic, with simple questions going to faster, cheaper models and harder questions going to more powerful ones. No manual routing rules are required.

The architecture diagram in the README shows a source code level at the bottom feeding into @savoir/sdk, which feeds into the AI application layer (Discord bot, GitHub bot, and so on).

Installing and Running Locally

The template requires Bun as its package manager and GitHub OAuth credentials for authentication. The quick-start for self-hosting follows these steps:

git clone https://github.com/vercel-labs/knowledge-agent-template.git
cd knowledge-agent-template
bun install
cp apps/app/.env.example apps/app/.env
bun run dev

Three environment variables are required at minimum:

BETTER_AUTH_SECRET=your-secret
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

BETTER_AUTH_SECRET signs sessions and tokens; the README suggests generating it with openssl rand -hex 32. GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET come from a GitHub OAuth App created at github.com/settings/apps/new. The full list of variables is documented in docs/ENVIRONMENT.md in the repository.

For a one-click Vercel deployment, the README includes a deploy button that passes the required environment variables through Vercel's project creation flow. The package manager is Bun 1.3.14, as specified in the packageManager field of package.json.

Using @savoir/sdk in Your Own Agent

The SDK can be used independently of the full Nuxt app if you want to add file-based search to an existing agent. The README provides this example:

import { generateText } from 'ai'
import { createSavoir } from '@savoir/sdk'

const savoir = createSavoir({
  apiUrl: process.env.SAVOIR_API_URL!,
  apiKey: process.env.SAVOIR_API_KEY,
})

const { text } = await generateText({
  model: yourModel,
  tools: savoir.tools,
  maxSteps: 10,
  prompt: 'How do I configure authentication?',
})

console.log(text)

The savoir.tools object includes bash and bash_batch, both of which are AI SDK compatible tool definitions. Any AI SDK compatible model can be passed as yourModel. The SAVOIR_API_URL points to the sandbox API; SAVOIR_API_KEY is optional and used for securing that endpoint.

Admin Panel and Operational Observability

The template ships with a built-in admin panel. The README lists usage stats, error logs, user management, source configuration, and content sync controls as included features. An admin agent accepts natural-language questions about the application's own operation: the README gives examples such as querying errors from the last 24 hours, token usage by model, or identifying slow endpoints. The admin agent has access to internal tools including query_stats, query_errors, run_sql, and chart.

The chat UI shows real-time tool visualization: which files the agent is reading, which commands it is running, and the duration of each step. Conversations are shareable with a single-click link that generates a public read-only view with full metadata.

Limitations: Read-Only Commands and Sandbox Sharing

The sandbox command policy is a hard constraint. Only read-only commands are permitted: grep, find, and cat. An agent cannot write files, install packages, or run arbitrary code inside the sandbox. This is by design for multi-user safety, but it means the template is unsuitable for agents that need to produce or modify files as part of their task.

The shared sandbox model also means that multiple concurrent users reach the same sandbox. Because sandboxes are pooled, heavy usage by one user can affect available capacity for others, though the README does not document specific concurrency limits or queue behavior. The cold-start path of 1 to 3 seconds applies when no pre-warmed sandbox is available, which means latency on first interaction can vary.

The README does not document how to add sources that require authentication beyond what the GitHub adapter already handles. Custom API sources are mentioned as supported, but the customization guide in docs/SOURCES.md (referenced in the README) contains the specifics. The README also does not specify whether source sync runs on a schedule or must be triggered manually from the admin panel.

An alternative approach is LlamaIndex or LangChain with a vector store such as Pinecone. Those frameworks support semantic search over unstructured content and allow write operations from the agent. The trade-off is infrastructure complexity: an embedding model and a vector index must be maintained alongside the application. Knowledge Agent Template's value is removing that infrastructure entirely at the cost of restricting search to exact file matches.

Maintenance Status and License

The last push to the repository was on 2026-09-15, within the past month, which indicates active development. The repository is organized as a Turborepo monorepo with a Bun package manager, and the package.json scripts include build, lint, typecheck, and test targets. The Renovate configuration suggests automated dependency updates are enabled. A CONTRIBUTING.md and a SECURITY.md are present in the repository root.

The project is licensed under MIT, which permits commercial use, modification, and distribution. Attribution is required. The monorepo name is @savoir/monorepo and the author is listed as HugoRCD in the package.json. An AGENTS.md file in the root documents the agentic configuration for tools that support it.

Editorial conclusion

Knowledge Agent Template is the right starting point when you want a self-hosted AI agent over structured text sources, you accept the constraint of read-only bash commands inside sandboxes, and you are comfortable with a Nuxt monorepo requiring Bun and GitHub OAuth credentials. It is a poor fit when your knowledge base is primarily unstructured binary content, when you need write access from the agent, or when you need a deployment target other than Vercel. Verify that the sandbox shared pool model suits your usage pattern before depending on it in production: cold-start time is 1 to 3 seconds when no pre-warmed sandbox is available, and the command policy is intentionally restrictive.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. vercel-labs/knowledge-agent-template on GitHub