Documentation

Imagine a company has an application that uses artificial intelligence. It could be a chatbot, an automation, an internal tool or a feature used by customers.

At first, this may be easy to manage. As usage grows, the company starts asking questions that are harder to answer from one place.

• How much are we using AI?
• How much money are we spending?
• Which application is using the most?
• Are requests working or failing?
• Why are some responses slower?

Clyvel gives the company one place to see and control what is happening with the AI used by its applications. You do not need to understand the technical pieces yet. We will introduce them one by one in the next chapters.

• Companies can lose visibility as AI usage grows.
• Clyvel exists to bring that information together.
• You do not need technical knowledge to continue.

Suppose a user writes: “Summarize this document.” The application takes that instruction and sends it to an artificial intelligence model so it can produce an answer.

1. 1

   A person asks for something

   For example: summarize a document.

2. 2

   The application sends the request

   The application sends the text to an AI model.

3. 3

   The AI returns an answer

   The application shows or uses that answer.

For now, that is all you need to know. Later, Clyvel will let you see each of these Requests and understand how they behaved.

• A Request is one individual AI request.
• An application can send many Requests over time.

A Provider is a company that offers AI models that applications can use.

• OpenAI
• Anthropic
• Google / Gemini

A Model is the specific AI system that receives the Request and produces the answer. A Provider can offer several different Models.

A Request leaves your application, reaches a Provider and is processed by a Model. We still have not added Clyvel to the picture. That comes later.

• Provider = the company offering AI models.
• Model = the specific AI system that processes a Request.

A company may have more than one thing using AI. For example, a chatbot, an n8n automation and a Python application can all send Requests.

Clyvel calls each application, automation or system that you want to observe separately an Agent.

• An Agent is something in your company that sends AI Requests.
• Clyvel keeps Agents separate so you can compare their activity later.

Until now, our simple flow looked like this: your Agent sends a Request to a Provider, and one of that Provider's Models produces the answer.

With Clyvel, the Agent sends the Request to Clyvel first. Clyvel then forwards it to the configured Provider. The answer still comes from the Provider's Model.

The Clyvel Gateway is the address your Agent sends AI Requests to before they continue to the Provider. It is the entry point that lets Clyvel observe what is happening.

Clyvel does not replace OpenAI, Anthropic or Google. Those Providers still process the AI request. Clyvel adds the layer that makes the activity visible and controllable.

• Clyvel sits between your Agent and the Provider.
• The Gateway is the address where your Agent sends Requests to Clyvel.

Because the Request passes through Clyvel, Clyvel can record useful facts about what happened. We will use these facts throughout the rest of the product.

Status tells you whether the Request completed successfully or failed.

AI models process text in small units called tokens. A Request can use tokens when sending information to the model and more tokens when the model generates its answer.

Latency is the amount of time a Request takes to complete. Lower latency usually means the user receives an answer faster.

Clyvel can attribute model usage cost to the Request when the necessary usage information is available. It also records errors so you can see when a Request did not complete correctly.

• Status tells you whether a Request worked.
• Tokens help describe how much model usage occurred.
• Latency tells you how long the Request took.
• Cost and errors help explain efficiency and failures.

You now know the pieces: an Agent sends a Request, the Request is processed by a Model from a Provider, and Clyvel can sit in the middle through its Gateway.

The goal of this chapter is simple: send one real Request through Clyvel and then find it in the product.

1. 1

   Sign in to Clyvel

   Open the dashboard. A new workspace may still show example previews until real traffic arrives.

2. 2

   Connect a Provider

   Choose OpenAI, Anthropic or Google/Gemini and provide the credential requested by Clyvel. Clyvel validates the connection.

3. 3

   Connect an existing application

   Use Guided Connection if you want Clyvel to walk you through the setup for your integration.

4. 4

   Copy the Gateway URL

   This is the Clyvel address your application will send AI Requests to.

5. 5

   Use the Clyvel API Key

   This key identifies and authorizes the Agent with Clyvel. It is different from the Provider credential stored in Clyvel.

6. 6

   Run the application

   Make the application send at least one real AI Request through the Gateway.

7. 7

   Verify the result

   Clyvel should detect traffic, the Agent can become Connected, and the Request should appear in Requests and begin contributing to Overview.

