Self-host

Run it yourself

On your own machine it's one script. On a server it's two parts: the API, a Docker container that clones repositories and runs each question for a minute or three, and the website, which can live on Vercel or be served by the API itself. Everything is set with environment variables; nothing secret goes in the repository or the image.

On your machine

You need Python 3.11+, uv, git and Node.js. Clone the repository, then:

./start.sh   # installs everything, builds the website, opens http://localhost:8765

The first run creates .env. Put a key in it: GEMINI_API_KEY (free tier, get one) or ANTHROPIC_API_KEY. Locally you can open any clone on your disk as well as GitHub repositories. ./start.sh ask <repo> works in the terminal without the website.

The API on Render

  1. Push the repository to GitHub. A private repository is fine; .env is git-ignored.
  2. In Render, choose New → Blueprint and pick the repository. Render reads render.yaml.
  3. Fill in what it asks for: GEMINI_API_KEY and/or ANTHROPIC_API_KEY, and optionally GITHUB_TOKEN (a fine-grained token with Public repositories (read-only) and no other permissions).
  4. Apply. When it's live, note the service URL, copy the generated ARCH_ACCESS_CODE from Environment, and check that /api/health answers {"ok":true}.

The Render URL already serves the whole website. If that's all you need, you're done.

The website on Vercel

  1. In Vercel, add a project from the same repository.
  2. Set Root Directory to frontend. The build settings come from frontend/vercel.json.
  3. Add the environment variable VITE_API_URL: your API's URL, without a trailing slash, for example https://repo-archaeologist-api.onrender.com.
  4. Deploy, open the site, and enter the access code.

VITE_API_URL is built into the website, so changing it needs a redeploy. To let only your website call the API, set ARCH_CORS_ORIGINS on the API to your Vercel URL; the access code is what protects it either way.

Anywhere Docker runs

docker build -t repo-archaeologist .
docker run -p 8765:8765 -v archaeologist-data:/data \
  -e GEMINI_API_KEY=... -e GITHUB_TOKEN=... -e ARCH_ACCESS_CODE=choose-one \
  repo-archaeologist

Fly.io, Railway, Google Cloud Run and a plain VPS all work. On Cloud Run, raise the request timeout (for example --timeout=3600), because progress streams for minutes. Mount a volume at /data wherever the host offers one.

Settings

API settings
VariableContainer defaultWhat it does
GEMINI_API_KEY / ANTHROPIC_API_KEY—LLM keys; at least one. With only a Gemini key, Gemini is used; with both, Claude is.
GITHUB_TOKEN—GitHub token for pull request and issue lookups (5,000 requests an hour instead of 60).
ARCH_ACCESS_CODE— (Render generates one)The code visitors must enter. Empty means anyone can use your keys.
ARCH_PROVIDERfrom the keysgemini or anthropic.
ARCH_MODEL / ARCH_GRADER_MODELprovider defaultThe model for every step, or for relevance grading only.
ARCH_RUNS_PER_HOUR20Questions per visitor address per hour (0 = no limit).
ARCH_MAX_REPO_MB500 (Render: 300)The largest GitHub repository it will clone.
ARCH_CORS_ORIGINS*Websites allowed to call the API, comma-separated.
ARCH_EMBEDDERFastEmbed (Render: none)none = keyword search only, which needs less memory.
ARCH_WEB_ALLOW_LOCAL0The container opens GitHub repositories only.
ARCH_HOME/dataWhere clones, indexes and question history are kept.
PORT8765Port to listen on (Render sets it).

The website has one setting, VITE_API_URL: the API's URL, or empty when the API serves the website itself.

Free plans, honestly

  • Render's free plan sleeps after about 15 idle minutes; the next visit takes up to a minute to wake it, and the website says so while it waits.
  • Its disk is temporary: cloned repositories and question history disappear on each restart or deploy. A paid instance with a disk at /data keeps them (uncomment disk: in render.yaml).
  • With 512 MB of memory, keep ARCH_EMBEDDER=none and a modest ARCH_MAX_REPO_MB.
  • Gemini's free tier takes about 20–40 seconds per call and caps requests per day. One question uses about 4–10 calls.

Why the API isn't on Vercel

A question runs for minutes, needs git and a clone on disk, and streams its progress to the page watching it. Vercel Functions stop after 300 seconds on the Hobby plan, don't keep files between requests, and may send the next request to a different instance. The website fits Vercel perfectly; the API needs a server that stays up.