# A guided tour of the dashboard

[Documentation](../public-index.md) / Tutorials / Dashboard

The dashboard is where you connect models, give applications access, prepare
configuration changes and understand what happened to a request. You do not need
to learn the internal YAML names before using it. Start with the task you want to
complete, then open technical details when you need to automate or deploy it.

**All screenshots on this page show the built-in demo with sample data.** They are
screenshots of the real interface, not a connected production gateway. Model names,
counts, budgets and request records are illustrative. On your installation, available
pages and actions depend on your account's role, scope and enabled features.
The images were refreshed on 28 October 2026 from the dashboard source included in
the qualified candidate; capture provenance records
the routes and local draft states. They illustrate the UI, not endurance evidence.

## Open your console

After the [quickstart](README.md), open `http://localhost:3001` and sign in with your
operator account. This login is separate from the virtual key your application uses.
An administrator sees the broadest set of pages; tenant administrators and viewers
have more limited access. An empty page can mean there is no data in your scope yet.

The navigation follows four jobs:

| Area | Use it when you want to… |
|---|---|
| **Connect** | Add providers and models, issue API keys and send a first request. |
| **Control** | Set routing, budgets, guardrails and caching; prepare configuration changes. |
| **Observe** | Inspect requests, usage, failures and learning signals. |
| **Admin** | Organize people and scopes, manage login accounts and review audit history. |

Use **Find anything** to find a page and **Page guide** for help on the page you are
viewing. A demo banner means the displayed data is simulated. Do not use demo values
to assess your deployment's health or cost.

## Choose a setup recipe

![Get started showing the three setup recipes and credential boundaries](../assets/dashboard/start.jpg)

Open **Connect → Get started**, or the **Setup recipes** link in the compact guide.
Choose **First application request**, **Protect a shared budget** or **Consider
adaptive routing**. The first recipe follows **Connect → Authorize → Send → Inspect**
across pages. The highlighted step shows your location, not a completed installation.
Advanced navigation and search remain available. **Hide guide** dismisses it;
**Show setup guide** brings it back.

Only recipe and dismissal preferences persist, scoped to the signed-in account and
this gateway origin. Inventory is read again after reload. Request correlation stays
in memory until cleared, reload or account change; prompts, outputs and credentials
are not carried into the guide. Organization selection survives navigation in memory,
but clears on reload or sign-out. Changing accounts also clears query caches.

A root administrator configures the shared provider/model registry. A tenant
administrator manages authorized application access, not global registry settings.
A viewer without workspace membership asks an authorized administrator or workspace
member for a key; a workspace member's actions remain limited to that placement.
A forbidden action is an access boundary, not evidence of a broken installation.

The collapsible **What changes here, and how to verify it** help explains scope,
source, activation, refusal and readback on configuration and request pages. Its
lifecycle words describe separate facts:

| State | What it establishes |
|---|---|
| Local draft | An unsaved proposed value. Clicking a setup link establishes nothing. |
| Saved configuration | A successful authorized write. Read back the intended fields and revision. |
| Deployment required | A reviewed export still needs the documented deployment/restart procedure. |
| Observed effective value | A value reported by this instance, with only the provenance/time supplied. |
| Behavior verified | Evidence for a particular operation and conditions, not a whole-system health badge. |

![Configuration ownership help expanded in a synthetic sample preview](../assets/dashboard/configuration-state-guide.jpg)

## 1. Connect a provider, then enable its models

A provider is an upstream service with an adapter, endpoint and credential reference.
A model is a callable entry associated with that provider. Registering a provider
does not automatically make every model at that vendor available.

![Provider cards with adapter, credential reference, enabled state and connection-test controls](../assets/dashboard/providers.jpg)

In **Connect → Providers**, add or configure the provider. Supply the credential in
the gateway's environment or secret system and reference it by the supported name;
your application's virtual key is not that credential. A missing-environment badge
means the gateway cannot resolve the reference. The screenshot intentionally shows
this state in the demo.

Use the provider's **Test** action deliberately and inspect its result before relying on it.
An enabled switch is a configuration state, not proof of current health. Testing a
real provider can transmit data and incur spend; only perform it on the deployment
you intend to test. Navigation, draft review and onboarding never probe automatically.

Next open **Connect → Models**. Check the provider association, upstream model name,
capabilities, context limit and pricing before enabling a model. Incorrect metadata
can affect eligibility, context checks or cost estimates.

![Model inventory showing available models and their configured metadata](../assets/dashboard/models.jpg)