• Check that the application is using the Clyvel Gateway URL.
• Check that the Clyvel API Key is the one created for the connection.
• Check that the Provider is connected and its credential is valid.

• How the basic Clyvel flow fits together.
• Why you need both a Provider connection and a Clyvel API Key.
• How to confirm that the first real Request reached Clyvel.

Guided Connection is the step-by-step path Clyvel uses to help you connect an existing application or automation. You choose what you use, choose the AI Provider, follow the configuration, run your application, and Clyvel waits for the first real Request.

1. 1

   Choose the integration

   Tell Clyvel what kind of application you are connecting.

2. 2

   Choose the Provider

   Choose the company that will process the AI Requests, such as OpenAI, Anthropic or Google/Gemini.

3. 3

   Apply the configuration

   Clyvel shows the Gateway URL and the Clyvel API Key in the appropriate steps.

4. 4

   Run your application

   Send a real AI Request. Clyvel then listens for traffic and confirms the connection when it sees it.

The guided catalog currently covers the connection paths below. The exact instructions differ, but the goal is always the same: make the application's AI traffic pass through the Clyvel Gateway.

• n8n
• Make
• Python
• Node.js
• LangChain
• LangGraph
• CrewAI

The conversational AI can explain a step, clarify a doubt and answer contextual questions. It does not decide critical connection state by itself. The connection recipe and state machine remain the authority for moving to the next critical step.

Overview is the first place to look when you want a quick picture of the whole AI operation. It combines activity, success and failure, tokens, cost, latency, Agents, Providers, Models and Incidents so you can decide where to investigate next.

Average latency can hide a slow minority of Requests. p95 looks closer to the slow end. If p95 is 2.4 seconds, roughly 95 out of every 100 Requests completed in 2.4 seconds or less, while the slowest few took longer.

• If Error Rate jumps, move to Requests, Providers and Incidents.
• If cost jumps, move to Costs and compare Provider, Agent and Model activity.
• If latency rises, compare Providers, Models and recent Requests.
• If an Agent becomes inactive, inspect its connection and recent traffic.

1. 1

   Read the error

   Start with the specific failure recorded for the Request.

2. 2

   Check Provider and Model

   Confirm the Provider is connected and the selected Model is valid for the application.

3. 3

   Look at nearby Requests

   One isolated failure and a wave of failures usually point to different problems.

4. 4

   Check Incidents

   If the problem is broader, an Incident may give you the operational context.

A single Request tells you what happened once. A trend tells you how a measurement is changing across a period. Analytics helps you see patterns in traffic, tokens, latency and errors instead of judging the system from one isolated event.

• Traffic: are more or fewer Requests arriving?
• Tokens: is each Request consuming more text/model usage?
• Latency: is the experience becoming slower?
• Errors: are failures concentrated in one Agent, Provider or Model?

• Requests rose slightly but cost rose sharply: inspect tokens and the Model mix.
• Latency increased only for one Provider: start the investigation there.
• One Agent produces most failures: inspect that Agent's recent Requests and connection.

An Alert is a signal that a condition deserves attention. It helps you notice that something changed or crossed a relevant threshold. Alerts can be operational or related to budgets, depending on the real rule or event being monitored.

An Incident is an operational problem that is recorded and managed. It has a lifecycle: you investigate it, acknowledge that someone is handling it, and resolve it when the problem is finished.

1. 1

   Requests begin to fail

   For example, a Provider credential is no longer accepted.

2. 2

   Investigate

   Open the Incident and related Requests to understand the cause.

3. 3

   Acknowledge

   Mark that the problem is being handled.

4. 4

   Resolve

   After correcting the underlying issue, close the Incident as resolved.

Clyvel can respect each user's notification preferences for supported critical incidents, budget alerts and usage/billing notifications. Those preferences live in Settings. The current V2 does not promise Slack, SMS or Teams delivery.

Costs is about the money your organization spends using AI Providers and Models. It is not the price of the Clyvel subscription. Think of it as Provider Spend: the model usage generated by your own applications and Agents.

Input tokens represent the text sent to the Model. Output tokens represent the generated answer. More tokens generally mean more model usage, and model usage can increase Provider Spend. The exact price depends on the Provider and Model rather than on the language selected in Clyvel.

