> ## 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.

# Quickstart

> Install the Ambral skill, ask your coding agent to connect your app, and see your first trace.

Your coding agent sets Ambral up for you. You install the Ambral skill in your project, then ask the agent to
connect your app.

## Before you start

* An Ambral account and an org. Sign up at [app.ambral.ai](https://app.ambral.ai).
* Credits in the org. A new org starts with none, and the Gateway answers no request until it has some. An owner
  or admin adds them on the **Billing** page of the web app.
* Node 22 or later.
* An app or agent that calls a model through OpenAI's Chat Completions API or Anthropic's Messages API.

## Set it up

**1. Install the skill**

Run this in your project's root:

```sh theme={null}
npx ambral@latest skill install
```

It writes the skill where Claude Code and other agents that read skills find it. The skill matches the
version of the CLI that installed it, and later `ambral` commands keep it up to date.

**2. Ask your agent**

In Claude Code, Codex, Cursor or any agent that reads skills:

> Connect this app to Ambral.

## What your agent does

The skill takes the agent through these steps. It asks you before it creates anything.

1. **Signs in.** If the CLI isn't signed in, the agent runs `ambral login` and shows you a link and a code. Approve
   them in your browser. If the project isn't linked to an org yet, it asks which of yours to use.
2. **Picks or creates a workload.** A workload is one kind of task your agent repeats. The agent reads your code,
   suggests a short name such as `support-agent`, and confirms it and the model that serves it first with you.
3. **Asks you for a key.** Create a key on the **API keys** page of the web app and store it where your app reads
   its secrets, such as a `.env` file that git ignores. Tell the agent the name you stored it under. Don't paste
   the key to the agent: it never needs to see it.
4. **Points your client at the Gateway.** Where your code builds its OpenAI or Anthropic client, the agent sets
   the base URL, the key's secret, the model, and the headers that name the workload and each session.
5. **Runs one session and checks it was recorded.** A session is stored once it has gone quiet for a little while,
   so the first trace takes about half a minute to appear.

## See your first trace

The commands on this page are written as `ambral …`. Where `ambral` isn't installed, run each as
`npx ambral@latest …`, which runs the newest release.

List the workload's recorded sessions:

```sh theme={null}
ambral traces list <workload>
```

Then read one whole, with the id the list printed:

```sh theme={null}
ambral traces get tr_…
```

Under each reply it shows the model that served it, why it finished, its tokens and its latency. In the web app,
the Overview page shows **Connected** once your app's traffic arrives.


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