Onboarding Wizard

Getting Started

The wizard walks you through connecting a model, choosing how developers sign in, connecting an agent with a virtual key (outside Kubernetes), and, on Kubernetes, protecting your first agent. Along the way, live panels show your first governed requests, and the wizard ends on You're protected, with what the gateway governed since you started and a Set up more list of optional setup: MCP servers, starter policies, a spend cap, and GitHub. It shows only the steps that apply to how you use AIControls. Most teams finish in under 10 minutes.

Starting the wizard

Log in to your workspace at https://YOUR_ORG.aicontrols.dev. If this is your first login, the wizard launches automatically. To re-run it later, open the guided-tour picker (the Tour button) and select Restart setup on the Setup wizard card — re-running is always safe, since the wizard edits live settings rather than creating duplicates.

Where the wizard starts depends on where AIControls runs:

• Self-hosted on Kubernetes: the wizard opens on Usage, where you choose what to govern.
• Anywhere else, including SaaS: agents can't run in the cluster AIControls runs in, so there's no Usage step. The wizard opens on Model, governs AI coding agents, and issues virtual keys for your agents on the Agents step.

Every step is left-aligned in a column no wider than 760 pixels, and the progress bar stays one row on a phone. To leave the wizard early, select Skip setup in the header and confirm. You can rerun setup from the Tour menu.

The progress bar shows the steps ahead:

1

Usage

Kubernetes only

→

2

Model

A free model to start

→

3

Users

With AI coding agents

→

4

Agents

Outside Kubernetes: a virtual key

→

5

First agent

With agents in Kubernetes

→

6

Done

You're protected, and set up more

How will you use AIControls

The First agent step appears only in self-managed installations. Workload Trust isn't available on Nirmata-hosted workspaces. See Feature availability.

This step appears only when AIControls runs in your Kubernetes cluster. Select one or both choices; both are selected by default.

Choice	What the wizard adds
Governance for AI agents on user endpoints	The developer AI tools section in Model, and the Users step.
Governance for AI agents in Kubernetes	The First agent step, where you deploy, watch, and register an agent.

Below the choices, Already set up lists what the cluster already has, for example Cluster identity: verified (discovered) or Model provider: openrouter. A problem doesn't show here: the First agent step warns about it.

Select Continue to go to Model.

Connect a model

Agents call models through the gateway, so the gateway holds the key. An agent sends no provider key of its own, so the upstream you connect here must hold a credential: its own key, or managed auth, where AIControls signs in with the cloud credentials in its own environment.

Under Model for your agents, choose your organization's provider: Anthropic, OpenAI, Azure OpenAI, OpenRouter, AWS Bedrock, vLLM, or Other for any other provider. The chips name the provider, not the coding tool built on it. See vLLM and Other providers. If an upstream that holds a credential already exists, its own key or managed auth such as Google workload identity, the step offers it and preselects it. See An upstream that's already set up. Otherwise nothing is preselected, and Continue stays disabled until you choose a provider. To add more upstreams later, follow the Settings → Providers link below the choices.

When you don't govern agents in Kubernetes, which is always the case outside Kubernetes, the step has no Model for your agents section. It's about developer AI tools only, and opens on How do your developers access their AI tools?. Outside Kubernetes, the step starts on Developers use the organization's key, so it shows Organization model for your developers below the choices, with the same providers, and you connect a model before you continue. Developers bring their own sign-in needs no model, so Continue is enabled right away. Virtual keys on the Agents step need a model: when you choose Developers bring their own sign-in, select Connect a model on the Agents step to come back to this step.

AWS Bedrock connects Claude models on Bedrock. There's no key to paste: AIControls signs requests with the AWS credentials in its own environment, such as an IAM role for its service account. Enter the AWS Region where you enabled the Claude models and, optionally, an IAM role ARN for AIControls to assume, then select Save and test. The wizard saves an upstream named org-bedrock. For the other Bedrock settings, such as the inference profile, see Add a provider.

No key yet? Follow No key? Try free models → to Try AIControls with free models and a public MCP server.

Your organization's provider key