1. 1

   Confirm the period

   Make sure you are comparing the same time window.

2. 2

   Compare Providers

   See whether the increase is concentrated in one Provider.

3. 3

   Compare Agents and Models

   Find which workload and Model mix changed.

4. 4

   Open Requests

   Check whether larger prompts, longer answers or more traffic explain the change.

Cost visibility tells you what you spent. A Budget gives you a number to watch against that spend. A simple example is: 'I want to know when my AI spend approaches 500 dollars this month.'

Budget Alerts help you notice when spend reaches a configured threshold. Supported email delivery also respects the user's Budget notification preference in Settings. A Budget is primarily a financial-control and warning mechanism; do not assume it automatically shuts down your Provider unless the product explicitly says so in that flow.

Review your Clyvel subscription and any model charges billed directly by your AI provider. Billing shows your Clyvel subscription and observability usage; Costs shows AI usage recorded through the Gateway. Clyvel AI is part of the workspace experience rather than a separate credit balance. Check the current plan price in Pricing.

When only one person uses one AI tool, informal decisions may be enough. When several people, applications and Providers share the same AI operation, the organization needs a clearer view of what is allowed, who can change important settings and how activity is kept inside the correct Workspace.

In Clyvel, Governance is the set of visibility and control surfaces used to keep AI operations organized. It works together with organization scoping, roles, Providers, API Keys, Budgets and other controlled settings. It does not mean that Clyvel automatically grants a compliance certification.

• Keep resources scoped to the correct organization.
• Limit sensitive changes according to Owner, Admin and Member roles.
• Keep operational settings and evidence visible instead of relying on memory.

A production system can return an answer and still perform poorly for the purpose you care about. Evaluations give you a structured way to run checks and record results instead of relying only on intuition.

• Suites: groups of evaluation checks.
• Runs: individual executions of an evaluation.
• Pass / Fail and score: the recorded result of the run.
• Latency and recent runs: context about how the evaluation behaved over time.

Start with the evaluation goal, then look at the pass/fail result and score, and finally use latency and recent runs as context. A single result can be useful, but repeated runs are better for understanding whether a change is consistent.

Once you know how the system behaves and what it costs, you can look for opportunities to improve it. Optimization organizes those opportunities so they can be reviewed rather than applied blindly.

• Category and recommendation: what kind of change is being suggested.
• Priority and risk: how important the opportunity is and how carefully it should be handled.
• Potential savings: an estimate when the product has enough evidence to present one.
• Validation status and evaluation evidence: context used before treating the opportunity as ready.

Reports help turn the evidence already present in Clyvel into a structured document for a specific audience or purpose. Current report types include executive, operations, incidents, and cost & efficiency oriented views.

Releases keep versioned records for an Agent. A release can preserve status, snapshots, release notes, published state and the latest evaluation context. This lets you discuss a version of an Agent without confusing it with live Request traffic.

Clyvel AI is the assistant inside Clyvel. It can use controlled tools to look at information from the current Workspace and help you understand what is happening. It is not a general agent with unrestricted access to everything.

• Overview and Agents
• Requests and Costs
• Incidents and Optimization
• Financial Control and Governance
• Evaluations, Models and Reports

• Why did my costs increase this week?
• Which Agent has the highest error rate?
• Are there unresolved Incidents?
• Which Provider is causing higher latency?

Clyvel AI answers from controlled Clyvel data rather than inventing operational facts. When it uses a read-only tool, the returned evidence becomes the basis for the explanation.

If useful telemetry is not available, Clyvel AI should say that the evidence is missing instead of pretending it exists. It also avoids unnecessary model calls when there is nothing useful to analyze.

1. 1

   Ask

   Ask about the current Workspace in natural language.

2. 2

   Collect evidence

   Read-only tools retrieve the relevant Clyvel data.

3. 3

   Explain

   Clyvel AI explains the result and recommends what to review next without changing Workspace state.

Clyvel AI can inspect the operational context available to its controlled tools and explain what it finds. It does not change production configuration, budgets, incidents or routing on its own.

• Requests, latency, tokens and failures
• Costs, budgets and optimization evidence
• Incidents, governance, models and reports

Use the answer to decide what deserves attention, then open the relevant Clyvel module to review or apply any change yourself.

