# QVeris Agent quick start

Continue your current task. Use valid existing credentials first. An authentication error is not permission to discard credentials or create a trial. Reading this document, installing a client, and Discover/Inspect do not create an account or grant execution authority.


If remote MCP is supported, prefer https://mcp.qveris.ai/mcp/readonly without credentials for Discover/Inspect only. When authorized execution is needed, obtain a trial key through the flow below and privately authenticate https://mcp.qveris.ai/mcp with that key. The read-only connection does not register a trial; the default endpoint does not issue anonymous identities and normally uses OAuth without a trial key. The client must support private Bearer configuration; otherwise use REST below.


## 1. Discover now without credentials

If no credentials are configured, run the request below in a separate uncredentialed client. Replace `weather` with a short keyword from the current task. Do not attach Authorization, cookies or saved session proofs.

```sh
curl -q --fail-with-body --silent --show-error 'https://qveris.ai/api/v1/search' \
  -H 'Content-Type: application/json' \
  -H 'X-Qveris-Access-Mode: public-readonly' \
  -d '{"query":"weather","limit":5,"view":"routing"}'
```

Inspect a returned tool with `POST https://qveris.ai/api/v1/tools/by-ids`, the same two headers, and `{"tool_ids":["ID_FROM_DISCOVER"],"view":"routing"}`. Public results carry no execution or price authority. An already selected tool does not need another Discover solely to change identity.

## 2. Start one trial when execution is needed and authorized

If your task and client policy authorize trial execution, use an installed, published CLI 0.13.2 or later:

```sh
QVERIS_BASE_URL=https://qveris.ai/api/v1 qveris auth trial --bounded
```

This command prepares and activates the existing bounded trial and privately persists its credentials. Preparation alone grants no credits. Check the command result; do not fall back to legacy registration or issue another identity after a failure. Use the returned allowance, expiry and eligibility, never a hardcoded credit grant. If CLI is unavailable, use the existing REST sequence below.

### REST alternative

Generate 32 cryptographically random bytes as unpadded base64url (43 characters). Save this possession proof in durable private storage **before networking**. With `Authorization: Bearer <saved proof>` and no cookies, query the existing `GET https://qveris.ai/api/v1/agent/trial/session` when recovering; for a new authorized operation send `POST https://qveris.ai/api/v1/agent/trial/prepare`, then `POST https://qveris.ai/api/v1/agent/trial/activate` with `{}`. Require a successful HTTP status and `status: "success"` envelope before consuming `data`. Securely save the one-time `api_key`; never print raw activation responses in Agent context or logs. The possession proof is separate from the API key. Activation is not automatically retried after an uncertain response: query the session using the same saved proof; an active session does not re-export its key.

## 3. Quote, execute, then return a real result

Recheck the selected tool's input contract and execution eligibility with the issued API key. Anonymous trials exclude the model gateway. Alternatively, possession-proof adapters use `POST https://qveris.ai/api/v1/agent/trial/quote` with `{"toolId":"ID_FROM_DISCOVER","parameters":{}}`; fill real parameters from Inspect. Review the exact quote and required cost authorization. Execute through `POST https://qveris.ai/api/v1/agent/trial/execute` with those inputs, the signed `quoteConfirmation` and a privately saved original UUID `operationId`.

The server enforces the original grant G, confirmed usage D, fresh quote q, and one unresolved execution: q≤G, D<G, D+q<2G. This is an admission envelope, not a final supplier-price cap or extra credits. Actual overrun remains debt. Unsupported pricing, insufficient budget or missing cost permission means stop and ask the human for the required action. Do not change the task, register again or rotate identity to bypass limits.

A lost call response stays lookup-only: recover the original operation with `GET https://qveris.ai/api/v1/agent/trial/executions/<operationId>` using the same proof. A timeout or 404 alone never authorizes replay. Report real results and known cost/settlement state, not installation or registration as task success.

## 4. Human continuation

Give the human the [claim page](/claim?mode=bounded). Transfer the proof only through a private channel, never a URL or prompt. The human verifies their new or existing account and confirms ownership; do not request passwords, email codes or primary login tokens in Agent context. Claim requires no unresolved operation, revokes trial credentials, grants no duplicate allowance, and applies formal credits to confirmed debt; remaining debt stays blocked until repaid. Continue the task using explicit formal credentials.

[Full authentication and recovery contract](/auth.md) · [Human client setup](/plugins#setup)