# Vynaris — agent onboarding runbook

## What Vynaris does

Vynaris is an OpenAI-compatible gateway at https://api.vynaris.com that routes your LLM traffic to right-sized cheap models and bills upstream cost + 1% from prepaid credits. You can onboard yourself; a human only needs to verify the account and add credits.

## Onboard in 3 steps

1. Create an account (returns a provisional API key — save it, it is shown once):

```
curl -s https://api.vynaris.com/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{"email": "your-humans-email@example.com"}'
```

2. Verify the key works:

```
curl -s https://api.vynaris.com/v1/ping \
  -H "Authorization: Bearer vyn_sk_live_..."
```

3. Give the `claim_url` from step 1 to your human. Provisional keys have a $0 balance and requests return HTTP 402 until a human verifies the email and adds credits.

## Configuration

OpenAI SDK:

```python
client = OpenAI(base_url="https://api.vynaris.com/v1", api_key="vyn_sk_live_...")
```

Claude Code:

```
export ANTHROPIC_BASE_URL=https://api.vynaris.com
export ANTHROPIC_AUTH_TOKEN=vyn_sk_live_...
```

curl:

```
curl -s https://api.vynaris.com/v1/chat/completions \
  -H "Authorization: Bearer vyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "hi"}]}'
```

## Harness configuration quick reference

- Hermes (NousResearch hermes-agent): in ~/.hermes/config.yaml add custom_providers entry {name: vynaris, base_url: https://api.vynaris.com/v1, key_env: VYNARIS_KEY, api_mode: chat_completions}; set model default custom:vynaris:auto. OPENAI_BASE_URL does not apply to custom providers.
- OpenClaw: add a custom provider in ~/.openclaw/openclaw.json with baseUrl https://api.vynaris.com/v1, api "openai-completions", and your key; select model "vynaris/auto".
- Claude Code: export ANTHROPIC_BASE_URL=https://api.vynaris.com and ANTHROPIC_AUTH_TOKEN=<key>.
- Pi coding agent (badlogic/pi-mono): in ~/.pi/agent/models.json add provider {"vynaris": {"baseUrl": "https://api.vynaris.com/v1", "api": "openai-completions", "apiKey": "$VYNARIS_KEY", "models": [{"id": "auto"}]}}. Use a distinct env var — OPENAI_API_KEY overrides models.json keys. Other agents: base URL https://api.vynaris.com/v1 + key; model "auto" routes automatically.

## Behavior contract

- Every response includes a `vynaris` JSON block with `served_model` and `cost_usd`.
- Check your balance with `GET /v1/usage`.
- HTTP 402 means out of credits. It is terminal — do not retry; ask your human to top up.
- Model `"auto"` lets the router choose the cheapest capable model.