English | 简体中文

Turnstile

Governed AI access, spend, and operations through one self-hosted control plane.

🌐 Website · 📚 Docs · Changelog · 🛠️ Local setup · 🚀 Deployment · 🤝 Contributing

Turnstile is a self-hosted control plane for governed AI model access. It combines an Azure API Management gateway, token and cost telemetry, budgets, application access, model onboarding, release controls, and an operational web console.

For employee setup and administrator workflows, see the enterprise plugin guides (Simplified Chinese, with redacted screenshots).

Note

Turnstile v1.2 is the current public release. The project is evolving rapidly, so APIs, configuration, and deployment workflows may change as it matures. Review changes carefully before upgrading production deployments.

Important

The included infrastructure templates deploy only the Turnstile platform. They do not create an Azure AI Foundry project, deploy provider models, or preload customer connections and models. Operators connect their own Foundry or compatible provider resources after the platform is running.

_{Executive overview across usage, cost, reliability, and governance. This product screenshot is redacted for public use.}

Core capabilities

• Provider-neutral model, runtime, and gateway registry
• APIM-backed OpenAI and Anthropic-compatible endpoints
• Event Hub ingestion with PostgreSQL-backed usage and cost analytics
• Monthly budgets, model access policies, and application attribution
• Managed provider connections and model registry APIs
• APIM native backend pools for failover, balanced, or weighted delivery
• Versioned gateway releases, integrity checks, rollback, and protected releases
• Owner-only application subscription provisioning and key management
• Password-based and Microsoft Entra authentication
• AI FinOps with a FinOps Assistant and a directory-based Report Center grounded in stored telemetry (design)
• GitHub Copilot usage and governance integration (in active development)

Warning

The GitHub data source and GitHub Copilot integration are still under active development and are not production-ready. Enable them with care, and independently verify usage, cost, and governance data before relying on it for operational or financial decisions. If you only need FinOps for GitHub Copilot, see OctoFinance.

Model Intelligent Router is intentionally not part of this release. It may return as an optional extension in a future version.

What's New in v1.2

• Model pricing: provider catalog or manual prices, connection and model discounts, regional references, explicit short/long-context tiers, reviewed price synchronization, and historical request costs that retain the applicable price snapshot.
• Gateway management: separate Models, Connections, Self-hosted Gateways, and APIM workspaces; gateway registration, initialization, creation/bootstrap, diagnostics, and per-model serving scope.
• Publication and request diagnostics: explicit target Gateways, verified API Revisions, credential recovery, and invocation-attempt records that distinguish failures and unknown usage from confirmed provider telemetry.
• Model operations: inventory filters, dedicated editors, connection diagnostics, and an independently versioned model-availability command across Managed and Self-hosted Gateways.
• Atomic USD and Token budget execution: real-time admission reservations, USD and Token monthly limits, and automated settlement reconciliation.

An unavailable model switch means the deployment has not established the required Gateway coverage; it does not mean the model has been stopped. Do not bypass this check. The availability protocol requires compatible workers, migration 016, retained-Revision policies, primary Table access, self-hosted node enrollment, and verified admission/recovery before use.

Start with the documentation index, configuration reference, and availability installation requirements. Existing installations must review the matching migrations and infrastructure steps; an application ZIP upload is not a complete protocol upgrade.

Architecture

Turnstile separates the inference data plane from its management plane. Clients call Azure API Management, which applies authentication, budget, and model-access policy before selecting a provider route. A response-aware observer emits metadata-only usage events to Event Hubs; Azure Functions persist and reconcile them in PostgreSQL. The FastAPI application and React console manage registry, governance, and release state without sitting on the provider request path. See Architecture.

Repository layout

backend/          FastAPI entry points, HTTP routes, and web-only services
turnstile_core/   Shared domain, persistence, integrations, and worker services
frontend/         React, TypeScript, Vite web application
functions/        Azure Functions for telemetry and control-plane work
infra/            Bicep modules, APIM policies, and deployment templates
migrations/       PostgreSQL migrations; 001 is the clean-install schema
contracts/        OpenAPI and Event Hub contracts
scripts/          Build and deployment staging utilities
tests/            Unit, contract, API, infrastructure, and source tests
docs/             Maintainer and operator documentation

