Codebase Researcher

Why deploy codebase-researcher on Render?

Documentation explains supported behavior, but many questions can only be answered from the implementation: what a setting really does, why a command fails in one environment, or what happens in an edge case. Those questions usually land on an engineer, often in a vague form they have to untangle before they can answer.

codebase-researcher does the first investigation. Post a question to its HTTP API or run the included pnpm ask CLI, and an AI coding agent reads your repositories in a fresh, locked-down Render Sandbox. It returns a structured answer that separates what it saw in the code from what it inferred and what it couldn't establish. Every citation is checked against the exact commit, file, and line range it read, and the agent suggests an owner and an escalation-ready question for whatever remains.

The default configuration researches three public Render repositories (the CLI, SDK, and agent skills), so you can try the whole system before connecting your own code. To use it on your repositories, fork the template, edit config.ts and prompt.md, and deploy the fork.

Architecture

Two independent flows keep questions fast and credentials separate. Every hour, a cron job clones the configured repositories into a privileged builder Sandbox, removes the clone credentials, locks the checkout down, verifies it, and saves an immutable snapshot. It keeps the newest two so a question that started restoring just before a new build can still finish.

For each question, the Workflow restores a new Sandbox from the newest snapshot, verifies its security properties, runs the agent as an unprivileged user, validates the result, and terminates the Sandbox. The API returns 202 immediately with a signed question ID. Callers poll that ID or supply a callback URL. Render Workflows owns long-running execution, retries, and run history, so no application database is needed.

