> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Personal IDE keys: your AI tools, governed by your company
> Install LangWatch, run `langwatch login`, and use Claude Code / Cursor / Codex with org-attributed spend, a personal budget, and no per-tool configuration.
A personal IDE key is a single virtual key that Claude Code, Codex,
Cursor, Gemini CLI, and opencode all share. Your IT admin issues it through
LangWatch Governance, and it is bound to your identity and governed by
your team's policy.
This page is the **end-user** flow. If you're an admin setting it up
for your organization, see [Admin setup](/docs/ai-gateway/governance/admin-setup).
On SaaS, governance rollout is managed per organization: if you don't see these surfaces, or `langwatch login --device` is refused with a governance error, ask your admin.
## Why this exists
Your IT or platform team gives you Claude Code, Cursor, Codex, and
Gemini CLI, and asks for four things in return:
* **Per-user spend attribution** so finance can stop staring at unnamed Anthropic invoices
* **A personal budget** for the period your admin configures (monthly or weekly) so a runaway recursive prompt at 3 AM Saturday doesn't burn \$10k overnight
* **Audit trail** for SOC 2 / ISO 27001 / HIPAA / EU AI Act
* **Zero-config provider setup**: your IT team wired up Anthropic + OpenAI + Gemini at the org level, and you inherit them
LangWatch covers all four. After one `langwatch login`, the wrappers
route every request through the gateway, attributed to you and
governed by your company's policy.
## What you get
* One CLI command to sign in: `langwatch login`
* Wrappers that let you keep using the tools you already know:
`langwatch claude`, `langwatch codex`, `langwatch cursor`,
`langwatch gemini`
* A personal dashboard at [https://app.langwatch.ai/me](https://app.langwatch.ai/me)
showing your spending, requests, most-used models, and recent
activity
* Budget enforcement at the gateway: if you go over that cap, the
request fails fast with an actionable error
## Setup
### 1. Install the CLI
The `langwatch` CLI ships as an npm package. Today the supported install path is npm / npx:
```bash npm (global install) theme={null}
npm install -g langwatch
```
```bash npx (no install) theme={null}
# Run any command without globally installing
npx langwatch --version
npx langwatch login --device
```
The single-binary installers (`curl ... | sh`, Homebrew tap, PowerShell `iex`) are on the roadmap but not yet published. Until then, `npm install -g langwatch` is the canonical path on every OS where Node.js is available.
Verify:
```bash theme={null}
$ langwatch --version
0.26.0
```
### 2. Sign in via your company SSO
The CLI uses RFC 8628 device-flow OAuth. Pass `--device` to go straight to the SSO path. The bare `langwatch login` first asks how you want to use LangWatch, and picking "AI tools / agentic flows" reaches the same flow:
```bash theme={null}
$ langwatch login --device
🔐 LangWatch login
Control plane: https://app.langwatch.ai
Mode: device session (will write ~/.langwatch/config.json)
Opening: https://app.langwatch.ai/cli/auth?user_code=ABCD-EFGH
If your browser doesn't open, paste the URL above and enter code: ABCD-EFGH
⠋ Waiting for you to approve in the browser
```
Your browser opens to a LangWatch page that asks for your work email,
then redirects to your company's IdP (Okta, Azure AD, Auth0,
whatever). After you complete SSO + MFA, control returns to the
CLI with your inherited providers + budget already populated:
```text theme={null}
✓ Logged in as jane@your-company.com @ your-company
Your AI tools (run any of these):
$ langwatch claude # Claude Code
$ langwatch codex # Codex
$ langwatch cursor # Cursor
$ langwatch gemini # Gemini CLI
Model providers you can issue a virtual key for:
• anthropic
• openai
• gemini
Monthly budget: $500 | Used: $0.00
Or open the app in your browser:
$ langwatch open
Dashboard: https://app.langwatch.ai
```
Behind the scenes:
1. The CLI ran an [RFC 8628 device-flow OAuth](https://datatracker.ietf.org/doc/html/rfc8628) handshake against the LangWatch control plane.
2. Your browser ran the SSO flow your IT admin configured (Okta, Google Workspace, Azure AD, or password-only).
3. LangWatch minted a **personal virtual key** scoped to your user identity, signed by the gateway, bound to your monthly budget, and audit-trailed per request.
4. The CLI fetched your AI tools, inheritable providers, and budget from `/api/auth/cli/bootstrap` and rendered the ceremony you see above.
Tokens persisted at `~/.langwatch/config.json` (mode 0600).
You did **not** pick a model provider during setup. Your
admin already wired up Anthropic, OpenAI, Gemini, etc. at the
organization level. You just inherit them.
### 3. Use your tools normally
```bash theme={null}
$ langwatch claude
▲ Claude Code v2.1.0
✓ Connected via LangWatch (jane@your-company.com)
> help me refactor this auth middleware
```
Same Claude Code experience as before: flags, terminal handling, and
exit codes are all identical because `langwatch claude` `exec`'s
the underlying tool with the right env vars pre-injected.
The same pattern works for Codex, Cursor, Gemini CLI, and opencode:
```bash theme={null}
$ langwatch codex "fix the failing tests"
$ langwatch cursor # opens Cursor with gateway env
$ langwatch gemini "explain this stack trace"
$ langwatch opencode # opens opencode with gateway env
```
**Verified end-to-end in CI.** `langwatch login` + each of the five wrappers above (`claude`, `codex`, `cursor`, `gemini`, `opencode`) is exercised in the `governance-wrapper.e2e.test.ts` Node-only e2e suite (fake control-plane, fake gateway, mocked tool binaries) covering login config write, env-var injection, routing with bearer-VK, budget pre-flight (402/200/5xx), and exit-code propagation. 16 scenarios, 3-second runtime, runs on every PR. See [CLI debug → e2e coverage](/docs/ai-governance/cli-debug#cli-wrapper-e2e-coverage) for the assertion shape per tool.
### 4. Or, set it up without the wrapper
If typing `langwatch` every time is friction, `langwatch instrument ` writes the telemetry wiring for a tool and exits. A plain
`claude` or `codex` run then reports to LangWatch on its own:
```bash theme={null}
langwatch instrument claude
langwatch instrument codex
```
Claude Code takes an `env` block in `~/.claude/settings.json`, Codex
takes an `[otel]` block in `~/.codex/config.toml`, and the other tools
take a scoped function in your shell start file, which applies to that
tool and to nothing else. Add `--project ` to send the
telemetry to a team project, or `--key ` on a machine that
never logs in. See the [Claude Code integration
guide](/docs/integration/tools/integrations/claude-code).
The model calls keep going wherever the tool itself points them. To
route them through the gateway, start the tool with the wrapper.
## Your dashboard
Open `https://app.langwatch.ai/me` (or run `langwatch me`) to see
your usage:
* Spent vs. budget for the month
* Total requests, week-over-week
* Most-used model
* Spending breakdown by tool (Claude Code, Cursor, Codex)
* Recent activity (last 10 requests with cost + summary)
Your dashboard shows **only** your usage. To switch to a team's
view, use the workspace switcher in the top-left of the navbar.
## Hitting your budget
If you cross 80% of your monthly cap, the dashboard shows a yellow
warning banner. If you hit 100%, your next request fails with a
clear message:
```bash theme={null}
$ langwatch claude
⚠ Budget limit reached
You've used $500.00 of your $500.00 monthly budget.
To continue, ask your team admin to raise your limit.
Admin: platform-team@your-company.com
Need urgent access? Request an increase:
https://app.langwatch.ai/me/budget/request?scope=user&scope_id=user_2a1f&limit_usd=500.00&spent_usd=500.00
```
The server builds that link and returns it with the budget response. It
carries the blocked scope, the scope id, the limit and the spend as query
parameters, so the budget-request page opens with the context already
filled in and the admin can change your limit at once. On an older server
that returns no link, the CLI prints the plain
`https://app.langwatch.ai/me/budget/request` page instead, and the
dashboard reads the same context from your signed-in session. No token
re-issuance is required.
Budgets reset on the period your admin configured (monthly or
weekly).
## Security
* Your access token is short-lived (\~1h) and refreshed automatically.
* Your refresh token is stored at `~/.langwatch/config.json` with
mode 0600. We're working on OS keyring integration; for now,
protect that file as you would any local secret.
* Revoking your account at the LangWatch admin console invalidates
both tokens immediately. Your CLI begins failing within 60s.
* The CLI never sees a raw provider key. The gateway holds the
upstream credentials.
## Sign out
```bash theme={null}
$ langwatch logout
Logged out. Credentials cleared.
```
This clears `~/.langwatch/config.json` locally **and** revokes your
refresh token at the server, so leaked-state can't be reused. The
`-device` suffix disambiguates from the older `langwatch login` API-
key flow (which has its own logout via clearing the env var or
re-running `langwatch login`).
## What's behind the scenes
If you're curious about the platform side:
* [Compliance architecture](/docs/ai-gateway/governance/compliance-architecture): how the unified observability substrate underwrites SOC 2 / ISO 27001 / EU AI Act / GDPR / HIPAA-most-uses
* [Governance data retention](/docs/ai-gateway/governance/retention): how long the activity recorded from your key is kept
* [OCSF / SIEM export](/docs/ai-gateway/governance/ocsf-export): your security team's SIEM (Splunk, Datadog, Sentinel) pulls these events on a cron via the OCSF v1.1 read API
* [Ingestion sources](/docs/ai-governance/ingestion-sources/index): what other AI platforms feed into the same governance dashboard
## For admins setting this up
* [Admin setup](/docs/ai-gateway/governance/admin-setup): SSO, gateway provider keys, org-wide monthly budget ceiling
* [Verify it yourself](/docs/ai-gateway/governance/admin-setup#verify-it-yourself): mint a personal virtual key, send a real completion, watch the spend land on `/me/usage`
* [Control plane](/docs/ai-gateway/governance/control-plane): the full Tier 1-5 governance dashboard architecture