Setup guide

Run the installer and click through it. It is not code-signed, so Windows SmartScreen does not recognise the publisher the first time.

Windows

1. Double-click OrientimSetup-1.0.0.exe.
2. If SmartScreen appears, click More info, then Run anyway.
3. Click through the installer — no admin rights needed. It installs for your user only and adds a Desktop and Start Menu shortcut.
4. Leave Launch Orientim ticked. It opens your browser to the dashboard in about ten seconds.

Installs for your user only, so it never needs administrator rights. If your machine blocks installers entirely, email support@orientim.com and we'll send a portable build instead.

Once it starts, Orientim lives in your system tray and opens the dashboard in your browser at http://localhost:8501.

You can skip this step for now. Orientim is free until it has metered $20 of your own spend — not $20 you pay us, but $20 of the API traffic you were going to send anyway. There is no countdown and no card: the meter only moves when Orientim is actually working, so it can’t run out while you’re busy elsewhere. Everything is included in the trial — every agent, every cap, every alert.

When the meter reaches $20, Orientim stops forwarding requests. It does not keep working with the caps switched off, because that would leave you believing you were protected when you weren’t. Your agents, keys, limits and history all stay exactly where they are.

To carry on, paste the license key from your purchase email and click Activate — from the sidebar at any time, or from the screen that appears when the trial ends. Apart from releasing a machine with Deactivate this device, this is the only time the app talks to the network; after that it works offline.

An "agent" is just one of your provider API keys with a hard budget cap attached. Click Add agent, then fill in four things:

Your real key is stored locally and masked immediately (sk-v…1234). Repeat for as many keys/agents as you like — each has its own independent limit.

Using a provider that isn't in the list — DeepSeek, xAI, Mistral, a local vLLM? Choose Custom (OpenAI-compatible) and paste its base URL (for example https://api.deepseek.com/v1). Anything speaking the OpenAI API works, including providers that launch after this build.

There are two keys, and they do different jobs:

• Your real provider key (sk-…) — entered once in the dashboard. You never put this in your tools again.
• The local key (orientim-secure-key) — what your tools use instead. It stays on your machine.

Orientim checks the local key, then swaps in your real key only on the outbound call to the official API. We never receive it, and your tools never hold it:

your tool  → sends orientim-secure-key
Orientim   → checks limit, swaps in sk-…real
provider   ← official API responds, cost is metered on the way back

That swap is the whole idea: your tools hold a key that only works here, and only Orientim holds the one that can spend.

Each agent card shows a local address to send traffic to. You keep using your tool exactly as before — you just change where it points and use the local key orientim-secure-key in place of your real one.

Claude Code — step by step

Claude Code reads two environment variables. Copy them from the agent's card in Orientim, set them in your terminal, then run claude.

1. Copy the connection from the agent's card in Orientim:

2. Paste them in your terminal, then run Claude Code:

3. Done — Claude Code now runs through Orientim, and every call counts toward your cap. To make it permanent, add the two lines to your PowerShell profile ($PROFILE), or to ~/.bashrc if you use WSL or Git Bash.

Continue / Cline (VS Code)

In the model config, set the API base and key:

apiBase: http://127.0.0.1:8000/proxy/<agent-id>/v1
apiKey: orientim-secure-key

Aider

OPENAI_API_BASE=http://127.0.0.1:8000/proxy/<agent-id>/v1
OPENAI_API_KEY=orientim-secure-key
aider --model gpt-5.6-terra

Any OpenAI-compatible SDK

# python
client = OpenAI(
    base_url="http://127.0.0.1:8000/proxy/<agent-id>/v1",
    api_key="orientim-secure-key",
)

Agent frameworks

Set it in the environment, not on one client. A framework that fans out — a CrewAI crew, an AutoGen group chat, a LangChain agent with tools — builds its own clients for sub-agents, memory and default embedders. Those inherit environment variables. They do not inherit a base_url you passed to a different client object: that child talks straight to the provider and past your cap. Do this once, before anything else is constructed:

# put this at the top, before you build anything
import os
os.environ["OPENAI_BASE_URL"] = "http://127.0.0.1:8000/proxy/<agent-id>/v1"
os.environ["OPENAI_API_BASE"] = "http://127.0.0.1:8000/proxy/<agent-id>/v1"
os.environ["OPENAI_API_KEY"]  = "orientim-secure-key"

# Anthropic-native SDKs use these instead (note: no /v1)
os.environ["ANTHROPIC_BASE_URL"] = "http://127.0.0.1:8000/proxy/<agent-id>"
os.environ["ANTHROPIC_API_BASE"] = "http://127.0.0.1:8000/proxy/<agent-id>"
os.environ["ANTHROPIC_API_KEY"]  = "orientim-secure-key"

