AI models

OpenRouter integration

Ahena works with your OpenRouter account: it checks your API key, its credit limit, expiry and free-tier status, and that your configured model is in OpenRouter's model list, then generates an adapter behind the common ahena.ai interface using the official openai SDK pointed at OpenRouter. Your app calls OpenRouter directly. Ahena is never in the inference path.

BetaFull OpenRouter docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at OpenRouter.

The connected key through GET /api/v1/key: credit limit, credit left, usage, expiry, free tier, and whether it's a management key. A masked-key label is never shown.
The models OpenRouter lists (ahena inspect openrouter), with context length, max output and expiration date.

Nothing to configure

OpenRouter has nothing to plan or apply. Ahena gives you Doctor, model discovery and a generated adapter behind the common ahena.ai interface, so each environment can use a different AI provider. See AI providers.

Generated code: src/ahena/ai/providers/openrouter.ts behind ahena.ai.generate(), on the official openai SDK with OpenRouter's base URL; ahena.ai.raw is the client.

How Ahena verifies

There's nothing to read back: Ahena changes nothing in your OpenRouter account, so there's no plan, apply or VERIFIED state. Doctor runs read-only checks and records PASS, INFO, WARNING or FAIL findings.

Checks use only the key and model-list endpoints, which cost nothing. Ahena never sends a completion.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the OpenRouter docs.

Check	What it means
`openrouter.key`	Key accepted.
`openrouter.key_limit`	Credit left on the key: INFO with no limit, WARNING under 10% left, FAIL when the limit is reached.
`openrouter.free_tier`	The account has never bought credits; WARNING in production.
`openrouter.model`	Configured model is listed; WARNING or FAIL as its expiration date nears, FAIL when it isn't listed.
`openrouter.key_kind`	A management key is connected; use a regular API key (WARNING).

More on findings, health and continuous checks: Doctor.

Approvals

There's nothing to approve: connecting, Doctor, ahena inspect and ahena generate change nothing in your OpenRouter account. Generated code is written to your repository, where you review it like any other change.

Manual steps

Ahena can't do these for you:

Create a key in OpenRouter (Settings → API Keys) and give it a credit limit.
Buy credits before production traffic.
Set OPENROUTER_API_KEY (and AI_PROVIDER=openrouter if several adapters exist) where your app runs.

Credentials and permissions

Name	Secret	Notes
`OPENROUTER_API_KEY`	Yes	A regular API key (`sk-or-v1-…`), not a management key.

Least privilege

OpenRouter keys have no scopes, so Ahena can only check that the key works.
Use a dedicated key with a small credit limit; Ahena never spends credits.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, then generate. There's no plan or apply step for an AI provider.

OPENROUTER_API_KEY=sk-or-v1-… ahena connect openrouter -e production

Connect a regular API key.

```
ahena doctor -e production
```
Check the key, its credit limit and the configured model.
```
ahena inspect openrouter -e production
```
Show the key's limits and the models OpenRouter lists.
```
ahena generate -e production
```
Write the ahena.ai adapter for this environment's provider.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How OpenRouter is tested

Tested against a simulated version of the OpenRouter API (key and model-list endpoints, offset/limit pagination, error shapes); not yet verified against the real service.
The generated adapter is typechecked against the openai SDK, not run.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

The common interface covers text generation. Tools, streaming, routing preferences and fallbacks use ahena.ai.raw.
Account credits need a management key, so Ahena reports the connected key's own limit and usage instead.
There's no drift tracking for AI providers.

Disconnecting

ahena disconnect openrouter removes the stored key (delete or disable it in OpenRouter); nothing in your OpenRouter account is changed.