# Kimss AI — full documentation corpus (llms-full.txt) # Canonical origin: https://kimss.ai # Generated: 2026-09-13 # Source: reports/templates/documents/*.md via docs.manifest.json # Prefer /llms.txt for a short index; this file is the long-form dump. > Full docs: https://kimss.ai/docs > Short index: https://kimss.ai/llms.txt ## Why Kimss Source: https://kimss.ai/docs/why_kimss Last-updated: 2026-09-12 # Why Kimss — Model-Agnostic Enterprise Gateway Kimss is **not** a model host and **not** a replacement for any provider runtime. Providers execute models and agents. Kimss is the **secured multi-tenant control plane** your platform team would otherwise build on top: one API for chat and agents, Entra SSO, tenant isolation, governed-request metering, kill switch, and audit-ready gateway telemetry. > [!NOTE] > **Three things that matter on day one** > > 1. **Just-In-Time (JIT) auto-discovery** — Production agents appear in **Governance → Agents** when your code sends `X-Kimss-Agent-Id` through the gateway. You do not pre-build agents in Studio to go live. > 2. **1-line `.env` drop-in (Invisible Proxy)** — Keep your native SDK. OpenAI: `OPENAI_BASE_URL=https://api.kimss.ai/v1`. Anthropic: `ANTHROPIC_BASE_URL=https://api.kimss.ai` (SDK appends `/v1/messages` — do not add `/v1` yourself). Use your Kimss API key. No application rewrite. > 3. **1-click kill switch** — Disable an agent on **Governance → Agents**; subsequent attributed gateway traffic returns **403**. > [!NOTE] > **Executive summary:** You keep the runtime. Kimss adds governance, metering, and a single developer surface. Share the visual CTO brief at [https://kimss.ai/docs/why_kimss](https://kimss.ai/docs/why_kimss). ## Positioning for architecture reviews | Layer | Role | |-------|------| | **Your providers** | Data plane — Azure OpenAI / Foundry you own, OpenAI-compatible BYO, native Anthropic, registered external agents | | **Kimss** | Control plane — auth, vault, routing, governed requests, kill switch, workspaces, SDK, optional APIM audit | | **Your app / OpenAI client / SPA** | Single Kimss credential from prototype through production | Kimss multiplexes chat inference and agentic flows (tools, retrieval) through one authenticated edge. Routing targets the endpoint you vaulted per workspace. ## Comparison: model account alone vs Kimss gateway | Capability | Model account alone | Kimss gateway | |------------|---------------------|---------------| | Model & agent execution | Native provider projects | Same backends — Kimss routes per workspace | | Multi-tenant workspaces | Build yourself | PostgreSQL RLS + workspace model | | Identity (Entra SSO, SCIM) | Wire yourself | [Identity & SSO](identity_sso.md) | | One key: chat + agents | Separate integration paths | One gateway | | Spend control | Ad-hoc / per-project | Governed requests + hard 429 over cap | | Usage & chargeback | Custom metering | Usage Hub + [execution logs](product_integrations.md) | | Audit trail for procurement | You design the sink | Optional APIM → Log Analytics ([Security & Compliance](security_compliance.md)) | | Kill switch | Content filters only | Authoritative sever at the gateway | | Procurement | Provider billing only | Self-serve PAYG + Enterprise sales | ## Six differentiators CTOs care about 1. **Integration gap** — Using AI to write code ≠ shipping governed agents in your product. 2. **Flip the order** — Start with the control plane; do not bolt on identity and audit later. 3. **Invisible Proxy (dual-listener)** — Keep your OpenAI or Anthropic SDK. OpenAI: `base_url=https://api.kimss.ai/v1` → `POST /v1/chat/completions`. Anthropic: `base_url=https://api.kimss.ai` → `POST /v1/messages`. Azure official clients are not inbound — vault Azure and call through one of those listeners. 4. **Shadow agents & prompt ownership** — JIT inventory and execution logs. 5. **Audit-ready by design** — Gateway logs, admin audit trail, questionnaire evidence. 6. **Azure-native control plane** — Managed Identity, Entra. The data plane is yours. ## Request path ``` Your OpenAI or Anthropic client / SDK / SPA → Kimss Gateway (auth, vault, JIT inventory, governed requests, kill switch) → Optional APIM (audit, token metrics) → Your models (OpenAI-compatible / Azure OpenAI / native Anthropic / external agents) ``` See [Security & Compliance](security_compliance.md) and [Trust Center](https://kimss.ai/trust). ## FAQ ### We already pay for a model host — why Kimss? The host is execution. Kimss is the multi-tenant product layer: identity, metering, logs, and a single developer surface. ### Can we build this ourselves? Yes — budget platform engineering for orchestration, metering, audit, and provider API churn. Kimss ships that layer as a managed product. ### Is this another vendor or cloud? No. Kimss runs on Azure, uses Entra for identity, and routes inference to **your** vaulted endpoint (OpenAI-compatible, Azure OpenAI, or native Anthropic). ### What about security review? See [Security & Compliance](security_compliance.md). ### How do we register models we already run? Vault an OpenAI-compatible or native Anthropic endpoint under Connected Infrastructure, then call `"model": "custom:"`. Register existing agents with `POST /v1/agents/register`. Walkthrough: [Register agents and models](external_agents.md). ### How do we buy it? Self-serve Developer / Production / Scale, PAYG upgrade paths, or sales-led Enterprise — [Plans & subscriptions](plans_subscriptions.md). ## Related - [Why Kimss CTO brief (HTML)](https://kimss.ai/docs/why_kimss) - [Quick start](quick_start.md) - [Plans & subscriptions](plans_subscriptions.md) - [Register agents and models](external_agents.md) - [Connected Infrastructure (BYO)](custom_model_endpoints.md) --- ## Onboarding paths and naming Source: https://kimss.ai/docs/onboarding_paths Last-updated: 2026-09-12 # Onboarding paths and naming Kimss setup is **three dedicated surfaces** — no single wizard page. Legacy `/app/onboarding` and `/app/connect` redirect to **Vault**. > See also: [Route your traffic](route_traffic.md) · [Quick start](quick_start.md) · [Register agents and models](external_agents.md) · [Provider Vault (BYO)](custom_model_endpoints.md) ## Canonical order (always) ```text 1. Provider → register each custom: in Vault (/app/vault) 2. Gateway API key → mint kimss_... at Gateway API keys (/app/keys) 3. Connect your app → either/or: manual snippets OR AI coding agent (see Vault journey rail) 4. Agents → inventory rows appear JIT after first call ``` **Step 3 is a fork, not two separate tasks.** On Vault (and Keys), the header **go-live journey** rail surfaces steps 1–3. Clicking **Connect your app** opens a chooser: | Method | What the customer does | Drawer | |--------|------------------------|--------| | **I'll wire it myself** | Copy `.env` / Python / cURL into their app | Manual guided console | | **Let my AI coding agent do it** | Paste one prompt into Cursor / Claude Code / Cascade | AI-assisted setup | Either path ends the same: agents appear on **Agents** after the first governed call. When traffic is flowing, the journey rail collapses to a **Live · traffic flowing** chip. **Optional (any time before or after step 3):** - **Endpoint governance** — set a monthly token cap (alert or block) on the vaulted endpoint in Provider Vault (`/app/vault`). Article 12 record-keeping is always on. ## Two key types (do not confuse them) | Term | Who issues it | Who uses it | Typical prefix | |------|---------------|-------------|----------------| | **Provider API key** | OpenAI / Azure / Anthropic / Groq / … | Kimss → upstream LLM | `sk-…`, Azure KEY 1/2, `sk-ant-…`, `gsk_…` | | **Gateway API key** | Kimss | Your app → Kimss | `kimss_…` | In SDK drop-in snippets, `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` hold the **Gateway API key**, not the provider key. The provider key stays vaulted in Vault. ## Two registries (do not confuse them) | Registry | UI name | Route | What it stores | How it fills | |----------|---------|-------|----------------|--------------| | **Model routes** | **Vault** | `/app/vault` | Provider URL, encrypted Provider API key, `custom:` alias | Manual registration (wizard: Connect → Model → Guardrails) | | **Agent inventory** | **Agents** | `/app/agents` | Agent id, model binding, kill switch | **JIT** from gateway traffic with `X-Kimss-Agent-Id` | **Shadow agent discovery** means a JIT Agents row whose **model is not in Vault**. Customers do not register agents in Studio; Vault endpoints are the only registration. Gateway traffic still fills the inventory; the Shadow badge is for unvaulted models only. ## Three surfaces (replaces Onboarding wizard) 1. **Vault** (`/app/vault`) — register providers with connection test, model discovery, guardrails 2. **Gateway API keys** (`/app/keys`) — list, mint, revoke; personalized `.env` snippet at mint time 3. **Connect your app** — Vault/Keys journey rail → method fork (manual guide or AI-agent guide); full docs at [route_traffic.md](route_traffic.md) New workspaces land on **Vault** (`/app` or `/app/vault`) until agents exist; then `/app` opens **Agents**. ## Azure OpenAI note Register with the Azure **Endpoint** (`https://.openai.azure.com` or Foundry `…services.ai.azure.com`) and **Deployment name**. Kimss composes `{endpoint}/openai/v1` (no dated `api-version` required). The deployment name becomes the vaulted `model_id`. ## AI coding agent (repo onboarding) When you point Cursor, Claude Code, Cascade, etc. at **your** application repo: 1. Complete Vault + Gateway API key in the Kimss app 2. Paste: *Onboard this repo to the Kimss control plane.* (full prompt on [Route your traffic](route_traffic.md)) 3. The agent reads the canonical A2A spec ([kimss-control-plane `AI_INTEGRATION.md`](https://raw.githubusercontent.com/kimss-ai/kimss-control-plane/main/AI_INTEGRATION.md)) and rewires `OPENAI_BASE_URL` / `OPENAI_API_KEY` — it does not clone the Kimss control-plane source 4. Remember: `OPENAI_API_KEY` is the Kimss **Gateway** key ## Legacy names | Current | Legacy | |---------|--------| | **Vault** | Onboarding step 1, Provider Vault, Connected Infrastructure, `/app/onboarding/providers` | | **Gateway API keys** | Onboarding step 2, `/app/onboarding/keys`, `/app/workspace/keys` | | **Route traffic doc** | Onboarding step 3, Connect, Getting Started, Developer Hub | | `/app/vault` | `/app/onboarding`, `/app/connect`, `/app/getting-started`, `/app/gateway` | | `/app/keys` | `/app/onboarding/keys`, `/app/connect/keys`, `/app/workspace/keys` | ## Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | `custom endpoint not found for model custom:…` | Model not vaulted | Register at **Vault** | | 401 on gateway | Missing or revoked Gateway key | Mint at `/app/keys` | | Agent not in inventory | No `X-Kimss-Agent-Id` on calls | Set header; see [route_traffic.md](route_traffic.md) | --- ## Quick start Source: https://kimss.ai/docs/quick_start Last-updated: 2026-09-12 # Quick start Get productive on Kimss in a few minutes: **vault a model**, **drop in one line of config**, and **govern** traffic from your existing OpenAI or Anthropic client. Prefer a local agent loop first? Use the free MIT [`kimss-agents` harness](agent_harness.md) (no Kimss account), then connect with `gateway="kimss"` when you need production governance — see also [/open-source](/open-source). > [!NOTE] > **The three pillars** > > 1. **JIT auto-discovery** — Send `X-Kimss-Agent-Id` on gateway calls; Kimss creates the inventory row automatically. > 2. **1-line `.env` (Invisible Proxy)** — OpenAI: `OPENAI_BASE_URL=https://api.kimss.ai/v1` and `OPENAI_API_KEY=kimss_...`. Anthropic: `ANTHROPIC_BASE_URL=https://api.kimss.ai` and `ANTHROPIC_API_KEY=kimss_...`. Your existing native SDK keeps working. > 3. **1-click kill switch** — **Agents** (`/app/agents`) → disable; attributed traffic for that agent id returns **403**. See [Onboarding paths and naming](onboarding_paths.md) for vault vs agent discovery order. ## 1. Sign in and subscribe 1. Go to [kimss.ai](https://kimss.ai) and choose **Sign up** (`/app/signup`) or **Sign in** (`/app/login`). 2. Sign in with **Microsoft** or **Google** (personal CIAM) or your **work account** (enterprise). 3. Start on **Developer** (free) or upgrade to **Production / Scale / Enterprise**. See [Plans & subscriptions](plans_subscriptions.md) and [/pricing](/pricing). > [!NOTE] > Kimss does **not** provision a hosted model runtime. You vault **your** provider endpoint first. ## 2. Setup (required) After sign-in, new workspaces open **Vault** (`/app/vault` — also `/app`): 1. **Vault** — register each `custom:` using the provider wizard (credentials → test → pick model once → optional guardrails). 2. **Gateway API keys** (`/app/keys`) — mint a workspace-scoped `kimss_...` key (this is what goes in `OPENAI_API_KEY` — not your provider key). Copy the personalized `.env` snippet shown once at mint time. 3. **Connect your app** — open **Connect your app** on Vault/Keys for a single quickstart: copy `.env` / Python / cURL, or the **AI agent prompt** tab. The checklist refreshes live after you vault/mint. Send `X-Kimss-Agent-Id` on every call. Full detail: [Route your traffic](route_traffic.md). Legacy `/app/onboarding` redirects to Vault. Key management lives at `/app/keys`. ## 3. Integrate — Invisible Proxy ```env OPENAI_BASE_URL=https://api.kimss.ai/v1 OPENAI_API_KEY=kimss_... # or ANTHROPIC_BASE_URL=https://api.kimss.ai ANTHROPIC_API_KEY=kimss_... ``` Keep the native SDK you already use — only the base URL and key change. Use `"model": "custom:"` after you vault the endpoint. **OpenAI** ```python from openai import OpenAI client = OpenAI( api_key="kimss_...", base_url="https://api.kimss.ai/v1", ) client.chat.completions.create( model="custom:your-vaulted-model", messages=[{"role": "user", "content": "Hello from Kimss"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, ) ``` **Anthropic** (SDK appends `/v1/messages`) ```python from anthropic import Anthropic client = Anthropic( api_key="kimss_...", base_url="https://api.kimss.ai", ) client.messages.create( model="custom:your-vaulted-model", max_tokens=1024, messages=[{"role": "user", "content": "Hello from Kimss"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, ) ``` Optional: set `X-Kimss-Agent-Id` so the agent appears in **Agents** (**JIT auto-discovery**). See [Onboarding paths](onboarding_paths.md) and [SDK & API](api_docs.md). Already have agents elsewhere? [Register agents and models](external_agents.md). ## 4. Playground (optional sandbox) **Playground** (`/app/playground`) is a **stateless proxy simulator** for testing gateway routing before production traffic. - Choose a **Target Agent ID** (simulates `X-Kimss-Agent-Id`), review the **Connected Model**, and optionally inject a **Test System Message** for this run only - Production agents are **JIT-discovered** from API traffic with `X-Kimss-Agent-Id` ## 5. Govern — usage, audit, guardrails In the product sidebar: - **Connect**, **Playground**, **Agents**, **Activity**, **Guardrails**, **Threat Intercepts** (paid), **Team & Access** (paid) - **Agents** — inventory, **1-click kill switch**. Token caps live on endpoints in Provider Vault. - **Threat Intercepts** (Production and above) — searchable log when guardrails block traffic; export JSON/CSV for SIEM - **Team & Access** (Production+) — members and invites; use **Plan & Billing** to upgrade ## 6. Next steps | Goal | Where to read | |------|----------------| | Agent configuration | [Agent configuration](creating_agents.md) | | Register existing agents / vault models | [Register agents and models](external_agents.md) | | Governed-request limits | [Usage & governed requests](usage_credits.md) | | Full API reference | [SDK & API](api_docs.md) | | Use Kimss from Cursor, Windsurf, or Claude Desktop (MCP) | [Python SDK: MCP & IDEs](python_sdk_mcp.md) | | Product integrations telemetry | [Product integrations](product_integrations.md) | | Security & procurement | [Security & Compliance](security_compliance.md) | --- ## Route your traffic Source: https://kimss.ai/docs/route_traffic Last-updated: 2026-09-12 # Route your traffic Point your application (or AI coding agent) at the Kimss gateway. Use your **Gateway API key** (`kimss_…`) — not the provider key vaulted in [Provider Vault](/app/vault). > Mint a key at **Gateway API keys** (`/app/keys`) if you have not already. Replace `your_kimss_gateway_key` below with the secret shown once at mint time. **How to read the snippets:** italic gray lines are comments (guidance). Bright assignments and strings are required — copy those into your repo. ## Prerequisites 1. **Provider Vault** — register each `custom:` you will call. 2. **Gateway API key** — mint at `/app/keys`. 3. **Agent identity** — send `X-Kimss-Agent-Id` on every request so Agents Discovery and governance can attribute traffic. ## Tell your coding agent You do not need to rewire the repo by hand. Paste this into Cursor, Claude Code, Cascade, Windsurf, or any coding assistant working **in your application repo**: ```text Onboard this repo to the Kimss control plane. Read https://kimss.ai/docs/route_traffic and https://raw.githubusercontent.com/kimss-ai/kimss-control-plane/main/AI_INTEGRATION.md, then apply those rules here. I already finished Provider Vault (/app/vault) and minted a Gateway API key (/app/keys). Use that Gateway key as OPENAI_API_KEY / ANTHROPIC_API_KEY. Never put the provider key in this repo. Always send X-Kimss-Agent-Id on inference calls. Keep the native OpenAI or Anthropic SDK — do not use KimssClient for chat. ``` That prompt works because [kimss-control-plane `AI_INTEGRATION.md`](https://github.com/kimss-ai/kimss-control-plane/blob/main/AI_INTEGRATION.md) is the public **agent-to-agent spec**: keep the native SDK, point `base_url` at `api.kimss.ai`, use the Gateway key, inject agent headers. It rewires **this** codebase. It does **not** clone the Kimss control-plane source (runtime stays on `api.kimss.ai`). Optional control-plane Python client: [github.com/kimss-ai/kimss-python-sdk](https://github.com/kimss-ai/kimss-python-sdk) (mirrors `kimss_sdk/` in the product monorepo). ## 1-Line .env ```bash # guidance: Gateway key goes in OPENAI_API_KEY / ANTHROPIC_API_KEY # guidance: provider keys stay in Provider Vault — never in this repo # OpenAI client drop-in (required) OPENAI_BASE_URL="https://api.kimss.ai/v1" OPENAI_API_KEY="your_kimss_gateway_key" # Anthropic client drop-in (required if you use Anthropic) ANTHROPIC_BASE_URL="https://api.kimss.ai" ANTHROPIC_API_KEY="your_kimss_gateway_key" ``` ## OpenAI Python ```python from openai import OpenAI # required — keep the native SDK # api_key is your Kimss Gateway API key (kimss_…), not the provider key client = OpenAI( base_url="https://api.kimss.ai/v1", # required api_key="your_kimss_gateway_key", # required ) response = client.chat.completions.create( model="custom:your-model-id", # required — vaulted alias messages=[{"role": "user", "content": "Hello!"}], extra_headers={ "X-Kimss-Agent-Id": "my-service", # required }, ) print(response.choices[0].message.content) ``` ## Anthropic Python ```python from anthropic import Anthropic # required — keep the native SDK # api_key is your Kimss Gateway API key (kimss_…), not the Anthropic provider key client = Anthropic( base_url="https://api.kimss.ai", # required api_key="your_kimss_gateway_key", # required ) response = client.messages.create( model="custom:your-model-id", # required — vaulted alias max_tokens=1024, messages=[{"role": "user", "content": "Hello!"}], extra_headers={ "X-Kimss-Agent-Id": "my-service", # required }, ) print("".join(b.text for b in response.content if getattr(b, "type", "") == "text")) ``` ## cURL ```bash #!/usr/bin/env bash # Use your Kimss Gateway API key API_KEY="${OPENAI_API_KEY:-your_kimss_gateway_key}" curl -sS -X POST 'https://api.kimss.ai/v1/chat/completions' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -H "X-Kimss-Agent-Id: my-service" \ -d '{"model":"custom:your-model-id","messages":[{"role":"user","content":"Hello!"}],"stream":false}' ``` ## Java (JDK 11+) ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // required: Gateway API key from /app/keys — not the provider key String apiKey = System.getenv().getOrDefault("KIMSS_API_KEY", "your_kimss_gateway_key"); String body = "{\"model\":\"custom:your-model-id\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}]}"; HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://api.kimss.ai/v1/chat/completions")) // required .header("Authorization", "Bearer " + apiKey) // required .header("Content-Type", "application/json") .header("X-Kimss-Agent-Id", "my-service") // required .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponse res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()); System.out.println(res.body()); ``` ## What happens next After the first governed request with `X-Kimss-Agent-Id`, the agent appears in **Agents** (`/app/agents`) automatically — no manual pre-registration required. ## Related - [Onboarding paths and naming](onboarding_paths.md) - [Quick start](quick_start.md) - [Provider Vault (BYO)](custom_model_endpoints.md) --- ## Security & Compliance Source: https://kimss.ai/docs/security_compliance Last-updated: 2026-08-22 # Security & Compliance **Audience:** CISOs, security reviewers, procurement teams, and engineers integrating the Kimss gateway. **Updated:** 2026-08-22 **Public hub:** [kimss.ai/trust](https://kimss.ai/trust) Kimss is the **Secure Enterprise Agent Control Plane**. Customers bring agents and model providers; Kimss provides registry, identity, a **1-click kill switch** on routed traffic, spend governance, and an audit trail. Kimss is **not** a second model vendor. Inference stays on **your** OpenAI-compatible endpoint, Azure OpenAI / Foundry project you own, or native Anthropic Messages API. This page is not legal advice. Your counsel should validate fit for your sector and obligations. ## The man-in-the-middle objection Enterprise security teams correctly treat any proxy that sees provider keys or prompt traffic as a high-risk hop. The Kimss answer is not “trust us.” It is: 1. **You hold the keys** — customer provider credentials are envelope-encrypted, **client-write-only**, and decrypted only in memory for routing. 2. **We meter the hop; we do not archive the payload** — default telemetry is metadata and token counts, not full request/response text. 3. **Centralized governance is safer than Shadow AI** — unmanaged scripts with hardcoded keys have no kill switch and no identity mapping. Traffic that actually flows through Kimss does. Security posture and procurement language: [Trust Center](https://kimss.ai/trust). --- ## Certifications and attestations (procurement language) Kimss designs and operates its security program to align with common enterprise frameworks (including **SOC 2–oriented controls**, **ISO 27001–style practices**, and **GDPR–oriented privacy commitments**). **Formal third-party attestations** (for example SOC 2 Type II reports) and **certification specifics** are provided **under NDA** as part of procurement; your **order form / DPA** remains the legal source of truth for what is in scope at signing. --- ## Pillar 1: Cryptographic Isolation (The Vault) **Concept.** Kimss never holds exploitable provider keys in a form that the API or UI can return. ### What is vaulted **Connected Infrastructure (BYO)** stores customer provider API keys (OpenAI-compatible Azure OpenAI, Anthropic-compatible gateways, Ollama, vLLM, and similar) in PostgreSQL table `iam.custom_model_endpoints`, column `auth_secret_encrypted`. This vault does **not** apply to: - **Kimss SDK API keys** — stored as SHA-256 hashes in `iam.api_keys`; the plaintext is shown once at generate time. - **Kimss platform Azure credentials** — App Service managed identity or environment configuration for the control plane itself, not rows in `custom_model_endpoints`. ### Envelope encryption (`enc.v3`) When Azure Key Vault is configured (`KIMSS_SECRETS_KEK_VAULT_URL`, key name `kimss-secrets-kek` by default), **new secrets in production** always use envelope encryption. Fernet encrypt is not permitted in production; legacy Fernet rows still decrypt when `KIMSS_SECRETS_ENCRYPTION_KEY` is set. 1. Each secret gets its own random **32-byte data encryption key (DEK)**. 2. The plaintext key is encrypted with **AES-GCM** (12-byte IV). The DEK plaintext exists only in process memory during encrypt/decrypt. 3. The DEK is wrapped with **RSA-OAEP-256** via Azure Key Vault `wrap_key`. The **key encryption key (KEK)** never leaves Key Vault. 4. PostgreSQL stores a single blob: `enc.v3...`. ### Client-write-only guarantee Register and rotate accept `api_key` in the write body. List, get, and rotate **responses** never include decrypted credentials. Decryption is confined to server-side routing for chat/completions proxy and Hermis tool hops. Verify in product: Governance → Provider Vault. See [Connected Infrastructure (BYO)](custom_model_endpoints.md). ### Endpoint URL policy (production) In production, `base_url` must use **`https://`**. Plain `http://` is rejected at registration and on each proxy resolve. SSRF checks block private IPs, localhost, and internal hostnames. ### Per-endpoint token caps Optional monthly token caps on vaulted models (`monthly_token_cap`, `cap_action`) are customer guardrails on provider spend — not Kimss governed-request billing. When `cap_action=block` and the meter cannot be read, Kimss logs a monitorable `custom_endpoint_cap_fail_open` event rather than silently allowing unbounded traffic. Operators should alert on that signal in Application Insights. --- ## Pillar 2: Data Transience (The Payload) **Concept.** Kimss observes the hop so it can govern and meter it. It does not operate a customer knowledge lake of proprietary prompts and completions. The production billing/telemetry path writes **metadata and token counts** to `telemetry.ai_requests` (correlation IDs, identity claims, attribution, token usage, **gateway-verified** vs **self-reported** trust labels). Kimss does **not** log full request/response text bodies in the default telemetry pipeline. Article 12–oriented evidence is **APIM GatewayLogs** forwarded to Log Analytics when diagnostic settings are enabled — URL, status, correlation, and audit headers — not a prompt archive. **Honest caveats:** conversation turns in Hermis threads retain text because the product needs memory; opt-in semantic cache (off by default) may retain snippets. --- ## Pillar 3: Shadow AI vs Centralized Governance Unmanaged scripts with hardcoded provider keys have no inventory, no SSO binding, no kill switch, and no audit label. | Path | Governance | |------|------------| | Hardcoded keys in a developer laptop / CI script | None. Kimss cannot see or stop the call. | | **Register** only (`POST /v1/agents/register`) | Inventory. Kill switch is advisory until traffic hits Kimss. | | **Report** (`POST /v1/usage/events`) | Usage. Trust label **self-reported** — never Article 12–grade. | | **Route** (`custom:*` through the vaulted proxy) | Identity, tool allowlist, **argument-level policies**, kill switch, **gateway-verified** audit. | See [Register agents and models](external_agents.md). ### 1-click kill switch For **Hermis- and gateway-routed** traffic, disabling an agent on **Governance → Agents** is an **authoritative kill switch**. Subsequent calls that carry that agent id return **403**. Register-only agents that never call Kimss stay inventory until you report or route. --- ## Identity layers and PostgreSQL tenancy Kimss uses **two distinct credential stories**: 1. **Human and SDK access to Kimss** — Browser sessions (Microsoft Entra where configured) and **Kimss API keys** authenticate callers to the Kimss HTTP API. 2. **Kimss service access to Azure** — App Service **managed identity** obtains tokens for Azure resource APIs without embedding long-lived secrets in configuration. Kimss runs on a **single PostgreSQL cluster** (per environment) with **shared control-plane schemas** (`iam`, `telemetry`, `billing`) and **per-tenant schemas** for usage detail and `audit_log` — hard separation at the database object level. Workspace switching (`X-Workspace-ID`) is validated against explicit membership so a principal cannot pivot to another tenant’s agents by header alone. Role matrix: [Security & permissions](security_permissions.md). --- ## Request path and enforcement A typical inference request: 1. **Terminates TLS** at the public edge (minimum TLS 1.2 on `apiKimss`). 2. **Authenticates** the caller (Entra session, bearer JWT, or Kimss API key). 3. **Resolves** workspace / vaulted endpoint / quota key from `iam` state. 4. **Routes** to your model provider through **APIM byo-proxy** after in-process vault unwrap. Inbound listeners are `POST /v1/chat/completions` (OpenAI) and `POST /v1/messages` (Anthropic). 5. **Emits** telemetry, execution logs, and billing events (GatewayLogs on byo-proxy, PostgreSQL usage, admin audit). ## Dual-layer security gateway (internal MCP) Identity-blind models cannot enforce Entra roles. Kimss authenticates the scoped API key, then matches the SSO payload to `iam.mcp_tool_grants` before an internal MCP tool runs. Hermis pauses on `tool_call`, evaluates the kill switch and tool-name allowlist, validates argument values against optional `iam.tool_argument_policies`, unwraps MCP `auth_headers` in memory via Azure Key Vault, executes, drops plaintext, and writes tenant `audit_log`. Argument-policy denials soft-fail as a tool result (logged as `argument_policy_violation`) so the agent can correct without aborting the chat. --- ## Auditability for AI activity - **Gateway logs**: Azure API Management diagnostic settings can send gateway events to Log Analytics for an immutable audit trail. Production APIM (`apikimss-apim`) targets **`kimssLogWorkSpace`** for **GatewayLogs**. - **Token and usage telemetry**: model token metrics with tenant and governance dimensions for cost allocation and operational dashboards. - **Admin audit trail**: tenant administration and API actions traceable to users, API keys, and workspace context. - **Threat Intercepts** (Production+): when guardrails block traffic (including argument-policy denials), Kimss retains timestamp, agent, trigger, and sanitized excerpt for security review and SIEM export. See [Guardrails](trust_safety.md). This architecture is intended to support EU AI Act Article 12-style record keeping. It does not certify that a customer's full system is compliant. ## Data residency model Tenant configuration maps each customer workspace to the model provider and gateway backends selected for that customer. The application does not rely on a client-supplied region header to decide where AI traffic goes. Confirm region during onboarding. ## Zero-trust model access Kimss avoids exposing model provider credentials directly to end users. Backend services unwrap vaulted customer keys in memory and hop through **APIM byo-proxy** to **your** HTTPS endpoint. Customers use Kimss session auth or Kimss API keys scoped to tenant permissions. Gateway policies enforce routing, telemetry, and content controls. ## Evidence customers commonly request During procurement or security review, customers usually ask for: - Logging fields, retention, and export process. - Region and tenant mapping for their workspace. - Identity model for browser sessions, API keys, and managed identity. - Role model for admins, contributors, readers, and audit access. - Plan-specific limits around telemetry, audit export, retention, or support response. ## What this document does not claim - A published SOC 2 Type II or ISO 27001 certificate number in public copy (attestations under NDA). - That Kimss blocks unmanaged consumer chat apps at the network edge. - That full prompt/completion SIEM export is available as a product toggle today. - That every registered agent is mid-flight killable if it never sends traffic through Kimss. ## Related - [Trust Center](https://kimss.ai/trust) - [Compliance framework mapping](compliance_framework_mapping.md) - [Security & permissions](security_permissions.md) - [Identity & SSO](identity_sso.md) - [Guardrails](trust_safety.md) - [Register agents and models](external_agents.md) - [Incident response (summary)](incident_response.md) - [Security testing & vulnerability management](security_testing.md) - [SDK & API](api_docs.md) Incidents: **security@kimss.ai**. Enterprise procurement: [Contact sales](https://kimss.ai/enterprise). --- ## Compliance framework mapping Source: https://kimss.ai/docs/compliance_framework_mapping Last-updated: 2026-08-22 # Compliance framework mapping Kimss maps product controls to common AI and security frameworks so procurement and security reviewers can see **how** the platform supports their obligations. This page is **alignment guidance**, not a certification claim and not legal advice. Formal attestations (for example SOC 2 Type II reports) are provided **under NDA** during procurement; your **order form / DPA** remains the legal source of truth. Related: [Security & Compliance](security_compliance.md) · [Security & permissions](security_permissions.md) · [Guardrails](trust_safety.md) ## How to read this page | Column | Meaning | |--------|---------| | **Framework theme** | Control area commonly asked about in RFPs | | **Kimss capability** | What ships in the product today | | **Evidence** | Where operators or auditors look | ## ISO/IEC 42001 (AI management system) — themes | Theme | Kimss capability | Evidence | |-------|------------------|----------| | Roles & accountability for AI systems | Tenant RBAC (Reader / Contributor / Admin); SCIM user/group lifecycle for enterprise | Admin Assign Role; SCIM `/scim/v2/*`; [Security & permissions](security_permissions.md) | | AI system inventory & ownership | Agent SSOT in `iam.agent_definitions`; ownership metadata; Governance → Agents | Governance → Agents; agent list `created_by` / `status` | | Risk treatment for AI tools | Guardrails (content safety thresholds, web/MCP gates, **argument-level tool policies**); governed-request caps; **agent kill switch** | Guardrails settings; Usage / Plan & Billing; disable agent (kill switch) in Governance → Agents | | Operational monitoring | Per-tenant usage and audit logs; optional APIM GatewayLogs | Usage reports; Audit report; [Security & compliance](security_compliance.md) | | Continual improvement | Settings changes audited; kill switch enable/disable audited | Audit actions `disable` / `enable` on entity `agent` | ## EU AI Act — record-keeping & governance themes Kimss does **not** certify that a customer’s end application is “high-risk” compliant. It provides **platform evidence** that supports Article 12-style record-keeping when AI traffic is routed through Kimss: | Theme | Kimss capability | Evidence | |-------|------------------|----------| | Logging of AI system activity | Tenant audit log; chat usage rows; optional immutable APIM **GatewayLogs** → Log Analytics | `POST /audit_log/`; usage tables; APIM diagnostics when gateway enabled | | Traceability of operators | Session JWT / API keys scoped to identity and workspace | [Identity & SSO](identity_sso.md) | | Human oversight / intervention | Admin **kill switch** blocks Invisible Proxy and `/v1/agents/run` for a disabled agent | Governance → Agents; `POST /agent_set_status/` | | Data & access control | Workspace isolation; least-privilege keys; tool registry allowlists; **tool argument constraints** | [Security & Compliance](security_compliance.md) | ## NIST AI RMF (Govern / Map / Measure / Manage) | Function | Kimss mapping | |----------|---------------| | **Govern** | RBAC, SCIM, workspace scoping, documented roles | | **Map** | Agent inventory (list + SSOT), risk posture badges (web search, BYO endpoint, no owner, stale usage, soft guardrails) | | **Measure** | Governed-request metering and token volume; risk flags computed from existing configuration/usage (no new telemetry pipeline required) | | **Manage** | Guardrails, over-cap **429** `governed_requests_exhausted`, kill switch, optional content-safety path via APIM | ## SOC 2–oriented control themes | Theme | Kimss capability | |-------|------------------| | Access control | Entra SSO, API keys, RBAC hierarchy | | Change / admin accountability | Per-tenant audit log for agent create/update/delete/disable/enable | | Monitoring | Usage aggregates; enterprise alerting webhooks (governed-request thresholds) | | Availability / abuse limits | Plan caps with hard **429**; rate limits on public API paths | **Formal SOC 2 report scope** is contractual and provided under NDA — not implied by this mapping table. ## Agent kill switch (operational control) Workspace **Admins** can set an agent to `disabled` from Manage Agents. While disabled: - `POST /v1/chat/completions`, `POST /v1/messages`, and `POST /v1/agents/run` return **403** (`agent_disabled`) when the call carries that agent id. `POST /assistant_chat/` returns **410 Gone**. - The agent remains visible on **Governance → Agents** with a Disabled badge so it can be re-enabled - Actions are written to the tenant audit log (`disable` / `enable`) API keys are **user/tenant-scoped**, not agent-scoped. Disabling an agent does **not** automatically revoke keys; revoke keys separately via API Keys if needed. ## What this page does **not** claim - Shadow-AI discovery across the corporate estate outside Kimss - Behavioral UEBA / anomaly detection as a product feature - Prompt-injection prevention as a core product guarantee - That enabling APIM alone makes a customer EU AI Act compliant ## Related - [Security & compliance architecture](security_compliance.md) - [AI agent security (marketing)](https://kimss.ai/ai-agent-security) - [Guardrails](trust_safety.md) - [SDK & API](api_docs.md) --- ## Incident response Source: https://kimss.ai/docs/incident_response Last-updated: 2026-08-22 # Kimss — Security Incident Response (Customer Summary) This document summarizes how Kimss handles **security incidents** that may affect customer data or service availability. It is **not** a substitute for your incident response plan or your contract / DPA; those control response times and legal obligations. ## Reporting - **Suspected security issues:** Email **security@kimss.ai** with subject line `SECURITY` and include tenant/workspace identifiers, timestamps, and any indicators of compromise. - **General enterprise / procurement:** **enterprise@kimss.ai** or the website **Contact Sales** form. ## Severity definitions (internal alignment) | Level | Description | Example | |-------|-------------|---------| | **Sev1** | Active exploitation or confirmed tenant data exposure | Confirmed unauthorized access to tenant-scoped data | | **Sev2** | High risk of exposure or widespread service impact | Misconfiguration exposing admin APIs without auth | | **Sev3** | Limited impact or no confirmed customer data access | Single-region degradation, suspicious activity contained | ## Customer notification (tenant-impacting) For **confirmed** security incidents that **materially impact a specific customer tenant** (Sev1 / Sev2 scoped to that tenant): 1. Kimss will notify the customer’s **designated security contacts** (as provided in the enterprise agreement or support profile) **within 24 hours** of confirmation of tenant impact. 2. **Weekends and public holidays:** If your contract specifies business hours only, those hours apply; otherwise calendar hours apply. 3. Kimss will provide **initial containment steps**, **ongoing status updates** at least every 48 hours while active, and a **written post-incident summary** including root cause analysis when available (typically within 30 calendar days of closure). ## Post-incident - **Remediation:** Tracked to completion; critical issues are prioritized for patch deployment. - **Regulatory:** Customers remain responsible for their own regulatory notifications; Kimss will provide reasonable cooperation and factual information subject to legal review. ## Document control - **Owner:** Kimss Security / Operations - **Review:** At least annually or after any major architecture change - **Related:** [Security & Compliance](security_compliance.md) · [Security testing](security_testing.md) --- ## Security testing Source: https://kimss.ai/docs/security_testing Last-updated: 2026-08-22 # Kimss — Security Testing & Vulnerability Management This page describes **how Kimss approaches vulnerability management and security testing**. It does not publish raw penetration-test reports (available under NDA for enterprise customers). ## Continuous practices 1. **Dependency updates** — Automated dependency update proposals (e.g. Dependabot) for Python and JavaScript ecosystems used in this repository. 2. **CI security checks** — Pull requests run static analysis and dependency scanning (e.g. Ruff, `pip-audit` with documented allowlists where needed). See `.github/workflows/main_apikimss.yml`. 3. **Code scanning** — GitHub **CodeQL** analysis for Python and JavaScript on default branches and PRs (see `.github/workflows/codeql.yml`). 4. **Change control** — Production changes flow through reviewed merges and automated deployment pipelines. ## Penetration testing - Kimss engages **independent third-party** penetration testing on at least an **annual** cadence for the production application and critical infrastructure. - Findings are tracked to remediation with severity-based SLAs aligned to internal security policy. ## Vulnerability disclosure - Report suspected vulnerabilities to **security@kimss.ai**. Do not perform destructive or availability-impacting tests without prior written authorization. ## Related documents - [Security & Compliance](security_compliance.md) - [Incident response (summary)](incident_response.md) --- ## Security & permissions Source: https://kimss.ai/docs/security_permissions Last-updated: 2026-09-12 # Security & permissions Kimss applies **role-based access control (RBAC)** per **tenant**, consistent with common enterprise expectations: strong authentication, **least privilege**, and **isolation** between customer organizations. ## Tenant isolation - **Data and configuration** are partitioned so one customer’s workspace does not expose assets to another. - **API keys** and **sessions** are scoped to identities within **your** tenant unless explicit federation features say otherwise. > [!NOTE] > Alignment with frameworks such as **ISO 27001**-style management or **SOC 2**-oriented practices is described at the **principles** level. Your **agreement**, **DPA**, and any **audit reports** you purchased remain the legal source of truth. ## Roles | Role | Scope | |------|--------| | **Reader** | Use existing agents; limited admin surfaces. | | **Contributor** | Create and maintain agents and tools allowed by policy; view tenant usage in many deployments. | | **Admin** | User lifecycle, roles, governed-request policy, billing links, API key governance, full admin console, **IAM groups** (cohorts / SCIM-linked grants). | ## Groups (optional) Some tenants use **IAM groups** (cohorts) for optional **role boosts** and **feature gates** managed by administrators or synced from Microsoft Entra via SCIM. Your effective permissions are still bounded by tenant RBAC and organization policy. | Action | Reader | Contributor | Admin | |--------|:------:|:-----------:|:-----:| | Chat with agents | Yes | Yes | Yes | | Create / edit **owned** agents | No | Yes | Yes | | Edit **shared** agents you don’t own | No | No | No | | **Disable / enable agents** (kill switch) | No | No | Yes | | Provider Vault / MCP servers | No | No | Yes | | Assign roles / SCIM setup | No | No | Yes | | API keys (own) | Yes* | Yes* | Yes* | | Audit log (tenant) | No | Yes† | Yes† | \* Subject to UI surfacing; keys inherit the **creator’s** permissions. † Exact visibility can depend on tenant configuration; treat **Admin** as the guaranteed role for sensitive exports. ## Agent kill switch Workspace **Admins** can **disable** an agent from **Governance → Agents** (or `POST /agent_set_status/`). While disabled: - Chat and run routes return **403** (`agent_disabled`) - The agent stays listed with a Disabled badge and can be re-enabled - Disable/enable events are written to the tenant **audit log** API keys are **not** automatically revoked (they are user/tenant-scoped). Revoke keys separately in **API Keys** if needed. Risk posture badges on **Governance → Agents** are informational (web search, BYO endpoint, missing owner, stale usage, soft workspace guardrails) and do not by themselves block chat. ## Audit and accountability **Administrative and API** actions are designed to be **traceable** to identities and keys for governance. Retention windows and export formats depend on your **plan** and **configuration**. Use the **Audit** report in the admin console where available. ## API inheritance API requests run as the **user who created the key**. A **Reader** key cannot perform **Admin-only** mutations even if the HTTP route exists—expect **403**. ## Related - [Security & Compliance](security_compliance.md) - [Identity & SSO](identity_sso.md) - [SDK & API](api_docs.md) - [Guardrails](trust_safety.md) - [Compliance framework mapping](compliance_framework_mapping.md) --- ## Identity & SSO Source: https://kimss.ai/docs/identity_sso Last-updated: 2026-09-12 # Identity & SSO Kimss is built for **workforce** use: each **tenant** (organization) has isolated users, roles, and configuration. Sign-in is typically wired to your company identity provider. ## Supported sign-in patterns | Pattern | Description | |---------|-------------| | **Microsoft Entra ID** | Employees sign in with their **work or school** account. | | **Google Workspace** | Organizations using Google as IdP. | | **Guest access** | Some tenants invite external collaborators as guests; rules depend on your admin configuration. | > [!NOTE] > Exact buttons and IdP labels in the UI follow your tenant’s setup. If a method is missing, ask your **Kimss admin** or IT owner. ## Roles after sign-in Kimss uses **Reader**, **Contributor**, and **Admin** roles. Your role controls whether you can create agents, vault Provider Vault / MCP endpoints, open billing links, or assign other users. See [Security & permissions](security_permissions.md) for the full matrix. Envelope encryption and client-write-only BYO keys are in [Security & Compliance](security_compliance.md). Internal MCP tools add a second gate after the API key: `iam.mcp_tool_grants` matches the Entra/SSO payload to a tool role. See [Trust Center](https://kimss.ai/trust). ## Enterprise provisioning (SCIM) Enterprise customers can provision users from **Microsoft Entra** (or compatible IdPs) using **SCIM 2.0**, so accounts appear in Kimss without manual invites. High-level operator steps: 1. Your platform team obtains a **SCIM base URL** and **bearer token** for your tenant. 2. In the IdP **enterprise application**, enable provisioning and map core attributes (`userName`, `displayName`, active status). 3. Run a test cycle and confirm users arrive with the expected **default role** (often **Contributor** until an admin tightens policy). 4. Optionally enable **group** provisioning so directory **security groups** sync into Kimss as **IAM groups** (cohorts). Group membership can attach optional **role boosts** and **feature entitlements** resolved at sign-in; see [Security & permissions](security_permissions.md) for how that combines with Reader / Contributor / Admin. > [!NOTE] > SCIM details (exact URL, secrets, and attribute maps) are **tenant-specific**. Your onboarding packet or admin console is the source of truth. ## Session and security hygiene - Use **managed devices** and your org’s browser policy where required. - **Sign out** on shared machines. - If the app says your **session expired**, refresh or sign in again—especially after password changes or conditional-access prompts. ## Related - [Troubleshooting](troubleshooting_faq.md) — auth and 401-style issues. - [Contact support](contact_support.md) — enterprise IdP or SCIM escalations. --- ## Guardrails Source: https://kimss.ai/docs/trust_safety Last-updated: 2026-09-12 # Guardrails (Trust & safety) Kimss exposes **provider-agnostic guardrails** for agents on the gateway. Admins configure them under **Governance → Guardrails** (`/app/guardrails`). ## What gets checked Depending on your configuration, checks run on **user input**, **tool context** (web/file/MCP results before they enter the model window), and **model output**. Azure AI Content Safety classifies Hate, Violence, Sexual, and Self-harm. User prompt attacks use Prompt Shields. The subscribed model (including Anthropic) does not self-judge harm. When a message is blocked, the product shows a **clear, non-technical** explanation instead of raw policy JSON. ## What you see as a user - A **blocked message** card may appear in chat with the **direction** (inbound vs outbound), **category**, and **severity** your admin configured. - You may be pointed to **Governance → Guardrails** (admin-only) or asked to contact your administrator if you believe the block is incorrect. ## What admins configure **Admins** can configure gateway guardrails and Kimss capability gates: 1. **Agent guardrail controls** — set **severity levels** (Low, Medium, High, Off) for risk categories such as Hate, Violence, Sexual, Self-harm, and User prompt attacks on prompts, tool context, and responses. 2. **Web Search** — **off by default**. Enabling requires explicit consent: agent search queries are executed by the **model provider's search service**, outside Kimss. Kimss gates attach-time access but does not inspect individual queries or results. Some provider projects with **private networking** cannot use web search (the control plane returns a clear error when you try to enable it). 3. **Internal MCP servers** — **off by default**. Enabling requires explicit consent; tool arguments are sent to customer-hosted MCP endpoints through the Kimss proxy. 4. **PII & secret scrubbing** (Production+) — **off by default**. Scans prompts and responses for emails, phones, credit cards, SSNs (hyphenated/`078-05-1120`, or contiguous 9 digits near “SSN” / “social security”), IPs, and common API keys / JWTs / Bearer tokens. **Alert** logs to Threat Intercepts and continues; **Block** returns HTTP 451. No extra model cost (in-process patterns). 5. **Tool argument policies** (Production+ to configure) — declarative constraints on the **argument values** Hermis may pass to a tool (not only which tools are allowed). Constraint types: `exact_match`, `allowlist`, `regex`, `deny_pattern`, `max_length`, `require_provenance`, plus optional `default_deny_unmapped` (deny argument names not listed in your constraints — never keyed off discovered MCP schemas). Configure under **Guardrails → Tool argument policies** or via REST. Violations **soft-fail**: the model receives a JSON tool result (`error: policy_violation`) so it can correct the payload; the chat is not aborted with HTTP 403. Rows appear in Threat Intercepts as `argument_policy_violation`. Enforcement still applies on Developer if policies already exist. 6. **Authority Boundary** (Production+) — **off by default**. When enabled, arguments marked `require_provenance` are allowed only if the value was named in the authenticated user message (or trusted config / approval) — not if it only appeared in tool output or retrieved data. Domain allow-lists remain necessary but not sufficient. Denials soft-fail with `error: authority_boundary` and appear in Threat Intercepts as `argument_taint`. The tool executor is never called on deny. ### Web Search — boundary detail When web search is enabled for a workspace: - Kimss allows agents to declare a web search tool only after the workspace opt-in and recorded consent (`web-egress-v1` or prior policy version). - Actual search execution happens on the **provider** infrastructure (for example Azure Grounding with Bing Search on Microsoft Foundry). Those queries are **not** processed under Kimss's control plane boundary. - Enterprise buyers should treat this as **egress** in their own risk review alongside your agreement and DPA. > [!NOTE] > Kimss does not replace your legal or compliance review. Your **agreement**, **DPA**, and internal policies remain authoritative. See [Foundry guardrails overview](https://learn.microsoft.com/en-us/azure/foundry/guardrails/guardrails-overview) for provider-native controls where applicable. ## API and automation Automated clients calling Kimss APIs — including Invisible Proxy `POST /v1/chat/completions` and Anthropic `POST /v1/messages` — may receive **HTTP 451** (or an application-level envelope) when content is blocked by policy. Integrations should treat this as **non-retryable** for the same payload unless an admin changes policy or the user edits the content. See [SDK & API](api_docs.md) for error handling patterns. Admin settings: - `GET/PUT /api/v1/settings/trust_safety` - `GET/PUT /api/v1/tool-policies` — list / upsert argument-level policies (PUT requires Production+) - `DELETE /api/v1/tool-policies/{id}` — soft-disable a policy (Production+) - `GET /api/v1/agents/{agent_id}/effective-tool-policy?tool=` — resolved tenant + agent overlay ## Threat Intercepts (paid plans) When a guardrail **blocks** traffic (content safety, prompt injection, web search egress, MCP egress, **argument policy**, **Authority Boundary / argument taint**) — or when **PII scrub** is set to alert/block — Kimss writes an async row to `telemetry.gateway_intercepts`. **Production, Scale, and Enterprise** workspaces can review under **Monitoring & Security → Threat Intercepts** (`/app/intercepts`). Each row includes timestamp, agent identity, trigger reason, and a sanitized payload excerpt (truncated prompt hash + metadata — not a full prompt archive). Retention follows your plan (`billing.plan_catalog.retention_days`). Scale and Enterprise include **Export to SIEM** (JSON/CSV of the filtered view). **Enterprise** can also stream each new intercept live to NOC webhooks via event type `threat_intercept.recorded` (opt-in on the webhook endpoint). Developer tier enforces guardrails but does not include the Threat Intercepts dashboard — upgrade to Production for blocked-traffic forensics. ## Related - [Security & Compliance](security_compliance.md) — vault, metadata-only telemetry, kill switch. - [Security & permissions](security_permissions.md) — roles and audit visibility. - [Troubleshooting](troubleshooting_faq.md) — blocked messages and session recovery. --- ## Register agents and models Source: https://kimss.ai/docs/external_agents Last-updated: 2026-08-22 # Register agents and models Kimss is the **control plane**. Your providers stay the **data plane**. This page is the short path to put existing agents and vaulted models (OpenAI-compatible or native Anthropic) under Kimss identity, kill switch, and audit. > **Order:** Complete [Provider Vault](custom_model_endpoints.md) and a [Gateway API key](quick_start.md) before routing traffic. See [Onboarding paths and naming](onboarding_paths.md). In-app: **Agents Discovery** for inventory after traffic, or **Gateway Connection** snippets. Endpoint governance (token caps) lives in **Provider Vault**. ## Three trust tiers | Tier | What you do | Trust label | Typical time | |------|-------------|-------------|--------------| | **1 — Register** | Declare an externally built agent; Kimss returns `agent_id` | Inventory only | A few minutes | | **2 — Report** | Push token usage from your runtime | **self-reported** | One helper + two env vars | | **3 — Route** | Vault each model in **Provider Vault**; call Kimss with `custom:` | **gateway-verified** | Same as [Provider Vault (BYO)](custom_model_endpoints.md) | Self-reported rows are never Article 12–grade evidence. Routed traffic is. Cryptographic isolation of vaulted keys and the metadata-only proxy contract are in [Security & Compliance](security_compliance.md). ## 1. Register an external agent Works for LangChain, OpenAI Assistants, Copilot Studio, in-house bots — anything you already run. Kimss does **not** create a Foundry agent. It writes `iam.agent_definitions` with `origin=external` and an `ext-…` id. **UI:** Agents appear in Agents Discovery after the first call with `X-Kimss-Agent-Id`. To register via API before traffic, use the SDK below. Set token caps on the vaulted endpoint in Provider Vault. **SDK** (API key with **management** scope): ```python from kimss import KimssClient client = KimssClient(api_key="kimss_...", base_url="https://api.kimss.ai") row = client.agents.register( name="Support bot", framework="langchain", models=["gpt-4o"], purpose="Customer support", risk_tier="limited", ) print(row["agent_id"]) # ext-… ``` **REST:** ```http POST /v1/agents/register X-Kimss-Key: kimss_... Content-Type: application/json { "name": "Support bot", "framework": "langchain", "models": ["gpt-4o"], "purpose": "Customer support", "risk_tier": "limited" } ``` Optional fields: `description`, `owner`, `endpoint_url`, `external_ref`. The kill switch (`status=disabled` on Agents Discovery) **rejects** later usage events for that id. For agents that never call Kimss, that is advisory. For traffic that sends `X-Kimss-Agent-Id` through the gateway, a disabled agent is **403**. ## 2. Report usage (optional) Use this when inference stays on **your** SDK and you still want Usage / audit inventory. Requires a **run**-scoped API key. Each event counts as **one governed request**. Over-cap returns **429** `governed_requests_exhausted` — events are never silently dropped. ```python client.usage.report([{ "agent_id": "ext-…", "correlation_id": "unique-per-call", "model": "gpt-4o", "prompt_tokens": 120, "completion_tokens": 40, }]) ``` ```http POST /v1/usage/events X-Kimss-Key: kimss_... Content-Type: application/json { "events": [{ "agent_id": "ext-…", "correlation_id": "unique-per-call", "model": "gpt-4o", "prompt_tokens": 120, "completion_tokens": 40 }] } ``` Max 25 events per call. On your own streaming OpenAI-compatible client, set `stream_options={"include_usage": True}` so the provider puts tokens in the final SSE chunk. Do not estimate. ## 3. Register a model endpoint (Route) When you want Kimss to **proxy** chat completions (identity, kill switch, gateway logs): 1. Vault the provider base URL under **Governance → Provider Vault** (OpenAI-compatible or native Anthropic). 2. Call completions with `"model": "custom:"`. 3. Traffic is **zero-rated** for Kimss compute and labeled **gateway-verified**. Full steps (health check, API, rotate keys, troubleshooting): [Connected Infrastructure (BYO)](custom_model_endpoints.md). **OpenAI inbound** (`base_url` includes `/v1`): ```python from openai import OpenAI llm = OpenAI(api_key="kimss_...", base_url="https://api.kimss.ai/v1") llm.chat.completions.create( model="custom:acme-ft-v1", messages=[{"role": "user", "content": "Hello"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, ) ``` **Anthropic inbound** — official SDK appends `/v1/messages`. Set `base_url` to `https://api.kimss.ai` (**not** `.../v1`): ```python from anthropic import Anthropic llm = Anthropic(api_key="kimss_...", base_url="https://api.kimss.ai") llm.messages.create( model="custom:acme-ft-v1", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, ) ``` Same vaulted `custom:`, same kill switch, same governed-request meter. Azure official clients are not inbound — vault Azure and call through one of the listeners above. See [Quick start](quick_start.md). ## What to show procurement | Surface | Path | |---------|------| | Agent inventory + kill switch | `/app/agents` | | Usage / Activity (governed requests + request log) | `/app/audit` | | Tracking (where agents last ran) | `/app/agents/tracking` | | Audit | `/app/audit/log` | Plans and caps: [Plans & subscriptions](plans_subscriptions.md). Metering: [Usage & governed requests](usage_credits.md). ## Related - [Connected Infrastructure (BYO)](custom_model_endpoints.md) - [BYO FAQ](teams_byo_and_custom_models_faq.md) - [SDK & API](api_docs.md) - [Quick start](quick_start.md) --- ## Connected Infrastructure (BYO) Source: https://kimss.ai/docs/custom_model_endpoints Last-updated: 2026-08-22 # Connected Infrastructure (BYO) Register a **customer-hosted model** — **OpenAI-compatible** (`POST /chat/completions`) or **native Anthropic** (`POST /v1/messages`, `x-api-key`). Kimss vaults the endpoint, proxies chat completions through APIM, records audit events, and applies workspace policies. **Inference on your endpoint is never billed as Kimss compute** — you pay your provider; Kimss meters a **governed request**. UI: **Governance → Provider Vault** — [/app/governance/custom-models](/app/governance/custom-models) (Legacy URLs `/app/settings/custom-models` and `/app/governance/connected-infrastructure` redirect here.) API keys are **client-write-only**: list/register/update/rotate never return the secret. Update via `PATCH /api/v1/custom-model-endpoints/{model_id}` (optional `api_key` — omit to keep the vaulted secret). Rotate via `POST /api/v1/custom-model-endpoints/{model_id}/rotate`. Envelope encryption (AES-GCM + Azure Key Vault RSA-OAEP-256) is documented in [Security & Compliance](security_compliance.md). ## When to use BYO Use Connected Infrastructure when you want Kimss governance (identity, kill switch, audit) while running inference on **your** infrastructure — Foundry projects you own, fine-tuned models, GPU clusters, or cost-optimized open-source stacks. Eligible on **Production**, **Scale**, and **Enterprise** (workspace **admin**). Developer (free) is for PLG sandbox evaluation — vault production endpoints on a paid plan. See [Plans & subscriptions](plans_subscriptions.md), [Register agents and models](external_agents.md), and the [BYO FAQ](teams_byo_and_custom_models_faq.md). ## API contract Kimss expects Set **provider** when you register. Paths are relative to **base URL**. ### OpenAI-compatible / Azure OpenAI Base URL usually ends in `/v1` (or an Azure deployment path). | Call | Method | Path | Auth | |------|--------|------|------| | Health check (on register) | `GET` | `{base_url}/models` | `Authorization: Bearer` | | Chat completion (runtime) | `POST` | `{base_url}/chat/completions` | Bearer (injected by APIM) | ### Native Anthropic Base URL is `https://api.anthropic.com` (**no** trailing `/v1`). Runtime path is `/v1/messages`. | Call | Method | Path | Auth | |------|--------|------|------| | Health check (preferred) | `POST` | `{base_url}/v1/messages` | `x-api-key` + `anthropic-version` | | Health check (discovery) | `GET` | `{base_url}/v1/models` | same — only after Messages succeeds, to populate the model picker | | Messages (runtime) | `POST` | `{base_url}/v1/messages` | `x-api-key` (injected by APIM) | The `model_id` you register (e.g. `acme-ft-v1` or `claude-sonnet-4-5`) becomes `custom:acme-ft-v1`. At runtime Kimss strips the `custom:` prefix and sends that id as `"model"` upstream. Hermis still uses an OpenAI-shaped tool loop; the Anthropic adapter translates tools and messages before APIM. **Use a workspace-scoped key.** Create the API key **inside** the Anthropic Workspace you want (Console → that Workspace → Settings → API keys). Org-level *Default* / identity-linked (all-workspaces) keys are rejected by Anthropic unless every request names a workspace; Kimss does not collect Workspace ID — register a workspace-scoped key instead. Do **not** use an Admin key (`sk-ant-admin…`). ## Call Kimss (inbound) vs vault a provider (outbound) These are two different hops: | Direction | What you do | Host / path | |-----------|-------------|-------------| | **Inbound (Invisible Proxy)** | Your app calls **Kimss** with a Kimss API key | OpenAI: `https://api.kimss.ai/v1` → `POST /v1/chat/completions`. Anthropic: `https://api.kimss.ai` → `POST /v1/messages` (do not set Anthropic `base_url` to `.../v1`) | | **Outbound (this page)** | Kimss calls **your** vaulted provider | OpenAI-compatible `POST {base}/chat/completions` or native Anthropic `POST {base}/v1/messages` | You can vault Anthropic as the backend **and** keep using the official Anthropic client against Kimss. You can also vault Azure OpenAI and still call Kimss with the OpenAI **or** Anthropic listener. Azure official clients are **not** inbound drop-ins. ## Host your own OpenAI-compatible endpoint Kimss does **not** install or operate models in your cluster. Common options: ### Option A — Ollama (CPU-friendly, quick test) [Ollama](https://ollama.com/) serves an OpenAI-compatible API on port `11434` under `/v1`. ```bash ollama pull llama3.2:1b ollama serve curl http://localhost:11434/v1/models ``` **Azure Container Apps (public HTTPS):** deploy `ollama/ollama` with external ingress; reference manifest: `scripts/byo/ollama-containerapp.yaml`. Then `base_url` is `https:///v1`. ### Option B — vLLM (GPU) ```bash vllm serve mistralai/Mistral-7B-Instruct-v0.3 --api-key sk-your-secret ``` ### Option C — Your own gateway Any reverse proxy that forwards `GET /v1/models` and `POST /v1/chat/completions` with OpenAI-shaped JSON, on a **public** hostname Kimss can reach. ## Reachability and security | Allowed | Blocked | |---------|---------| | Public hostnames with **`https://`** (required in production) | `http://` URLs in production | | Standard DNS names | `localhost`, `127.0.0.1`, `::1` | | Paths preserved (use `/v1` suffix) | Private IP ranges (10.x, 172.16–31.x, 192.168.x) | | | `.local` / `.internal` hostnames | Secrets are encrypted at rest (Fernet or Key Vault RSA-OAEP envelope). Use HTTPS and a real API key. See [Security & Compliance](security_compliance.md) for the `enc.v3` wrap. > [!NOTE] > Local development may register `http://` endpoints for Ollama on localhost. Production (`kimss.ai` / App Service) rejects non-HTTPS `base_url` values at registration and on proxy resolve. ## Register in the UI 1. Sign in as a workspace **admin** on Production, Scale, or Enterprise. 2. Open **Governance → Provider Vault** and stay on the **Endpoints** tab (MCP servers has its own tab). 3. **Add endpoint** — a three-step wizard guides setup: - **Connect** — pick provider, enter **required credentials only** (API key; Azure also needs Endpoint; self-hosted needs Base URL). Required fields are marked with `*`. **Test connection** verifies reachability and discovers models (no model id yet). **Skip test** jumps to manual model entry. - **Model** — pick **one** discovered model (or enter the model id / Azure deployment name manually). Display name is optional (defaults to the model id). - **Guardrails** (optional) — toggle a monthly token cap, pick **Alert only** vs **Block at cap**, and select alert threshold chips. You can **Skip — register now** without caps. 4. **Register & verify** runs the same health check as before. On success the reference is `custom:`. **Edit** uses a sectioned form (Connection + Guardrails) with **Test connection** (reuses the vaulted key when the API key field is blank). The endpoints table shows a **Usage / cap** column (`month_tokens_used` / `monthly_token_cap` and percent used for the current billing month). | Status | Meaning | |--------|---------| | **Healthy** | Reachable; auth accepted or not required | | **Warning** | Reachable but unexpected HTTP status | | **Error** | Unreachable, `401`, or upstream `5xx` | ## Register via API ```http POST /api/v1/custom-model-endpoints Authorization: Bearer Content-Type: application/json { "display_name": "Acme fine-tuned LLM", "base_url": "https://models.acme.example/v1", "api_key": "sk-...", "model_id": "acme-ft-v1", "provider_type": "openai", "monthly_token_cap": 5000000, "cap_action": "block", "alert_thresholds": [50, 80, 90, 100] } ``` `display_name` is optional (defaults to `model_id`). Self-hosted endpoints may omit `api_key` when the upstream requires no auth. Update an existing endpoint (omit `api_key` to keep the vaulted secret; use `clear_monthly_token_cap: true` to remove a cap): ```http PATCH /api/v1/custom-model-endpoints/acme-ft-v1 Content-Type: application/json { "monthly_token_cap": 10000000, "cap_action": "alert" } ``` ```http GET /api/v1/custom-model-endpoints POST /api/v1/custom-model-endpoints/test DELETE /api/v1/custom-model-endpoints/acme-ft-v1 POST /api/v1/custom-model-endpoints/acme-ft-v1/rotate ``` **Pre-flight test** (wizard / edit **Test connection**; does not vault credentials): ```http POST /api/v1/custom-model-endpoints/test Content-Type: application/json { "provider_type": "openai", "base_url": "https://models.acme.example/v1", "api_key": "sk-..." } ``` Response: `{ "status": "ok"|"warn"|"error", "latency_ms", "models": ["..."], "error_hint" }`. For edit flows, omit `api_key` and pass `model_id` to reuse the vaulted secret. List responses include `month_tokens_used`, `cap_pct_used`, and `usage_year_month` when a cap is configured. They **never** include decrypted keys. Ineligible plans return `403` with `{"error": "plan_not_eligible"}`. Custom `alert_thresholds` require **Enterprise**. ## Monthly token caps (provider spend guardrails) Per-endpoint caps limit **provider tokens** on a vaulted model — separate from your Kimss **governed request** allowance. | Field | Meaning | |-------|---------| | `monthly_token_cap` | Optional monthly token budget (input + output tokens summed from provider `usage`) | | `cap_action` | `alert` (default) — email workspace admins at thresholds; `block` — return **429** `custom_endpoint_cap_exceeded` when usage ≥ cap | | `alert_thresholds` | Percentages that trigger email (default `50, 80, 90, 100`). Custom arrays are **Enterprise** only | | `clear_monthly_token_cap` | PATCH only — remove the cap | **Packaging** | Capability | Plans | |------------|-------| | Set cap (`alert` or `block`) | Production, Scale, Enterprise (any plan that can vault endpoints) | | Email alerts at thresholds | All eligible plans (admins with usage alert permission) | | Custom threshold percentages | Enterprise | | NOC webhook on threshold crossings | Enterprise | Caps meter from gateway-verified `usage` on proxied calls and from telemetry ingest for self-reported events. Counters reset each calendar month (`usage_year_month`). ## Use in completions and agents ```json { "model": "custom:acme-ft-v1", "messages": [{"role": "user", "content": "Hello"}] } ``` Anthropic clients send the same `model` on `POST /v1/messages` (`base_url=https://api.kimss.ai`, `max_tokens` required). Kimss proxies to your endpoint, returns the upstream shape, increments **governed requests**, and records telemetry as **zero-rated** for Kimss compute (`source=gateway_verified` on the proxy path). Bind agents to `custom:` the same way; bindings are audited. Kill switch on the agent still severs tool access at the gateway. ## Verify 1. Completion with `"model": "custom:"` — content from **your** model. 2. **Audit Log** — `/app/governance/audit-log`. 3. **Usage** — governed request counted; token volume when usage is present; no Kimss compute charge for BYO. 4. Endpoint remains **Healthy** on Connected Infrastructure. ## Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | `base_url must not point to private or local addresses` | Localhost / private IP | Public FQDN or cloud ingress | | `authentication failed` | Upstream `401` | Fix API key / bearer auth | | `anthropic-workspace-id is required ...` / identity-linked key | Org-level Default / all-workspaces Anthropic key | In Anthropic Console open the **specific Workspace** → Settings → API keys → create a **workspace-scoped** key and register that. Not an Admin key (`sk-ant-admin…`). Skip test will not bypass this. | | `403 plan_not_eligible` | Free tier or non-admin | Upgrade; use admin role | | `429 custom_endpoint_cap_exceeded` | Monthly token cap with `cap_action=block` | Raise cap, wait for next month, or set `cap_action=alert` | | `http://` rejected in production | Non-HTTPS base URL | Use `https://` on a public hostname | | Completion works but wrong metering | Missing `custom:` prefix | Use exact `custom:` | | Provider Vault missing | Stale shell | Hard refresh; open `/app/governance/custom-models` | ## Limits (today) - Proxied mode — Kimss calls your public endpoint; it does not run inside your VPC. - Kimss does not install, scale, or patch models in your cluster. - Token counts depend on the `usage` object your endpoint returns; the gateway injects `stream_options.include_usage` on streaming where supported. - Per-endpoint token caps are a customer guardrail on provider spend — they do not replace Kimss governed-request billing. See [Usage & governed requests](usage_credits.md). ## Related - [BYO & Connected Infrastructure FAQ](teams_byo_and_custom_models_faq.md) - [Plans & subscriptions](plans_subscriptions.md) - [Usage & governed requests](usage_credits.md) - [Models & metering](models_pricing.md) - [SDK & API](api_docs.md) --- ## Routing Internal MCP Servers Source: https://kimss.ai/docs/routing_internal_mcp_servers Last-updated: 2026-08-16 # Routing Internal MCP Servers Kimss is the **secure proxy** between your chosen model and your internal Model Context Protocol (MCP) servers. You do not expose databases or internal APIs directly to an unmanaged model. Every tool call is mapped to a verified SSO identity, checked against the agent kill switch and RBAC, then executed with vaulted credentials that never leave the control plane in plaintext. This is **not** the [Kimss Python SDK MCP server](/docs/python_sdk_mcp) (IDE → Kimss API). This page is the **inbound** path: Studio agents → Kimss Hermis → your MCP server. ## Flow ```text User (Entra SSO tid/oid) → Kimss proxy (identity, kill switch, audit) → Customer model (tool_calls only) → Kimss decrypts auth headers in memory → Customer MCP server (tools/call) → Result back to the model ``` Register servers under **Governance → Provider Vault → MCP servers**. Attach them to an agent under **Studio → Tools → Attach MCP Server**. Enable the tenant opt-in under **Account → Guardrails**. ## Vault Auth headers (for example `{"Authorization":"Bearer …"}`) are stored in `iam.mcp_servers.auth_headers_encrypted` using the same **AES-GCM + Azure Key Vault KEK** envelope (`enc.v3`) as Connected Infrastructure model keys. List and GET responses never return decrypted headers. Rotate is write-only. The MCP URL must be **public HTTPS** reachable from Kimss (same SSRF rules as BYO model endpoints). Private RFC1918 addresses are rejected. ## Runtime controls 1. **Kill switch** — `iam.agent_definitions.status = disabled` severs the Hermis loop mid-hop, including MCP tools. 2. **Guardrails** — tenant `mcp_enabled` consent is required before register/attach/execute. 3. **Agent allowlist** — only discovered tools you toggle for that agent are injected into the model `tools` array (`mcp__{server}__{tool}`). 4. **RBAC** — callers need contributor or admin. If `iam.mcp_tool_grants` rows exist for the server, they become authoritative (role, Entra oid, or group). 5. **Argument-level tool policies** — after name allowlist and RBAC, Hermis validates proposed arguments against `iam.tool_argument_policies` (workspace-wide or per-agent). A violation soft-fails as a JSON tool result and logs `argument_policy_violation` to Threat Intercepts; the MCP `tools/call` never runs. 6. **Audit** — each execution writes tenant `audit_log` (`tool_execute`) and a zero-token `telemetry.ai_requests` row (`correlation_id` `mcp-tool-*`, `path` `/mcp/tools/call`) labeled `gateway_verified`. MCP does not add a separate SKU; the parent model turn is one **governed request**. Provider tokens stay on your Azure / OpenAI / Anthropic bill. ## Verify (operators) Use a public HTTPS dummy MCP (Kimss rejects localhost). The in-repo dummy is `scripts/mcp_dummy_server.py` (`echo` and `ping`). Tunnel it with ngrok, then run `scripts/e2e_mcp_routing_verify.py` with `KIMSS_E2E_API_KEY` and `KIMSS_E2E_MCP_URL`. Checks: Guardrails block when MCP is off; GET `/api/v1/mcp-servers` never returns vaulted `Authorization` headers; discover populates tools; Hermis injects the decrypted Bearer in-memory; toggling a tool off never reaches the MCP `tools/call`; agent kill switch returns `agent_disabled`; tenant `audit_log` maps `tool_execute` to the SSO oid and `telemetry.ai_requests` records `mcp-tool-*` with zero tokens. ## Related - [Connected Infrastructure (BYO)](/docs/custom_model_endpoints) - [Register agents and models](/docs/external_agents) - [Guardrails](/docs/trust_safety) - [Security & Compliance](/docs/security_compliance) --- ## BYO & Connected Infrastructure FAQ Source: https://kimss.ai/docs/teams_byo_and_custom_models_faq Last-updated: 2026-08-22 # BYO & Connected Infrastructure — FAQ Quick answers for teams that vault **their own model endpoints** on Kimss. > [!NOTE] > Docs URL slug `/docs/teams_byo_and_custom_models_faq` is retained for existing links. The former seat-priced BYO business SKU is **retired** — use Production / Scale / Enterprise + Connected Infrastructure. ## What replaced the retired seat-priced BYO SKU? That SKU was a seat-priced, credit-light business plan. The current product meters **unlimited workspace members** (paid tiers) by **governed requests**. You vault endpoints under **Connected Infrastructure** and pay your model provider directly for tokens. See [Plans & subscriptions](plans_subscriptions.md) and [kimss.ai/pricing](https://kimss.ai/pricing). ## What is Connected Infrastructure? You register a **customer-hosted** endpoint: OpenAI-compatible (`GET /models`, `POST /chat/completions`) or **native Anthropic** (`GET /v1/models`, `POST /v1/messages`, `x-api-key`). Kimss proxies through APIM, records audit events, applies policies, and counts **governed requests**. Inference on your endpoint is **not** sold as Kimss compute. Setup: [Connected Infrastructure (BYO)](custom_model_endpoints.md). ## Where do I configure endpoints in the app? 1. Sign in as a workspace **admin** on **Production**, **Scale**, or **Enterprise**. 2. Open **Governance → Provider Vault** Direct link: [/app/governance/custom-models](/app/governance/custom-models) 3. **Add endpoint** — choose OpenAI-compatible, Azure OpenAI, or Anthropic; display name, model id, base URL, API key (write-only; never shown again). 4. Use `"model": "custom:your-model-id"` on inbound OpenAI (`POST /v1/chat/completions`) or Anthropic (`POST /v1/messages`). ## Which plans can vault custom endpoints? | Plan | Connected Infrastructure | Typical use | |------|--------------------------|-------------| | Developer (free) | Limited / PLG sandbox | Evaluate the control plane | | **Production** | Yes | Unlimited workspace members, 100k governed requests | | **Scale** | Yes | Higher volume + longer retention | | **Enterprise** | Yes | SCIM, SIEM, custom volume | ## How do I call Kimss from an Anthropic SDK? Point the official client at Kimss, not at `api.anthropic.com`: ```python from anthropic import Anthropic client = Anthropic(api_key="kimss_...", base_url="https://api.kimss.ai") client.messages.create( model="custom:your-vaulted-model", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, ) ``` The SDK appends `/v1/messages`. Do **not** set `base_url` to `https://api.kimss.ai/v1`. Auth also accepts `x-api-key: kimss_...` or `X-Kimss-Key`. Azure official clients are not inbound — vault Azure and use this listener or the OpenAI listener. ## How am I billed for BYO traffic? - Each accepted routed or reported call = **1 governed request** against your plan allowance. - Provider tokens are **your** Azure/OpenAI/etc. bill. Kimss does not estimate that invoice. ## What shows up in Usage and Audit? - **Usage / Activity** — governed request consumption vs included, plus the retained request log (trust-labeled). - **Tracking** — live topology of where agents last ran (call-site clusters). - **Audit Log** — identity-aware trail for routed calls. - **Provider Vault** — per-endpoint token usage vs optional monthly cap (`month_tokens_used` / `monthly_token_cap`). ## Can I cap provider token spend on one vaulted model? Yes. On **Production**, **Scale**, and **Enterprise**, workspace admins can set an optional **monthly token cap** per vaulted endpoint in Provider Vault. Choose **alert** (email at 50/80/90/100%) or **block** (HTTP **429** `custom_endpoint_cap_exceeded`). This limits tokens on **your** provider bill — it is separate from Kimss **governed requests**. **Enterprise** can customize threshold percentages and send NOC webhooks. See [Connected Infrastructure (BYO)](custom_model_endpoints.md) and [Usage & governed requests](usage_credits.md). ## Does Kimss require HTTPS for my endpoint URL? **Yes in production.** Registration and runtime proxy resolve reject `http://` base URLs on the live service. Use a public `https://` hostname (or test locally in dev with `http://` on localhost only). ## Related docs - [Register agents and models](external_agents.md) - [Plans & subscriptions](plans_subscriptions.md) - [Connected Infrastructure (BYO)](custom_model_endpoints.md) - [Usage & governed requests](usage_credits.md) - [Models & metering](models_pricing.md) --- ## Product integrations & execution logs Source: https://kimss.ai/docs/product_integrations Last-updated: 2026-09-12 # Product integrations & execution logs Kimss records **SDK and integration execution context** so admins can see **where agents and LLM calls run in the product**, attribute governed requests, and review traffic outside Studio. ## Gateway — in-browser proof loop **Vault** (`/app/vault`) is the integration console for BYO endpoints and go-live snippets. After a successful governed call, recent rows appear in **Activity** (`/app/audit`). Use **Tracking** (`/app/agents/tracking`) for live topology of where agents last ran. **Studio** (`/app`) is where users build and test sandbox agents; Vault + API Keys are for first governed call and BYOI register/report/route. ## Who can see execution logs? | Role | Access | |------|--------| | **Enterprise admin** | **Tracking** (`/app/agents/tracking`) and **Activity** (`/app/audit`) | | **Individual users** | Profile usage summary; full execution log UI is oriented to workspace admins | ## What is captured? Each row typically includes: - **Host environment** (`host_environment`) — named call site when the client sends `X-Kimss-SDK-Context` (Python `kimss.gateway_headers()` or legacy `KimssClient`). - **Inferred runtime** (`caller_runtime`, `caller_sdk`, `caller_os`, `caller_ip`) — auto-captured from `User-Agent` and `x-stainless-*` on gateway traffic when SDK context is absent (no customer code required). - **Source file** (`source_location`) — the first non-SDK stack frame (e.g. `workflows/growth.py`). - **Agent** or **model** used, API **path**, **auth** channel - **Governed requests** and optional **token volume** when telemetry is attributed - **Timestamps** and correlation IDs for support Data is stored in PostgreSQL (`telemetry.agent_execution_logs`) and exposed via: - `GET /api/v1/telemetry/execution-summary` - `GET /api/v1/telemetry/filters` - `GET /api/v1/telemetry/agent-tracking` (Tracking canvas) ## Tracking (admin UI) **Tracking** shows live topology clustered by call site (named `X-Kimss-SDK-Context` or inferred runtime), with status from the latest governed request. The retained per-request list is **Activity** (`/app/audit`). Audit log is admin actions. > **Deprecated:** the former **Call Sites** page (`/app/governance/integrations`) redirects to Tracking. Bookmarks and old docs that mention Call Sites should use Tracking or Activity instead. ## SDK developers When calling `POST /v1/chat/completions` or Anthropic `POST /v1/messages` through the Invisible Proxy, send `X-Kimss-Agent-Id` (and optional `X-Kimss-Agent-Name`) so JIT inventory and Tracking stay attributed. For named environments in **Agent Tracking**, use Python `kimss.gateway_headers(agent_id=...)` as `extra_headers` (adds `X-Kimss-SDK-Context`). Manual header details: [SDK & API](api_docs.md). **Cursor / Windsurf / Claude Desktop users:** the Kimss **MCP server** (`pip install 'kimss[mcp]'`, `kimss-mcp-server`) sends the same headers as the Python client for tool-backed calls. See **[Python SDK: MCP & IDEs](python_sdk_mcp.md)** for client configuration and security notes (API keys in MCP `env`, file upload tools, workspace id). ## Related - [Quick start](quick_start.md) - [Usage & governed requests](usage_credits.md) - [SDK & API](api_docs.md) --- ## Agent configuration Source: https://kimss.ai/docs/creating_agents Last-updated: 2026-08-22 # Agent configuration & deployment This guide covers how to **create**, **scope**, and **iterate** on **AI agents** in Kimss—binding a vaulted `custom:` model from Connected Infrastructure with instructions and tools. Retrieve on your side and pass grounded `messages` through the gateway. Already-running agents (LangChain, Copilot Studio, in-house) belong in the [external registry](external_agents.md), not this Studio create flow. ## Agent vs model chat | | **Agent** | **Direct model completion** | |---|-----------|------------------------------| | **Persona** | Custom instructions and tools | Raw model messages | | **Sharing** | Personal or shared with tenant | Per-user / API sessions | | **Best for** | Repeatable workflows | Scripts and BYO `custom:` calls | Both count toward **governed requests**. Prefer agents + Connected Infrastructure over any leftover Model Playground bookmarks (those surfaces are retired). See [Models & metering](models_pricing.md) and [Usage & governed requests](usage_credits.md). ## Visibility: personal, shared, workspace - **Personal** — Only you (and admins with oversight) see the agent in the builder list. Use for drafts and experiments. - **Shared** — Published for colleagues per your tenant rules. Non-owners can **chat** but generally **cannot** change instructions or tools (enforced server-side with **403** on update APIs). - **Workspace / org** — Naming in the UI may vary; the important distinction is **owner vs consumer**: owners edit, consumers chat unless policy says otherwise. > [!NOTE] > Once visibility is set, changing it may be restricted for non-admins. Plan your **Personal → Shared** promotion path before go-live. ## Create flow (summary) 1. Open **Create** (or **New agent**) from Studio (`/app`). Studio requires at least one vaulted Connected Infrastructure endpoint. 2. Set **name**, **model** (Connected Infrastructure `custom:`), and **instructions**. 3. Choose **visibility** (personal vs shared). 4. Optionally enable **code interpreter**, **web search** (tenant Guardrails opt-in required), **functions**, and attached **MCP servers**. Kimss does **not** host vector stores or RAG — retrieve on your side and pass grounded `messages` through the gateway ([Agent knowledge](data_assets.md), [Retrieval on your side](agentic_rag.md)). 5. Save and run a **test conversation** before sharing. ## Instructions (prompt) best practices - **Tone and format** — Specify audience, length, and output shape (Markdown, bullets, JSON). - **Boundaries** — Say what the agent must **refuse** or **hand off** to humans. - **Tool use** — If functions are enabled, describe when to call them and what inputs look like. ## Modify after deploy - **Owners** can update instructions, tools, and attachments for agents they created. - **Shared agents you do not own** — chat only; edits return **403** from the API (see [SDK & API](api_docs.md)). ## Troubleshooting | Issue | Check | |-------|--------| | Teammates don’t see a shared agent | Visibility, role, and admin **sharing** policy. | | Tool or interpreter greyed out | Your **role** or tenant feature flags (web search and MCP need Guardrails opt-in). | | Weak answers with documents | Retrieval happens in **your** app — confirm chunks in `messages`. Kimss does not index a knowledge base. | ## Connect from your codebase After your agent is configured (instructions, tools, optional retrieval on your side): 1. Open **Gateway** (`/app/gateway`) and select the agent (or use JIT discovery with `X-Kimss-Agent-Id`). 2. Copy the **1-Line .env**, OpenAI client, or Anthropic client snippet. 3. Deploy — each governed call counts toward your plan. OpenAI: `base_url="https://api.kimss.ai/v1"`. Anthropic: `base_url="https://api.kimss.ai"` (SDK appends `/v1/messages`). See [Quick start](quick_start.md) and [SDK & API](api_docs.md). ## Related - [Quick start](quick_start.md) - [Register agents and models](external_agents.md) - [Security & permissions](security_permissions.md) --- ## Agent knowledge Source: https://kimss.ai/docs/data_assets Last-updated: 2026-08-22 # Agent knowledge Kimss does **not** host vector stores, document ingest, or RAG. Retrieve on your side (your search index, your MCP tools, your app) and send the already-augmented `messages` array through the Invisible Proxy — OpenAI `POST /v1/chat/completions` or Anthropic `POST /v1/messages`. The former Studio **Data** tab and Governance **Data Assets** page are removed. Bookmarks to `/app/governance/data-assets` redirect to Studio. ## Pattern 1. Your application retrieves relevant chunks from your own store. 2. You include those chunks in the prompt / `messages` you send to Kimss. 3. Hermis routes that payload (plus attached MCP tool schemas) to the subscribed model. It does not query pgvector or generate embeddings for knowledge. `POST /v1/files/upload` remains for **ephemeral model attachments** (short-lived Redis blobs for completions), not a knowledge base. ## Related - [Agent configuration](creating_agents.md) - [Retrieval on your side](agentic_rag.md) - [Connected Infrastructure (BYO)](custom_model_endpoints.md) - [Quick start](quick_start.md) --- ## Retrieval on your side Source: https://kimss.ai/docs/agentic_rag Last-updated: 2026-08-22 # Retrieval on your side Kimss is a control plane: identity, security, audit, and tool routing. It does **not** ingest documents, generate embeddings for RAG, or query an internal vector store. Customers retrieve on their infrastructure and pass the augmented `messages` through the gateway. Hermis then routes that payload plus attached MCP tool schemas. ## What changed - Studio **Data** tab, File Search, and `/api/v1/rag/documents` are gone (HTTP **410** `rag_deprecated`). - Public `POST /v1/vector_stores/create` and `POST /v1/vector_stores/{id}/files` return **410**. - The Python SDK no longer exposes `client.vector_stores` or MCP `kimss_create_vector_store`. - `POST /v1/files/upload` remains for ephemeral completion attachments only. ## Agentic pattern (Invisible Proxy + tools) Retrieve in **your** app, then call Kimss through the native OpenAI client (`POST /v1/chat/completions`) or Anthropic client (`POST /v1/messages`): ```python from openai import OpenAI client = OpenAI(api_key="kimss_...", base_url="https://api.kimss.ai/v1") grounded = "Context from our index:\n" + my_retriever("returns policy") client.chat.completions.create( model="custom:your-vaulted-model", messages=[{"role": "user", "content": grounded + "\n\nWhat is our returns policy?"}], extra_headers={"X-Kimss-Agent-Id": "support-rag"}, ) ``` ```python from anthropic import Anthropic client = Anthropic(api_key="kimss_...", base_url="https://api.kimss.ai") client.messages.create( model="custom:your-vaulted-model", max_tokens=1024, messages=[{"role": "user", "content": grounded + "\n\nWhat is our returns policy?"}], extra_headers={"X-Kimss-Agent-Id": "support-rag"}, ) ``` For client-side tool loops with the optional Kimss Python SDK, see [SDK & API](api_docs.md) — advanced path only. ## Web Search **Agents → Web column** (`/app/agents`) toggles Hermis `web_search` (Bing Web Search REST or `KIMSS_WEB_SEARCH_HTTP_URL`). A tenant admin must enable it under **Account → Guardrails**. ## Related - [Agent knowledge](data_assets.md) - [Agent configuration](creating_agents.md) - [Quick start](quick_start.md) --- ## Environments & agent portability Source: https://kimss.ai/docs/environments_and_agent_portability Last-updated: 2026-09-12 # Environments and agent portability Kimss stores **agent definitions** in its control-plane database (Hermis). Your vaulted provider is the **data plane** for inference. That separation keeps agents portable when you change Connected Infrastructure endpoints. ## What lives where | Asset | Kimss SSOT | Provider | |-------|------------|----------| | Instructions, model, tools, metadata | Yes (`iam.agent_definitions`) | Inference only | | Knowledge / RAG | No — retrieve on your side; see [Agent knowledge](data_assets.md) | Your search index or MCP tools | | Conversation threads | Yes (`orchestration.threads` / messages) | Not migrated across workspaces | ## Upgrade: Developer → Production / Scale / Enterprise Kimss does **not** provision a hosted model runtime when you upgrade. You keep the same workspace, vaulted endpoints (OpenAI-compatible, Azure OpenAI, or native Anthropic), and Hermis agents. Billing moves to governed-request allowances on the paid plan. **Chat history stays in the workspace.** Export separately if you need an archive. ## Clone environments (QA → staging → prod) Promote agent definitions and vault a matching endpoint in the target workspace. Contact Kimss support for operator-led clones. Hosted-runtime migration jobs are **not** the customer product path. ## Bring your own model See [Connected Infrastructure (BYO)](custom_model_endpoints.md). Custom endpoints change where **inference** runs; agent definitions still live in Kimss. Call the gateway with OpenAI (`/v1/chat/completions`) or Anthropic (`/v1/messages`). ## Related - [Plans & subscriptions](plans_subscriptions.md) - [Why Kimss](why_kimss.md) - [Quick start](quick_start.md) --- ## Plans & subscriptions Source: https://kimss.ai/docs/plans_subscriptions Last-updated: 2026-08-15 # Plans & subscriptions Kimss is a **Secure Enterprise Agent Control Plane**. Metering is by **governed requests** — not seat-metered credit packs and not compute resale. Public list: [kimss.ai/pricing](https://kimss.ai/pricing). In-app: **Plan & Billing**. ## Feature matrix (what you get) | Capability | Developer (free) | Production / Scale / Enterprise | |------------|:----------------:|:-------------------------------:| | Agents inventory, Tracking, kill switch | Yes | Yes | | Playground, Guardrails, Activity, Vault, Keys, Onboarding | Yes | Yes | | **Threat Intercepts** (blocked-traffic dashboard) | — | Yes | | **Tool argument policies** (configure constraints) | — (enforcement if policies exist) | Yes | | **Authority Boundary** (provenance / taint on sinks) | — | Yes | | **Team & Access** (members / invites) | — (solo) | Yes (unlimited members) | Paid-only product surfaces are **Threat Intercepts**, **Team & Access**, **Tool argument policies** (configuration), and **Authority Boundary**. Agents and the rest of the control-plane sidebar are included on free Developer. Argument-policy *enforcement* still runs on Developer if policies already exist. Hermis **HITL approvals** for irreversible tools are planned for **Scale+** (not yet generally available). ## Current lineup | Plan | Price | Workspace members | Governed requests | Retention | Notes | |------|-------|-------------------|-------------------|-----------|-------| | **Developer** | Free | Solo (owner only) | 25,000 / month (hard 429 over cap) | 14 days | PLG default — includes Agents | | **Production** (mid-market) | $49 / mo ($441 / yr) | Unlimited (Team & Access) | 100,000 included; **$16** per additional 100k | 30 days | Threat Intercepts included | | **Scale** | $199 / mo ($1,791 / yr) | Unlimited | 1,000,000 included; **$8** per additional 100k | 90 days | SSO + longer retention | | **Enterprise** | Custom | Unlimited | Negotiated | Custom | SCIM, SIEM export, invoice/PO | Overage is priced per **governed request** (per 100k block), not by token volume, so the control plane cost stays decoupled from underlying provider inference spend. Production is the mid-market tier; its **$16 / 100k** overage is the billing SSOT (Stripe `STRIPE_PRICE_GOVERNED_REQUESTS_PRODUCTION`), matched by `billing.plan_catalog` (migration 124). ## What is a governed request? One **governed request** = one accepted event in the control-plane telemetry trail (proxied Tier 3 call, self-reported Tier 2 usage event, or Hermis-orchestrated step). A batch `POST /v1/usage/events` with N events counts as N requests. Correlation-id dedupe prevents double counting. Over-cap behavior: **429** `governed_requests_exhausted` — never a silent drop of audit events. ## Control plane vs data plane | Layer | Who pays | What Kimss meters | |-------|----------|-------------------| | **Control plane** (Kimss) | Your Kimss plan | Governed requests, retention, identity, kill switch, audit | | **Data plane** (your providers) | Your Azure / OpenAI / Anthropic / etc. bill | Token spend on your accounts — Kimss does not estimate that invoice | BYO / gateway-routed inference is **zero-rated** for leftover credit-tracking columns. You are not buying model compute from Kimss. ## Connected Infrastructure caps (provider tokens) Optional **per-endpoint monthly token caps** on vaulted models are a spend guardrail on your provider bill — not Kimss governed-request overage. | Capability | Developer | Production / Scale | Enterprise | |------------|:---------:|:------------------:|:----------:| | Vault custom endpoints | Yes | Yes | Yes | | **Threat Intercepts** (blocked-traffic log) | — | Yes (retention follows plan) | Yes (+ custom retention / SIEM) | | **Team & Access** | — | Yes | Yes | | Set monthly token cap (`alert` or `block`) | — | Yes | Yes | | Email threshold alerts (50/80/90/100%) | — | Yes | Yes | | Custom alert threshold percentages | — | — | Yes | | NOC webhook on threshold crossings | — | — | Yes | Details: [Connected Infrastructure (BYO)](custom_model_endpoints.md) and [Usage & governed requests](usage_credits.md). ## Retired from sale These labels may still appear in older invoices or internal `plan_tier` rows, but they are **not** offered on `/pricing`: - Pro, Pro+, Ultra (individual credit packs) - Legacy team SKUs that billed by seat and light credit bundles (retired; use Production / Scale / Enterprise) - One-time top-up packs and auto-recharge as the primary bill If you still see leftover “credits” labels in a legacy workspace view, treat them as **tracking-only** unless Support says otherwise. The customer bill is **governed requests**. ## How to buy | Path | Where | |------|--------| | Self-serve | [/pricing](https://kimss.ai/pricing) or `/app/signup` | | Enterprise contract | [/enterprise](https://kimss.ai/enterprise) | ## Related - [Register agents and models](external_agents.md) - [Usage & governed requests](usage_credits.md) - [Models & metering](models_pricing.md) - [Connected Infrastructure (BYO)](custom_model_endpoints.md) - [Identity & SSO](identity_sso.md) --- ## Usage & governed requests Source: https://kimss.ai/docs/usage_credits Last-updated: 2026-08-22 # Usage & governed requests Kimss meters **control-plane traffic** as **governed requests**. It does **not** bill you for model tokens as a compute reseller, and it does **not** estimate what you pay your model provider. > [!NOTE] > The docs URL slug remains `/docs/usage_credits` for stable links. Product language is **governed requests**. ## What counts? | Event | Counts as governed request? | Kimss invoice impact | |-------|----------------------------|----------------------| | Routed call through Connected Infrastructure / APIM proxy (`POST /v1/chat/completions` or Anthropic `POST /v1/messages`) | Yes | 1 request; inference **zero-rated** (you pay the provider) | | Self-reported `POST /v1/usage/events` batch item | Yes (per event) | 1 request; trust level **self-reported** | | Hermis / Studio agent step accepted into telemetry | Yes | 1 request | Correlation-id dedupe prevents double counting the same logical call. ## Caps and overage - **Developer (free):** 25k governed requests / month — over cap returns **429** `governed_requests_exhausted`. - **Production:** included allowance, then **$16 per additional 100k**. - **Scale:** included allowance, then **$8 per additional 100k** (see [Plans & subscriptions](plans_subscriptions.md)). - **Enterprise:** negotiated volume and retention. Mid-tier subscriptions that predate the 2026-08-23 overage change keep their prior metered rate until they change plans (new Production signups use **$16 per additional 100k**). Over-cap is always an **explicit 429** for both routed and self-reported traffic — audit events are never silently dropped. ## Per-endpoint token caps (Provider Vault) Workspace **governed requests** and **per-endpoint token caps** are different meters: | Meter | What it limits | Kimss bill? | Where configured | |-------|----------------|-------------|------------------| | **Governed requests** | Control-plane events (proxied calls, usage reports, Hermis steps) | Yes — plan allowance + overage | Plan & Billing | | **Endpoint token cap** | Provider tokens on one vaulted `custom:*` model | No — guardrail on **your** provider invoice | Provider Vault | Optional caps on [Connected Infrastructure](custom_model_endpoints.md) endpoints sum input + output tokens from provider `usage`. With `cap_action=block`, exhausted caps return **429** `custom_endpoint_cap_exceeded` before the upstream call. With `cap_action=alert`, Kimss emails workspace admins at configured thresholds (50/80/90/100% by default). Enterprise workspaces may set custom thresholds and NOC webhooks. The Provider Vault table shows `month_tokens_used` / `monthly_token_cap` for the current month. This does not reduce your governed-request counter — each proxied call still counts as one governed request. ## Where to look in the app | Surface | Path | Purpose | |---------|------|---------| | **Usage / Activity** | `/app/audit` | Governed-request meter plus the retained per-request log | | **Tracking** | `/app/agents/tracking` | Live topology of where agents last ran (call-site clusters) | | **Plan & Billing** | `/app/billing` | Plan, workspace members, token volume by model | | **Audit Log** | `/app/audit/log` | Identity-aware trail | Legacy **Telemetry**, **FinOps**, pool-tracking, **Models**, and **Call Sites** tabs are hidden; old URLs redirect to Activity, Tracking, Plan & Billing, or Provider Vault. ## Trust levels | Label | Meaning | |-------|---------| | **gateway-verified** | Traffic went through the Kimss proxy / APIM path with provider usage capture | | **self-reported** | Customer systems pushed token counts via the usage API / SDK reporter | | **recorded** | Older or untagged ingest (formerly unlabeled / kimss-hosted) | Never treat self-reported rows as Article 12–grade gateway evidence. ## Permissions (summary) | Capability | Reader | Contributor | Admin | |------------|:------:|:-----------:|:-----:| | Personal / agent activity | Yes | Yes | Yes | | Workspace usage | No | Yes | Yes | | Plan & cap policy | No | No | Yes | ## Related - [Plans & subscriptions](plans_subscriptions.md) - [Models & metering](models_pricing.md) - [Register agents and models](external_agents.md) - [Connected Infrastructure (BYO)](custom_model_endpoints.md) - [Security & permissions](security_permissions.md) --- ## Models & metering Source: https://kimss.ai/docs/models_pricing Last-updated: 2026-08-22 # Models & metering Kimss is a **Model-Agnostic Enterprise Gateway**. You run models on **your** providers (Azure OpenAI, OpenAI-compatible endpoints, native Anthropic, registered external agents). Kimss governs identity, routing, kill switch, and audit — and meters **governed requests**, not a Kimss credit catalog of hosted deployments. ## How models show up | Path | Where | Metering | |------|-------|----------| | **Provider Vault** | Governance → Provider Vault (`/app/governance/custom-models`) | Vaulted BYO (OpenAI-compatible or native Anthropic); routed traffic is gateway-verified and metered as governed requests | | **External agent registry** | [Register agents and models](external_agents.md) — `POST /v1/agents/register` + optional `POST /v1/usage/events` | Inventory + self-reported usage (trust-labeled) | The old **Model Playground / Try models** surface and the public “23 Kimss-hosted deployments” catalog are **deprecated** as the primary product. Do not plan procurement around buying Kimss-hosted model compute. ## Token volume Usage and Plan & Billing may show **token counts** when the gateway sees a provider `usage` object. Kimss does **not** convert those tokens into dollars — BYO rates are on your provider contract, not the Kimss catalog. ## API access List and complete against vaulted models with the same API keys and permission model as agents. Prefer `custom:` on inbound OpenAI `POST /v1/chat/completions` (`base_url=https://api.kimss.ai/v1`) or Anthropic `POST /v1/messages` (`base_url=https://api.kimss.ai`). See [SDK & API](api_docs.md). ## Commercial pricing Plan tiers and governed-request allowances: **[kimss.ai/pricing](https://kimss.ai/pricing)** and [Plans & subscriptions](plans_subscriptions.md). ## Related - [Usage & governed requests](usage_credits.md) - [Register agents and models](external_agents.md) - [Connected Infrastructure (BYO)](custom_model_endpoints.md) - [BYO & Connected Infrastructure FAQ](teams_byo_and_custom_models_faq.md) - [SDK & API](api_docs.md) --- ## SDK & API Source: https://kimss.ai/docs/api_docs Last-updated: 2026-09-01 # Kimss SDK & API: Production Integration Guide This is the authoritative reference for integrating **Kimss** into production. Kimss is the **Model-Agnostic Enterprise Gateway** (control plane): you register agents, vault OpenAI-compatible or native Anthropic models, and run governed chat/agent traffic. Providers remain the data plane. **Recommended integration — Invisible Proxy (dual-listener):** keep your native **OpenAI** or **Anthropic** client. OpenAI: `base_url="https://api.kimss.ai/v1"`. Anthropic: `base_url="https://api.kimss.ai"` (SDK appends `/v1/messages`). Use your Kimss API key. See **§ 6.0** and [Quick start](quick_start.md). **Optional:** the Kimss Python SDK (`KimssClient`) for register/report flows and advanced agent runs. **Bring your own agents or models in minutes:** [Register agents and models](external_agents.md) and [Connected Infrastructure (BYO)](custom_model_endpoints.md). **Public SDK source and releases:** [github.com/kimss-ai/kimss-python-sdk](https://github.com/kimss-ai/kimss-python-sdk) (mirrored from this monorepo’s `kimss_sdk/`). **IDE integration (MCP):** see [Python SDK: MCP & IDEs](python_sdk_mcp.md). For **plans, metering, and model choice** from a product perspective, see **Plans & subscriptions**, **Models & metering**, and **Usage & governed requests** in this documentation. --- ## 1. Architecture & integration overview In a typical production setup: - **Management:** **Agent** inventory and kill switch live in the **Kimss web app** (Agents Discovery); **model catalog** visibility and toggles (where your tenant has them) are also managed in-app or via supported **admin** and **API** operations. - **Execution (recommended):** **OpenAI** clients at `https://api.kimss.ai/v1` or **Anthropic** clients at `https://api.kimss.ai` with a Kimss API key — no app rewrite. - **Execution (optional):** **Kimss Python SDK** or **REST** with long-lived **API keys** (`X-Kimss-Key`). - **Models:** When the **universal model gateway** is on for your tenant, you can **list** models the same identity is allowed to use (see **§ 6.3**), alongside existing **agent** endpoints. - **Ownership model:** You may **chat** with any agent you can see, but you can only **modify** (update instructions, add functions) **agents you created**—**shared** agents are **read/chat** for non-owners, enforced with **403** on update paths. --- ## 2. Installation ### Python (verified clean env) ```bash pip install kimss ``` Requires **Python ≥ 3.10**. Declared runtime dependency: **`requests>=2.28`**. For the Invisible Proxy you only need **`openai`** and/or **`anthropic`**; install **`kimss`** when you use the optional control-plane SDK. ### Java (Maven / Gradle) Coordinates: **`ai.kimss:kimss-java`** (JDK 11+). Source: monorepo `kimss_java_sdk/` (mirrored like the Python SDK). Published on [Maven Central](https://central.sonatype.com/artifact/ai.kimss/kimss-java). The Developer Hub **Java** tab also shows JDK `HttpClient` + `X-Kimss-Key` with no Maven deps. ```xml ai.kimss kimss-java 0.1.2 ``` ```kotlin implementation("ai.kimss:kimss-java:0.1.2") ``` ### Optional PyPI extras The same **`kimss`** package on PyPI supports optional dependency groups: | Extra | Command | Purpose | |-------|---------|---------| | **MCP** | `pip install 'kimss[mcp]'` | Stdio **Model Context Protocol** server (`kimss-mcp-server`) for Cursor, Windsurf, Claude Desktop, and other MCP clients. | | **Privacy** | `pip install 'kimss[privacy]'` | Optional PII redaction (Presidio) for sensitive pipelines. | | **Types** | `pip install 'kimss[types]'` | Reserved for future typed models. | | **Dev** | `pip install 'kimss[dev]'` | Test and lint tooling for contributors. | Full MCP setup (Cursor / Windsurf / Claude Desktop `mcpServers`, environment variables, tool list) is documented in **[Python SDK: MCP & IDEs](python_sdk_mcp.md)**. ### Development / Editable mode ```bash cd kimss_sdk pip install -e . # or with MCP + dev tooling: pip install -e ".[dev,mcp]" ``` --- ## 3. Authentication & Configuration ### 3.1 API Key Provisioning API access requires a **long-lived API key**. **Steps** 1. In the Kimss application navigate to: ``` Gateway → Generate Key ``` (Same secrets under **Governance → API Keys**.) 2. Generate a new API key. 3. Copy the key immediately. The secret is displayed **only once**. **Security Recommendations** - Store keys in environment variables - Use secret managers (Azure Key Vault, AWS Secrets Manager, etc.) - **Never commit API keys to version control** --- ### 3.2 Connectivity Initialize the client with the canonical Kimss API host. For production, use `https://api.kimss.ai` with **no trailing slash**. ```python from kimss import KimssClient client = KimssClient( api_key="kimss_xxxxxxxxxxxxxxxxxxxxxxxx", base_url="https://api.kimss.ai" # No trailing slash ) ``` --- ## 4. Capability & Permission Matrix Permissions are enforced **server-side** based on the user identity tied to the API key. | Feature | Scope | SDK Support | REST Endpoint | |--------|------|-------------|--------------| | Chat / Inference (OpenAI) | Vaulted models + attributed traffic | Yes (OpenAI client) | **POST `/v1/chat/completions`** (`base_url=https://api.kimss.ai/v1`) | | Chat / Inference (Anthropic) | Vaulted models + attributed traffic | Yes (Anthropic client) | **POST `/v1/messages`** (`base_url=https://api.kimss.ai`) | | Chat / Inference (optional SDK) | Accessible agents | Yes | **POST `/v1/agents/run`** | | Register external agent | Management API key | Yes (`client.agents.register`) | POST `/v1/agents/register` | | Report BYO usage | Run API key | Yes (`client.usage.report`) | POST `/v1/usage/events` | | Vault BYO model endpoint | Workspace admin | REST | POST `/api/v1/custom-model-endpoints` | | Update BYO endpoint / token cap | Workspace admin | REST | PATCH `/api/v1/custom-model-endpoints/{model_id}` | | Tool argument policies | Workspace admin (Production+) | REST | `GET/PUT /api/v1/tool-policies`, `DELETE /api/v1/tool-policies/{id}`, `GET /api/v1/agents/{id}/effective-tool-policy?tool=` | | Create agent | Privileged / policy | Yes (`client.agents.create`) | POST `/v1/agents/create` | | List agents (inventory) | Personal + Shared | Studio UI | **Agents Discovery** in Studio — not a public golden-path REST surface | | Delete | In-app | No | N/A | **Connected Infrastructure cap fields** (register/update body): `monthly_token_cap`, `cap_action` (`alert`|`block`), `alert_thresholds` (Enterprise only for custom arrays), `clear_monthly_token_cap` (PATCH). List responses add `month_tokens_used`, `cap_pct_used`, `usage_year_month`. Blocked caps return **429** `custom_endpoint_cap_exceeded`. See [Connected Infrastructure (BYO)](custom_model_endpoints.md). **Tool argument policies** (Production+ to configure): constrain Hermis tool-call argument values with `exact_match`, `allowlist`, `regex`, `deny_pattern`, or `max_length` per argument name. Optional `default_deny_unmapped` rejects argument keys not listed in your constraints. PUT body example: ```json { "tool_selector": "mcp__mail__send_message", "constraints": { "to": { "type": "regex", "pattern": ".+@yourco\\.com$" } }, "default_deny_unmapped": false } ``` Violations soft-fail as a JSON tool result (`error: policy_violation`) and log `argument_policy_violation` to Threat Intercepts. See [Guardrails](trust_safety.md). --- ## 5. Detailed Permission Logic ### 5.1 Visibility (Listing) **Preferred:** use Studio **Agents Discovery** (`/app` → Agents) to see personal, shared, and discovered agents for your workspace. Legacy root route `POST /assistant_user_list/` may still exist with `Deprecation` / `Sunset` headers for internal Studio and ops tooling. New customer integrations should **not** depend on it. --- ### 5.2 Ownership & Modification (The 403 Rule) To preserve organizational integrity, **Shared agents cannot be modified via API**. #### Authorized Updating instructions or adding functions to agents where: ``` created_by == current_user ``` #### Unauthorized Attempting to modify an agent shared with you will return: ``` 403 Forbidden ``` Example error: ``` Editing is only allowed for agents you own. This agent is shared with you; you can view and chat but not modify it. ``` --- ## 6. SDK Implementation ### 6.0 Invisible Proxy (recommended) Kimss inbound is **dual-listener**. Keep the native SDK you already use. **OpenAI** — set in `.env`: ```env OPENAI_BASE_URL=https://api.kimss.ai/v1 OPENAI_API_KEY=kimss_... ``` ```python from openai import OpenAI client = OpenAI(api_key="kimss_...", base_url="https://api.kimss.ai/v1") resp = client.chat.completions.create( model="custom:your-vaulted-model", messages=[{"role": "user", "content": "Hello"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, # JIT inventory ) ``` **Anthropic** — the official client appends `/v1/messages`: ```env ANTHROPIC_BASE_URL=https://api.kimss.ai ANTHROPIC_API_KEY=kimss_... ``` ```python from anthropic import Anthropic client = Anthropic(api_key="kimss_...", base_url="https://api.kimss.ai") resp = client.messages.create( model="custom:your-vaulted-model", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], extra_headers={"X-Kimss-Agent-Id": "my-product-agent"}, ) ``` Send **`X-Kimss-Agent-Id`** so Kimss **JIT auto-discovers** the agent in **Governance → Agents**. Disable there for the **1-click kill switch** (**403** on later calls). Azure official clients are not inbound — vault Azure and call through one of the listeners above. Also available: `GET /v1/models`, streaming on both listeners, and `"model": "custom:"` after vaulting BYO endpoints. Full OpenAI-shape notes in **§ 6.3**; Anthropic inbound contract in **§ 6.0c**. ### 6.0b Register agents and vault models Kimss can inventory agents it does not host, and proxy models you already run. ```python from kimss import KimssClient client = KimssClient(api_key="kimss_...", base_url="https://api.kimss.ai") row = client.agents.register(name="Support bot", framework="langchain", models=["gpt-4o"]) client.usage.report([{ "agent_id": row["agent_id"], "correlation_id": "unique-per-call", "model": "gpt-4o", "prompt_tokens": 120, "completion_tokens": 40, }]) ``` Route inference through Kimss with `"model": "custom:"` after vaulting the endpoint. Full walkthrough: [Register agents and models](external_agents.md). ### 6.0c Anthropic inbound (`POST /v1/messages`) Same control plane as OpenAI chat: vault, catalog enablement, governed-request cap, Guardrails **451**, and kill switch **403**. | Item | Contract | |------|----------| | Host | `https://api.kimss.ai` — **do not** append `/v1` (the official SDK adds `/v1/messages`) | | Route | `POST /v1/messages` and `POST /v1/messages/` | | Auth | `x-api-key: kimss_...`, `X-Kimss-Key: kimss_...`, or `Authorization: Bearer kimss_...` | | Attribution | `X-Kimss-Agent-Id` (required for JIT inventory / kill switch); optional `X-Kimss-Agent-Name` | | Body | Anthropic Messages JSON: `model`, `messages`, `max_tokens` (required; default 1024 if omitted by some clients), optional `stream`, `system`, `temperature` | | Success | Anthropic `type=message` object (`content` text blocks, `usage.input_tokens` / `output_tokens`) | | Stream | Anthropic SSE (`message_start`, `content_block_delta`, `message_delta`, `message_stop`) | | Feature flag | Returns Anthropic-shaped **404** `feature_disabled` if the universal gateway is off for the environment | ```http POST /v1/messages x-api-key: kimss_... X-Kimss-Agent-Id: my-product-agent Content-Type: application/json { "model": "custom:your-vaulted-model", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}] } ``` ### 6.1 Agent interaction (optional Kimss SDK) For teams that prefer `KimssClient` over the Invisible Proxy, Kimss executes agents on the **gateway / Hermis** runtime using **conversations**. The JSON field **`thread_id`** is still the wire name for the **conversation id** returned from Kimss; new **Python SDK (v2+)** code uses the keyword **`conversation_id`**, which maps to `thread_id` in the POST body. **Optional — Python (`kimss` ≥ 2.0)** ```python from kimss import KimssClient client = KimssClient(api_key="...", base_url="https://api.kimss.ai") # First turn: omit conversation_id res = client.agents.run("asst_xxxx", "Summarize Q1 risks.", stream=False) cid = res.conversation_id # may be None if the service omits it for this tenant # Next turn: continue the same conversation follow = client.agents.run( "asst_xxxx", "Compare to Q4.", stream=False, conversation_id=cid, ) # Streaming: iterate SSE JSON chunks (same route) for chunk in client.agents.run("asst_xxxx", "Stream this answer.", stream=True): ... # handle dict events from Kimss / model stream ``` **Removed:** `POST /assistant_chat/` returns **410 Gone**. Use **`POST /v1/agents/run`**. --- ### 6.1b Custom JavaScript (embedded / white-label) Use **`fetch`** against **`POST https://api.kimss.ai/v1/agents/run`** with **`"stream": true`** and parse **`text/event-stream`** lines. The example below is self-contained (no Kimss npm package): keep your API key on the server in production; shown inline only for clarity. ```html Kimss stream demo 

  