Select a provider, enter your organization's API key, and enter the model for the test call. The wizard suggests one for Anthropic and OpenAI. For Azure OpenAI, also enter the endpoint URL, and enter a deployment name as the model. The Azure key is optional: the gateway sends a key in Azure's api-key header, and with the key left blank it authenticates with managed identity configured on the AIControls proxy's environment (see Add a provider). Select Save and test. The wizard saves an upstream named org-<provider>, with the key when you entered one, and sends the test call. If org-azure already has a key for the same endpoint origin, a blank key doesn't switch it to managed identity: delete org-azure in Settings → Providers first.

OpenRouter

OpenRouter routes to models from many vendors with one key from your OpenRouter account. Paste the sk-or-v1-... key into OpenRouter API key, and keep or change the model for the test call. Optionally, select Test Connection to check the key and the model with OpenRouter. Select Save and test: the wizard saves an upstream named openrouter, with live model discovery, and sends the test call. The upstream routes any OpenRouter model ID your agent sends. See Add a provider.

tip

Keys are encrypted at rest. Agents and developers never see the underlying provider credential.

vLLM

vLLM connects a vLLM server you run. URL starts at http://localhost:8000; change it to your server's address. API Key is optional, because a local server needs no key. Enter the Model for the test call, a model your server serves, and select Save and test. The wizard saves a vLLM upstream named vllm, or vllm-2 and so on when that name is taken, the same upstream Settings → Providers → Add Upstream creates for vLLM, and sends the test call.

Other providers

Other opens the Choose a provider drawer, with the provider picker from Settings → Providers → Add Upstream: search, then the Providers and OpenAI-compatible vendors groups. The drawer leaves out the providers that have their own choice in the step, and ChatGPT OAuth and GitHub Copilot, which are sign-in options under How do your developers access their AI tools?.

1. Select a provider, for example Groq, Google Vertex, Google Vertex (Anthropic Claude), or Custom OpenAI-compatible.
2. Fill in its connection fields, the same as in Add Upstream:
   • URL is filled in and locked for a vendor with one host. For Custom OpenAI-compatible, enter your endpoint, such as https://llm.example.com.
   • The vendor panel shows where to get a key, the vendor's endpoints, and its models.
   • API Key is required for a hosted provider, including Custom OpenAI-compatible, and optional for a local server such as Ollama. Google Vertex and AWS Bedrock take no key: Vertex uses workload identity, and Bedrock takes an AWS Region and an IAM Role ARN.
   • Google Vertex (Anthropic Claude), Claude from Vertex AI Model Garden, takes no key either. Enter the Project ID where Claude is enabled and keep or change the Region, which starts on global. The read-only URL is built from them, and Model for the test call starts on claude-sonnet-4-5@20250929. See Add Claude on Google Vertex AI.
3. Keep or change the Model for the test call, and select Test call. The drawer saves the upstream Add Upstream creates for the provider, named after it (for example groq, or groq-2 when that name is taken), and sends a test call through the gateway.
4. When Your model answered appears, select Use this provider. It stays disabled until a test call passes. To pick another provider, select Change.

Back in the step, the Other choice shows the provider's name and logo, and a card shows the provider with Test call passed. Change on the card reopens the drawer on that provider. Select Continue to go on.

How agents get the model

When you govern agents in Kubernetes, a passing test call adds the model you chose, and its upstream, to the default Workload Blueprint's Access Binding, which is named default. There's nothing to select: the model you connect here is the agents' model. AIControls writes the grant as an audited binding edit, so agents you register against the default Blueprint can call the model without a separate grant, including agents already registered. An agent already in Enforce also gets the grant, because bindings are live. To remove the model or block it for one workload, edit the binding later. If the grant fails, the step says why, and Continue anyway moves on without it. Agents with a virtual key don't use the Blueprint. See Review and restore a binding change.

The test call

Save and test sends one short chat completion through the gateway, the way an agent's call goes: routing, policies, the upstream's own credential, and the audit log. A provider key check alone can pass while every agent call fails, for example when the upstream holds no key. The step is done only when Your model answered appears. The call is recorded in the audit log under your account. If a policy answers the test call instead of your model, for example with a confirmation or a denial, the test call fails with A policy answered the test call instead of the model, because it proves nothing about your provider. Check the policy on the Policies page, then test again.

Try a blocked call

