AI explanations | ShellOrbit

These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.

Add your own AI provider, and every incident and finding gets an Explain with AI button: what happened, whether and where it affects you, the fix step by step, and how to check it worked. Your provider bills you for the model calls; ShellOrbit charges nothing extra.

Providers

AI explanations: Provider, What you add
Provider	What you add
OpenAI (ChatGPT), Anthropic, Google Gemini, Mistral, Groq, DeepSeek, xAI, OpenRouter, Together AI	An API key
Azure OpenAI	An API key and your resource URL, `https://<resource>.openai.azure.com/openai/v1`
Google Cloud Vertex AI	A service account JSON key, the project ID, and the region, such as `us-central1` or `global`
AWS Bedrock	An access key ID and secret access key, an optional session token, and the region
Local or self-hosted (Ollama, LM Studio, vLLM)	The model’s URL, reachable over public https, for example through a tunnel, and a key if it needs one
Custom OpenAI-compatible	The base URL, how it takes the key (`Authorization: Bearer` or an `api-key` header), and the key

Any URL you give must be public https. ShellOrbit runs in the cloud, so it cannot reach localhost or a private network, and it does not follow redirects.

Add a provider

Open Settings, AI & MCP. Owners and admins can change it; everyone else sees the status.
Choose the provider, type the model ID (suggestions are offered, any model works), and pick an effort.
Enter the credentials and press Test and save. ShellOrbit makes one tiny call with them and saves only if it works; otherwise the provider’s reason is shown and nothing is kept.

To change the model or effort later, leave the credentials empty to keep the saved ones. Remove deletes them.

Model and effort

AI explanations: Provider, Effort
Provider	Effort
Anthropic, and Claude models on Vertex AI	Provider default, low, medium, high, xhigh, or max
AWS Bedrock	For `anthropic.*` models as for Anthropic; other models use the provider default
OpenAI and every OpenAI-compatible provider	Provider default, low, medium, or high, sent as `reasoning_effort`

Higher effort gives more considered answers and takes longer. If a model does not accept the effort you chose, the test call says so: pick another level or the provider default.

What is sent

Only what ShellOrbit already shows you about that one item:

An incident: the advisory (title, summary, severity, CVEs, CISA status and deadline, the published fix) and where it matched your account, with the evidence.
A finding: its title, severity, source, the kind of key, the masked value such as sk_…a1b2, where it was found, and the fix.

Never a secret: ShellOrbit does not hold one in full. Your provider processes the request under your account and its own terms.

Your credentials

Stored encrypted with a separate key, used only for these explanations, never shown again (only the last four characters), and deleted when you remove them or delete the account. Each explanation is kept 7 days.

Limits

AI explanations: Limit, Value
Limit	Value
Explanations	30 an hour per account
Test and save	10 an hour per account
Test call	15 seconds, 16 output tokens
Explanation	Up to 2,000 output tokens (4,000 for Anthropic models at high effort or above), and up to 4 minutes

API

AI explanations: Method, Path, Notes
Method	Path	Notes
`GET`	`/v1/ai/settings`	Provider, model, effort, last four characters of the key, and the provider list
`PUT`	`/v1/ai/settings`	Owners and admins. Tests the credentials, then saves
`DELETE`	`/v1/ai/settings`	Owners and admins. Removes the credentials
`POST`	`/v1/ai/explanations`	`{"kind": "incident" or "finding", "id": "..."}`. Returns `202` with an `id`; `409` if no provider is set up
`GET`	`/v1/ai/explanations/{id}`	`running`, `done` with the text, or `failed` with the reason

These routes use a dashboard session. An API key can read the GET routes only.