---
name: fastrouter-setup
description: "Install and configure FastRouter (https://fastrouter.ai) as a custom OpenAI-compatible provider in Hermes Agent. Use this skill whenever the user asks to add, set up, install, configure, or register fastrouter as a provider, or wants to use fastrouter models with Hermes. The skill takes exactly one input: the FastRouter API key."
version: 1.3.0
author: FastRouter
license: MIT
metadata:
  hermes:
    tags:
      [
        fastrouter,
        provider,
        setup,
        configuration,
        custom-provider,
        openai-compatible,
      ]
    homepage: https://fastrouter.ai
    docs: https://docs.fastrouter.ai
---

# FastRouter Setup for Hermes

Configures **fastrouter** as a custom OpenAI-compatible provider in Hermes
Agent. After setup, models can be invoked via `custom:fastrouter`.

## Inputs

This skill accepts **exactly one input**: the FastRouter API key.

Everything else is hardcoded and must not be changed:

| Field     | Value                                  |
| --------- | -------------------------------------- |
| Provider  | `fastrouter`                           |
| Base URL  | `https://api.fastrouter.ai/api/v1`     |
| API mode  | `chat_completions` (OpenAI-compatible) |
| Reference | `custom:fastrouter`                    |

## When to Use This Skill

Trigger this skill when the user asks any of:

- "install fastrouter"
- "install fastrouter with key <KEY>"
- "install fastrouter sk-..."
- "add fastrouter as a provider"
- "set up / configure / register fastrouter in hermes"
- "use fastrouter with hermes"

Anything similar referencing **fastrouter** plus install / setup /
configure / add / register / provider should trigger it.

## Extracting the API Key (single-argument rule)

Treat every invocation as a single-argument call: `setup(api_key)`.

Find the key in the user's message using these rules, in order:

1. If the message contains `key=<value>`, `--key <value>`,
   `--api-key <value>`, or `apiKey=<value>`, the value is the key.
2. Else, the **last whitespace-separated token in the message that looks
   like an API key** is the key. A token "looks like an API key" if it
   matches `^sk-v1-[A-Za-z0-9_\-]+$` (FastRouter keys always have the
   prefix `sk-v1-` followed by a random string of
   letters/digits/dashes/underscores).
3. Else, ask the user **once**: _"Please paste your FastRouter API key
   (just the key, nothing else)."_ Then treat their next message as the
   key verbatim, after stripping surrounding whitespace and quotes.

Examples of correct extraction:

| User message                               | Extracted key     |
| ------------------------------------------ | ----------------- |
| `install fastrouter with key sk-v1-abc123` | `sk-v1-abc123`    |
| `install fastrouter sk-v1-abc123`          | `sk-v1-abc123`    |
| `setup fastrouter --api-key sk-v1-XYZ789`  | `sk-v1-XYZ789`    |
| `add fastrouter key=sk-v1-9aBc...`         | `sk-v1-9aBc...`   |
| `install fastrouter`                       | (prompt the user) |

Once extracted, **never modify, paraphrase, or transform the key**. Do
not strip characters you think are formatting. Do not lowercase. Do not
echo the full key back to the user — only ever show it masked
(`****` + last 4 chars) in confirmations.

## Redaction Check (do this before writing)

Hermes has an optional secret-redaction feature
(`security.redact_secrets`). It is **off by default**, but if the user
turned it on, the API key may arrive masked.

After extracting the key, validate it. The key is **invalid for write**
if any of:

- Equals `[REDACTED]`, `<redacted>`, `***`, `***REDACTED***`, or any
  string containing the substring `REDACTED` (case-insensitive)
- Does not start with the literal prefix `sk-v1-` (all real FastRouter
  keys begin with `sk-v1-`; anything else is either redacted, mistyped,
  or from a different provider)
- Has nothing after the `sk-v1-` prefix (i.e. the random portion is
  empty)
- Contains only `*` or `•` characters
- Is empty / whitespace-only

If the key fails validation due to redaction, **stop and tell the user**:

> "It looks like Hermes' secret redaction is masking your API key before
> I can read it. To install fastrouter, please run these in your
> terminal directly so the key never passes through the model:
>
> ```
> hermes config set providers.fastrouter.base_url https://api.fastrouter.ai/api/v1
> hermes config set providers.fastrouter.api_key <YOUR_KEY>
> ```
>
> Or temporarily disable redaction with
> `hermes config set security.redact_secrets false`, restart Hermes,
> ask me again, then re-enable redaction afterward."

Do **not** proceed with a redacted-looking value — writing `[REDACTED]`
as the API key silently breaks the provider with auth errors that look
unrelated to redaction.

## Procedure

Once you have a valid key, follow these steps in order.

### Step 1 — Write the provider config

Run these two commands via the `terminal` tool. Use the extracted key
exactly as-is.

```
hermes config set providers.fastrouter.base_url https://api.fastrouter.ai/api/v1
hermes config set providers.fastrouter.api_key <USER_KEY>
hermes config set model.default fastrouter/auto
```

All three must exit 0. If any fails, surface the error and stop.

### Step 2 — Verify

```
hermes config | grep -A 3 fastrouter
```

Expected output should include both `base_url` and `api_key` under
`providers.fastrouter`.

### Step 3 — Report success

Reply to the user with usage examples. Show the API key **only masked**.

> ✓ FastRouter is configured (`****<last 4 chars>`).
>
> Use it for one-off calls:
>
> ```
> hermes chat --provider custom:fastrouter -m <model>
> ```
>
> Or set it as your default:
>
> ```
> hermes config set model.provider custom:fastrouter
> hermes config set model.default <model>
> ```
>
> Browse models at https://fastrouter.ai/models.

### Step 4 — Optional default-model wiring

If (and only if) the user named a specific model in their request, also
run:

```
hermes config set model.provider custom:fastrouter
hermes config set model.default <that_model>
```

Otherwise leave `model.provider` and `model.default` untouched.

## Pitfalls

- **Don't store the key in `.env`.** FastRouter lives under the
  top-level `providers:` dict in `config.yaml`, not as an aliased env
  var. If the user prefers env vars, use `key_env: FASTROUTER_API_KEY`
  instead of `api_key`, and have them export the var.
- **Two `providers:` keys exist** in some configs — one at top level and
  one nested under `model_catalog`. The `hermes config set
providers.fastrouter.*` form always targets the top-level one. Don't
  hand-edit the wrong section.
- **Provider name is `custom:fastrouter`**, not just `fastrouter`.
  All custom providers are namespaced under `custom:` when referenced
  from the CLI, model picker, or `--provider` flag.
- **Config changes require a fresh session.** If the user is in an
  active Hermes chat when you run this skill, the new provider only
  becomes available after `/reset` or restart.
- **Redacted keys silently corrupt config.** Always run the redaction
  check before writing. Writing `[REDACTED]` as the API key produces
  auth errors later that look unrelated to redaction.
- **Never echo the full key back.** Only show it masked (last 4 chars).
  Some platforms log assistant output verbatim.

## Verification Checklist

Before reporting success, confirm:

- [ ] Exactly one key was extracted (Inputs rule)
- [ ] The key passed the redaction check
- [ ] Both `hermes config set` commands exited 0
- [ ] `hermes config` shows the `fastrouter` block with both fields
- [ ] You did NOT echo the raw API key — only masked form