Prerequisites

• Python 3.11+
• uv
• Node.js 20.19.x or 22.12+ and npm
• PostgreSQL 16+
• Azure CLI with Bicep for Azure deployment
• An Azure subscription where you can create the platform resources
• Optional: a multi-tenant Microsoft Entra SPA registration
• Optional after deployment: an existing Azure AI Foundry project or another supported provider

Local setup

1. Create local configuration:

   cp .env.example .env
   cp frontend/.env.example frontend/.env.local

2. Set DATABASE_URL, generate independent values for CREDENTIAL_ENCRYPTION_KEY and MANAGEMENT_API_KEY, and configure authentication as described in Configuration.

3. Install dependencies:

   uv sync --frozen
   npm --prefix frontend ci

4. Apply the clean-install schema to an empty PostgreSQL 16+ database:

   uv run python -m backend.migrate

5. If you use password authentication, create the first Owner account. The command prompts for a password of at least 12 characters:

   uv run python -m backend.accounts owner@example.com --role owner

6. Start the API and frontend in separate terminals:

   uv run uvicorn backend.api:app --host 127.0.0.1 --port 8000
   npm --prefix frontend run dev -- --host localhost --port 5173

7. Open http://localhost:5173.

The Vite server proxies /api and /health to API_PROXY_TARGET, which defaults to http://127.0.0.1:8000.

Configuration

All runtime configuration is environment-based. Real .env files, deployment parameter files, keys, logs, packages, and generated output are ignored by Git.

• Root template: .env.example
• Frontend template: frontend/.env.example
• Full reference: Configuration

Never reuse secrets across environments. Keep CONTROL_PLANE_ENABLED, publication workers, and key-management features disabled until their Azure identities and least-privilege roles are deployed.

Development and testing

uv run ruff check backend turnstile_core scripts tests functions/telemetry/function_app.py functions/control_plane/function_app.py
uv run mypy backend turnstile_core scripts tests
uv run pytest -q
npm --prefix frontend run build
az bicep build --file infra/main.bicep
xmllint --noout infra/policies/foundry-finops-policy.xml
npx --yes @redocly/cli@2.38.0 lint contracts/openapi.yaml
git diff --check

In-memory repositories are used only for isolated unit tests. Integration and end-to-end claims must use a real Turnstile deployment and its configured Azure services. See Testing and E2E Validation.

Deployment

The Bicep templates create Turnstile platform resources such as PostgreSQL, Event Hubs, Storage, Key Vault, Application Insights, Web App, Functions, and APIM integration. The deployment does not create an Azure AI Foundry project or provider model deployment.

For Turnstile v1.2, choose the matching deployment path:

• Upgrading an existing installation: follow the upgrade guide. Keep the original state, database, ledger, APIM, identities and history; apply the required infrastructure changes as well as the application packages.
• Installing from zero: follow the fresh-install guide. Use a unique prefix and new state; a new StandardV2 APIM is the default. Provider models and credentials must already be available separately.

The quick start below is for a new installation. Do not replace an existing installation's state with a newly generated file.

1. Copy the public parameter example into an ignored file and set the subscription-independent values, including resource names, regions, publisher email, and bootstrapOwnerEmail:

mkdir -p .turnstile
cp infra/main.parameters.example.json .turnstile/main.parameters.json

2. Sign in to Azure, select a subscription, and run the repository deployment command:

az login
uv sync --frozen
uv run python -m scripts.deploy deploy \
   --subscription <subscription-id> \
   --parameters .turnstile/main.parameters.json

The command prompts for the initial Owner password, runs a subscription-scope what-if, and requires the exact confirmation deploy. It stops on any Delete change. It then provisions the platform and observer, builds immutable Linux x86-64 packages, deploys the API and Functions, enables workers only after the observer exists, and verifies health, Function indexing, and password Owner login. Generated secrets are stored only in .turnstile/deployments/<resource-group>.json with mode 0600; back up that ignored file in an approved secret store.