Next to a passing test call, select Try a blocked call to see a policy stop a request. The gateway sends a prompt that carries a fake AWS access key with the model you tested. On a new installation, the content-safety-credentials starter policy blocks it before it reaches your provider, and the step shows Blocked by content-safety-credentials · logged to Activity, with a link to Security → Activity, where the blocked call is recorded. If no policy blocks it, for example because content-safety-credentials is turned off or in audit mode, the step says No policy blocked this call and links to Policies. The call then reaches your provider like any other test call. If a policy asks for confirmation instead of blocking, the step says A policy intercepted this call without blocking it, links to Activity, and the prompt doesn't reach your provider.

If the test call fails, the wizard scrolls the result into view and explains what to try. For a rejected key (HTTP 401), it says which provider refused and what to check. For an unknown model (HTTP 404), it suggests a model to try. For Google Vertex (Anthropic Claude), when Google answers that permission is denied (HTTP 403), it adds: Check that the service account AIControls runs as has the Vertex AI User role (roles/aiplatform.user) on project your project. A 403 from one of the gateway's own policies shows only the gateway's message. The gateway's own message stays below as secondary text, for example No API key configured on upstream .... A new upstream whose test call fails isn't kept, so it never shows as configured, in this step or under Already set up in Usage. A failure because the deployment reached its license limit keeps it, since the key itself works. A 402 from the provider, such as an account out of credit, is a failed test like any other. Fix the problem and select Save and test again. The Continue without a passing test link under the result saves the upstream anyway and moves on, but agents can't call models until a test call passes. A keyless upstream, such as the Passthrough upstream, goes back to having no key. A stored key can't be read back, so when you save a new key over an Anthropic, OpenAI, or OpenRouter upstream that already holds one, the wizard checks it with the provider first and keeps the stored key if the provider rejects it.

If the gateway answers that this deployment reached its license limit, for example the free tier's limit on an install with no license, the wizard says so and links to Settings → License. Agents' calls are blocked the same way. Load a trial or enterprise license there, then test again. The free tier counts every call through the gateway, including blocked calls and the test call.

An upstream that's already set up

Each upstream that already holds a credential, and that has a model for the test call, appears as a <name> (configured) chip, for example the openrouter upstream that make kind-quickstart creates from OPENROUTER_API_KEY. The credential is either the upstream's own key or managed auth, where AIControls signs in with the cloud credentials in its own environment. The step preselects the first configured upstream in the Settings → Providers list; no provider is preferred. Select another chip to use that upstream instead.

The model for the test call starts on the provider's test model, for example nvidia/nemotron-3.5-lightning:free for OpenRouter, claude-haiku-4-5 for Anthropic, and claude-sonnet-4-5@20250929 for Google Vertex (Anthropic Claude). As you type a model, the field suggests the models the upstream advertises.

The card for an upstream that holds its own key shows the provider, the upstream name, Key stored with a masked key, and the model for the test call. The wizard never shows the key itself. An upstream on a server that needs no key, such as a local Ollama, shows no key row.

The card for an upstream with managed auth has no key. It shows Authentication instead, with how the upstream signs in, and No API key needed:

Provider	Authentication	Also shown
Google Vertex (Anthropic Claude)	Google workload identity	Project ID and Region, read from the upstream's URL. A part the URL doesn't name, for example behind a proxy, shows —.
AWS Bedrock	AWS IAM role

1. Keep or change the model for the test call.
2. Select Test call to send the test call through the gateway. For an upstream with managed auth, the test call uses the upstream as it is and saves nothing to it.
3. When Your model answered appears, select Continue.

To use a new key on an upstream that holds one, select Replace key, enter it, and select Save and test. The wizard stores the key on the same upstream and keeps its other settings. For an Anthropic, OpenAI, or OpenRouter upstream at the provider's own URL, the wizard first checks the new key with the provider. If the provider rejects it, the stored key stays unchanged. An upstream with managed auth has no Replace key: change how it signs in under Settings → Providers. To use a different provider instead, select it under Model for your agents.

Developer AI tools

When you govern AI coding agents, the step adds a developer AI tools section below the agent model, and the wizard adds the Users step. Outside Kubernetes the wizard always governs them; on Kubernetes, clear Governance for AI agents on user endpoints in Usage to skip both. The two choices are separate: agents keep the agent model you chose above, and developers use the access you choose here.

Under How do your developers access their AI tools?, choose one of two cards:

