> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambral.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# Shadow evals

> A shadow eval, also called a replay eval, replays your agent's recorded sessions to candidate models and scores each reply.

A **shadow eval**, also called a **replay eval**, scores models on your agent's recorded production sessions. It
is a taskset of those sessions with a scoring config, and each run of it is a **replay run**: at each point the
config picks, each candidate writes the next reply to the session as production lived it, and the config scores
that reply beside the one production gave.

It needs no environment, no tools and no test suite, only [recorded traces](https://docs.ambral.ai/guides/connect-an-agent.md). So it is
where to start, and the fastest way to find failure modes, try a prompt, and compare models on real traffic.

Its signal is directional. A candidate writes one reply at a time to production's history, never to its own
earlier replies, so anything that shows only on the candidate's own path is invisible to it. Before a candidate
serves everything, try it on whole sessions too, with [your own suite](https://docs.ambral.ai/guides/offline-evals) or on part of
production: see [Concepts](https://docs.ambral.ai/concepts.md#replay-runs-and-offline-runs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.