```

Prefer **`POST /v1/agents/run`** with `"stream": true` for Kimss agent SSE. Do **not** use the legacy **`POST /assistant_chat_stream/`** route for new integrations.

**Key behavior**

- First request without **`thread_id`** / **`conversation_id`** starts a **new conversation**.
- Returning the **`thread_id`** from **`res`** (or SSE events) on the next call continues context.
- Kimss does **not** expose classic Assistants-style **run** polling for standard chat; use **streaming** or wait for the full **`res`** on non-stream calls.

---

### 6.2 Extending Capability (Functions)

Available for **Personal agents only**.

This registers a **tool definition** that the agent can invoke during execution.

```python
agent.add_function(
    name="get_order_status",
    description="Retrieve status for a specific order ID.",
    parameters={
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string"
            }
        },
        "required": ["order_id"]
    }
)
```

Functions must follow a **JSON schema** structure describing:

- function name
- description
- parameter definitions

---

### 6.3 Models and gateway (list / catalog / OpenAI-compatible)

When **universal gateway v2** is enabled for your tenant, you can query which **models** are available to the current principal for routing, UI, or automation. If these return **404** with `feature_disabled`, the feature is not active for that environment or tenant.

**List models (JSON body, authenticated — Kimss shape)**

```http
POST /v1/models/list
```

or the alternate path (same behavior):

```http
POST /v1/models/list/
```

**Response shape (simplified):** a JSON object whose `res.models` field contains a list of model records (ids, display metadata, and tenant enablement as implemented by the service). Use the response your tenant actually returns to drive dropdowns or server-side model selection.

**OpenAI-compatible list + chat (IDE / CLI gateways)**

Point any OpenAI-compatible client at `https://api.kimss.ai/v1` with your Kimss API key as `Authorization: Bearer kimss_...` (or send `X-Kimss-Key`). Anthropic Messages inbound is `POST /v1/messages` at host `https://api.kimss.ai` (see **§ 6.0**).

