Tutorial 23

Connect a CLI provider (Claude Code, Cursor, Codex)

Why this matters

When you use a CLI like Claude Code or Cursor, by default it talks directly to the AI provider — Anthropic, OpenAI, whoever — using whatever account those tools are configured with. Your prompts go straight to the model; nothing in between. That’s fine for personal exploration, but for team work, it means: no shared context files, no team-aware governance, no audit trail of what got asked, no per-team budgets, no fallback routing if the provider has a bad day.

Pointing your CLI tool at Auxot instead routes everything through your governance layer. Same CLI experience, same models — but with team context attached, audit logs, and the ability to swap providers without touching your CLI’s config.

Quick start

Auxot exposes an OpenAI-compatible API endpoint, so any CLI tool that supports custom OpenAI base URLs can use it.

1. Sign in — open Auxot in your browser and log in.
2. Generate an API key — click Settings → API Keys, then + Create. Copy the key (Tutorial 02 covers this in detail).
3. Find your Auxot endpoint — it’s https://[your-auxot-server]/api/openai/v1 (or /api/openai — both work; Auxot normalizes the /v1 prefix).
4. Open your CLI tool’s settings — Claude Code, Cursor, and Codex each have a settings file or env-var pattern for the OpenAI base URL and API key.
5. Paste the endpoint and key, save, restart the CLI — your CLI is now talking to Auxot.

Done? Run any command in your CLI that calls the AI. Open Auxot’s System Health → Recent Activity in your browser — you should see the request appear there.

The agent can do that?

The Admin Agent helps you decide which agent to wire up, why the connection isn’t working, and what your CLI traffic is actually doing once it’s flowing.

1. Have the Admin Agent design the CLI workflow you should set up

Open chat with the Admin Agent and ask:

I'm about to connect [Claude Code / Cursor / Codex] to Auxot. Looking at the agents I've already built, which one should the CLI route to by default — and what's the pattern of work I'd do in this CLI that the agent would handle well? Tell me what to type in my terminal as a first prompt that proves the routing works.

Why it’s non-obvious: Most users connect a CLI to Auxot and then default-route to a generic AI model — losing the entire reason to go through Auxot. The Admin Agent reads your fleet and picks the right agent for the kind of work you do at the terminal, then writes you a starter prompt. Your first CLI session uses your context files, not a blank slate.

2. Have the Admin Agent debug a CLI connection that won’t authenticate

When the CLI throws an auth error, paste it to the Admin Agent:

I'm trying to connect [CLI tool] to Auxot. I configured the base URL as [URL] and the API key. When I run a command, I get this error: [paste exact error]. What's likely wrong, and what should I check first?

Why it’s non-obvious: CLI auth failures are usually one of: wrong endpoint path (missing /api/openai/v1), expired or mistyped key, the CLI not actually using the new env var (still pinned to its old one), or a model name the CLI sends that Auxot doesn’t recognize. The Admin Agent reads the error and triages the most likely cause, so you debug in minutes instead of an hour.

3. Have the Admin Agent audit which CLI traffic is hitting which agent

Inverted-usage move. Once your CLI is connected and you’ve used it for a few days, ask:

Look at the last week of API requests to my Auxot account from [the CLI's API key name]. Which models or agents has the CLI been hitting most? Are there patterns I should turn into a workflow? Is there work currently going to a generic model that should be going to one of my custom agents?

Why it’s non-obvious: It’s easy to set up the CLI once and never look at what it’s actually doing. The Admin Agent reads your audit logs (Tutorial 12) for the CLI’s API key and surfaces patterns — work you’re doing repeatedly that should be promoted to a Skill (Tutorial 19) or a Workflow (Tutorial 13), or generic-model traffic that should be routed to a specialized agent.

Go deeper

Why Auxot exposes an OpenAI-compatible endpoint

Most modern AI CLI tools (Claude Code, Cursor, Codex, Aider, and others) speak OpenAI’s API format because that became the de facto standard for “talk to a chat model.” Auxot accepts requests in that format at /api/openai/v1/chat/completions (or /api/openai/chat/completions — both paths work, Auxot normalizes the /v1/ prefix). When a CLI tool sends a request there, Auxot:

1. Authenticates the API key.
2. Looks at the model field — if it’s a model identifier (like gpt-4 or claude-3-7-sonnet-latest), Auxot routes the request to the right cloud provider. If it’s an Auxot agent UUID, the request goes through that agent’s full setup (Description, context files, tool policies).
3. Streams the response back in OpenAI’s format.

The CLI tool doesn’t know it’s talking to Auxot. It thinks it’s talking to OpenAI.

CLI provider records in Auxot

In Settings → Providers, you can optionally create a CLI provider record (with cli_type of “claude” / “cursor” / “codex”). This is informational — it lets you label which CLI is connected, set an allowlist of models the CLI can use, and pick a default. It’s not required to make the connection work; it’s metadata for your own organization.

Troubleshooting

• CLI can’t reach Auxot at all (connection refused). The CLI is configured with the wrong base URL. Check it’s /api/openai/v1 (or /api/openai), not /v1 alone or /api/v1.
• 401 Unauthorized on every request. API key is wrong, expired, or you’re sending it in the wrong header. Most CLIs expect Authorization: Bearer [key] — Auxot accepts that.
• 400 Model not found or similar. The CLI is sending a model name Auxot doesn’t recognize. Either change the CLI’s configured model to one Auxot has connected (see Settings → Providers) or use an Auxot agent UUID.
• Requests succeed but the responses feel generic. The CLI is hitting Auxot’s auto-routing to a generic model, not one of your custom agents. Configure the CLI’s model parameter to an agent’s UUID to route through your Description + context files.

Variations & edge cases

• Personal vs. Team API Key. Use a Personal Key (Tutorial 02) for your own CLI usage. Use a Team Key (Tutorial 11) only if the CLI session represents the team’s work, not yours specifically. Personal keys are easier to revoke when you switch laptops or rotate credentials.
• Local CLI tools that bundle their own AI providers. Some CLI tools (older Cursor versions, certain Codex variants) hardcode the provider; check their docs for whether the OpenAI base URL is configurable. If not, you can’t point them at Auxot.
• Streaming vs non-streaming. Auxot supports both. Most CLI tools default to streaming for a smoother typing experience.
• Free tier: CLI provider connections work the same as on paid tiers. Same OpenAI-compatible endpoint, same auth flow.
• Audit log visibility. Every CLI request appears in Audit Logs (Tutorial 12) tagged with the API key that made it. Useful for figuring out what your CLI session is actually doing.

Walkthrough

Step 1: Generate an Auxot API key

Click Settings → API Keys, then + Create. Name the key after the tool that’ll use it — “Claude Code on my work laptop” or “Cursor on my dev machine.” Copy the full key (it starts with user. for personal, team. for team) — you’ll only see it once.

If you’ve never generated an API key before, work through Tutorial 02 first. It covers naming, copying, and saving the key safely.

Step 2: Find your Auxot endpoint

Your endpoint is your Auxot server URL plus /api/openai/v1. For self-hosted Auxot, that’d be something like https://auxot.your-company.com/api/openai/v1. For Auxot Cloud, it’d be https://auxot.com/api/openai/v1 (or whichever cloud URL applies to your account).

The /v1 is OpenAI-compatible API versioning. Auxot also accepts requests at /api/openai (no /v1) — they go to the same place.

Step 3: Configure your CLI tool

The exact location of the OpenAI base URL setting differs per CLI. Common ones:

• Claude Code — set ANTHROPIC_BASE_URL (or whichever env var Claude Code uses for custom endpoints) to your Auxot endpoint, and ANTHROPIC_API_KEY to your Auxot key. Claude Code expects an Anthropic-format endpoint by default; Auxot’s OpenAI-compatible endpoint may or may not work depending on Claude Code’s version. Check Claude Code’s docs for “custom endpoint” support.
• Cursor — open Cursor’s settings, find AI / Models / Custom OpenAI Base URL. Paste the Auxot endpoint there and the Auxot API key in the API key field.
• OpenAI Codex CLI — set OPENAI_BASE_URL (or OPENAI_API_BASE depending on version) and OPENAI_API_KEY to your Auxot endpoint and key respectively.

Tip: Restart the CLI after changing config. Most CLIs cache the env vars at startup; they won’t pick up the new endpoint until the next launch.

Step 4: Pick which model or agent the CLI talks to

Most CLI tools let you choose a default model in their settings. Two options:

• A connected AI model — type the model name (like gpt-4-turbo or claude-3-5-sonnet) that you’ve connected to Auxot via Settings → Providers. Auxot routes the request through that provider.
• An Auxot agent — type the agent’s UUID as the model identifier. Auxot recognizes UUIDs and routes the request through the agent’s full setup (Description, context files, tool policies). This is where the value lives — your CLI now uses your custom agent instead of a generic model.

To find an agent’s UUID: Settings → Agents → click the agent → copy the UUID from the agent’s detail page URL or the copy-id button.

Step 5: Test it

Run any command in your CLI that calls the AI. Then open System Health → Recent Activity in your Auxot browser tab — you should see the request appear within a second or two, tagged with your API key’s name.

If nothing shows up: double-check the endpoint, the API key, and that the CLI actually restarted with the new config. (See Troubleshooting in Go deeper above.)

Step 6: (Optional) Register a CLI provider record in Auxot

Open Settings → Providers, click + Create Provider. Pick provider type CLI, then pick the CLI type (Claude Code, Cursor, or Codex). Name it after the user or workstation. This step is purely organizational — it doesn’t affect routing. It’s so when you look at your providers list later you can see “ah, that’s Claude Code on Sarah’s laptop.” Skip it if you don’t care about labels.

What’s next

• → Tutorial 02: Generate your first API key — if you skipped here, this is where the API key story starts.
• → Tutorial 11: Create a shared Team API Key — for CLI sessions that represent team work rather than your individual work.
• → Tutorial 12: View your audit logs — see exactly what your CLI is doing, request by request.

Reference

• Pages in Auxot: Settings → API Keys, Settings → Providers
• Endpoint: [your-auxot-server]/api/openai/v1 (or /api/openai — same place)
• OpenAI-compatible: yes — any CLI that supports custom OpenAI base URLs works
• Auth: Authorization: Bearer [key]
• Supported CLIs: Claude Code, Cursor, OpenAI Codex CLI (and any other OpenAI-compatible CLI)
• model field: can be a connected provider model name OR an Auxot agent UUID (for full agent routing)
• See also: Tutorial 02: Generate your first API key, Tutorial 11: Create a shared Team API Key, Tutorial 12: View your audit logs