# ShinrAI for Onyx

Protect questions, retrieved company knowledge and supported local search tool exchanges before model inference. Keep your model credentials and optional reply restoration inside your environment.

## Connect

1. Obtain a ShinrAI API key. Download and unpack the connector bundle, including its `python` relay directory.
2. Copy `.env.example` to `.env`. Restrict that file to your deployment account (`chmod 600 .env`). Set the ShinrAI key, your existing provider URL/model/key, a separate random relay key, and Onyx's Docker network name.
3. Run `docker compose up -d --build` in this directory.
4. In Onyx, open **Admin Panel → Configuration → Language Models → Add Custom LLM Provider**.
5. Name it **ShinrAI protected models**. Set provider name **openai**, base URL **http://shinrai-relay:8080/v1**, and API key to the **relay key**.
6. Add **shinrai-private** (retain pseudonyms) and **shinrai-restored** (restore recognized replacements in replies). Set both to text only. Run Onyx's connection test for each.
7. Choose a protected default model. Route auxiliary/fast calls through the same relay. In Onyx 4.7.1, leave the dedicated chat-naming model unset: it inherits the protected chat model. Older configurations with an explicit fast-model field must select a protected alias there too.
8. Make only protected models visible to the intended users. Remove direct provider routes and unprotected fallbacks. Use local embeddings and local search; disable external search, external actions, vision and code-execution tools in the reference configuration.

The relay exposes only its two aliases. Unknown models, unsupported payloads, invalid keys and unavailable protection stop the call. No marketplace installation or enterprise-only Onyx hook is required.

## Verify

Upload a synthetic document to Onyx containing `Contact Max Mustermann: max.mustermann@example.org. The ORBIT service level is platinum.` Include the name in its title. Ask for ORBIT's service level and contact email, with a citation. Repeat a follow-up question in both reply modes. The private model keeps pseudonyms; the restored model restores recognized values in your local interface. Inspect a controlled upstream destination to verify that titles, retrieved passages and outgoing tool data contain protected values and no restoration map.

Original documents, questions and citations remain in Onyx. This integration protects onward model calls. It does not redact Onyx's own storage or local citations. Original-containing tool results are protected before the next model request. Restored tool arguments are for local tools; separate external exports need their own protection step.

## Troubleshooting and release status

- Connection fails: verify Docker network membership, `/v1` in the base URL and the separate relay key.
- Search works but inference fails: confirm all auxiliary models use a supported alias and your provider accepts the requested tool schema. Raw images/audio/files are rejected; ingest protected text first.
- Empty/incomplete stream: keep proxy buffering disabled and allow at least 300 seconds. Do not add an unprotected fallback.
- Onyx 4.7.1 rejects custom aliases as a dedicated naming model. Leaving that field unset uses its default chat-model fallback.
- The tested Innovius OpenAI route accepted plain GPT completions but rejected tool-history IDs during conversion. The Anthropic route passed the relay's tool round trips. This is a provider-specific compatibility finding, not a reason to rewrite protocol IDs in the connector.

Reference application version: Onyx **4.7.1**. Connection tests are live. Full application acceptance and independent installation remain in progress until the QA report marks them passed. No marketplace listing is claimed.

[Onyx custom-provider instructions](https://docs.onyx.app/admins/ai_models/custom_inference_provider). German instructions: `README.de.md`. Connector license: MIT. Onyx retains its own license and notices.

## Validated example

The [screenshots](screenshots/) show the actual installed test application with synthetic data. Replacement values vary between runs. The download includes shared example documents and an executable connection test in `../fixtures/`.