---
title: "Deploy Grep Knowledge Agent"
description: "Self-hosted AI knowledge agent — grep, not vector embeddings"
category: "AI/ML"
url: https://railway.com/deploy/grep-knowledge-agent
---

# Deploy Grep Knowledge Agent

Self-hosted AI knowledge agent — grep, not vector embeddings

**[Deploy Grep Knowledge Agent on Railway](https://railway.com/template/grep-knowledge-agent)**

- **Creator:** Jesse Ouellette's Projects
- **Category:** AI/ML

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### web

- **Source:** https://github.com/jesseoue/grep-knowledge-agent
- **Public domain:** Yes

### sandbox

- **Source:** https://github.com/jesseoue/grep-knowledge-agent

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2.1
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

## Documentation

# Deploy and Host a Grep-Based Knowledge Agent with Railway

A self-hosted AI knowledge agent that replaces vector embeddings with `grep`, `find`, and `cat`. Give the LLM a filesystem and `bash` — it searches your docs deterministically, explains every step, and costs ~75% less than vector RAG. No vector database, no Vercel lock-in.

```
┌─────────────┐   ┌──────────────────────────────────────────┐   ┌──────────────┐
│  Chat UI    │──▶│  Web (Nuxt 4 + Nitro)                    │──▶│  Sandbox      │
│  /settings  │   │  · AI SDK agent loop + complexity router │   │  (gVisor)     │
│  /login     │   │  · Postgres (chats, sources, users)      │   │  grep/cat/    │
│             │   │  · Redis (sessions, rate limits)         │   │  find (RO)    │
└─────────────┘   │  · GitHub sync → snapshot volume         │   └──────────────┘
                  └──────────────────────────────────────────┘
```

## About Hosting a Grep Knowledge Agent

The agent clones your GitHub repos into a snapshot volume, then uses a sandboxed shell to run read-only `grep`/`find`/`cat` commands against them. A complexity router classifies each question and routes to the right model — `gemini-2.0-flash` for trivial questions, `claude-sonnet-4` for moderate, `claude-opus-4` for complex. Every answer cites the files it read. Deploying on Railway gives you Postgres, Redis, persistent volumes, and private networking — all provisioned automatically with one click.

## Features

- **Terminal Noir UI** — a distinctive CRT/command-line aesthetic, honest to the product (filesystem + bash + LLM). JetBrains Mono, animated `grep` terminal hero, blinking cursor.
- **Markdown-rendered answers** — chat responses render as rich markdown (code, tables, lists), not raw text.
- **Command trace sidebar** — see every `grep`/`cat` command the agent ran in real time. No black box.
- **No embeddings. No chunking. No vector DB.** A filesystem, `bash`, and an LLM.
- **Complexity router** — lightweight model routes questions to `gemini-2.0-flash` (trivial) → `claude-sonnet-4` (moderate) → `claude-opus-4` (complex).
- **GitHub sources** — point it at any public repo and it clones the docs into a searchable snapshot.
- **Bring-your-own-key** — no AI gateway lock-in. Use OpenAI, Anthropic, Google Gemini, or all three.
- **Authentication** — GitHub OAuth + email/password (Better Auth), auto-detected trusted origins.
- **Auto-migration** — database tables created automatically on first deploy.
- **Rate limited + cost-observable** — 20 req/min per user, per-request token usage logging.
- **Typed SDK** — `@grep/sdk` for embedding the agent anywhere.

## Common Use Cases

- **Documentation Q&A** — point it at your repo's `docs/` folder and ask questions about your product
- **Codebase exploration** — let an LLM grep through your source code to answer architecture questions
- **Internal knowledge base** — sync multiple repos and search across all of them with one query
- **Self-hosted alternative** to Vercel's knowledge-agent-template — no vendor lock-in, bring your own AI keys
- **Cost-effective RAG replacement** — no embedding model, no vector DB, no chunking pipeline to maintain

## Dependencies for Grep Knowledge Agent Hosting

### Deployment Dependencies

- [Railway](https://railway.com) — hosts the web app, sandbox service, Postgres, and Redis
- [OpenAI](https://platform.openai.com/api-keys) / [Anthropic](https://console.anthropic.com/settings/keys) / [Google Gemini](https://aistudio.google.com/apikey) — at least one AI provider key (bring your own)
- [GitHub OAuth App](https://github.com/settings/developers) — for user authentication

### Implementation Details

| Vercel primitive | Railway replacement |
|---|---|
| Vercel Sandbox | gVisor sandbox (sidecar service with read-only grep/cat/find) |
| Vercel Blob | Railway Volume (snapshot directory) |
| NuxtHub KV | Redis (sessions, rate limits) |
| Vercel AI Gateway | Bring-your-own-key — OpenAI, Anthropic, or Google Gemini |
| Vercel Cron | Railway Cron (snapshot refresh) |
| Vercel Workflow | Node + Redis job runner |

### Why Deploy on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying this knowledge agent on Railway, you get Postgres, Redis, persistent volumes, and private networking — all provisioned automatically with one click.

## After Deploy (3 steps)

1. **Set an AI provider key** — at least one of:
   - `OPENAI_API_KEY` → [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
   - `ANTHROPIC_API_KEY` → [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
   - `GOOGLE_GENERATIVE_AI_API_KEY` → [aistudio.google.com/apikey](https://aistudio.google.com/apikey)

2. **Create a GitHub OAuth app** (Settings → Developer settings → OAuth Apps) with callback URL `https://.up.railway.app/api/auth/callback/github` — set `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`. Trusted origins + base URL are auto-detected from your Railway domain.

3. Open your app → sign in → **Settings → Add GitHub source** → enter `owner/repo` → **Sync**

4. Ask it anything about your repo. It answers with `grep`, not vectors.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/grep-knowledge-agent