# Configuring a Sherlock AI Run

Runs can be configured in two ways: a quick per-run setup in the UI, and a shared default via a repo config file.

***

### UI flow

1. Click **Create Codebase Run** at the top of the dashboard.
2. Select the **repository**, then its **branch**, then the exact **commit**.
3. The **Advanced options** toggle appears. Open it to:
   * Choose **Files to analyze** (whitelist specific files or folders from that commit).
   * Add **Additional context files** (docs/configs that help the model).
   * Provide an **Additional context prompt** such as key areas to focus on, vulnerabilities to skip, or relevant information about the codebase.

Changes made here apply only to that run.

***

### Repo defaults with `.sherlock-ai.json`

Place a `.sherlock-ai.json` at the repo root (on the branch/commit being run). When the commit is selected in the UI, the values in  `.sherlock-ai.json`  will prefill the advanced options.

Example:

```json
{
  "whitelist_files": ["contracts/core/Vault.sol", "contracts/periphery/Router.sol"],
  "context_files": ["docs/security-model.md", "specs/withdrawals.md"],
  "extra_prompt": "Prioritize withdrawal logic and pause/unpause controls."
}
```

Fields:

* `whitelist_files` (string\[]): if empty, the whole repo is eligible. Only paths to files are supported. Paths should be relative to the repo root. Only `.sol` files are supported.
* `context_files` (string\[]): documentation to load and help the model. Only paths to files are supported. Paths should be relative to the repo root. The following file extensions are supported: `.md`, `.txt`, `.json`, `.yml`, `.yaml`
* `extra_prompt` (string): concise guidance. Useful for specifying key areas to focus on, vulnerabilities to skip, and relevant information about the codebase.

Configurations done through the UI will override what's defined in `.sherlock-ai.json`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sherlock.xyz/sherlock-ai/configuring-a-sherlock-ai-run.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.