[Detailed provider and model setup](../how-to/add-a-provider-and-a-model.md) ·
[Provider credential rotation](../how-to/add-a-second-provider-key.md)

## 2. Give an application access and verify a request

**Connect → Get started** brings the first-request steps together: a provider, an
enabled model, a virtual key and a request that you can inspect.

![First-request recipe in the synthetic sample dashboard, with distinct credentials and setup directions](../assets/dashboard/setup-recipes.jpg)

1. Create the organization or workspace that will own the application's access.
2. Open **API keys** and issue a key for that scope. Set the model permissions and
   limits your application needs. Copy the full key when it is first shown.
3. Open **Playground**, choose an allowed model and send a small test prompt using
   the intended virtual key. On a connected deployment this is a real request and
   can incur provider charges.
4. Check response correlation, served provider/model and cache result. **Copy
   correlation** carries only identifiers, response status and observation time to
   inspection in this signed-in session. Open **Observe → Requests**, locate the
   numeric ledger ID, then use **Verify request** to read that exact authorized row.
   The guide never picks the latest row or converts a correlation ID into a ledger ID.

`X-Request-ID` correlates gateway logs and can be caller supplied. The separate
`X-Pointsman-Request-ID` is the gateway-minted UUID stored in the ledger's
`request_id`. Neither is its numeric `id`. The current console API has numeric
ledger detail lookup but no exact UUID search. Compare the UUID when both are
available; otherwise compare recorded time, scope and identifiers manually.
A different UUID is a mismatch even when the row records HTTP 200.

Recording may lag the response. **Record not yet available** can also mean a wrong
ID or a record outside this account's access; it is not successful accounting or
necessarily a failed request. Retry the exact ID manually. There is no onboarding
poll loop. A recorded 2xx proves only that recorded status; stream completion,
final billing settlement and answer quality require separate evidence. Missing
usage or cost stays unknown, including when inspecting a response with absent usage.

A login account lets a person use the console. A virtual key lets an application
call `/v1`. Creating one does not create the other.

[Key ownership and budgets](../how-to/issue-keys-and-set-budgets.md) ·
[Application API examples](../reference/client-api.md)

### Recipe: protect a shared budget

Choose **Protect a shared budget** in Get started. Review two application keys
under one organization, their explicit/inherited constraints and existing refusal
evidence. Administrators can follow the links to limits and scope previews; read-only
accounts get instructions for obtaining help. The guide issues no traffic.

**Example (sample amounts):** a key has $40 remaining, but its organization has only
$5. A request requiring a $6 reservation can be refused at the organization. The
reservation sets aside an estimated amount before dispatch; it does not promise an
accurate final provider invoice. These nested ceilings are not $45 to spend. Different
windows cannot be reduced to the smallest displayed number. Request, token, spend
and concurrency limits use different units and do different jobs.

**Example (shared gateway scope):** a gateway-wide limit of 100 requests per minute
is shared by organizations A and B, not 100 each. Organization/application/user/key
constraints are additional. Read usage, reservations, windows, remaining capacity
and binding references only where the server supplies them; absent fields stay
unknown. Never deliberately exhaust a real budget to complete a tutorial.

With the tree request path off, limit rules on mirrored fixed-chain scopes still
apply. A deeper-only rule does not join that default path because it was saved or
shown in a preview. Management grants are a separate concern.

![Hierarchy mode explanation and scope previews in a synthetic sample dashboard](../assets/dashboard/hierarchy-path-guide.jpg)

[Fixed-chain limits](../design/authentication.md) ·
[Hierarchy boundary](../design/authorization.md) ·
[Limits and keys](../how-to/issue-keys-and-set-budgets.md)

### Recipe: consider adaptive routing

Choose **Consider adaptive routing**. Name a workload and incumbent model, decide
what evidence would justify a change, inspect available cost/latency/quality coverage,
then ask the gateway administrator to review a group draft. Missing feedback is not
proof of good quality; a cost or latency observation does not judge an answer.

A concrete model names a fixed selection, though availability fallback can substitute.
Weighted-random uses configured weights. Bandit groups support balanced and cost
objectives; quality-guarded paths remain experimental. Follow the existing
[strategy reference](../routing-strategies.md) and
[outcome-learning guide](../how-to/turn-on-outcome-learning.md) for precise semantics.
Use the matching qualified gateway and dashboard build. Its provider/model cost-arm
views preserve objective and provenance; the combined source and package checks
are recorded in [launch status](../release-status.md). This recipe itself establishes
no routing-quality or savings result.