1. 1

   Ask

   Describe the operational question in natural language.

2. 2

   Investigate

   Clyvel AI gathers the context its read-only tools can access.

3. 3

   Decide

   Review the evidence and choose the next action from the relevant module.

A Workspace is the organizational space where Clyvel groups a company's users and resources. Agents, Providers, Requests, Costs, Budgets, Incidents, Billing and other records are resolved in the context of the current organization instead of being treated as one global pool.

Clyvel is built so that an operation in one organization should not become an operation on a resource owned by another organization. This is the tenant-isolation idea: identity and resource access stay scoped to the correct organization.

Not everyone who needs visibility also needs permission to change credentials, Billing, Budgets or administrative settings. Clyvel therefore uses roles so a person can see what they need without automatically receiving every sensitive capability.

Workspace invitations use the native Clyvel identity system. The invitation is tied to the organization and is handled as a controlled onboarding flow rather than as a free-form organization ID chosen by the browser.

• Native email/password authentication with secure password hashing.
• Google OAuth sign-in as an additional identity path.
• Session management, email verification and password reset flows.
• RBAC and organization isolation to keep sensitive operations scoped.

A Provider credential lets Clyvel connect to a Provider on behalf of the current organization. Those credentials are treated as secrets and are encrypted at rest. The product should not display them back as plain text after they have been stored.

A Clyvel API Key identifies traffic sent to the Clyvel Gateway. It is different from your Provider credential. Your application uses the Clyvel key to authenticate to Clyvel; Clyvel uses the configured Provider connection for the upstream AI request.

• General: profile, Workspace information, language and timezone preferences.
• Members: membership and role management according to permissions.
• Security: password, Google identity state and session management.
• Notifications: supported email preferences for operational and billing-related events.

Settings controls how a user wants to receive supported notifications; it does not replace the Alerts module itself. Current real email integrations include critical incidents, Budget alerts and usage/billing notifications. Automated Reports or broad product/system email campaigns are not documented as active V2 delivery paths here.

The V2 manual documents Leave Workspace only when the action is safe and available. Delete Workspace is intentionally not exposed as a supported action because full transactional deletion is not part of the current safe V2 behavior.

These prices describe the Clyvel subscription. They do not include the money you spend directly with AI Providers.

Billing reflects the real subscription state. Owner/Admin users with the required permissions can start checkout, upgrade, downgrade or cancel through the existing Billing flow. The browser does not grant itself a plan after checkout; the signed Paddle webhook is the authority that synchronizes the subscription.

When the observability allowance is exhausted, Clyvel pauses new telemetry for that allowance. The customer's request to the configured AI provider continues; Clyvel does not cut provider traffic because an observability limit was reached.

1. 1

   Check whether the application is actually running

   No traffic means Clyvel has nothing to observe.

2. 2

   Check the Gateway URL

   The application must send AI traffic through Clyvel rather than directly to the Provider.

3. 3

   Check the Clyvel API Key

   An invalid or revoked key prevents the Gateway request from authenticating.

4. 4

   Check the Provider

   The Provider connection must exist and be valid for the organization.

• Requests became slow: compare latency by Provider/Model and open recent Requests before assuming the whole system is slow.
• Costs are zero: confirm real Requests and cost-capable Provider/Model data exist for the selected period.
• Budget Alert did not arrive: verify the Budget condition and the user's Budget email preference in Settings.
• Clyvel AI does not answer: check whether the Workspace has useful telemetry and retry the analysis.
• My plan did not update after checkout: Billing waits for the signed Paddle webhook; browser checkout success alone is not provisioning.

Autopilot applies configured routing policies to compatible gateway traffic. A policy can define a primary provider/model, optional fallback and cost routes, and a balance among cost, reliability and the standard mode. It does not automatically enable every model or provider: the selected routes must be supported and connected.

1. 1

   Select the scope

   Choose the organization or application and the environment that should use this policy.

2. 2

   Configure routes and safeguards

   Set the primary route and, if needed, fallback/cost routes; review retry limits, error statuses, health thresholds and budget threshold.

3. 3

   Enable and verify

   Enable the policy, run representative gateway traffic and examine recent Autopilot decisions and Requests before relying on it in production.