```http
GET /v1/models
POST /v1/chat/completions
POST /v1/messages
```

- `GET /v1/models` returns `{ "object": "list", "data": [ { "id": "custom:your-vaulted-model", "object": "model", ... } ] }` (`id` prefers vaulted `custom:` ids and catalog `logical_id` when mapped).
- `POST /v1/chat/completions` accepts a standard OpenAI chat body (`model`, `messages`, optional `stream`, `temperature`, `max_tokens` / `max_completion_tokens`). Non-stream responses are bare `chat.completion` objects (no Kimss `{"res": ...}` envelope). Streaming uses OpenAI chunk SSE ending with `data: [DONE]`.
- Prefer **`custom:`** from Provider Vault. Catalog `logical_id` values still resolve when mapped for your workspace.
- Governed-request caps, tenant enablement, and safety match `POST /v1/models/completions` and Anthropic `POST /v1/messages`.

Example (`openai` Python SDK):

```python
from openai import OpenAI

client = OpenAI(api_key="kimss_...", base_url="https://api.kimss.ai/v1")
print(client.chat.completions.create(
    model="custom:your-vaulted-model",
    messages=[{"role": "user", "content": "Hello"}],
).choices[0].message.content)
```

**Model settings catalog (browser or server-side with session / cookie auth as used by the app)**

