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 → Upstreams → 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 Configuring Upstreams →
Step 3 — Generate a Personal Access Token
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.
In passthrough mode, developers configure two credentials in their tool: the workspace token (for identity) and their own provider API key (for the upstream call).
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