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:8765The 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
- Push the repository to GitHub. A private repository is fine;
.envis git-ignored. - In Render, choose New → Blueprint and pick the repository. Render reads
render.yaml. - Fill in what it asks for:
GEMINI_API_KEYand/orANTHROPIC_API_KEY, and optionallyGITHUB_TOKEN(a fine-grained token with Public repositories (read-only) and no other permissions). - Apply. When it's live, note the service URL, copy the generated
ARCH_ACCESS_CODEfrom Environment, and check that/api/healthanswers{"ok":true}.
The Render URL already serves the whole website. If that's all you need, you're done.
The website on Vercel
- In Vercel, add a project from the same repository.
- Set Root Directory to
frontend. The build settings come fromfrontend/vercel.json. - Add the environment variable
VITE_API_URL: your API's URL, without a trailing slash, for examplehttps://repo-archaeologist-api.onrender.com. - 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-archaeologistFly.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
| Variable | Container default | What 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_PROVIDER | from the keys | gemini or anthropic. |
ARCH_MODEL / ARCH_GRADER_MODEL | provider default | The model for every step, or for relevance grading only. |
ARCH_RUNS_PER_HOUR | 20 | Questions per visitor address per hour (0 = no limit). |
ARCH_MAX_REPO_MB | 500 (Render: 300) | The largest GitHub repository it will clone. |
ARCH_CORS_ORIGINS | * | Websites allowed to call the API, comma-separated. |
ARCH_EMBEDDER | FastEmbed (Render: none) | none = keyword search only, which needs less memory. |
ARCH_WEB_ALLOW_LOCAL | 0 | The container opens GitHub repositories only. |
ARCH_HOME | /data | Where clones, indexes and question history are kept. |
PORT | 8765 | Port 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
/datakeeps them (uncommentdisk:inrender.yaml). - With 512 MB of memory, keep
ARCH_EMBEDDER=noneand a modestARCH_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.