Onboarding Wizard
The wizard walks you through five steps — AI provider, identity & access, starter policies, spend cap, and a summary. The required settings come first; policies and spend cap are optional and can be revisited anytime. 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 click Restart the setup wizard — re-running is always safe, since the wizard edits live settings rather than creating duplicates.
The wizard shows you what's ahead before asking any questions:
Step 1 — AI providers
The wizard asks two questions to determine the right deployment mode for your team. It opens pre-set to the most common quick-start path — Claude via a claude.ai subscription, which uses Passthrough mode — so you can continue immediately if that matches your setup.
What AI product are you governing? — Select from Claude Code / Anthropic, OpenAI, Azure OpenAI, or GitHub Copilot.
How do your developers access it? — For Claude, choose between subscription-based (Claude Pro, Max, Team) or API plan. For OpenAI, between ChatGPT Plus/Pro, individual API key, or org-managed key.
Based on your answers, the wizard derives and highlights the appropriate mode:
| Mode | Who holds the API key | Developer experience |
|---|---|---|
| Proxy | AIControls workspace | Developers authenticate with a workspace access token — no provider credentials on their machines. |
| Passthrough | Each developer | Developers use their own credentials alongside a workspace token for identity. |
Budgets, policies, MCP governance, and audit logging work identically in both modes. The only difference is where upstream credentials live.
Proxy mode — enter your API key
If the wizard recommends (or you select) Proxy mode, it shows a form to enter your organization's LLM API key. You can test the key before saving — the wizard validates it against the provider and reports any permission or quota issues immediately.
Keys are encrypted at rest. Developers receive scoped access tokens and never see the underlying provider credential.
Passthrough mode — no credentials needed
If the wizard recommends Passthrough mode (for example, Claude Pro/Max subscriptions or Codex OAuth), no API key entry is required.
Passthrough is supported for Anthropic (Claude Code) and OpenAI (Codex). See Prerequisites for details on which plans support each mode.
Step 2 — Identity & Access
This step has two tabs — one for the people using AI tools, one for autonomous agents.
Users tab
Choose how developers will authenticate their requests to AIControls:
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.
- Token is generated immediately and shown once — copy it before proceeding
- Developers get their own tokens from Settings → Access Tokens
- Each token is scoped to one identity — audit entries are attributed per person
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 — 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
After the wizard generates your token, it shows a configuration snippet tailored to your AI tool and mode — copy it and follow the inline instructions. For the full per-tool details (including troubleshooting), see Claude Code, Cursor, OpenAI Codex, and GitHub Copilot.
Agents tab
Autonomous agents (CI bots, ops agents, background workers) get their own identity options:
Scoped, revocable stand-ins for your real API key — works anywhere an agent runs.
- Issue an agent's first key directly in the wizard: enter an agent name and an optional monthly spend cap
- The key is shown once — the agent uses it in place of the real provider key
- Add model allowlists, expiry, and more keys later from Settings → Identity & Access → Agents
Agents running in Kubernetes authenticate with projected ServiceAccount tokens — no secrets to issue, distribute, or rotate.
- Enter your cluster's OIDC issuer and an audience, then Save & verify — applied live, no restart
- The wizard includes issuer lookup instructions for EKS, AKS, and kind/minikube, plus a copyable pod-spec snippet
- Agent identity resolves to
system:serviceaccount:<namespace>:<name>automatically
Step 3 — Starter policies (optional)
Every workspace starts with a small audit-first policy set already active: an audit-everything baseline plus detections for secret reads, shell injection, privilege escalation, malicious file writes, sensitive file access, and command-and-control traffic — all in Audit mode, so nothing is blocked while you observe. The one exception is PII scanning in prompts, which enforces from day one.
This step shows the full active set so you can customize it:
- Switch any policy on or off; mode select flips it between Audit, Warn, Enforce, and Approval — changes apply immediately.
- Select multiple policies with the checkboxes, then set the mode or enable/disable them all at once from the bulk action bar.
- Preview opens any policy's full definition, read-only. Every policy can be edited or cloned later on the Policies page.
- Recommended policies carry a green tag; disabled ones sort to the bottom.
The Built-in Library on the Policies page has 35+ more ready-made policies — OWASP MCP Top 10 coverage, model access controls, data residency, and approval gates. See Policies for how modes and matching work.
Step 4 — Set spend cap (optional)
Set an org-wide monthly spend cap. When the cap is hit, new LLM calls are blocked with a clear error — in-flight requests complete normally.
The wizard includes a spend calculator: enter your approximate number of AI users and usage intensity (light / moderate / heavy), and it suggests a monthly cap with a 20% buffer. You can accept the suggestion or enter your own value.
You'll receive a Slack or email alert when spend reaches 80% of the cap. Per-team sub-limits and model-downgrade fallback can be configured via policy after setup.
This step is skippable — you can set or change the cap later from Settings → Budgets.
Step 5 — Summary
The final screen shows the configuration you chose — mode and provider, monthly budget, auth method, and how many policies are active — plus a concrete next-action plan for your first day, week, and month. From here you can invite team members by email; they receive setup instructions for the AI tool you configured.
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
- Upstreams — add more providers or adjust your existing upstream
- MCP governance — control which MCP tools agents can call