Review every member, condition, objective and fallback in the complete draft,
including choices outside the displayed page. Export, merge through the documented
deployment path, restart as required and read settings back before an explicit
application request. No evaluation runner, ranking algorithm, savings estimate or
quality-preservation guarantee is provided by this recipe. Keeping a static policy
can be the appropriate decision.

Jev is optional task classification, not answer-quality judgment or a prerequisite
for a first request. Its destination, tenant opt-in, consent, secret reference and
bounds must be reviewed before enabling real classification. Reading/searching,
reviewing or exporting its configuration makes no billable preview call.

## 3. Give several models one routing name

A routing group lets your application request a stable name, such as `support-chat`,
while you control which eligible models can serve it. The group's strategy decides
how to choose among them. The default strategy for a group without an explicit
strategy is weighted-random; an editor can start with a different explicit selection,
so review the exported value.

![Routing group draft showing priority selection, model membership and configuration review](../assets/dashboard/routing.jpg)

In **Control → Routing → Create group**:

1. Choose a new group name and describe what it is for.
2. Select enabled candidate models and a strategy. Set weights or priority order
   where that strategy uses them.
3. Review the generated configuration, including any conditions and fallback.
4. Download the group draft and merge it with your existing deployment configuration.
5. Deploy and restart the gateway, then confirm the group appears in **Current
   settings** and test it with an authorized virtual key.

**Creating a group here prepares a local draft. It does not save a live group or
restart the gateway.** Export before leaving the page; drafts are not saved.
The routing rehearsal helps explain selection and fallback, but does not prove
provider availability, answer quality or a particular production traffic split.

Jev also needs classifier configuration and tenant opt-in. Choosing `jev` in a group
alone does not enable classification or authorize prompt export.

[Traffic splitting](../how-to/split-traffic-between-models.md) ·
[Strategies](../routing-strategies.md) · [Jev setup](../how-to/jev-routing.md)

## 4. Understand Studio, Canvas and Delivery

These pages answer different questions. They complement the dedicated provider,
guardrail and budget editors.

| Page | Question it answers | What it changes |
|---|---|---|
| **Configuration studio** | What is this setting, what is its current value, and what could I change? | Local drafts and exported partial configuration. No management writes from Studio. |
| **Canvas** | How do the gateway's controls relate to this kind of request? | A probe and explanatory view. Guardrail tracing calls the gateway's dry-run endpoint; it makes no model-provider call. |
| **Routing** | Which models are candidates, which strategy chooses, and what is the fallback? | Rehearsals and group configuration drafts, requiring deployment. |
| **Configuration delivery** | What did we intend to deploy, how would we roll it back, and does the gateway report the expected values? | Exported review/forward/rollback files and a comparison against a fresh configuration read. No deployment or restart. |
| **Dedicated editors** | How do I maintain providers, models, keys, limits or supported guardrail settings? | Successful authorized saves can update runtime records. Read each action and its scope before saving. |

### Studio: understand the setting before changing it

![Configuration Studio showing configuration areas and a local draft workflow](../assets/dashboard/studio.jpg)

Choose an area such as **Cache**, then a setting. Studio presents its purpose,
current value, available guidance and activation method. Technical details retain
the exact configuration key for operators who need it.

![Exact-cache capacity selected in Studio, with an example local draft of 12000 entries](../assets/dashboard/studio-setting.jpg)

For example, **Exact-cache capacity** is easier to discover than
`pointsman.cache.l1.max-size`. They name the same setting. The example draft above
changes the entry budget to 12,000; it is not a recommended sizing value. The cache
also has a weight budget, so increasing entries alone does not guarantee a larger
resident cache. See [operational limits](../reference/operational-limits.md).

Gateway-wide request, token and spending ceilings show the **Loaded platform rules**
source and **Restart required**. Their values and windows come from the constructed
rules; changing a configuration target does not update these until restart. An absent loaded
rule shows Uncapped, including when a non-positive startup target created no rule.
Concurrency reads its mutable holder separately. These policy observations still need
appropriate request evidence before claiming behavior was verified.

Only supported scalar settings are editable here; complex or deployment-owned
values link to dedicated tools. Review the before/after values, units and activation
badge before export. Fetch the baseline again if the gateway has changed since you
started. Exported YAML is partial configuration, not a replacement for your full file.

### Canvas: explain a possible request path