For automation, copy infra/owner.credentials.example.json to .turnstile/owner.credentials.json, set the same email as bootstrapOwnerEmail, choose the password, run chmod 600 on the file, and add --owner-credentials .turnstile/owner.credentials.json. Plaintext never enters Bicep or deployment state; only its scrypt hash is deployed.

After the Owner changes their password in User settings, supply the current password for rerun verification or update that private credentials file. Keep the original deployment state and bootstrap hash; reruns do not reset the existing account.

Use scripts.deploy plan for a preview without creating resources. See Deployment for prerequisites, reruns, and recovery.

Post-deployment model onboarding

A fresh Turnstile deployment automatically registers its platform-provisioned APIM instance during initial bootstrap, while starting with no customer provider connection, runtime, or business model.

1. Sign in with the password Owner created by the deployment command.
2. Verify the initial APIM instance in Model Management → APIM instances (or add additional APIM instances via Add APIM instance; same-subscription APIMs are authorized automatically, and Turnstile automatically grants the APIM's managed identity access to the platform's Ledger Table, Route Table, Event Hub, and Credential Key Vault).
3. In Model Management, add a connection to an existing Foundry project or supported provider, then choose Add Model for an existing provider deployment.
4. Optionally configure an APIM native backend pool for failover, balanced, or weighted routing.
5. Publish the gateway change and wait for candidate verification. For same-tenant Foundry managed identity, an authorization pause displays the exact APIM principal, Cognitive Services User role, and Foundry resource scope. Grant that role in Azure IAM, then resume verification in the dialog.
6. Run a small attributed invocation and confirm its telemetry record.

Turnstile never creates or modifies the customer Foundry project. The Azure user performing the IAM grant must already be authorized on that resource.

Security

• No prompt or completion content is persisted in telemetry.
• Credentials are encrypted before database storage.
• Azure-hosted components use managed identity where supported.
• APIM roles are scoped to the smallest practical resource and action set.
• Secret-bearing responses use Cache-Control: no-store and are never query-cached.
• Production cookies set the HttpOnly and Secure attributes and are role-bound.
• Local and generated configuration is excluded by .gitignore.

Review Security before deployment.

Known limitations

• PostgreSQL is required; there is no supported local or embedded production data store.
• APIM and Azure resource provisioning can take several minutes.
• For streamed responses where the APIM policy cannot capture a usage breakdown, token and cost records are initially incomplete. Reconciliation restores prompt and completion counts when gateway logs are available, but per-request cache usage remains unknown and resulting costs may remain lower bounds.
• Model Intelligent Router is not included in this release.

Troubleshooting

See Troubleshooting for startup, authentication, database, APIM, observer, and telemetry diagnostics. Deployment failures are resumable: correct the reported cause and rerun the same scripts.deploy deploy command with the original private state file.

Documentation

The docs/ tree mirrors upstream main. For this branch's configuration, complete migration chain, operations and acceptance evidence, also read the branch documentation index.

Guide	What it covers
Documentation index	Entry point for operators and maintainers
Architecture	Runtime boundaries, ownership, and data flow
Configuration	Environment variables, authentication, and feature gates
Organization Management	Persistent directory, department delegation, reviewed Entra synchronization, initialization and upgrade
Deployment	Azure provisioning, packaging, rollout, and verification
Testing	Local, contract, infrastructure, and end-to-end validation
Security	Threat boundaries, secret handling, and deployment controls
Troubleshooting	Database, authentication, APIM, telemetry, and startup checks

Contributing

Contributions should be focused, tested, and free of deployment secrets or customer data. Read CONTRIBUTING.md for the development workflow and SECURITY.md for responsible vulnerability reporting.

License

Turnstile is released under the MIT License. Third-party product names and trademarks shown in documentation or screenshots remain the property of their respective owners; their appearance does not imply endorsement.