```http
GET /api/v1/settings/models/catalog
```

Returns catalog rows for the **Model Catalog** / settings experiences; admin flows may also use **POST** `/api/v1/settings/models/toggle` to change tenant enablement where your role allows it (see product UI and your organization’s policy).

> [!NOTE]
> **Base URL:** call these on the canonical Kimss API host, `https://api.kimss.ai`, the same `base_url` used by `KimssClient`. **Public** `GET /api/v1/settings/models/catalog` is intended for **authenticated** browser or service patterns that already work with your Kimss session or approved integration model—**API key** traffic for model listing should use **POST** `/v1/models/list` (Kimss shape) or **GET** `/v1/models` (OpenAI shape).

---

### 6.4 MCP, streaming, Entra, and Usage Hub metadata

- **MCP (IDE tools):** Install `kimss[mcp]` (package **2.x** for `conversation_id` tool args) and run **`kimss-mcp-server`** (or `uvx --with kimss[mcp] kimss-mcp-server`). Exposes non-streaming tools for chat, `v1` agent run/create, model completions, file upload, and add-function. Hosted vector-store tools are **removed**. Configure **`KIMSS_API_KEY`**, optional **`KIMSS_BASE_URL`** and **`KIMSS_WORKSPACE_ID`**. See **[Python SDK: MCP & IDEs](python_sdk_mcp.md)**.
- **Streaming (library only):** `KimssClient.agents.run(..., stream=True)` and `KimssClient.models.create(..., stream=True)` return an SSE iterator. MCP v1 tools do not stream.
- **Microsoft Entra ID:** Headless workers can use `KimssClient(credential=DefaultAzureCredential(), token_scope="api:///.default", workspace_id=...)` instead of an API key. See the [public SDK README](https://github.com/kimss-ai/kimss-python-sdk/blob/main/README.md#authentication).
- **Usage Hub:** The Python SDK may send **`X-Kimss-SDK-Context`** (base64url JSON) on agent/model routes for attribution in **Product integrations**. Remove it with `before_request_hooks` if your policy forbids sending caller paths. See **[Product integrations & execution logs](product_integrations.md)**.

---

## 7. Direct REST Patterns (Non-SDK)

Developers can integrate Kimss using standard HTTP requests.

Authentication uses the header:

```
X-Kimss-Key: 
```

---

### Agent inventory

**Preferred:** Studio **Agents Discovery** for listing and kill-switch.

Legacy `POST /assistant_user_list/` is **deprecated** for customer integrations (may still serve Studio / internal tooling with `Deprecation` headers). Prefer [Register agents and models](external_agents.md) for inventory APIs (`POST /v1/agents/register`) and the Invisible Proxy for inference.

---

### Chat / Inference

**Recommended — Invisible Proxy**

```
POST /v1/chat/completions
Authorization: Bearer kimss_...
X-Kimss-Agent-Id: my-product-agent   # optional JIT attribution
```

Use the OpenAI client (`base_url=https://api.kimss.ai/v1`) or the Anthropic client (`base_url=https://api.kimss.ai`). See **§ 6.0**.

**Optional — Kimss agent run**

```
POST /v1/agents/run
```

Use the Kimss Python SDK when you need conversation threading via `KimssClient`. **`POST /assistant_chat/`** has been removed (**410 Gone**).

Example request body (non-stream, simplified — Universal AI Gateway v2 must be enabled for **`/v1/agents/run`**):

```json
{
  "assistant_id": "asst_xxx",
  "usr_chat": "Analyze this dataset",
  "stream": false,
  "chat_type": "user_chat"
}
```

Optional continuation: set **`thread_id`** to the **conversation id** returned in the previous **`res`** (same field name the SDK maps from **`conversation_id`**).

---

## 8. Error Reference

| Code | Status | Context |
|-----|------|--------|
| 401 | Unauthorized | Invalid, missing, or revoked `X-Kimss-Key` (or session bearer where applicable) |
| 403 | Forbidden | Attempted modification of a shared agent you do not own, or role insufficient for the route |
| 404 | Not Found | Invalid `assistant_id`, unknown **conversation** / **`thread_id`**, or feature disabled for the tenant (`feature_disabled` in body) |
| 429 | Too Many Requests | Usually **`governed_requests_exhausted`**, **rate limit**, or **subscription required**. Honor **`Retry-After`** when present. Legacy workspaces may still surface credit-pool error codes. |
| 451 | Unavailable For Legal Reasons | **Guardrails** block—do not retry the same harmful payload; see [Guardrails](trust_safety.md) |
| 500 | Server Error | Infrastructure anomaly; check system status |

Streaming and gateway responses may wrap errors in an envelope (`detail`, `message`, or nested JSON). Parse defensively and map **401** / **451** to user-safe messages.

---

## 9. Production Best Practices

### Environment Isolation

Use separate API keys for:

- **Development**
- **Staging**
- **Production**

---

### Stateless vs conversational automation

**Recommended:** use the **Invisible Proxy** — OpenAI `POST /v1/chat/completions` (`base_url=https://api.kimss.ai/v1`) or Anthropic `POST /v1/messages` (`base_url=https://api.kimss.ai`) — for one-shot and streaming flows.

**Optional SDK:** `KimssClient.agents.run(..., stream=False)` (or **`stream=True`**) for conversation threading. Use **`conversation_id`** (Python SDK ≥ 2) or JSON **`thread_id`** to continue a conversation.

### Timeout Management

The standard chat timeout is:

```
120 seconds
```

Ensure your application properly handles **long-running reasoning tasks**.

---

### Key Rotation

Periodically rotate API keys via:

```
Governance → API Keys
```

This mitigates the risk of credential leaks or compromise.

---

## 10. Support & Troubleshooting

If you encounter issues integrating with Kimss:

1. Verify your API key is valid and active.
2. Confirm your `base_url` is `https://api.kimss.ai` for production (or the documented staging host for staging).
3. Ensure your request headers include:

```
X-Kimss-Key: 
```

4. Check returned HTTP status codes using the error reference table above.
5. See [Troubleshooting](troubleshooting_faq.md) for browser cache, SSO, and common API codes.

For platform issues or infrastructure anomalies (HTTP 500 responses), consult the Kimss system status dashboard or contact platform support.

---

## 11. SDK versioning

The Kimss SDK follows semantic versioning:

```
MAJOR.MINOR.PATCH
```

- **MAJOR** — Breaking API changes (e.g. **2.0.0**: `thread_id` kwargs → **`conversation_id`** on the optional Kimss SDK).
- **MINOR** — New features without breaking compatibility
- **PATCH** — Bug fixes and performance improvements

Upgrade recommendations:

```
pip install --upgrade kimss
```

When **2.0.0** is on PyPI, pin major version in production requirements (`kimss>=2,<3`) until you have migrated call sites.

---

## Agent harness (open core)
Source: https://kimss.ai/docs/agent_harness
Last-updated: 2026-09-13

# Agent harness (open core)

`kimss-agents` is the **open-source agent harness**: build and run agents against any OpenAI-compatible model endpoint with **no Kimss account**. When production needs governance, connect the Kimss AI Gateway with one line.

> [!NOTE]
> **Open-core split**
>
> - **Free / MIT:** local multi-turn loop, `@tool` functions, optional MCP (`pip install 'kimss-agents[mcp]'`).
> - **Kimss Developer (free tier):** Invisible Proxy, identity, audit, **kill switch**, 25k governed requests/month.
> - **Paid (Production+ / Scale / Enterprise):** Authority Boundary, Team & Access, Threat Intercepts UI, PII scrub, SSO, SCIM.

Marketing overview: [/open-source](/open-source). Pricing: [/pricing](/pricing).

## Install

```bash
pip install kimss-agents
```

## Local (no Kimss)

```python
from kimss_agents import Agent, tool

@tool
def multiply(a: float, b: float) -> float:
    """Multiply two numbers."""
    return a * b

agent = Agent(model="gpt-4o-mini", tools=[multiply])
print(agent.run("What is 6 times 7?"))
```

Set `OPENAI_API_KEY` (and optionally `OPENAI_BASE_URL` for Azure/Foundry, Ollama, vLLM, etc.).

## Production via Kimss (one line)

1. Sign up → vault a model → mint a `kimss_...` workspace key ([Quick start](quick_start.md)).
2. Point the same `Agent` at the gateway:

```python
agent = Agent(
    model="custom:your-vaulted-model",
    tools=[multiply],
    gateway="kimss",
    agent_id="ops_bot",
    workspace_key="kimss_...",  # or KIMSS_API_KEY
)
```

This uses `https://api.kimss.ai/v1` and sends `X-Kimss-Agent-Id`. Disable the agent under **Agents** to enforce the [kill switch](/agent-kill-switch).

## Related packages

| Package | Role |
|---------|------|
| [`kimss-agents`](https://pypi.org/project/kimss-agents/) | OSS harness (this page) |
| [`kimss`](https://pypi.org/project/kimss/) | Optional control-plane client (register agents, report usage) — see [Python SDK: MCP & clients](python_sdk_mcp.md) |
| [Invisible Proxy](route_traffic.md) | Native OpenAI/Anthropic SDKs pointed at Kimss (no harness required) |

## Source

- GitHub: [kimss-ai/kimss-agents](https://github.com/kimss-ai/kimss-agents)
- Monorepo SSOT: `kimss_harness/` (mirrored to the public repo; do not treat public `main` as SSOT)

---

## Python SDK: MCP & clients
Source: https://kimss.ai/docs/python_sdk_mcp
Last-updated: 2026-08-22

# Python SDK: MCP, IDEs, and optional extras

This page describes **Model Context Protocol (MCP)** support and related capabilities of the **Kimss Python SDK** (`pip install kimss`). MCP lets **Cursor**, **Windsurf**, **Claude Desktop**, and other MCP-capable clients call Kimss as **tools** (chat, agents, models, files) without writing glue code.

For a **standalone local agent loop** that works without a Kimss account, see the open-core [Agent harness](agent_harness.md) (`pip install kimss-agents`).

> [!NOTE]
> **Production traffic:** Prefer the **Invisible Proxy** — OpenAI at `https://api.kimss.ai/v1` or Anthropic at `https://api.kimss.ai`, with your Kimss API key and `X-Kimss-Agent-Id` on each call. See [Quick start](quick_start.md) and [SDK & API](api_docs.md) § 6.0. Use `KimssClient` for control-plane tasks (register agents, usage report, uploads), not as the Golden Path for chat.

**Sources of truth**

- **PyPI package:** [kimss](https://pypi.org/project/kimss/) — install with `pip install kimss` or extras below.
- **Public mirror (source, issues, releases):** [github.com/kimss-ai/kimss-python-sdk](https://github.com/kimss-ai/kimss-python-sdk)
- **Dense machine-oriented context** (for AI assistants): [docs/llm-context.md](https://github.com/kimss-ai/kimss-python-sdk/blob/main/docs/llm-context.md) in that repository.

For permissions, REST shapes, and the full production integration story, see **[SDK & API](api_docs.md)** (start with **§ 6.0 Invisible Proxy**). To register existing agents or vault OpenAI-compatible / native Anthropic models: **[Register agents and models](external_agents.md)**.

---

## 1. What you get

| Surface | Purpose |
|---------|---------|
| **Library** (`KimssClient`) | Production integrations: agents, v1 routes, uploads, optional streaming, retries, typed errors. |
| **MCP server** (`kimss-mcp-server`) | IDE / desktop tools over **stdio**: same API, exposed as named tools for the assistant. **v1 tools are non-streaming** (full JSON responses only). |
| **Optional extras** | `mcp`, `privacy` (PII redaction), `types`, `dev` — see section 6. |

---

## 2. Install the MCP extra

**Option A — global / venv (classic)**

```bash
pip install 'kimss[mcp]'
```

Then run **`kimss-mcp-server`** on your `PATH`. The process reads configuration from **environment variables** (see §5); do not pass the API key on the command line.

**Option B — no local venv (`uvx`, recommended for IDEs and Claude Desktop)**

Your client can pull the package on demand:

```text
uvx --from kimss[mcp] kimss-mcp-server
```

Use **`--from`** (not `--with`). `--from` installs the `kimss` package and runs its `kimss-mcp-server` console script; `--with` would look for a nonexistent PyPI package named `kimss-mcp-server`.

**Editable install** (contributors or monorepo checkout):

```bash
cd kimss_sdk && pip install -e ".[dev,mcp]"
```

---

## 3. Cursor, Windsurf, and other MCP clients

Register the server in your client’s MCP settings. Example for **Cursor** (`mcpServers`):

```json
{
  "mcpServers": {
    "kimss": {
      "command": "uvx",
      "args": ["--from", "kimss[mcp]", "kimss-mcp-server"],
      "env": {
        "KIMSS_API_KEY": "your_key_here",
        "KIMSS_BASE_URL": "https://api.kimss.ai",
        "KIMSS_WORKSPACE_ID": ""
      }
    }
  }
}
```

**Rules**

- Set **`KIMSS_API_KEY`** to a **long-lived** key from the Kimss app: **Governance → API Keys**. Treat it like a password; never commit it to git or paste it into shared prompts.
- **`KIMSS_BASE_URL`**: production **`https://api.kimss.ai`**, staging **`https://stg.kimss.ai`**. Do **not** append a trailing slash.
- **`KIMSS_WORKSPACE_ID`** (optional): when set, the client stamps **`X-Workspace-ID`** and can supply **`tenant_id`** on bodies where the API expects workspace isolation (same behavior as `KimssClient(..., workspace_id=...)` in the library).

If you already installed `kimss[mcp]` locally, you can use `"command": "kimss-mcp-server"` with the same `env` block instead of `uvx`.

**Windsurf:** put the same block in `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows), then reload Windsurf.

---

## 4. Claude Desktop

Use Kimss agents from [Claude Desktop](https://claude.ai/download) via the same stdio MCP server.

1. Install [`uv`](https://docs.astral.sh/uv/) so `uvx` is on your `PATH` (or install `kimss[mcp]` and use `"command": "kimss-mcp-server"`).
2. Create an API key: Kimss app → **Governance → API Keys**.
3. Open the config file with **Claude Desktop → Settings → Developer → Edit Config** (preferred — this opens the file your install actually reads).
4. Merge the `kimss` entry into `mcpServers`:

```json
{
  "mcpServers": {
    "kimss": {
      "command": "uvx",
      "args": ["--from", "kimss[mcp]", "kimss-mcp-server"],
      "env": {
        "KIMSS_API_KEY": "your_api_key_here",
        "KIMSS_BASE_URL": "https://api.kimss.ai",
        "KIMSS_WORKSPACE_ID": ""
      }
    }
  }
}
```

5. Fully quit and relaunch Claude Desktop. Confirm Kimss tools appear in the MCP / tools UI (often a hammer icon in the chat composer).

**Typical config paths** (use Edit Config if unsure):

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows (classic installer) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

On some Windows Store / MSIX installs the file lives under `%LOCALAPPDATA%\Packages\Claude_*\…` instead of `%APPDATA%\Claude\` — **Edit Config** avoids guessing.

**Smoke test:** ask Claude to call `kimss_run_agent` with an `asst_…` id from your Kimss workspace and a short message.

More detail and troubleshooting: the public README’s [Claude Desktop Integration](https://github.com/kimss-ai/kimss-python-sdk#claude-desktop-integration) section.

---

## 5. Environment variables (MCP server)

| Variable | Required | Description |
|----------|----------|-------------|
| `KIMSS_API_KEY` | **Yes** | Long-lived Kimss API key (`X-Kimss-Key`). |
| `KIMSS_BASE_URL` | No | Defaults to `https://api.kimss.ai`. |
| `KIMSS_WORKSPACE_ID` | No | Workspace / tenant routing header and JSON hints when applicable. |

The MCP entrypoint is optimized for **API key** auth. For **Microsoft Entra ID** (`Authorization: Bearer`) use the **Python library** in your own process (`KimssClient(credential=..., token_scope=...)`) — see the public README’s authentication section.

---

## 6. Optional PyPI extras (library)

| Extra | Install | Notes |
|-------|---------|--------|
| **MCP** | `pip install 'kimss[mcp]'` | FastMCP-based stdio server and `kimss-mcp-server` console script. |
| **Privacy** | `pip install 'kimss[privacy]'` | Microsoft Presidio–based PII redaction (`PresidioRedactor`). Often needs a spaCy model, e.g. `python -m spacy download en_core_web_lg`. |
| **Types** | `pip install 'kimss[types]'` | Reserved for future typed Pydantic models. |
| **Dev** | `pip install 'kimss[dev]'` | pytest, responses, ruff — for SDK contributors. |

---

## 7. MCP tools (v1, non-streaming)

Each tool wraps the Kimss HTTP API and returns the **JSON `res` payload** (or equivalent) that the API would return for a **non-streaming** call. There are **no streaming MCP tools** in v1; for SSE streams use the library (`stream=True`) from your own code.

| Tool | Kimss API (summary) |
|------|---------------------|
| `kimss_chat` | `POST /v1/agents/run` — optional **`conversation_id`** (JSON `thread_id`) for continuity. |
| `kimss_run_agent` | `POST /v1/agents/run` — **preferred** agent execution path for new work (non-stream). Optional **`conversation_id`**. |
| `kimss_create_agent` | `POST /v1/agents/create` — agent creation; may require a **privileged** API key depending on tenant policy. |
| `kimss_complete` | `POST /v1/models/completions` — direct model completion (non-stream). |
| `kimss_upload_file` | `POST /v1/files/upload` — multipart upload from a **local path** on the machine running the MCP server. |
| `kimss_add_function_to_agent` | `POST /agent_add_function/` — JSON Schema tool definition on an agent (**owned** agents only; shared agents return **403** — see [SDK & API](api_docs.md)). |

**Tool arguments** follow the schemas shipped with the SDK (e.g. `assistant_id` + `message` + optional **`conversation_id`** for chat/run tools — **kimss 2.x**; older **`thread_id`** tool args are removed). Your IDE surfaces these as structured inputs.

---

## 8. Errors from MCP tools

On Kimss API failures the server raises a **RuntimeError** whose message is a **JSON string** (not pretty-printed) with a stable shape, for example:

```json
{"kind":"kimss_api_error","http_status":429,"error_code":"governed_requests_exhausted","message":"...","detail":{...}}
```

Parse defensively if you branch automation on error type. Legacy workspaces may still see `credit_pool_exhausted`. In the **library**, over-cap and rate-limit conditions map to typed exceptions (see `kimss.errors` and the error reference in [SDK & API](api_docs.md)).

---

## 9. Library highlights (same package as MCP)

These features apply when you use **`KimssClient`** in Python (not necessarily through MCP). For production chat, prefer the **Invisible Proxy** ([Quick start](quick_start.md), [SDK & API](api_docs.md) § 6.0).

- **v1 agents and models (deprecated for chat):** `client.agents.run`, `client.models.create` still work but emit DeprecationWarning — prefer Invisible Proxy. Keep `client.agents.create`, `client.agents.register`, `client.files.upload` for control-plane / uploads.
- **Streaming:** `client.models.create(..., stream=True)` and `client.agents.run(..., stream=True)` return an **SSE iterator** of JSON chunks. MCP does not expose streaming in v1.
- **Retries:** `requests.Session` retries **5xx**; **429** and governed-request / quota responses are **not** silently retried so limits surface immediately.
- **`before_request_hooks`:** mutate `path` / `json` / `headers` before each POST (e.g. strip telemetry headers).
- **`X-Kimss-SDK-Context`:** optional Usage Hub metadata on agent/model routes — see **[Product integrations & execution logs](product_integrations.md)** and the main [SDK & API](api_docs.md) guide.

---

## 10. Security checklist

- [ ] Keys only in **env** or a **secret store**, never in repo or client-side bundles.
- [ ] Separate keys per environment (dev / staging / production).
- [ ] Restrict who can run MCP locally: tools run **as the key’s user** and can **upload files** from disk paths visible to the server process.
- [ ] Revoke and rotate keys on leak or personnel change.

---

## 11. Related documentation

- [SDK & API](api_docs.md) — permissions matrix, REST, streaming JavaScript example, **`conversation_id`** / **`thread_id`** semantics.
- [Product integrations & execution logs](product_integrations.md) — execution context and admin visibility.
- [Usage & governed requests](usage_credits.md) — plan caps and `governed_requests_exhausted`.

---

## Troubleshooting
Source: https://kimss.ai/docs/troubleshooting_faq
Last-updated: 2026-09-12

# Troubleshooting

Quick fixes for common issues before you open a ticket.

## Browser basics

1. **Hard refresh**: `Ctrl+F5` (Windows) or `Cmd+Shift+R` (macOS).
2. Try an **incognito / private** window to rule out extensions.
3. Confirm you are on a **supported** browser (current Chrome, Edge, Safari, or Firefox).

## Sign-in and session

| Symptom | What to try |
|---------|-------------|
| “Session expired” or repeated login | Refresh, sign out completely, sign in again. |
| Missing menus after role change | Ask an **Admin** to confirm your role; then refresh. |
| SSO loop | Clear site cookies for your Kimss host, or try another network to exclude SSL inspection. |

## Chat and agents

| Symptom | What to try |
|---------|-------------|
| Agent “stuck” on old context | Start a **new thread** / chat. |
| Shared agent cannot be edited | Expected: only the **owner** can change instructions or tools; you can still chat. |
| Need document grounding | Retrieve in your app and pass the chunks in `messages`. Kimss does not host RAG. |

## API and SDK

| HTTP code | Meaning |
|-----------|---------|
| **401** | Missing or invalid **API key** / bearer token. |
| **403** | Allowed to call, but not allowed for this **resource** (e.g. editing a shared agent). |
| **404** | Wrong `assistant_id`, conversation / `thread_id`, or feature not enabled for the tenant. |
| **429** | Plan cap — usually **`governed_requests_exhausted`**. Not a silent drop. |
| **451** | **Content safety** block—do not retry the same harmful payload. |
| Soft tool result `policy_violation` | **Argument-level tool policy** denied a parameter (e.g. email `to` outside allowlist). The chat continues; the model receives a JSON tool result and may retry with a compliant payload. Logged as `argument_policy_violation` in Threat Intercepts — not an HTTP error to the caller. |

Always send the header your integration uses (`X-Kimss-Key` for API keys, or bearer tokens for session-style calls as documented in [SDK & API](api_docs.md)).

## Gateway / Invisible Proxy

| Symptom | What to try |
|---------|-------------|
| 401 on `POST /v1/chat/completions` | Confirm `OPENAI_API_KEY=kimss_...` and `OPENAI_BASE_URL=https://api.kimss.ai/v1`. |
| 401 / not_found on Anthropic `POST /v1/messages` | Official SDK appends `/v1/messages`. Set `ANTHROPIC_BASE_URL=https://api.kimss.ai` — **not** `https://api.kimss.ai/v1`. Auth: `x-api-key`, `X-Kimss-Key`, or `Authorization: Bearer kimss_...`. |
| Agent not in inventory | Send `X-Kimss-Agent-Id` on gateway calls for JIT auto-discovery. |
| 403 after disable | Expected kill-switch behavior — re-enable on **Governance → Agents**. |
| Azure SDK against Kimss | Azure official clients are **not** inbound. Vault Azure under Provider Vault, then call Kimss with the OpenAI or Anthropic client. |

See [Quick start](quick_start.md).

## Governed-request limits

- **429 `governed_requests_exhausted`**: the workspace hit its monthly allowance. Ask an **Admin** to upgrade or wait for the next cycle. Events are never silently dropped.
- **Unexpected usage spikes**: admins should check **Activity** (`/app/audit`) and **Tracking** (`/app/agents/tracking`) for attribution by agent or call site.

## Still stuck?

Collect **timestamp (UTC)**, **browser**, **steps to reproduce**, and any **request id** or **agent id** (not secrets), then see [Contact support](contact_support.md).

---

## Contact support
Source: https://kimss.ai/docs/contact_support
Last-updated: 2026-09-12

# Contact support

Use the channels below so we can resolve issues quickly with the right priority.

## Channels

| Channel | Use for |
|---------|---------|
| **In-app support** | Product bugs, workflow issues, and tenant-specific errors. |
| **Account / billing** | Invoices, plan changes, governed-request caps—often via your **account manager** or billing contact. |
| **Security** | Vulnerability reports or suspected compromise—follow your contract’s security contact. |

> [!NOTE]
> Response times and escalation paths depend on your **support tier** and contract.

## Before you open a ticket

Work through [Troubleshooting](troubleshooting_faq.md) (browser refresh, session, common HTTP codes).

## Information to include

| Field | Why it helps |
|-------|----------------|
| **What you were doing** | e.g. “POST `/v1/chat/completions`” or “POST `/v1/messages`” with the SDK and version. |
| **Expected vs actual** | Screenshots or sanitized JSON (no secrets). |
| **Time** | Timestamp in **UTC**. |
| **Environment** | Production vs staging host, browser version. |
| **IDs** | `X-Kimss-Agent-Id`, `assistant_id`, `conversation_id` / `thread_id`, or correlation id if shown. |

> [!CAUTION]
> **Never** paste full API keys, SCIM tokens, or passwords. If needed, provide only the **first four characters** of a key for lookup.

## Checklist

- [ ] Hard refresh and extension-free browser tested.
- [ ] Role and permissions verified for the action.
- [ ] Error body captured without secrets.
- [ ] Reproduction steps written for someone outside your team.

---