![Canvas showing the conceptual stages of identity, permissions, capabilities, limits, guardrails, cache, routing, provider and learning](../assets/dashboard/canvas.jpg)

Select a stage to understand its role, or enter a model/group and sample prompt and
choose **Trace**. The view combines configuration-derived checks with a guardrail
dry run. Unknown results mean the page lacks the evidence to decide; they are not
successful checks.

The moving signals illustrate the conceptual flow. They are not live request traces
or timing measurements, and a cache hit or refusal can exit early. Use **Requests**
and **Investigate request** for evidence about an actual request. Tracing sends the
sample prompt to the gateway's guardrail dry-run endpoint, so use appropriate sample
content even though Canvas does not call a model provider.

### Delivery: carry a change through deployment

![Configuration delivery workspace preparing a local cache-capacity change for review](../assets/dashboard/delivery.jpg)

Export a reviewed package with baseline and proposed values, apply it through your
normal deployment process, then use Delivery's comparison against a fresh read.
Review the rollback values before a rollout. A matching comparison confirms the
reported settings; it does not replace readiness checks or a functional request.
The page requires a gateway administrator.

[Configuration workflow and examples](../how-to/configure-pointsman.md)

## 5. Find out what happened to a request

![Requests workspace showing sample request records and investigation controls](../assets/dashboard/requests.jpg)

Retain response correlation and locate the numeric ledger ID in **Observe → Requests**.
**Investigate request** reads that exact authorized ID; it does not search by
`X-Request-ID`. Compare the gateway UUID and recorded facts before associating a row
with your response. Look at the requested name and
served model separately, then check cache state, latency, usage and refusals.

**Overview** and **Analytics** show broader patterns. **Budget usage** focuses on
spending, while **Budget trust** and **Budget recovery** address whether counters
can be trusted after a failure. Recovery is an operator procedure requiring evidence;
it is not a button to reset spending so refused requests start working again.

Learning pages help inspect outcomes and policy state when those features are in use.
A preferred model in a learned policy does not by itself prove its answers are correct.

[Diagnose a request](../how-to/diagnose-a-request.md) ·
[Response headers](../reference/response-headers.md) ·
[Operational recovery](../operating-notes.md)

## Where to find the other tasks

| Task | Dashboard page | Read next |
|---|---|---|
| Discover model metadata or import supported configuration | Model catalog, Import | [Provider setup](../how-to/add-a-provider-and-a-model.md) |
| Control spending and rate limits | Budgets & limits, API keys | [Limits and budgets](../gateway-controls.md) |
| Check or enforce a content rule | Guardrails, Guardrail health | [Guardrail guide](../how-to/write-and-enforce-a-guardrail.md) |
| Understand answer reuse | Cache | [Cache tuning](../how-to/tune-the-semantic-cache.md) |
| Configure external task classification | Jev setup | [Jev guide](../how-to/jev-routing.md) |
| Inspect learning and exploration | Learning, Belief state, Convergence | [Outcome learning](../how-to/turn-on-outcome-learning.md) |
| Organize teams and their access | Organizations, Scope tree, Onboard people, Set up an organization | [Team hierarchy](../how-to/build-a-team-hierarchy.md) |
| Manage console identities and workspace access | Login accounts, Workspace members | [Authentication and tenancy](../design/authentication.md) |
| Check administrative changes | Audit history | [Admin API](../reference/admin-api.md) |

For scripted administration, use the [admin API](../reference/admin-api.md).
For an application's model calls, use the separate [client API](../reference/client-api.md).

See [Dashboard configuration ownership](../reference/dashboard-configuration.md) for conditional registry edits, Jev partial deployment drafts, operational observations and intentional API/deployment-only scope.

## Troubleshooting the first request

- Inventory loading, zero enabled registrations, an unavailable read and a forbidden
  operator view are distinct states. Existing registrations may belong to another
  application and never prove health.
- A key with no visible model needs an allowed-model or eligibility review, not an
  unrestricted administrator catalog substituted into the request picker.
- A validation failure keeps edits local. For a provider/model revision conflict,
  inspect the current row, accept the reviewed revision deliberately, then save
  again. Nothing automatically merges or retries; compare fresh readback afterwards.
- A stale effective baseline blocks trustworthy draft export or comparison. Reload
  deliberately and review the differences; an environment override can still win.
- An unmatched or absent record remains unverified. Do not treat a 2xx response
  header, empty usage or a successful save as settled billing or answer quality.