The API has no UI. Its only routes are /healthz and /v1/*, so opening the service URL in a browser shows 404 Not Found, which is expected.

What you can build

After deploying the example corpus, ask a question such as "How does the CLI pick a workspace in CI?" An investigation usually takes one to two minutes and returns:

If a question is ambiguous, the agent asks one clarifying question instead of guessing. Answer it as a follow-up with the earlier question ID, and the new investigation receives the whole exchange.

Because the interface is an authenticated HTTP API with idempotency keys, routing metadata, and signed callbacks, the same pipeline can sit behind a support tool, an internal dashboard, a chat bot, or a ticketing integration, each running as its own service.

Key features

• A fresh Sandbox for every question: No environment or agent state carries from one investigation to the next.
• Snapshot-based repository access: A scheduled builder prepares the repositories once an hour. Investigation Sandboxes restore from that snapshot and never receive Git credentials.
• Commit-pinned evidence: Every answer records the exact commits the agent read.
• Citation validation across a trust boundary: Trusted code rejects any submission whose repository, commit, path, or line range doesn't exist in the checkout, so the agent must fix it before it can answer. Trusted code, not the model, then builds the final source links.
• Structured uncertainty: The result schema separates observations, inferences, and unknowns, so a fluent answer can't hide gaps in the investigation.
• Read-only agent tools: The agent can read files, search source, and inspect git history. Repositories are root-owned and read-only; only a scratch directory is writable.
• Locked-down egress: By default, the investigation Sandbox can reach only the selected model provider's API over HTTPS. You can replace that with your own exact-host allow-list.
• Durable workflow execution: Infrastructure failures retry the investigation subtask without hiding agent failures or invalid submissions. Callback delivery has its own retry policy. A failed run returns a safe error and a trace ID that an operator can open in the Dashboard.
• Allow-listed callbacks: Callbacks are off until you list the origins they may be delivered to. Delivery is signed and never follows redirects.
• Provider-flexible models: The agent runs on the pi agent library. Anthropic is the default, and OpenAI and Google models are also tested.
• Try it without a model key: Run the workflow and API locally over local checkouts with a scripted --faux runner that exercises the real tools and citation checks without calling a model.

Use cases

• A support or developer-experience team runs a code-backed first investigation before escalating a product question to engineering.
• An engineer new to a large codebase gets answers with direct links to the implementation and tests.
• A platform team adds evidence-backed code research to a chat bot, support console, or internal API.
• A developer studies how to build, verify, snapshot, and restore a constrained agent environment with Render Sandboxes.

What's included

All three services run in a codebase-researcher project in Oregon. Builder and investigation Sandboxes are temporary resources created by the cron job and Workflow, not always-on services.

The API can use the free instance type because questions run in the Workflow, not the web process; a spun-down API adds a cold start to the first request. The snapshot cron uses Standard because bundling the agent runner needs more than 512 MB of memory.

Prerequisites

• A Render workspace with Sandboxes access in Oregon.
• A Render API key. The API uses it to start and read Workflow runs; the Workflow and cron job use it to manage Sandboxes. If you use scoped API keys, the quickstart lists the minimum permissions for each service.
• A dedicated, spend-capped model API key. Anthropic is the default; OpenAI and Google are also supported.
• A read-only Git token for private repositories (optional). Only the snapshot cron job receives it.
• Node.js and pnpm 11 to use the included pnpm ask client or run the project locally.
• Paid resources for snapshot builds. The Blueprint selects a Standard cron instance, and Workflow and Sandbox usage are billed separately.

Next steps

Try the public example corpus

1. Deploy the template and enter your Render API key and model key when prompted. The Blueprint generates the API token and a separate secret for signing question IDs, and wires the Workflow into the API.

2. Build the first snapshot. Open codebase-researcher-snapshots in the Render Dashboard and click Trigger Run instead of waiting for the hourly schedule. The first build takes about five minutes; wait for a snapshot_refresh log event with "ok": true.

3. Ask a question. Copy API_TOKEN from the Environment page of codebase-researcher-api and the service URL from the top of that page. Confirm the API is up, then ask:

4. Inspect the run. Open codebase-researcher-workflow in the Dashboard and find the run whose ID matches the answer's traceId. It shows the parent task, subtasks, timing, and any retries.

Connect your own code

1. Fork the repository.
2. Edit config.ts to list the repositories and branches the snapshot builder should clone.
3. Edit prompt.md to describe your product, likely askers, what each repository is responsible for, and which sources to trust.
4. Create a Blueprint from your fork, and add a read-only Git token to the snapshot cron job if any repository is private.
5. Rebuild the snapshot. After the cron job has deployed your commit, trigger a run and check that its snapshot_refresh event lists your repositories. Repository and prompt changes take effect only after a new snapshot builds successfully.
6. Enable callbacks if you need them. Set CALLBACK_ALLOWED_ORIGINS on the Workflow service to the origins of the integrations that should receive answers.

Security notes

The template assumes the agent can run shell commands and treats its environment as untrusted:

• Investigation Sandboxes never receive Git credentials. The builder removes clone credentials and verifies they're gone before saving a snapshot.
• Checked-out repositories are root-owned and read-only to the agent's user.
• The model key arrives as a one-time file that the runner deletes on read, and it's removed from tool environments. The runner's Node binary is execute-only and signal-triggered debugging is disabled, so the agent's commands can't read the key from memory. Every snapshot build and restored Sandbox must verify these protections before it does any work.
• HTTPS egress defaults to the selected model provider's API host.
• Trusted code validates citations and constructs evidence links after the model submits its result.
• Question IDs are signed with a server-only secret, separate from the token callers use, so a caller can't look up unrelated workflow runs.
• Callbacks go only to origins you list and never follow redirects.

DNS is a residual risk: the network policy blocks unapproved HTTP and HTTPS connections, but arbitrary DNS lookups still resolve. Anyone with API_TOKEN can read the configured repositories through the researcher, so treat it like a read token for them. Use a dedicated, spend-capped model key, and read the architecture guide's trust boundaries before pointing it at sensitive private source.

Current limits

• The researcher reads code and git history, not running production systems.
• It can't modify repositories, open pull requests, or reach arbitrary external services.
• Its view of the code updates after each successful snapshot refresh, not on every commit.
• It has an API and CLI, but no web UI or history database; Workflow run history is the audit trail.
• Sandbox API calls share the workspace's request limit, so expect a handful of concurrent questions, not dozens.
• Sandboxes run only in Oregon during early access.

Resources

• codebase-researcher README
• Quickstart
• Extension guide
• Architecture and trust boundaries
• Design takeaways
• Render Workflows docs
• Render Sandboxes docs