Card	What developers use
Developers bring their own sign-in (preselected on Kubernetes)	Each developer signs in to their own tool, and no key is held centrally. Pick the tool in the list: Claude.ai subscription (Pro, Max, Team), ChatGPT subscription (Codex), Each developer's own OpenAI API key, or GitHub Copilot.
Developers use the organization's key (preselected outside Kubernetes)	The key the gateway holds, with a workspace access token each. No provider credentials on their machines. For Azure OpenAI, choose Azure OpenAI as the model.

The first card lists what bringing your own sign-in gives and gives up. For API-key and OAuth sign-ins, each developer is identified by a valid AIControls personal access token, so you get policy enforcement, the full audit log, team and user model access, per-user budgets, and approvals. GitHub Copilot can use the AIControls extension with a personal access token for those identity-based controls. Signing in with only a GitHub token does not apply team or user model access limits. You don't get model routing or an organization-managed key, because the gateway forwards each developer's own provider credential and holds none. Under the hood, the first card is Passthrough mode and the second is Proxy mode. See Providers.

When the agent model and the sign-in tool use the same provider, for example an Anthropic key for agents and a Claude.ai subscription for developers, the wizard selects Developers use the organization's key and says that one upstream serves agents and developers. To use each developer's own sign-in instead, choose another agent model, or set up Passthrough for that provider later on Settings → Providers.

Agents need an organization key: an agent's call to a sign-in upstream fails with no-upstream-key, so agents always use the agent model, and the wizard says so. See Prerequisites for which plans support each mode.

The wizard saves the sign-in choice when you leave the wizard. If that save fails, the wizard stays open and shows Failed to save setup progress. Please try again. Select Open dashboard or Skip setup again to retry.

When you govern agents in Kubernetes but want to set up only developer AI tools for now, select Continue without an agent model. Agents can't call models until you connect one.

Both sections link to Settings → Providers, where you add more upstreams later.

note

Policies, MCP governance, and audit logging work on both cards. Team and user model restrictions, per-user budgets, and approvals are also available with a valid AIControls personal access token when developers bring their own sign-in. Model routing and an organization-managed key require Developers use the organization's key.

Agents in Kubernetes: nothing to set up

The wizard has no step for agent access: the defaults apply, and you can change them in Settings after the wizard.

How agents are identified

Each agent calls the gateway with its projected Kubernetes ServiceAccount token. The gateway verifies the token against your cluster's OIDC issuer, then maps the call to the agent's workload. There's nothing to issue or rotate.

At startup, AIControls reads the issuer from the Kubernetes API, because the Helm chart sets identity.discoverClusterOIDCIssuer: true by default. Attribution maps each verified call to the Deployment that owns the Pod, which is how a new agent appears in Workloads. It needs the chart's workloadIdentity.podRead.enabled: true, also the default, which grants a cluster-wide get on Pods: AIControls can read any Pod's spec in any namespace.

The First agent step shows How agents are identified: Ready when the issuer verifies, or Needs attention with the problem. It sits in the side column as one line. It moves above the deploy command only when the check fails and no agent has appeared yet. Expand Set up cluster identity here (or Change the issuer or audience), enter the issuer and the audience your agents' projected tokens carry, and select Save & verify. The change applies without a restart. When AIControls can't read Pods, the step also warns that agents won't appear in Workloads. You can also set the issuer and audience later in Settings → SSO / OIDC → Agent tokens. To find the issuer, run kubectl get --raw /.well-known/openid-configuration | jq -r .issuer. See Agent identity.

Unregistered agents

AIControls finds AI agents that run in your Kubernetes cluster. Until you register one, the unregistered workload mode sets what the gateway does with its calls. A new installation starts in Enforce: the gateway blocks the calls and records them, and lists the workload for registration. An installation upgraded from a release without this setting starts in Audit, which allows and records the calls.

Change the mode in Settings → General → Default access policy → Unregistered workloads. For automated installs, preset the mode in your Helm values.

When an unregistered agent calls the gateway on Kubernetes, the Dashboard shows Blocked an unregistered agent under Enforce, or An unregistered agent is calling the gateway under Audit. Select Register it to open the registration wizard for that workload.

Users

This step appears when you govern AI coding agents: always outside Kubernetes, and on Kubernetes when Governance for AI agents on user endpoints is selected in Usage, the default. Without it, the wizard skips this step: the bootstrap administrator is enough.