Why two spellings. The official OpenAI and Anthropic SDKs read the *_BASE_URL names. LiteLLM — which is what CrewAI routes through, and what many LlamaIndex and AutoGen setups sit on — reads the *_API_BASE names. Setting both costs nothing and removes the one failure you would never notice: the run completes, every request went straight to the provider, and your dashboard shows $0.00, which looks like an idle agent rather than an unmetered one.

After that, build your agents exactly as you normally would — no base_url anywhere. If you prefer to pass it per client, these are the shapes, but remember they only cover the client you hand them to:

# LangChain
llm = ChatOpenAI(
    base_url="http://127.0.0.1:8000/proxy/<agent-id>/v1",
    api_key="orientim-secure-key", model="gpt-5.6-terra",
)

llm = ChatAnthropic(          # note: no /v1 — the SDK adds it
    base_url="http://127.0.0.1:8000/proxy/<agent-id>",
    api_key="orientim-secure-key", model="claude-opus-4-5",
)

# LlamaIndex
llm = OpenAI(
    api_base="http://127.0.0.1:8000/proxy/<agent-id>/v1",
    api_key="orientim-secure-key", model="gpt-5.6-terra",
)

# AutoGen
client = OpenAIChatCompletionClient(
    base_url="http://127.0.0.1:8000/proxy/<agent-id>/v1",
    api_key="orientim-secure-key", model="gpt-5.6-terra",
)

Streaming works the same way. CrewAI and any other framework built on these SDKs follow the same pattern.

There are two caps, and they do different jobs.

• The agent cap stops that agent. Every other agent keeps running.
• The account cap (on the Dashboard) is a ceiling across all agents. When the total reaches it, they all stop — this is the number that matches your bill.

Without an account cap, five agents at $50 each is $250 of exposure and nothing enforces a limit on the total. Set one on the Dashboard under Account cap….

Budgets that reset themselves

Both caps can reset on a schedule, so you set them once instead of clearing them by hand every time they fill up:

• Every month — starts fresh on the 1st. Matches how your API bill works, and it's the default.
• Every week — starts fresh each Monday.
• Every day — starts fresh at your local midnight.
• Never — a one-off cap. Spends up to the limit, then stops for good until you raise or reset it yourself.

A cap is only as accurate as the price behind it. Orientim ships with prices for the current models of every supported provider. Edit them here when a provider changes a rate.

Prices are entered in USD per 1M tokens — the same figure OpenAI, Anthropic and Google publish, so you can copy a number straight across without converting anything. Edits save as you type; there is no Save button to forget.

When a provider changes a price

Open Pricing, find the model under Models you're using — the page shows only the models your own traffic actually touches, not a list of forty — type the new figure, done. Reset next to a row puts the built-in price back.

When a brand-new model appears

A model Orientim doesn't recognise is billed at a deliberately high fallback rate and flagged for you: the Dashboard warns, and the model appears at the top of Pricing under No price set. Enter its real price there, or use ➕ Add a model with the shorter family id (e.g. claude-opus-5) so every dated release of it is covered too.

Every call is metered as its response comes back and written to a local request log — model, token split, stop reason and cost. When an agent reaches its budget cap, the card turns red and further requests are hard-stopped with HTTP 402 — no new spend is possible until you raise the cap yourself.

Alerts at 80% and at the cap

A desktop alert fires once when an agent passes 80% of its cap — while there is still room to act — and again the moment it is actually stopped. Each fires once per approach, not on every request, so they stay worth reading. The account cap has the same two alerts.

Getting going again

• Raise the cap — open the agent, set a higher figure. It resumes immediately.
• Reset the spend — puts the counter back to zero for this period.
• Wait for the reset — if the agent is on a daily, weekly or monthly budget it starts fresh on its own when the period rolls over. A one-off cap (Resets: Never) stays stopped until you act.

Stopping everything at once

The Dashboard has ⏹ Stop all agents — one click pauses every agent, for the moment you want everything to stop and don't want to click five times. ▶ Resume all brings back the ones still inside their caps.

The dashboard won't open

The dashboard may be on 8502 rather than 8501 if a port was taken. The sidebar prints both numbers it actually bound. If startup fails, a proxy_error.log file is written next to the app with details.

My tool gets a 401

The tool must send orientim-secure-key as its API key — not your real key, and not a blank value. Double-check the base URL includes the full /proxy/<agent-id> path from the agent card.

Costs look slightly off

Cost is exact where the provider reports it (e.g. OpenRouter). For others it's computed from token usage and model rates, which you can adjust in the pricing settings. Anthropic cache tokens are billed at their published multipliers — reads at 0.10× and writes at 1.25× the input rate.