# Pointsman documentation

Pointsman is an open-source gateway between your applications and model providers. Use it to manage virtual keys, model access, spending controls, caching, guardrails and routing through a documented Chat Completions API.

## Get started

| Goal | Start here |
|---|---|
| Run a local stack and send a real request | [Quickstart](tutorial/README.md) |
| Explore without model-provider credentials or charges | [Mock-provider walkthrough](tutorial/mock-provider.md) |
| Tour the operator interface | [Dashboard tour](tutorial/dashboard.md) |
| Check your client integration | [API compatibility](reference/compatibility.md) |

A local walkthrough is an evaluation setup. Read [deployment](how-to/deploy.md) before exposing a gateway. This branch contains a performance candidate awaiting long-run requalification. The earlier qualified release scope and retained limitations are described in [release status](release-status.md).

## Understand the design

Start with the [architecture and request lifecycle](design/README.md), which connects the system diagram to the order of a real request. Explore each part of the design:

- [Authentication and identity](design/authentication.md)
- [Policy-based authorization: scopes, grants and inheritance](design/authorization.md)
- [Rate limiting, budgets and settlement](design/rate-limiting.md)
- [Guardrails](design/guardrails.md)
- [Exact and semantic caching](design/cache.md)
- [Routing and adaptive selection](design/adaptive-routing.md)
- [Policy service and durable learning](design/policy-service.md)

Each guide explains why the design exists, its state and trust boundaries, failure behavior, operational checks and tradeoffs. Adaptive and quality-based paths remain experimental and opt-in; weighted-random is the default.

## Configure your gateway

Connect [providers and models](how-to/add-a-provider-and-a-model.md), manage [provider credentials](how-to/add-a-second-provider-key.md), [issue virtual keys and budgets](how-to/issue-keys-and-set-budgets.md), or [build a team hierarchy](how-to/build-a-team-hierarchy.md).

Use [traffic weights](how-to/split-traffic-between-models.md), [guardrail rules](how-to/write-and-enforce-a-guardrail.md) and [cache tuning](how-to/tune-the-semantic-cache.md) to match your application's needs. Learn [where configuration lives](how-to/configure-pointsman.md) before changing it.

## Reference and operations

- [Application API](reference/client-api.md), [admin API](reference/admin-api.md) and [response headers](reference/response-headers.md).
- [Configuration keys](reference/configuration.md) and [operational limits](reference/operational-limits.md).
- [Request troubleshooting](how-to/diagnose-a-request.md), [operating notes](operating-notes.md), [security](security.md) and [known issues](limitations.md).
- [Latency and benchmark breakdown](performance.md).
- [Release scope and qualification](release-status.md).

The [GitHub repository](https://github.com/srinivas-reddy-gouru/pointsman) contains the project source. These public guides focus on using, understanding and operating the product.