Choose how developers authenticate their requests to AIControls. Start with access tokens today, and switch to SSO when your identity team is ready. Agents in Kubernetes don't sign in here: the gateway identifies them by their ServiceAccount.

Access token

Self-service, no IT involvement. The wizard generates a token for you right now. Developers copy it and add one environment variable to their AI tool.

• The token is generated immediately and shown once, so copy it before you continue
• Developers get their own tokens from Settings → Access Tokens
• Each token is scoped to one identity — audit entries are attributed per person

OIDC / SSO

Users sign in via Google, Okta, or Azure AD. Requires IT coordination to register AIControls as an OAuth app in your IdP.

• Groups and roles flow automatically, with no per-person token management
• IT admin must register the app and share Client ID + Secret with your platform team before this can complete
• Recommended: start with Access Tokens today and migrate to OIDC in Settings → Identity & Access when IT is ready

The Your access token heading shows the token with a one-line note that AIControls shows it only once. The Client setup instructions panel below the token is the same one developers see on their Access tokens tab. Choose the AI product (Claude, Codex, GitHub Copilot, or Azure OpenAI) and a setup method, such as settings.json or shell environment variables, and copy the snippet. Before you generate a token, the snippet shows a <your-pat-token> placeholder, so you can share the steps with your users. For the full per-tool details, including troubleshooting, see Claude Code, Cursor, OpenAI Codex, and GitHub Copilot.

Your first request

Below the sign-in choices, a live panel shows Waiting for your first request from your coding tool… while it checks for new requests every few seconds. Set up your coding tool and send one prompt. The panel then shows what the gateway recorded for the first one: the model, the input and output tokens, the cost, the identity (your email), and the decision. A blocked request shows the policy that blocked it, and a reply blocked by a response policy shows Reply blocked with that policy. Select See it in Security → Activity to open the request in the activity log. With Access token selected, the panel counts requests made with your access token; with OIDC / SSO, it counts requests you make after signing in with SSO. It counts only requests since this setup run started, and never the Model step's test call. Reloading the page keeps the run; Restart setup, a new browser tab or session, or 12 hours without finishing starts a new one. If the panel can't read activity, it says Live activity is unavailable right now and keeps trying; check Security → Activity instead. The panel never blocks Continue.

Agents

This step appears outside Kubernetes, including on SaaS. An agent there calls the gateway with a virtual key: a scoped, revocable stand-in for the upstream's credential, with an optional spend cap. The agent never sees the real key. The step is optional: select Continue to move on, and issue keys later.

1. Enter the agent's name, for example sre-bot, and optionally a monthly spend cap.
2. Check the upstream. The key borrows its credential, so you don't enter a provider key again. The upstream you connected in the Model step is preselected; when several upstreams hold a credential, choose one.
3. Select Issue key. Copy the key: it isn't shown again. The step shows a curl command that sends one request with the key, as a Bearer token, to the gateway's OpenAI-compatible endpoint, with the model you tested.
4. Run the command, or point your agent at the gateway with the key. A live panel shows Waiting for your first request from sre-bot…, then the model, tokens, cost, identity, and decision of the agent's first request, with a link to Security → Activity.

The step needs a model whose test call passed in the Model step. If there isn't one, for example when developer tools use their own sign-in and you didn't connect a model, or you selected Continue without a passing test, the step asks you to connect and test a model first: select Connect a model to go back to the Model step. With a tested model, you can also choose another upstream that holds a credential; the curl command then shows a <model> placeholder. Your coding tools don't need a virtual key: the live panel on the Users step shows their requests. For model allowlists, expiry, and more keys, follow the link to Settings → Agents → Virtual Keys; opening it finishes the wizard, and you can restart it from the Tour menu. See Virtual keys.

Protect your first agent

This step appears when you govern agents in Kubernetes. It hands off to the loop that protects an agent: deploy it, watch it appear, and register it.

In the side column, How agents are identified shows whether the gateway can verify agent tokens and lets you set the cluster's issuer and audience. See How agents are identified.

