Before you start
- An Ambral account and an org. Sign up at 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: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.- Signs in. If the CLI isn’t signed in, the agent runs
ambral loginand 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. - 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. - 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
.envfile 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. - 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.
- 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 asambral …. Where ambral isn’t installed, run each as
npx ambral@latest …, which runs the newest release.
List the workload’s recorded sessions: