Manual Setup
Full control over every configuration decision — provider, mode, upstream credentials, and per-tool setup. Follow the steps in order.
Have your provider credentials ready before starting. See Prerequisites for what each provider requires.
Step 1 — Choose your mode
The first decision shapes how developers authenticate and where API keys live:
| Mode | Who holds the API key | Developer experience | When to use |
|---|---|---|---|
| Proxy | AIControls workspace | Developers use a workspace-issued access token. No provider credentials on their machine. | Most teams. Centralized credential management, full cost attribution, no per-developer API accounts needed. |
| Passthrough | Each developer | Developers use their own provider API key alongside a workspace token for identity. | Teams with existing per-developer accounts, or regulated environments where centralizing credentials is restricted. |
Budgets, policies, MCP governance, and audit logging all work identically in both modes. The only difference is where upstream credentials live.
Step 2 — Create an upstream
Go to Settings → Providers → Add Upstream and select your provider.
In proxy mode, enter your organization's API key and any provider-specific fields. AIControls will use this key for all developer requests routed to this upstream.
In passthrough mode, create the upstream with provider and region settings but leave the API key empty. Developers supply their own credentials at request time.
For full field reference by provider, see Providers →
Step 3 — Generate a Personal Access Token
For PAT-backed access, each developer needs their own token. Go to Settings → Access Tokens → New token, give it a name that identifies the device or purpose (e.g. cursor-macbook-pro), and set an expiry.
Copy the token value immediately — it's only shown once.
Do not share tokens between developers. Every audit log entry is attributed to the token's owner — shared tokens make cost attribution and audit trails unreliable.
Fleet ingest tokens
To roll the observer out to managed devices with MDM, an admin can create one shared token of kind fleet_ingest (POST /api/v1/pats with "kind": "fleet_ingest") and use it as the observer's shipper token. A fleet ingest token can only report observer events (POST /api/v1/observer/events) and evaluate Cursor hook events (POST /api/v1/hook/eval). Every other request made with it gets 403, including LLM and MCP proxy traffic, the developer API, and the admin MCP server. Developers still use their own personal token in their AI tools.
In passthrough mode, developers forwarding provider API keys or OAuth/JWT credentials also send a valid workspace PAT in X-AIControls-Token for identity, unless they already present a supported AIControls credential. Requests without one are rejected with HTTP 401. GitHub Copilot and GitHub Models can instead use a GitHub token without the extra PAT header. GitHub-token-only access does not apply team or user model scopes or the Global Model Allowlist; use an AIControls PAT for those controls.
Step 4 — Configure your AI tool
Most tools route through the workspace proxy endpoint with your personal access token as the API key; GitHub Copilot instead uses a dedicated VS Code extension. The exact steps differ by tool:
| Tool | Configuration | Guide |
|---|---|---|
| Claude Code | Proxy endpoint https://YOUR_ORG.aicontrols.dev/proxy + access token | Setup guide → |
| Cursor | Proxy endpoint https://YOUR_ORG.aicontrols.dev/proxy/v1 + access token | Setup guide → |
| OpenAI Codex | Proxy endpoint https://YOUR_ORG.aicontrols.dev/proxy/v1 + access token | Setup guide → |
| GitHub Copilot | AIControls VS Code extension, connected via your GitHub account | Setup guide → |
Step 5 — Send a test request
Make any request in your configured AI tool — ask it to explain a file, write a function, anything. The request should complete normally; AIControls is transparent to the developer.
Step 6 — Verify in the Audit Log
In your workspace dashboard, go to Audit Log. Your request should appear within a few seconds, showing:
- Your identity — the developer name associated with the token you used
- The AI tool that made the request
- Model used, input and output token counts, estimated cost
- Policy decisions — which policies evaluated and whether any triggered
- Content safety findings, if any
- MCP tool calls made during the session, if applicable
If your request appears in the Audit Log, setup is complete. Your organization's policies, budgets, and content safety rules are enforced for all subsequent requests from this tool.
What's next
- Set up budgets — control spend per developer or team
- Write policies — enforce rules on tool calls and models
- MCP governance — govern tool calls from Claude Code and other MCP agents
- Optimization — reduce costs with caching and model routing