1. Deploy an agent. The step shows the kubectl apply command that deploys the sample FAQ agent from a checkout of the AIControls source. If you ran make kind-quickstart DEPLOY_AGENT=1, it's already running. For your own agent, expand Your own agent for the pod-spec essentials: a projected ServiceAccount token for the aicontrols audience and the gateway's address. The full sample manifest is in Deploy an agent that calls the gateway.
2. Watch it appear. Waiting for the agent's first call checks for discovered workloads every few seconds. Keep the page open: the agent appears within a minute of its first call, with the evidence, for example Called nvidia/nemotron-3.5-lightning:free through the gateway.
3. Register it. The found agent appears as a card with its discovery evidence, when it last called the gateway, and one line of status. Select Register it on the card to finish the wizard and open the registration wizard for that workload, with the default Blueprint preselected. A new registration starts in Learn first, so the agent keeps working while AIControls learns its access. This is separate from the unregistered agent mode. See Register a workload.

To move on before an agent appears, select Continue to open the finish screen, then Open dashboard. The Dashboard's Protect your first agent card tracks the rest: register, promote what the agent learned, switch to Enforce, and create a Blueprint.

The Your setup panel beside the steps shows what you configured: the model and its upstream, the unregistered agent mode, and how users sign in. Invite teammates by email from the same panel; each receives a welcome email.

You're protected

Every flow ends on You're protected, the Done step in the progress bar. It shows three numbers that refresh every 30 seconds while you watch. A number that can't be read shows Unavailable until a refresh succeeds.

• Requests governed since setup started: LLM requests the gateway handled since you opened the wizard, including test calls and blocked calls.
• Active policies: policies that are turned on.
• Identities seen since setup started: developers and agents that AIControls saw since you opened the wizard, through the gateway or through observer events from developer machines.

Below the numbers, a Set up more list shows optional setup that the wizard doesn't ask about step by step. Each item links to the page where you configure it, and selecting one finishes the wizard first. You can restart it from the Tour menu. The same list is on the Protect your first agent card on the Dashboard.

Item	Where it goes	What it does
Add an MCP server	Inventory → MCP Servers → Registration	Gives agents tools through the gateway. Every tool call is checked and recorded. See Connect an MCP server, or try a public server.
Review the starter policies	Security → Policies	Every workspace starts with an audit-first policy set. Switch policies on or off and choose Audit, Warn, Enforce, or Approval. See Policies.
Set a spend cap	Cost → Budgets	Blocks new LLM calls when an organization-wide monthly limit is hit. In-flight requests complete. See Cost governance.
Connect GitHub	Integrations → GitHub	Attributes pull requests to the AI work behind them. This item appears only where the deployment supports delivery attribution. See Configure GitHub attribution.
Issue a virtual key for an agent outside the cluster	Settings → Agents → Virtual Keys	Lets an agent that doesn't run in your Kubernetes cluster call the gateway. This item appears only on Kubernetes. Outside Kubernetes, the Agents step issues virtual keys. See Virtual keys.

Select Open dashboard to finish setup and open the Dashboard. Take a product tour finishes setup and starts the tour instead. Skip setup in the header still leaves the wizard directly, without this screen.

After the wizard

Governance is active. When you're ready to go further:

• Budgets — per-developer and team-wide spend limits
• Policies — enforce rules on tool calls and model usage
• Providers — add more providers or adjust your existing upstream
• MCP governance — control which MCP tools agents can call

Complete tenant setup

An administrator can complete tenant setup after account setup is finished and at least one valid, enabled AI upstream is configured. Disabled upstreams and malformed configuration do not qualify. An explicitly configured Passthrough upstream or cloud identity upstream can qualify without an organization API key. If completion reports an upstream configuration error, return to Model or Settings → Providers, correct the configuration, and retry Open dashboard.

This configuration check does not make a provider test call. Use Save and test or Test Connection to verify provider access. Leaving the wizard or starting a tour saves wizard progress separately; it does not establish tenant readiness.

Optional GitHub connection

When your administrator enables the managed GitHub integration, the finish screen offers Connect GitHub. This opens the Nirmata GitHub App installation page. Choose the account and repositories in GitHub, approve the installation, and return to AIControls. GitHub is optional for tenant setup and is required for GitHub productivity collection.

After connecting, open Settings → Effectiveness → Repositories to review collection scope and repository selection. If the connection succeeds but local setup is incomplete, use the card's retry action. If setup is unavailable, ask your operator to check the managed integration configuration. Your existing repository history is retained when disconnecting.