# Code Execution
Source: https://docs.onyx.app/admins/actions/code_interpreter

Enable Python code execution for your AI Agents in Onyx

The code execution action allows your Agents to write and run Python code to complete more complex tasks such as
performing calculations, analyzing data, and generating visualizations.

## Capabilities

* **Calculations**: Accurately perform large or complex mathematical operations
* **Data Analysis**: Run analysis on files provided by the user (e.g., CSVs, spreadsheets)
* **File Generation**: Create and return files such as reports, modified datasets, or exports
* **Visualizations**: Generate graphs and charts that render directly in the [Chat UI](/overview/core_features/chat)

## Configuration

No configuration is required. Code execution is a built-in action available to all Onyx deployments out of the box.

To enable it for a specific Agent, make sure the **Code Execution** action is toggled on in the Agent's configuration.

## Connect / Disconnect Code Execution Server

The code execution server is connected by default.
You can disconnect or reconnect it at any time from the **Admin Panel**.
This page also displays the server's health and connection status.

<img alt="Code Execution" />

## How It Works

Code execution runs in a secure, sandboxed Python environment with:

* **Pre-installed libraries** such as numpy, pandas, scipy, and matplotlib
* **Network access disabled** and restricted filesystem access for security
* **Resource limits and timeouts** to prevent runaway execution

The LLM decides when to invoke code execution based on the user's query — no explicit invocation is needed.


# Coding Agent
Source: https://docs.onyx.app/admins/actions/coding_agent

Enable your AI Agents to investigate and answer questions about a GitHub codebase

<Note>
  The Coding Agent is a **beta** Action.
  It is disabled by default and currently supports **public** GitHub repositories only.
</Note>

The Coding Agent action lets your Agents investigate a GitHub repository and answer questions about its codebase.
It clones the repository into an isolated sandbox, explores the code with shell commands, and returns a written answer.

## Capabilities

* **Codebase Q\&A**: Answer questions about how a repository is implemented and where logic lives
* **Code investigation**: Trace data flow and interactions between components
* **Onboarding**: Summarize a project's structure and key modules

## How It Works

When invoked, the Coding Agent:

<Steps>
  <Step title="Clones the repository">
    The target GitHub repository is cloned into an isolated sandbox.
  </Step>

  <Step title="Investigates the code">
    An iterative loop powered by an LLM executes shell commands to explore the codebase.
  </Step>

  <Step title="Returns an answer">
    A final answer is produced based on its findings.
  </Step>
</Steps>

The Coding Agent runs in the same sandboxed environment as the [Code Interpreter](/admins/actions/code_interpreter),
so it requires a connected code execution (bash) server.

## Configuration

The Coding Agent is a built-in Action, but because it is in beta it is **disabled by default**.

<Steps>
  <Step title="Enable the Action">
    Go to the **Admin Panel** and open the **Actions** tab. Locate the **Coding Agent** action and enable it.
  </Step>

  <Step title="Confirm the code execution server is connected">
    The Coding Agent relies on the same sandboxed bash environment as the Code Interpreter.
    Make sure the code execution server is connected and healthy from the Admin Panel.
  </Step>

  <Step title="Attach it to an Agent">
    Enable the **Coding Agent** action on the [Agents](/admins/agents/overview) that should be able to use it.
    Once enabled, the LLM automatically decides when to invoke it.
  </Step>
</Steps>

## Using the Coding Agent

Once enabled and attached to an Agent,
the LLM decides when to invoke the Coding Agent based on the user's query — no explicit invocation is needed.

<Tip>
  Be explicit about which repository you want analyzed. For example:
  *"Using the repository at [https://github.com/onyx-dot-app/onyx](https://github.com/onyx-dot-app/onyx), explain how the connector indexing pipeline works."*
</Tip>

## Limitations

* **Public repositories only**: Private repositories are not yet supported and will currently fail to clone. Support
  for private repositories is planned.
* **Beta**: Behavior and configuration may change as the feature matures.


# Image Generation
Source: https://docs.onyx.app/admins/actions/image_generation

Enable image generation capabilities for your AI Agents in Onyx

The image generation action allows your Agents to create images based on text prompts. Once configured,
any AI model in Onyx can invoke this action to generate images using supported image generation models.

## Supported Models

| Model           | Provider              |
| --------------- | --------------------- |
| GPT Image 1.5   | OpenAI / Azure OpenAI |
| GPT Image 1     | OpenAI / Azure OpenAI |
| DALL-E 3        | OpenAI / Azure OpenAI |
| Nano Banana     | Vertex (Google)       |
| Nano Banana Pro | Vertex (Google)       |

## Configuration

<Steps>
  <Step title="Navigate to Image Generation">
    Go to the **Admin Panel** and select **Image Generation** under the **Configuration** section.

    <img alt="Image Generation Configuration Page" />
  </Step>

  <Step title="Connect a Model">
    The page displays available models grouped by provider (OpenAI, Azure OpenAI and Vertex).

    Click **Connect** on any model to configure it. A modal will open where you can set up credentials:

    <Tabs>
      <Tab title="OpenAI">
        * **Use existing API key**: Select from previously configured OpenAI API keys
        * **Enter new API key**: Add a new OpenAI API key
      </Tab>

      <Tab title="Azure OpenAI">
        * **Use existing API key**: Select from previously configured Azure OpenAI API keys
        * **Enter new API key**: Add a new Azure OpenAI API key
      </Tab>

      <Tab title="Vertex (Google)">
        * **Service Account**: Create a Google Cloud service account, then generate and download a JSON key file
        * **Upload credentials**: Upload the service account JSON key file
        * **Region (Optional)**: Define the region you want requests sent to. Defaults to global
      </Tab>
    </Tabs>

    The last configured model will automatically become the **Current Default**.
  </Step>

  <Step title="Manage Default Model">
    The model marked as **Current Default** is used when users request image generation in chat.

    * To **remove** a model as default: Click the "Current Default" badge on that model
    * To **edit credentials**: Click the settings icon (gear) to open a modal where you can update the API key
  </Step>
</Steps>

## Using Image Generation

Once image generation is configured with a default model, any AI model in Onyx can invoke the image generation action.
When a user requests an image, the Agent will automatically use the configured default image generation model.


# MCP
Source: https://docs.onyx.app/admins/actions/mcp

Configure Model Context Protocol (MCP) actions in Onyx

Model Context Protocol (MCP) enables AI Agents to invoke tools and services in a controlled manner.
You can configure Onyx to be an MCP client and allow your Agents to retrieve data or perform operations.

<Tip>
  Onyx can also act as an MCP server! See the [Onyx MCP Server](/overview/onyx_anywhere/mcp_server)
  guide to connect Claude, Cursor, and other AI tools to your Onyx knowledge base.
</Tip>

## MCP in Onyx

<Steps>
  <Step title="Navigate to the Actions Dashboard">
    Click your user profile icon and select **Admin Panel** and select the **MCP Actions** tab in the sidebar.

    <img alt="MCP Actions dashboard in Onyx Admin Panel" />
  </Step>

  <Step title="Add an MCP Server to Onyx">
    Click the **Add MCP Server** button and fill out the following fields:

    <img alt="Add MCP Server dialog in Onyx Admin Panel" />

    * **Server Name** — A human-readable name for this MCP server.
      Typically the name of the service you're connecting to (e.g. "Slack", "Jira").
    * **Description** — Any additional information that helps identify the server.
      Useful for distinguishing multiple configured MCP server connections that talk to the same service.
    * **MCP Server URL** — The URL of the MCP server, which must be reachable from your Onyx instance. Most URLs end in `/mcp`, or `/sse` for older servers.
    * **Managed MCP server:** The URL is typically found in the provider's documentation describing how to connect.
    * **Self-hosted MCP server:** You'll need to run your server in HTTP transport mode — Onyx doesn't currently support connecting via stdio. If the server is running on the same machine as Onyx, use `http://127.0.0.1:<port>`. Otherwise, use the URL and port the server is exposed at.

    When you click **Add Server**, Onyx will create the server in a **disconnected** state.
    The next steps will set up authentication (if any) and validate that Onyx can connect to it.
  </Step>

  <Step title="Configure and Authenticate with an MCP Server">
    <img alt="MCP server authentication configuration in Onyx" />

    Onyx supports four authentication types when connecting to an MCP server:

    ### No Auth

    Use this when your MCP server is unprotected.
    Typically only used for testing when connecting to a local MCP server on a local Onyx instance,
    but may be useful if the server is deployed inside a VPC and you want all users to have the same unrestricted access
    to it.

    ### API Key

    The server is protected by API key authentication, typically using the `Authorization: Bearer <token>` format.
    There are two sub-modes:

    * **Shared Key** — The admin configures a single API key used for all user requests.
      Similar to No Auth in that users won't need any additional configuration and will all get the same level of access
      (whatever is provided by the API key you choose).
    * **Individual Key** — Users authenticate in the chat flow by providing their own API key(s)
      to connect to the server. Useful when you want users to have differing access to an external service by identity.
      This mode is also the most configurable — Onyx allows the admin to specify arbitrary header patterns to send to the
      MCP server.

    ### OAuth

    Many modern MCP servers support OAuth authentication to give users access to tools and data using the same login
    flow they use when manually accessing the service.

    Many OAuth-enabled MCP servers support [Client ID Metadata Documents
    (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
    or [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591).
    These standards let Onyx connect without a manually configured **Client ID** or **Client Secret**. In most cases,
    you can simply click **Connect** and complete the OAuth flow.

    If the MCP server's documentation requires you to register an OAuth app:

    1. Create an OAuth app in the IdP (Identity Provider) used by the MCP server.
    2. Add the following Onyx callback URL to the app:

    `https://<your-onyx-host>/mcp/oauth/callback`

    3. Enter the generated **Client ID** and **Client Secret** in Onyx, then click **Connect**.

    <Note>
      On HTTPS deployments, Onyx automatically publishes and uses a deployment-level,
      Onyx-branded CIMD at `https://<your-onyx-host>/api/mcp/oauth/client-metadata` when the authorization server
      supports it. HTTP local development uses DCR instead.
    </Note>

    ### Pass-Through OAuth

    Only available when your Onyx instance is configured to authenticate via OAuth. In this mode,
    Onyx passes the user's OAuth access token through as an `Authorization: Bearer` header to the MCP server.
    This is most often useful if your organization hosts its own MCP servers and would rather not require users to
    authenticate again after already going through the OAuth flow to log in to Onyx.

    Many MCP servers require scopes that Onyx does not request by default during login.
    Check the MCP server's documentation for the exact scopes it requires,
    then add them to the comma-separated scope override for your authentication type:

    * **Google OAuth:** `GOOGLE_OAUTH_SCOPE_OVERRIDE`
    * **OIDC:** `OIDC_SCOPE_OVERRIDE`

    These settings replace the default scopes, so retain `openid`, `email`,
    and `profile` alongside the additional scopes.
    See [Google OAuth scope configuration](/deployment/authentication/oauth#customizing-requested-scopes)
    or [OIDC scope configuration](/deployment/authentication/oidc#customizing-requested-scopes) for examples.

    <Note>
      Requesting a scope in Onyx does not guarantee that the identity provider will grant it.
      The scope must also be exposed and permitted for the Onyx OAuth/OIDC client in the identity provider,
      and some providers require an administrator to grant consent. The exact configuration varies by provider.
      The issued access token must include both the required scopes and an audience accepted by the MCP server.
    </Note>

    ***

    Clicking **Connect** will validate that Onyx can reach the MCP server using the provided authentication method.
    The MCP Actions dashboard then lets the admin list the tools available from the MCP server and select which subset
    of tools should be made available for use in Agents across the organization.
  </Step>
</Steps>


# OpenAPI
Source: https://docs.onyx.app/admins/actions/openapi

Configure custom actions in Onyx with OpenAPI

You can create custom actions in Onyx using an OpenAPI 3.0 or 3.1 specification of an API.
This enables your AI agents to interact with REST APIs and trigger workflows in external systems.

<Tip>
  Include only the endpoints you want your agent to call in the OpenAPI spec.
  Remove any endpoints you don't want the agent to access.
</Tip>

## Setting Up Custom Actions

<Steps>
  <Step title="Navigate to the Actions Dashboard">
    Click your user profile icon and select **Admin Panel**, then click the **OpenAPI Actions** tab in the sidebar.

    <div>
      <img alt="OpenAPI Actions tab in Onyx Admin Panel sidebar" />

      <img alt="OpenAPI Actions dashboard in Onyx Admin Panel" />
    </div>
  </Step>

  <Step title="Add an OpenAPI Action">
    Click the **Add OpenAPI Action** button.

    Paste your OpenAPI spec and configure any required authentication or headers.

    <img alt="Add OpenAPI Action modal in Onyx Admin Panel" />
  </Step>
</Steps>

## Example

The below OpenAPI spec can be used to create a Custom Action for fetching and creating Agents in Onyx.

```json OpenAPI expandable theme={null}
{
  "openapi": "3.1.0",
  "info": {
    "title": "Agents API",
    "version": "1.0.0",
    "description": "Minimal OpenAPI schema for creating and fetching agents in Onyx"
  },
  "servers": [
    {
      "url": "https://cloud.onyx.app/api"
    }
  ],
  "paths": {
    "/persona": {
      "post": {
        "summary": "Create Agent (Persona)",
        "operationId": "create_persona",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "document_set_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "num_chunks": { "type": "number" },
                  "is_public": { "type": "boolean" },
                  "recency_bias": {
                    "type": "string",
                    "enum": ["favor_recent", "base_decay", "no_decay", "auto"]
                  },
                  "llm_filter_extraction": { "type": "boolean" },
                  "llm_relevance_filter": { "type": "boolean" },
                  "tool_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "system_prompt": { "type": "string" },
                  "task_prompt": { "type": "string" },
                  "datetime_aware": { "type": "boolean" }
                },
                "required": [
                  "name",
                  "description",
                  "document_set_ids",
                  "num_chunks",
                  "is_public",
                  "recency_bias",
                  "llm_filter_extraction",
                  "llm_relevance_filter",
                  "tool_ids",
                  "system_prompt",
                  "task_prompt",
                  "datetime_aware"
                ]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Created" }
        }
      }
    },
    "/persona/{persona_id}": {
      "get": {
        "summary": "Get Agent (Persona) By ID",
        "operationId": "get_persona",
        "parameters": [
          {
            "name": "persona_id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": { "description": "OK" }
        }
      }
    }
  }
}
```


# Voice Mode
Source: https://docs.onyx.app/admins/actions/voice_mode

Set up voice providers to enable Voice Mode for your Onyx instance

The Voice Mode action allows your users to have spoken conversations with Onyx using speech-to-text and text-to-speech
providers.

## Setting up Voice Mode

<Steps>
  <Step title="Navigate to the Voice Mode Dashboard">
    Click your user profile icon and select Admin Panel, then select the Voice Mode tab in the sidebar.

    <img alt="Voice Mode dashboard in Onyx Admin Panel" />
  </Step>

  <Step title="Set up Speech-to-Text (STT) provider">
    Configure a provider to transcribe user speech into text.

    <img alt="Speech-to-Text Providers" />

    <Tabs>
      <Tab title="OpenAI Whisper">
        <div>
          <Steps>
            <Step title="Get an OpenAI API key">
              Navigate to the [OpenAI dashboard](https://platform.openai.com/api-keys) and create a new API key,
              or reuse an existing OpenAI API key already configured for your LLM provider.
            </Step>

            <Step title="Enter the API key">
              Click **Connect** and enter the API key.
            </Step>
          </Steps>
        </div>
      </Tab>

      <Tab title="Azure STT">
        <div>
          <Steps>
            <Step title="Get Azure Speech credentials">
              Navigate to the [Azure Portal](https://portal.azure.com) and create a Speech resource.
              Copy the API key and region.
            </Step>

            <Step title="Enter the credentials">
              Click **Connect** and enter the API key, region, and target URI.
            </Step>
          </Steps>
        </div>
      </Tab>

      <Tab title="ElevenLabs">
        <div>
          <Steps>
            <Step title="Get an ElevenLabs API key">
              Navigate to the [ElevenLabs dashboard](https://elevenlabs.io/app/settings/api-keys)
              and create a new API key.
            </Step>

            <Step title="Enter the API key">
              Click **Connect** and enter the API key.
            </Step>
          </Steps>
        </div>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set up Text-to-Speech (TTS) provider">
    Configure a provider to convert AI responses into spoken audio.

    <img alt="Text-to-Speech Providers" />

    <Tabs>
      <Tab title="OpenAI TTS-1">
        <div>
          <Steps>
            <Step title="Get an OpenAI API key">
              Navigate to the [OpenAI dashboard](https://platform.openai.com/api-keys)
              and create a new API key (or reuse the one from Whisper).
            </Step>

            <Step title="Enter the API key">
              Click **Connect** and enter the API key.
            </Step>
          </Steps>
        </div>
      </Tab>

      <Tab title="OpenAI TTS-1 HD">
        <div>
          <Steps>
            <Step title="Get an OpenAI API key">
              Navigate to the [OpenAI dashboard](https://platform.openai.com/api-keys)
              and create a new API key (or reuse the one from Whisper).
            </Step>

            <Step title="Enter the API key">
              Click **Connect** and enter the API key.
            </Step>
          </Steps>

          <Note>
            TTS-1 HD provides higher quality audio than TTS-1 but may have slightly higher latency and cost.
          </Note>
        </div>
      </Tab>

      <Tab title="Azure TTS">
        <div>
          <Steps>
            <Step title="Get Azure Speech credentials">
              Navigate to the [Azure Portal](https://portal.azure.com) and create a Speech resource.
              Copy the API key and region.
            </Step>

            <Step title="Enter the credentials">
              Click **Connect** and enter the API key, region, and target URI.
            </Step>
          </Steps>
        </div>
      </Tab>

      <Tab title="ElevenLabs">
        <div>
          <Steps>
            <Step title="Get an ElevenLabs API key">
              Navigate to the [ElevenLabs dashboard](https://elevenlabs.io/app/settings/api-keys)
              and create a new API key.
            </Step>

            <Step title="Enter the API key">
              Click **Connect** and enter the API key.
            </Step>
          </Steps>
        </div>
      </Tab>
    </Tabs>

    Once your TTS provider is configured, select a voice from the dropdown or input a voice ID directly.

    <img alt="Voice Selection" />
  </Step>

  <Step title="Set Default Provider">
    If you have multiple providers configured,
    make sure to **Set as Default** for both your preferred STT and TTS provider.

    <img alt="Set Default Provider" />
  </Step>
</Steps>

<Note>
  Make sure your users have microphone access enabled in their browser to use Voice Mode.
</Note>


# Web Search
Source: https://docs.onyx.app/admins/actions/web_search

Enable web search capabilities for your AI Agents in Onyx

The web search action allows your Agents to query the internet and retrieve real-time information from web sources.

## Web Search in Onyx

### On Onyx Cloud

Web search is already active and ready to use on Onyx Cloud - no additional configuration required!

### Self-Hosted

<Steps>
  <Step title="Naivigate to the Web Search Dashboard">
    Click your user profile icon and select Admin Panel and select the Web Search tab in the sidebar.

    <img alt="Web Search dashboard in Onyx Admin Panel" />
  </Step>

  <Step title="Set up web search providers">
    We currently support the following web search providers: Exa AI, Serper, and Google PSE. To set any ofthem up,
    follow the steps below.

    <img alt="Search Engine Providers" />

    <Tabs>
      <Tab title="Exa AI">
        Create an Exa API key in the [Exa AI dashboard](https://exa.ai/dashboard).

        In Onyx, click **Connect** and paste the API key in the **API Key** field.
      </Tab>

      <Tab title="Serper">
        Create a Serper API key in the [Serper dashboard](https://serper.dev/dashboard).

        In Onyx, click **Connect** and paste the API key in the **API Key** field.
      </Tab>

      <Tab title="Google PSE">
        Create a Google PSE API key in the [Google PSE
        dashboard](https://programmablesearchengine.google.com/controlpanel/all).

        In Onyx,
        click **Connect** and paste the API key in the **API Key** field and the Search Engine ID in the **Search Engine
        ID** field.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set up Web Crawler">
    We currently support the following web crawlers: Onyx web crawler and Firecrawl. To set them up,
    follow the steps below.

    <img alt="Crawler Providers" />

    <Tabs>
      <Tab title="Onyx Web Crawler">
        **(Recommended)** It is already set up and ready to use, no additional setup required.
      </Tab>

      <Tab title="Firecrawl">
        Create a Firecrawl API key in the [Firecrawl dashboard](https://firecrawl.com/dashboard).

        In Onyx, click **Connect** and paste the API key in the **API Key** field.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set Default Provider">
    Make sure to **Set as Default** the provider if you have multiple providers set up for the search engine and web
    crawler. You can change it at any time.

    <img alt="Set Default Provider" />
  </Step>
</Steps>

<Note>
  Make sure your Agent has the Web Search Action enabled!
</Note>


# Hook Extensions
Source: https://docs.onyx.app/admins/advanced_configs/hook_extensions

Inject custom logic into Onyx's pipeline at defined stages without modifying source code

<Note>
  Hook Extensions are an [Enterprise Edition](/deployment/miscellaneous/enterprise_edition)
  feature and are only available on **single-tenant** deployments.
</Note>

## Overview

Hook Extensions let you inject custom logic into Onyx's pipeline at defined stages — without modifying Onyx source code.
You provide an HTTP endpoint; Onyx calls it at the right moment, sends a JSON payload,
and uses your response to influence what happens next.

## Concepts

### Hook Points

A hook point is a defined stage in Onyx's pipeline where custom logic can be injected. Each hook point specifies:

* **When** it fires in the pipeline
* **What** payload it sends to your endpoint
* **What** response it expects back
* A default timeout and fail strategy

Hook points are intentional — once a hook point is added, Onyx commits to maintaining its payload structure,
response format, and behavior — meaning it won't change in a breaking way without a proper deprecation process.
Because of this long-term commitment, each proposal is evaluated carefully before being added.

### Hooks

A hook connects a hook point to your HTTPS endpoint. When the hook point is triggered,
Onyx POSTs a request to your endpoint and uses your response to continue, modify, or abort the pipeline.

Only one hook per hook point is allowed at a time.

## How It Works

<Steps>
  <Step title="Onyx reaches a hook point in the pipeline">
    The pipeline triggers at a defined stage.
  </Step>

  <Step title="Onyx POSTs to your endpoint">
    If an active hook is configured for that point, Onyx sends a JSON payload to your endpoint URL.
  </Step>

  <Step title="Your endpoint responds">
    Your endpoint processes the payload and returns a JSON response.
  </Step>

  <Step title="Onyx continues">
    Onyx uses your response to continue, modify, or abort the pipeline.
  </Step>
</Steps>

If your endpoint is unreachable, times out, or returns an invalid response,
Onyx follows the **fail strategy** you configured.

## Adding a Hook

<Steps>
  <Step title="Navigate to Hook Extensions">
    Go to the **Admin Panel** and select **Hook Extensions**.
  </Step>

  <Step title="Connect a hook point">
    Find the hook point you want to use and click **Connect**.
  </Step>

  <Step title="Fill in the hook details">
    Complete the form:

    <img alt="Add Hook Form" />

    | Field         | Required | Description                                                                                                   |
    | ------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
    | Display Name  | Yes      | A human-readable label for this hook                                                                          |
    | Fail Strategy | No       | **Hard** — abort the pipeline. **Soft** — log and continue. Defaults to the hook point's recommended strategy |
    | Timeout       | No       | Seconds to wait for your endpoint to respond (1–600). Defaults to the hook point's recommended timeout        |
    | Endpoint URL  | Yes      | The HTTPS URL Onyx will POST to when the hook point is triggered. Must use HTTPS.                             |
    | API Key       | No       | If provided, Onyx sends this as `Authorization: Bearer <api_key>` on every request                            |
  </Step>

  <Step title="Connect">
    Click **Connect**. Onyx validates your endpoint with a test request before saving. On success,
    the hook appears in the connected list.
  </Step>
</Steps>

## Managing a Hook

Once connected, you can:

* **Activate / Deactivate** — toggle whether the hook runs
* **Edit** — update the name, endpoint URL, API key, timeout, or fail strategy
* **Delete** — remove the hook entirely
* **View Logs** — inspect recent execution failures for debugging

## Hook Health

Onyx monitors your endpoint after the hook is registered and connected, displays its current health status.

| Status                 | Meaning                                           |
| ---------------------- | ------------------------------------------------- |
| <img />Connected       | Reachable, no failures in the last hour           |
| <img />Degraded        | Reachable, but failures occurred in the last hour |
| <img />Connection Lost | Onyx cannot reach your endpoint                   |

<img alt="Connected Hook Card" />

<img alt="Hook Errors in the Last Hour" />

<img alt="Hook Connection Lost" />

The 10 most recent failures from the past 30 days are also shown to help with debugging.

<img alt="Hook Errors in the Last 30 Days" />

***

## Document Ingestion

The Document Ingestion hook point lets you intercept every document before it enters the Onyx indexing pipeline.
Your endpoint receives the fully-formed document and can filter it out, rewrite its content,
or pass it through unchanged.

It runs immediately after Onyx's internal validation and before the indexing pipeline begins — no partial writes have
occurred yet.

| Setting               | Value                            |
| --------------------- | -------------------------------- |
| Default Timeout       | 30 seconds (configurable)        |
| Default Fail Strategy | Hard (configurable)              |
| On Hard Fail          | The document will not be indexed |

### Input Schema

Onyx sends a `POST` request to your endpoint once per document with the following JSON body:

```json theme={null}
{
  "document_id": "string",
  "title": "string | null",
  "semantic_identifier": "string",
  "source": "string",
  "sections": [
    {
      "text": "string | null",
      "link": "string | null",
      "image_file_id": "string | null"
    }
  ],
  "metadata": { "key": ["string"] },
  "doc_updated_at": "string | null",
  "primary_owners": [
    { "display_name": "string | null", "email": "string | null" }
  ],
  "secondary_owners": [
    { "display_name": "string | null", "email": "string | null" }
  ]
}
```

<Note>
  All input fields are provided for context only.
  Your endpoint can only influence the pipeline through the output schema — specifically the `sections` field.
</Note>

| Field                             | Type              | Required | Description                                                                                                                                                                                    |
| --------------------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document_id`                     | string            | Yes      | Unique identifier for the document.                                                                                                                                                            |
| `title`                           | string \| null    | Yes      | Title of the document.                                                                                                                                                                         |
| `semantic_identifier`             | string            | Yes      | Human-readable identifier used for display (e.g. file name, page title).                                                                                                                       |
| `source`                          | string            | Yes      | Connector source type. For the full list of possible values, see [`DocumentSource`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/constants.py) in the Onyx source code. |
| `sections`                        | object\[]         | Yes      | All sections of the document — both text sections and image sections.                                                                                                                          |
| `sections[].text`                 | string \| null    | Yes      | Text content. Set for text sections, `null` for image sections.                                                                                                                                |
| `sections[].link`                 | string \| null    | No       | Optional URL associated with this section.                                                                                                                                                     |
| `sections[].image_file_id`        | string \| null    | No       | Opaque image identifier. Set for image sections, `null` for text sections. Image content is not included — hooks can reorder or drop image sections but cannot read or modify the image.       |
| `metadata`                        | object            | Yes      | Key-value metadata. Values are always `string[]`. Connector-specific — see below.                                                                                                              |
| `doc_updated_at`                  | string \| null    | Yes      | Timestamp of the last update at the source in the format `YYYY-MM-DDTHH:MM:SS.ffffff+00:00`, or `null` if unknown.                                                                             |
| `primary_owners`                  | object\[] \| null | Yes      | Primary owners of the document, or `null` if not available.                                                                                                                                    |
| `primary_owners[].display_name`   | string \| null    | No       | Human-readable name of the owner.                                                                                                                                                              |
| `primary_owners[].email`          | string \| null    | No       | Email address of the owner.                                                                                                                                                                    |
| `secondary_owners`                | object\[] \| null | Yes      | Secondary owners of the document, or `null` if not available.                                                                                                                                  |
| `secondary_owners[].display_name` | string \| null    | No       | Human-readable name of the owner.                                                                                                                                                              |
| `secondary_owners[].email`        | string \| null    | No       | Email address of the owner.                                                                                                                                                                    |

#### Metadata Keys by Connector

The keys present in `metadata` depend on the connector source. Below are a few examples:

| Connector  | Keys                                                                                                                                                                                                                  |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Confluence | `space`, `labels`                                                                                                                                                                                                     |
| Jira       | `key`, `project`, `project_name`, `issuetype`, `status`, `priority`, `assignee`, `assignee_email`, `reporter`, `reporter_email`, `labels`, `created`, `updated`, `duedate`, `resolution`, `resolution_date`, `parent` |
| File       | Arbitrary user-defined tags. You can embed custom key-value pairs directly in the file using an `ONYX_METADATA` block — see the [File connector docs](/admins/connectors/official/file) for details.                  |

**Example**

```json theme={null}
{
  "document_id": "FILE_CONNECTOR__0376357d-6431-4082-b71a-9f83688f1f16",
  "title": "Q4 2024 Refund Policy",
  "semantic_identifier": "Q4 2024 Refund Policy",
  "source": "confluence",
  "sections": [
    {
      "text": "Our refund policy allows returns within 30 days...",
      "link": "https://wiki.example.com/pages/123456",
      "image_file_id": null
    },
    {
      "text": null,
      "link": null,
      "image_file_id": "846d6333-1a2b-4c5d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "metadata": {
    "space": ["HR"],
    "labels": ["policy", "finance"]
  },
  "doc_updated_at": "2024-10-01T12:00:00.000000+00:00",
  "primary_owners": [
    { "display_name": "Alice Smith", "email": "alice@example.com" }
  ],
  "secondary_owners": null
}
```

### Output Schema

A successful response from your endpoint must return HTTP `200` and a JSON body:

| Field              | Type              | Required | Description                                                                                                                                      |
| ------------------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sections`         | object\[] \| null | Yes      | The sections to index, using the same schema as the input `sections`. The hook controls final ordering. `null` or empty list drops the document. |
| `rejection_reason` | string \| null    | No       | Logged when `sections` is `null` or empty. Falls back to a generic message if omitted.                                                           |

<AccordionGroup>
  <Accordion title="Example: Pass through unchanged">
    ```json theme={null}
    {
      "sections": [
        {
          "text": "Our refund policy allows returns within 30 days...",
          "link": "https://wiki.example.com/pages/123456",
          "image_file_id": null
        },
        {
          "text": null,
          "link": null,
          "image_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      ],
      "rejection_reason": null
    }
    ```
  </Accordion>

  <Accordion title="Example: Rewrite content (PII redaction)">
    ```json theme={null}
    {
      "sections": [
        { "text": "Our refund policy allows returns within 30 days. Contact [REDACTED] for details." }
      ],
      "rejection_reason": null
    }
    ```
  </Accordion>

  <Accordion title="Example: Drop the document">
    ```json theme={null}
    {
      "sections": null,
      "rejection_reason": "Document contains restricted classification label."
    }
    ```
  </Accordion>
</AccordionGroup>

### Authentication

If you configured an API key when registering the hook, Onyx includes it in every request:

```
Authorization: Bearer <your-api-key>
```

### Lambda Example

You can use an [AWS Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)
as your hook endpoint by exposing it over HTTPS via a [Lambda Function
URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html).
This is the simplest way to deploy a hook without managing a server.

When Onyx calls your endpoint, the request arrives as an API Gateway-style event.
Your handler reads the JSON body from `event["body"]`, processes the document,
and returns a response with a `statusCode` and a JSON-encoded `body`.

If you configured an API key on the hook, validate it against the `Authorization` header in the event before processing.

<Accordion title="Lambda Example (Python)">
  ```python theme={null}
  import json
  import logging
  import os

  logger = logging.getLogger()
  logger.setLevel(logging.INFO)

  # Set the HOOK_API_KEY environment variable in your Lambda configuration.
  # If not set, API key validation is skipped.
  API_KEY = os.environ.get("HOOK_API_KEY")

  def lambda_handler(event, context):
      # Validate API key if configured
      if API_KEY:
          auth = (event.get("headers") or {}).get("authorization", "")
          if auth != f"Bearer {API_KEY}":
              logger.warning("Unauthorized request — invalid or missing API key")
              return {"statusCode": 401, "body": json.dumps({"error": "Unauthorized"})}

      body = json.loads(event.get("body", "{}"))
      source = body.get("source", "")
      document_id = body.get("document_id", "")
      sections = body.get("sections", [])

      logger.info("Received document: id=%s source=%s sections=%d", document_id, source, len(sections))

      # Reject documents from the file connector
      if source == "file":
          logger.info("Rejecting document %s — file connector documents are not allowed", document_id)
          return {
              "statusCode": 200,
              "body": json.dumps({
                  "sections": None,
                  "rejection_reason": "File connector documents are not allowed.",
              }),
          }

      logger.info("Passing through document %s", document_id)
      return {
          "statusCode": 200,
          "body": json.dumps({"sections": sections}),
      }
  ```
</Accordion>

### Testing

Use `curl` to test your Lambda Function URL before connecting it to Onyx.

**Pass-through (non-file source):**

```bash theme={null}
curl -X POST https://<your-function-url> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "document_id": "confluence::page::123456",
    "title": "Q4 Refund Policy",
    "semantic_identifier": "Q4 Refund Policy",
    "source": "confluence",
    "sections": [{"text": "Our refund policy allows returns within 30 days.", "link": null, "image_file_id": null}],
    "metadata": {},
    "doc_updated_at": null,
    "primary_owners": null,
    "secondary_owners": null
  }'
```

**Rejected (file source):**

```bash theme={null}
curl -X POST https://<your-function-url> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "document_id": "FILE_CONNECTOR__abc123",
    "title": "Internal Doc",
    "semantic_identifier": "Internal Doc",
    "source": "file",
    "sections": [{"text": "Some content.", "link": null, "image_file_id": null}],
    "metadata": {},
    "doc_updated_at": null,
    "primary_owners": null,
    "secondary_owners": null
  }'
```

Once the hook is connected, you can validate end-to-end by adding a File connector and uploading a document.
After the connector syncs, search for content from that document in the chat window — if the hook is working correctly,
the material should not appear in results since file connector documents are being rejected.

<img alt="File Connector" />

<img alt="Add File" />

<img alt="Document Ingestion Test — File Content Not Found" />

***

## Document Push

The Document Push hook point fires after each document is successfully indexed.
Use it to push indexed content to an external destination such as a wiki, data warehouse, or audit log.

Unlike Document Ingestion (which runs before indexing and can modify or drop documents),
this hook fires **after** the document has been written to the index.
The response body is not used — any `2xx` response is treated as success.

<Note>
  Document Push only fires for **public connectors** in **single-tenant** deployments,
  and only during **incremental syncs** — it does not fire during an initial index or a full re-index from the
  beginning.
</Note>

| Setting               | Value                                   |
| --------------------- | --------------------------------------- |
| Default Timeout       | 30 seconds (configurable)               |
| Default Fail Strategy | Soft (configurable)                     |
| On Soft Fail          | The push is skipped; indexing continues |
| On Hard Fail          | The indexing batch will fail            |

### Input Schema

Onyx sends a `POST` request to your endpoint once per successfully indexed document with the following JSON body:

```json theme={null}
{
  "document_id": "string",
  "title": "string | null",
  "content": "string",
  "source": "string",
  "url": "string | null",
  "doc_updated_at": "string | null",
  "metadata": { "key": ["string"] }
}
```

| Field            | Type           | Description                                                                                                                                                                                                             |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document_id`    | string         | Unique identifier for the document.                                                                                                                                                                                     |
| `title`          | string \| null | Title of the document.                                                                                                                                                                                                  |
| `content`        | string         | Full text content (all text sections joined with a space).                                                                                                                                                              |
| `source`         | string         | Connector source type (e.g. `confluence`, `slack`, `google_drive`). For the full list see [`DocumentSource`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/constants.py) in the Onyx source code. |
| `url`            | string \| null | Canonical URL of the document at its source, if available.                                                                                                                                                              |
| `doc_updated_at` | string \| null | ISO 8601 UTC timestamp of the last update at the source, or `null` if unknown.                                                                                                                                          |
| `metadata`       | object         | Key-value metadata. Values are always `string[]`.                                                                                                                                                                       |

**Example**

```json theme={null}
{
  "document_id": "confluence::page::789012",
  "title": "Engineering Onboarding Guide",
  "content": "Welcome to the engineering team. This guide covers...",
  "source": "confluence",
  "url": "https://wiki.example.com/pages/789012",
  "doc_updated_at": "2025-03-15T09:30:00.000000+00:00",
  "metadata": {
    "space": ["Engineering"],
    "labels": ["onboarding", "guide"]
  }
}
```

### Output Schema

The response body is **not used** — any `2xx` status code is treated as success.
Your endpoint can return an empty body or any JSON object.

### Authentication

If you configured an API key when registering the hook, Onyx includes it in every request:

```
Authorization: Bearer <your-api-key>
```

### Lambda Example

You can use an [AWS Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)
as your hook endpoint by exposing it over HTTPS via a [Lambda Function
URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html).

<Accordion title="Lambda Example (Python)">
  ```python theme={null}
  import json
  import logging
  import os

  logger = logging.getLogger()
  logger.setLevel(logging.INFO)

  API_KEY = os.environ.get("HOOK_API_KEY")

  def lambda_handler(event, context):
      if API_KEY:
          auth = (event.get("headers") or {}).get("authorization", "")
          if auth != f"Bearer {API_KEY}":
              return {"statusCode": 401, "body": json.dumps({"error": "Unauthorized"})}

      body = json.loads(event.get("body", "{}"))
      logger.info("Received document: id=%s title=%s", body.get("document_id"), body.get("title"))

      return {"statusCode": 200, "body": "{}"}
  ```
</Accordion>

### Testing

Use `curl` to test your endpoint before connecting it to Onyx:

```bash theme={null}
curl -X POST https://<your-function-url> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "document_id": "confluence::page::789012",
    "title": "Engineering Onboarding Guide",
    "content": "Welcome to the engineering team. This guide covers...",
    "source": "confluence",
    "url": "https://wiki.example.com/pages/789012",
    "doc_updated_at": "2025-03-15T09:30:00.000000+00:00",
    "metadata": { "space": ["Engineering"], "labels": ["onboarding"] }
  }'
```

***

## Query Processing

The Query Processing hook point lets you intercept every user query before it enters the Onyx pipeline.
Your endpoint receives the raw query and the user's identity, and can rewrite the query, reject it entirely,
or pass it through unchanged.

It runs immediately after the user submits a message, before anything is saved to the database or sent to the LLM.
This is the earliest possible point in the pipeline — no side effects have occurred yet.

| Setting               | Value                                                            |
| --------------------- | ---------------------------------------------------------------- |
| Default Timeout       | 5 seconds (configurable)                                         |
| Default Fail Strategy | Hard (configurable)                                              |
| On Hard Fail          | The query will be blocked and the user will see an error message |

### Input Schema

Onyx sends a `POST` request to your endpoint with the following JSON body:

```json theme={null}
{
  "query": "What is our refund policy?",
  "user_email": "alice@example.com",
  "chat_session_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Field             | Type           | Required | Description                                                           |
| ----------------- | -------------- | -------- | --------------------------------------------------------------------- |
| `query`           | string         | Yes      | The raw query exactly as the user typed it.                           |
| `user_email`      | string \| null | Yes      | Email of the user submitting the query, or `null` if unauthenticated. |
| `chat_session_id` | string         | Yes      | UUID of the chat session.                                             |

### Output Schema

A successful response from your endpoint must return HTTP `200` and a JSON body:

| Field               | Type           | Required | Description                                                                                   |
| ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------- |
| `query`             | string \| null | Yes      | The query to use downstream. Set to `null` or empty string to reject the query.               |
| `rejection_message` | string \| null | No       | Message shown to the user when `query` is `null`. Falls back to a generic message if omitted. |

<AccordionGroup>
  <Accordion title="Example: Pass through unchanged">
    ```json theme={null}
    {
      "query": "What is our refund policy?",
      "rejection_message": null
    }
    ```
  </Accordion>

  <Accordion title="Example: Rewrite the query">
    ```json theme={null}
    {
      "query": "What is the refund policy for enterprise customers?",
      "rejection_message": null
    }
    ```
  </Accordion>

  <Accordion title="Example: Reject the query">
    ```json theme={null}
    {
      "query": null,
      "rejection_message": "This topic is restricted. Please contact your administrator."
    }
    ```
  </Accordion>
</AccordionGroup>

### Authentication

If you configured an API key when registering the hook, Onyx includes it in every request:

```
Authorization: Bearer <your-api-key>
```

### Lambda Example

You can use an [AWS Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)
as your hook endpoint by exposing it over HTTPS via a [Lambda Function
URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html).
This is the simplest way to deploy a hook without managing a server.

When Onyx calls your endpoint, the request arrives as an API Gateway-style event.
Your handler reads the JSON body from `event["body"]`, processes the query,
and returns a response with a `statusCode` and a JSON-encoded `body`.

If you configured an API key on the hook, validate it against the `Authorization` header in the event before processing.

<Accordion title="Lambda Example (Python)">
  ```python theme={null}
  import json
  import os

  BLOCKED_KEYWORDS = ["ssn", "phone number"]

  # Set the HOOK_API_KEY environment variable in your Lambda configuration.
  # If not set, API key validation is skipped.
  API_KEY = os.environ.get("HOOK_API_KEY")

  def lambda_handler(event, context):
      # Validate API key if configured
      if API_KEY:
          auth = (event.get("headers") or {}).get("authorization", "")
          if auth != f"Bearer {API_KEY}":
              return {"statusCode": 401, "body": json.dumps({"error": "Unauthorized"})}

      body = json.loads(event.get("body", "{}"))
      query = body.get("query", "")

      # Reject queries containing blocked keywords
      for keyword in BLOCKED_KEYWORDS:
          if keyword.lower() in query.lower():
              return {
                  "statusCode": 200,
                  "body": json.dumps({
                      "query": None,
                      "rejection_message": "Your query contains restricted terms. Please contact your administrator.",
                  }),
              }

      return {
          "statusCode": 200,
          "body": json.dumps({"query": query}),
      }
  ```
</Accordion>

### Testing

Use `curl` to test your Lambda Function URL before connecting it to Onyx.

**Pass-through (no blocked keywords):**

```bash theme={null}
curl -X POST https://<your-function-url> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "query": "What is our refund policy?",
    "user_email": "alice@example.com",
    "chat_session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

**Rejected (contains blocked keyword):**

```bash theme={null}
curl -X POST https://<your-function-url> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "query": "What is the SSN format?",
    "user_email": "alice@example.com",
    "chat_session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

Once the hook is connected, you can also validate the logic directly in the Onyx chat window.
Try sending a query that contains a blocked keyword (e.g. "ssn" or "phone number")
— you should see the rejection message instead of a response.
Queries without blocked keywords should pass through normally.

<img alt="Query Processing Hook Test" />

***

## Suggesting a New Hook Point

If your use case requires a pipeline injection point that doesn't exist yet, open a GitHub issue describing:

* **Where** in the pipeline you need to inject logic (e.g. after retrieval, before document indexing)
* **What your endpoint would receive** — what context does it need to do its job?
* **What your endpoint would return** — how should Onyx change its behavior based on your response?
* **Use cases** — what problem does this solve? Are other customers likely to need the same point?

The Onyx team reviews proposals and implements hook points that have broad applicability. Once a hook point is added,
Onyx commits to maintaining its payload structure, response format,
and behavior — meaning it won't change in a breaking way without a proper deprecation process.
Because of this long-term commitment, each proposal is evaluated carefully before being added.


# Language Model Access Controls
Source: https://docs.onyx.app/admins/advanced_configs/llm_access_controls

Configure access controls for language model providers

## Overview

Onyx provides fine-grained access control for language model providers,
allowing administrators to control **who** can use specific models and **which agents** can use them.
This enables better cost control, governance, and enforcement of model usage policies.

<img alt="Language model access controls" />

### Access Control Types

<AccordionGroup>
  <Accordion title="Public vs Private Providers" icon="lock">
    **Public Providers**

    * Accessible to all users and agents
    * No restrictions applied
    * Useful for default, unrestricted models

    **Private Providers**

    * Subject to user group and/or agent restrictions
    * Enables fine-grained access control
    * Recommended for expensive or specialized models
  </Accordion>

  <Accordion title="User Group Restrictions" icon="users">
    Control **who** can use specific language model providers by restricting access to specific user groups.

    **How it works:**

    * Assign one or more user groups to a provider
    * Only users in those groups can use the provider
    * Admins bypass group restrictions (but not agent restrictions)
    * Leave empty for no group restrictions

    **Use cases:**

    * Restrict expensive models to specific teams
    * Provide specialized models to certain departments
    * Implement cost controls by team
  </Accordion>

  <Accordion title="Agent Restrictions" icon="robot">
    Control **which agents** can use specific language model providers.

    **How it works:**

    * Assign one or more agents to a provider via the "Agent Whitelist"
    * The provider will only appear as an option when using those agents
    * Applies to **all users**, including admins
    * Leave empty for no agent restrictions

    **Use cases:**

    * Reserve GPT-4 for "Code Review Agent" only
    * Use Claude Opus exclusively with "Legal Document Analyzer"
    * Prevent users from selecting inappropriate models for specific use cases
    * Enforce model policies per agent type
  </Accordion>

  <Accordion title="Combined Restrictions" icon="layer-group">
    You can combine both user group and agent restrictions for maximum control.

    **Access Rules (AND logic):**

    * User must be in an allowed group **AND** using an allowed agent
    * Both conditions must be satisfied for access
    * Admins bypass group restrictions but still require allowed agents

    **Example:**

    * Provider: GPT-4
    * User Groups: "Engineering Team"
    * Agent Whitelist: "Code Review Agent", "Architecture Advisor"
    * **Result:** Only Engineering Team members can use GPT-4, and only with those two agents
  </Accordion>
</AccordionGroup>

### Configuring Access Controls

To configure access controls for a language model provider:

<Steps>
  <Step title="Navigate to Language Models">
    Navigate to **Admin Panel → Configuration → Language Models**
  </Step>

  <Step title="Select Provider">
    Click on an existing provider or create a new one
  </Step>

  <Step title="Configure Access Controls">
    In the **Access Controls** section nested under Advanced options:

    * Toggle **Make Public** off to enable restrictions
    * Select user groups in **User Group Access** (optional)
    * Select agents in **Agent Whitelist** (optional)
  </Step>

  <Step title="Save Changes">
    Save your changes
  </Step>
</Steps>

<Note>
  When a provider is set to public, the access control selectors are automatically disabled.
</Note>

### Access Decision Logic

The system determines access based on the following logic:

| is\_public | Groups Set | Agents Set | Access Rule                                  |
| ---------- | ---------- | ---------- | -------------------------------------------- |
| `true`     | Any        | Any        | Everyone has access                          |
| `false`    | Yes        | Yes        | Must be in group **AND** using allowed agent |
| `false`    | Yes        | No         | Must be in group (admins bypass)             |
| `false`    | No         | Yes        | Must use allowed agent (applies to admins)   |
| `false`    | No         | No         | Admin-only access                            |

### Provider Visibility

Users will only see the language model providers they have access to:

* In the agent creation/editing interface
* In the chat UI model selector
* When using the API to list available providers

Restricted providers are completely hidden from users who don't have access,
preventing confusion and unauthorized usage attempts.


# OpenSearch Document Index Migration
Source: https://docs.onyx.app/admins/advanced_configs/opensearch_document_index_migration

Migrating indexed documents from Vespa to OpenSearch

## Overview

Onyx has gradually been working towards switching our backing document index database from Vespa to OpenSearch.
The motivating factors behind this decision are to reduce the baseline resources required to run Onyx,
and to switch to a widely used and supported documented index provider.

<Note>
  This is a living page and more details will be added over the coming weeks.
</Note>

## Migration

As of `v3`, Onyx uses both Vespa and OpenSearch.
Any documents which Onyx indexes while using this version are indexed into both Vespa and OpenSearch,
and there is no migration required.

Also as of `v3`, Onyx automatically runs a task to migrate your existing documents from Vespa to OpenSearch.
This task makes checkpointed progress so Onyx does not necessarily need to be running continuously until the migration
completes in order for it to complete successfully.
No explicit input is needed from admins other than upgrading to `v3` in order for this task to run.

The migration's progress can be monitored in the Admin Panel, in the Document Index Migration sidebar tab.

<Warning>
  The migration is best-effort. Although the vast majority of documents are not expected to have migration issues,
  some documents (in particular documents which were indexed a long time ago in versions of Onyx which enforced
  weaker/different contracts for indexed content) may have irreconcilable migration issues.
  In this event the only solution is a re-index of connectors for those documents,
  where they will be processed in such a way that they can then be indexed into OpenSearch.
</Warning>

## Deprecation of Vespa

`v4` of Onyx will represent the first major version to use OpenSearch entirely without Vespa.

<Warning>
  In order to preserve existing indexed content in Vespa without requiring re-indexing,
  it will be necessary to upgrade to `v3` of Onyx to allow migrations to run before upgrading to `v4`, when released.

  Although it may be technically feasible without breaking the product for a determined admin to upgrade Onyx directly
  from some version \< `v3` directly to some version > `v3` skipping `v3` entirely,
  this will result in complete loss of indexed data and will require re-indexing all connectors in order to be able to
  search over documents.
</Warning>

## Retrieval

During `v3`, document retrieval can be done via either Vespa (the default) or OpenSearch,
and which one is used can be toggled in the Document Index Migration sidebar tab on the Admin Panel. Naturally,
if the migration is not yet complete, retrieval via OpenSearch may not yield every expected document.

## cloud.onyx.app

The migration for cloud users began in March 2026,
and by April 2026 virtually all tenants' migrations indicated completion.

As of `v3.2.0-cloud.7` in April, all tenants in the cloud have been swapped over to OpenSearch for retrieval,
and Vespa is no longer in the loop with Onyx, so all new documents indexed are indexed only using OpenSearch.

<Warning>
  Due to a unique failure mode involving automatic updates in Vespa Cloud,
  there may be some migrations which report successful completion despite there being some existing documents which did
  not exist from the perspective of Vespa at the time of migration for that particular document,
  and which therefore might not have been migrated into OpenSearch.

  Similarly to the best-effort warning above,
  the recommended solution to this is a re-index for connectors suspected of having missing documents.
  Unfortunately due to the nature of this issue,
  there is little visibility into which specific documents may have experienced this.
</Warning>


# Index Settings
Source: https://docs.onyx.app/admins/advanced_configs/search_configs

Configure search settings and parameters

## Overview

From the **Search Settings** page, you can configure the embedding model, reranking,
and a variety of advanced search and indexing options.

<img alt="Search settings overview page" />

### Embedding Model

The embedding model is used to convert your documents into vectors that are stored in Vespa.
These vectors are used to search for relevant documents when a user queries Onyx.

A powerful embedding model can significantly improve the accuracy of your search results,
but comes at the cost of additional memory and disk usage.

<img alt="Embedding model configuration page" />

<AccordionGroup>
  <Accordion title="Cloud Models" icon="cloud">
    The best embedding models are generally available through a cloud provider such as Cohere or Google.

    To use a cloud provider, select the model you want to use, submit your credentials for the provider,
    and click **Continue**.
  </Accordion>

  <Accordion title="Self-hosted Models" icon="server">
    Self-hosted models run on your own infrastructure and guarantee that your data does not leave your bounds.

    <Note>
      Embedding data at the scale that Onyx operates requires significant compute resources.
      If you want to use a self-hosted model,
      we strongly recommend you make a GPU available to Onyx's indexing model server container.
    </Note>

    In the **Self-hosted** tab, you can select a suggested model or follow the instructions to connect your own model.
  </Accordion>
</AccordionGroup>

#### Embedding Swaps

If you select a new embedding model, Onyx will need to re-index all of your data. During this process,
the old embedding model will still be available for searches.

While the swap is in progress, you will see the Search Settings page show details indexing progress.

<Tip>
  This process can take a while. Additionally, private user data is also being re-indexed,
  but are not displayed to the Admin Search Settings page.
</Tip>

<img alt="Embedding swap in progress" />

### Reranking

Reranking is an optional step that can be used to improve the accuracy of your search results.
A reranking model will assess and re-organize your search results based on the relevance of the documents to the query.
This process adds a small amount of latency to your search results.

Generally, re-ranking is only useful if you have a very large number of documents.

<img alt="Reranking configuration page" />

### Advanced Configs

On the final page, you can configure a variety of advanced search settings.

<AccordionGroup>
  <Accordion title="Multilingual Expansion">
    Multilingual expansion rephrases your queries into the specified other languages.
    This can be helpful for cross-language results.
  </Accordion>

  <Accordion title="Multipass Indexing">
    Multipass indexing creates chunks of varying sizes and stores them in the index.
    This can help the hybrid search algorithm better identify relevant sources.
  </Accordion>

  <Accordion title="Contextual RAG">
    Contextual RAG adds additional document-level information to every chunk in the index.
    This can help the hybrid search algorithm better identify relevant sources.

    <Warning>
      Contextual RAG can be very expensive as it adds a signficnat amount of data to every embedding call.
    </Warning>
  </Accordion>

  <Accordion title="Embedding Precision">
    Embedding precision may be set to either `bfloat16` or `float`.
    Setting the precision to `bfloat16` can reduce the memory usage of the index,
    but may slightly reduce the accuracy of the results.
  </Accordion>

  <Accordion title="Reduced Dimension">
    Setting this value will reduce the number of dimensions in the embedding vectors.
    This can reduce the memory usage of the index, but may reduce the accuracy of the results.

    <Warning>
      Reduced dimension is only supported for OpenAI embedding models at this time.
    </Warning>
  </Accordion>
</AccordionGroup>

<img alt="Advanced search configurations page" />


# Spending Limits
Source: https://docs.onyx.app/admins/advanced_configs/spending_limits

Configure spending limits in Onyx

## Overview

Spending limits allow you to configure LLM rate limits and throttling settings.
These settings are found in the **Admin Panel** under **Appearance & Theming**.

Rate limits can be applied globally, by User, or by User Group.

<img alt="Spending Limits" />


# Tracing
Source: https://docs.onyx.app/admins/advanced_configs/tracing

Send LLM call traces to observability platforms to monitor and evaluate your Onyx deployment

Tracing forwards every LLM call Onyx makes to an external observability platform so you can monitor latency,
token usage, and cost, and evaluate response quality. Onyx supports [Braintrust](https://www.braintrust.dev)
and [Langfuse](https://langfuse.com).

<Note>
  Tracing is available on **self-hosted** deployments. It is not configurable on Onyx Cloud.
</Note>

## Connect a provider

<Steps>
  <Step title="Navigate to the Tracing dashboard">
    Click your user profile icon, select **Admin Panel**,
    and open the **Tracing** tab under the **Usage** section of the sidebar.
  </Step>

  <Step title="Connect Braintrust and/or Langfuse">
    You can connect either or both providers — traces are sent to every connected provider.

    <Tabs>
      <Tab title="Braintrust">
        Create an API key in the [Braintrust dashboard](https://www.braintrust.dev/app) under **Settings → API Keys**.

        In Onyx, click **Connect** on the Braintrust card and fill in:

        * **API Key** — your Braintrust API key.
        * **Project Name** *(optional)* — the Braintrust project traces are logged to. Defaults
          to `Onyx`.
        * **API URL** *(optional)* — only needed for self-hosted Braintrust or non-default
          regions. Defaults to `https://api.braintrust.dev`.
      </Tab>

      <Tab title="Langfuse">
        Create a key pair in your [Langfuse](https://cloud.langfuse.com) project settings under **Setup → API Keys**.

        In Onyx, click **Connect** on the Langfuse card and fill in:

        * **Secret Key** — your Langfuse secret key (`sk-...`).
        * **Public Key** — your Langfuse public key (`pk-...`).
        * **API Base URL** *(optional)* — defaults to the EU region
          (`https://cloud.langfuse.com`). Set this for the US region, another region, or a self-hosted Langfuse instance.
      </Tab>
    </Tabs>

    Onyx validates the credentials before saving. Once connected,
    the card shows **Connected** and traces begin flowing within about 30 seconds — no restart required.
  </Step>
</Steps>

## Disconnect a provider

Open the provider card, click the disconnect button, and confirm.
Onyx stops sending new traces to that provider immediately. Traces already delivered are unaffected.

## Configuring with environment variables

Configuring tracing from the Admin Panel is the recommended approach,
but Onyx also honors environment variables for backwards compatibility.
A provider configured through the UI takes precedence over its environment variables.

| Provider   | Variable              | Description                                                    |
| ---------- | --------------------- | -------------------------------------------------------------- |
| Braintrust | `BRAINTRUST_API_KEY`  | API key. Enables Braintrust tracing when set.                  |
| Braintrust | `BRAINTRUST_PROJECT`  | Project name traces are logged to. Defaults to `Onyx`.         |
| Braintrust | `BRAINTRUST_API_URL`  | Custom API URL for self-hosted / non-default regions.          |
| Langfuse   | `LANGFUSE_SECRET_KEY` | Secret key. Required (with the public key) to enable Langfuse. |
| Langfuse   | `LANGFUSE_PUBLIC_KEY` | Public key. Required (with the secret key) to enable Langfuse. |
| Langfuse   | `LANGFUSE_HOST`       | Base URL for a non-default region or self-hosted Langfuse.     |

<Note>
  Providers configured through environment variables appear in the Tracing dashboard as configured via environment.
  You can adopt them into UI-managed configuration by connecting the provider from the Admin Panel.
</Note>


# White Labeling
Source: https://docs.onyx.app/admins/advanced_configs/white_labeling

Customize Onyx's branding and appearance

White labeling allows you to customize Onyx's appearance to match your organization's identity.
These settings are found in the **Admin Panel** under **Appearance & Theming**.

<Note>
  White labeling is an [Enterprise Edition](/deployment/miscellaneous/enterprise_edition) feature.
</Note>

## White Labeling Options

### Logo and Name

You can customize the logo, the application name, or both independently:

* **Custom Logo** — upload an image to replace the default Onyx logo shown in the top left corner and on the login page
* **Application Name** — set a custom name displayed alongside or in place of the logo

<img alt="Custom Logo and Name" />

### Messaging

Customize the text shown throughout the chat interface:

* **Greeting Message** — shown to users when they start a new chat session
* **Chat Header Text** — displayed in the header of the chat interface
* **Chat Footer Text** — displayed in the footer of the chat interface

<img alt="Greeting Message, Chat Header, and Footer" />

### First Visit Notice

Configure a notice shown to users the first time they access Onyx. The notice has the following options:

| Option              | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| **Show Notice**     | Toggle to enable or disable the first visit notice                          |
| **Notice Header**   | Title text displayed at the top of the notice                               |
| **Notice Content**  | Body text of the notice                                                     |
| **Require Consent** | When enabled, users must acknowledge the notice before they can access Onyx |

<img alt="First Visit Notice" />


# Custom Agents
Source: https://docs.onyx.app/admins/agents/overview

Managing AI agents

Onyx Agents are customized AI assistants with unique instructions, knowledge sources, and Actions.

## Managing Agents

On the Agents page in the Admin Panel, you can see all of the Agents in your organization.

From this page, you can create new Agents, edit existing configurations, designate featured Agents,
hide or show certain Agents, and delete them.

<img alt="Onyx Agents Overview page showing available agents" />

## Creating Agents

<Steps>
  <Step title="Create a New Agent">
    Navigate to the **Admin Panel** and click **Agents** in the sidebar. Click **New Agent** to create a new agent.
  </Step>

  <Step title="Name and Prompt your Agent">
    Give your Assistant a name, description, instructions, and maybe even an icon.

    To help users understand how to use your Agent, you can add **Conversation Starters**.

    <img alt="Onyx Agent Configuration page" />
  </Step>

  <Step title="Attach Knowledge to your Agent">
    Onyx provides several methods for attaching information to Agents.

    <img alt="Onyx Agent Knowledge configuration" />

    If **Use Knowledge** is toggled on but nothing is selected (as in the screenshot above),
    the agent will have access to anything accessible to the person using the agent. This includes:

    * Any files that the user has uploaded ("Your Files" in the admin view, visible from the Upload Files icon in the
      chat window for basic users chatting with the agent)
    * All documents from all public connectors
    * Documents that the user has access to in the external source for permission-synced connectors

    See the [Connectors](/admins/connectors/overview) page for more detail on permissions.

    Explicitly selecting anything in Add Knowledge will narrow the Agent's scope to *only* that selected knowledge.
    This can be useful because search quality tends to slowly degrade at scale,
    so in larger organizations narrowing the scope of what is searched over may improve answer quality.

    For Onyx versions prior to 3.0 and 3.x deployments that have not yet completed a migration to OpenSearch,
    the primary way of scoping access to connectors and granting an agent access to private connectors is to put the
    desired connectors into a [Document Set](/admins/managing_features/document_sets),
    then select that document set in the Document Sets section of the Add Knowledge pane.

    <Note>
      The OpenSearch migration note above is relevant for existing deployments upgrading to 3.x, not new deployments.
    </Note>

    This functionality is still available in Onyx 3.x+,
    but with OpenSearch enabled Onyx also provides a more granular way to attach knowledge to agents.
    By clicking on specific source types (added by creating a connector of that source type and indexing successfully),
    you can view the hierarchy of knowledge in your source and select files and folders you want your agent to have
    access to when searching for knowledge.
    Selecting a folder gives the agent access to all information in that folder and in all its sub-folders.

    <img alt="Onyx Agent hierarchical knowledge selection showing folder and file browsing" />
  </Step>

  <Step title="Give your Agent Tools">
    Add Actions to your Agent to enable it to perform specific tasks. See [Actions Overview](/admins/actions/overview)
    for more information.

    <img alt="Onyx Agent Configuration page" />
  </Step>

  <Step title="Agent Configuration (Advanced)">
    You can publish your Agent to your entire organization or share it with specific users or groups.

    If you set your Agent as **Featured**, your users will see it at the top of the Agents explorer.

    You can configure the default language model for your Agent.

    You can also configure certain knowledge options for your Agent,
    such as a knowledge cutoff date and overwriting the system prompt.

    <img alt="Onyx Agent advanced configuration options" />
  </Step>
</Steps>

Once you've published your Agent, you can find it in the **Explore Agents** page from the Chat sidebar.

<img alt="Onyx Explore Agents page" />


# Anthropic
Source: https://docs.onyx.app/admins/ai_models/anthropic

Configure Anthropic Claude language models for Onyx

## Guide

<Steps>
  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Anthropic">
    Select **Anthropic** from the available providers.

    Give this configuration a **Display Name**.

    Create an [API key](https://console.anthropic.com/dashboard)
    from the Anthropic API dashboard and paste it in the **API Key** field.

    <img alt="Anthropic Provider Configuration" />
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Azure OpenAI
Source: https://docs.onyx.app/admins/ai_models/azure_openai

Configure Azure OpenAI for enterprise-grade GPT models

## Guide

<Steps>
  <Step title="Navigate to Azure Portal Resources">
    Go to the [Azure Portal](https://portal.azure.com/) and navigate to the Azure OpenAI Service.

    <img alt="Azure OpenAI Service" />
  </Step>

  <Step title="Create an Azure OpenAI Deployment">
    Click **Create** and fill out the required fields in each section. Default values are usually sufficient.

    The deployment may take a few minutes to complete.

    <img alt="Azure OpenAI Deployment" />
  </Step>

  <Step title="Create a Model Deployment">
    Go to the [Azure OpenAI Service](https://oai.azure.com/) and select your new AI resource.

    Navigate to the **Model Catalog** tab and select the model you want to use with Onyx.
    Click **Use this model** → **Deploy to selected resource**.

    <img alt="Azure OpenAI Service Landing Page" />

    <img alt="Azure OpenAI Model Deployment" />
  </Step>

  <Step title="Save Your Deployment Details and Credentials">
    In your deployed model page, save the **Target URI** and **API Key**. Your **Target URI** has the **API Base**,
    **API Version**, and **Deployment Name** necessary to configure the provider in Onyx.

    <img alt="Azure OpenAI Deployed Model Details" />

    <Warning>
      If you see `I'm sorry, but I cannot assist with that request` in Onyx chat responses,
      update the model deployment **Content filter** to **Default** instead of **DefaultV2**.

      <img alt="Azure OpenAI configuration page" />
    </Warning>
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Azure OpenAI Provider">
    Select **Azure OpenAI** from the available providers.

    Give this configuration a **Display Name**.

    Paste your **API Key** into the **API Key** field.

    From your **Target URI**, extract the **API Base**, **API Version**, and **Deployment Name**

    Example:
    `https://onyxazureai.openai.azure.com/openai/deployments/gpt-4.1/chat/completions?api-version=2025-01-01-preview`

    <img alt="Azure OpenAI Provider Configuration" />
  </Step>

  <Step title="Designate Provider Access">
    In the **Advanced Options**, you may select whether or not the provider is public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Amazon Bedrock
Source: https://docs.onyx.app/admins/ai_models/bedrock

Configure Amazon Bedrock models for use with Onyx

## Authentication Methods

Onyx supports 3 authentication methods for Amazon Bedrock:

<AccordionGroup>
  <Accordion title="IAM (Recommended for AWS environments)">
    * Automatically authorizes Onyx through an IAM Role attached to the environment
    * Use when running on AWS infrastructure (EC2, EKS)

    To connect Onyx to Bedrock using IAM, create an IAM Role with the `AmazonBedrockLimitedAccess` policy. Optionally,
    you can attach the `AmazonBedrockFullAccess` and `AmazonBedrockMarketplaceAccess` policies.

    Once created, attach the IAM Role to the environment that Onyx is running in. For example,
    attach the IAM Role to your Onyx EC2 instance or EKS service account.
  </Accordion>

  <Accordion title="Access Key (for non-AWS environments)">
    * Manual credential management using an Access Key ID and Secret Access Key
    * Recommended for accessing Bedrock from non-AWS environments

    To connect Onyx to Bedrock using Access Keys, create an IAM User with the `AmazonBedrockLimitedAccess` policy.
    Optionally, you can attach the `AmazonBedrockFullAccess` and `AmazonBedrockMarketplaceAccess` policies.

    Once created, go to your IAM User's **Security Credentials** tab.
    Create a new **Access Key** and copy the **Access Key ID** and **Secret Access Key**.

    Provide these credentials to Onyx using one of the following methods:

    * Add them to your Onyx `.env` file as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
    * Add them to your AWS CLI config in `~/.aws/credentials`
    * Enter them directly in the Onyx Bedrock configuration UI
  </Accordion>

  <Accordion title="Bedrock API Key (for non-AWS environments)">
    * New method to access Bedrock generated from the AWS Bedrock Console
    * Recommended for accessing Bedrock from non-AWS environments

    To connect Onyx to Bedrock using an API Key, navigate to the Bedrock console,
    select **API keys** and create a **Long-term API key**.
    AWS will automatically create a new IAM User with the `AmazonBedrockLimitedAccess` policy.

    Submit your API key to Onyx through the Onyx Bedrock configuration UI.
  </Accordion>
</AccordionGroup>

<Note>
  When using an IAM role, the role credentials must be attached to the Onyx environment.
  When using Access Keys or a Bedrock API Key, you must provide the credentials in the Onyx LLM configuration UI.
</Note>

## Guide

<Steps>
  <Step title="Set up your Authentication Method">
    Determine if IAM, Access Keys, or a Bedrock API Key is the best authentication method for your environment.

    Click the above accordions to learn more about each method and how to set them up.
  </Step>

  <Step title="Enable Desired Models">
    Navigate to the **Model Catalog** and decide the models you want to use with Onyx.

    If you don't already have access to your desired models, you can request access through the Bedrock Console.

    <Note>
      If your models are not enabled, you will not be able to see them in Onyx!
      Ensure your models are available before continuing.
    </Note>
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Bedrock Provider">
    Select **AWS Bedrock** from the available providers.

    Give your provider a **Display Name**.

    Determine your AWS region and enter it in **AWS Region Name**.

    <Tip>
      Certain models are only available in specific regions or through cross-region inference profiles.
      Onyx will automatically determine what is available in your region.
    </Tip>

    Depending on your authentication method,
    fill out `AWS Access Key ID` and `AWS Secret Access Key` or `AWS Bedrock API Key`.

    Once your region and credentials are set, click the **Fetch Available Model for Region** button.

    <Warning>
      If you do not click the **Fetch Available Model for Region** button,
      you will see all Bedrock models listed even if you cannot use them.
    </Warning>

    <img alt="Bedrock Provider Configuration" />
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Bifrost
Source: https://docs.onyx.app/admins/ai_models/bifrost

Configure Bifrost as a language model gateway for Onyx

## Guide

Configure Onyx to use models served through [Bifrost](https://docs.getbifrost.ai/overview).

<Note>
  Onyx connects to your Bifrost gateway by fetching the models exposed at its `/v1/models` endpoint.
  Bifrost can expose models from multiple vendors behind a single endpoint.
</Note>

<Steps>
  <Step title="Set Up Your Bifrost Gateway">
    Make sure your Bifrost deployment is reachable from the Onyx server.

    You will need your Bifrost **API Base URL**.

    If your Bifrost deployment requires authentication, also generate a Bifrost **API Key**.
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Bifrost">
    Select **Bifrost** from the available providers.

    Give your provider a **Display Name**.

    Enter the **API Base URL** for your Bifrost gateway.

    If your gateway requires authentication, enter your **API Key**.

    Click **Fetch Available Models** to load the language models currently exposed by Bifrost.
  </Step>

  <Step title="Review the Imported Models">
    Onyx will import the model IDs returned by Bifrost and use the display names returned by the gateway when available.

    This is useful when your Bifrost gateway exposes models from multiple vendors such as Anthropic, OpenAI, or others.
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Custom Inference Provider
Source: https://docs.onyx.app/admins/ai_models/custom_inference_provider

Configure an OpenAI-compatible language model provider

## Guide

If you want to use a language model provider that is not supported directly by Onyx,
you can configure a custom inference provider.

<Tip>
  Your custom provider must provide OpenAI-compatible API endpoints.
</Tip>

<Steps>
  <Step title="Setup your Custom Inference Provider">
    Determine your provider's API base URL.
    It should look something like `https://yourprovider.com/v1` or `http://localhost:12345/v1`.
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Custom Inference Provider">
    Select **Add Custom LLM Provider** from the available providers.

    Give your provider a **Display Name**.

    Enter your model's **Provider Name**.

    <Note>
      The **Provider Name** must match Litellm's [list of supported providers](https://docs.litellm.ai/docs/providers).
    </Note>

    In this example, the provider name is `vertex_ai`.

    <img alt="Custom inference provider name" />
  </Step>

  <Step title="Configure Optional Fields and Models">
    Enter the provider's **Base URL**.

    Fill out the other optional fields if applicable.

    In the **Model Configurations** section, enter each model you want to make available through this provider.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, you may select whether or not the provider is public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Google Vertex AI
Source: https://docs.onyx.app/admins/ai_models/google_ai

Configure Google Vertex AI language models for use with Onyx

## Guide

This guide walks through setting up Google Vertex AI language models for use with Onyx.

<Note>
  Google Vertex AI and Google AI Studio serve the same models. However,
  Vertex AI has enterprise-grade features that may be useful for your organization.
</Note>

<Steps>
  <Step title="Create a Service Account for Onyx">
    Go to the [Google Cloud Console Service Accounts Page](https://console.cloud.google.com/iam-admin/serviceaccounts)

    Select your project and click **Create Service Account**.

    Give your Service Account a name and a description.

    On the **Permissions** tab, grant the service account the **Agent Platform User** role.

    <img alt="Google Cloud Console Service Accounts Page" />

    <img alt="Google Cloud Console Service Account Configuration" />
  </Step>

  <Step title="Create a New Key for the Service Account">
    Click your newly created Service Account → **Keys** → **Add Key** → **Create new key**.

    Select **JSON** as the key type and click **Create**. The key will be automatically downloaded to your computer.
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Google Vertex AI">
    Select **Google Cloud Vertex AI** from the available providers.

    Give this configuration a **Display Name**.

    Upload your JSON key to the **Credentials File** field.

    If relevant, specify a **Location**.
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# LiteLLM Proxy
Source: https://docs.onyx.app/admins/ai_models/litellm_proxy

Configure LiteLLM Proxy as a language model gateway for Onyx

## Guide

Configure Onyx to use models exposed by your LiteLLM Proxy server.

<Note>
  Onyx reads the available models from the LiteLLM Proxy `/v1/models` endpoint.
  This is a good option when you want one gateway in front of multiple providers or self-hosted backends.
</Note>

<Steps>
  <Step title="Set Up LiteLLM Proxy">
    Deploy LiteLLM Proxy and make sure it is reachable from the Onyx server.

    You will need the LiteLLM Proxy **API Base URL** and **API Key**.

    The local default is commonly `http://localhost:4000`.
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure LiteLLM Proxy">
    Select **LiteLLM Proxy** from the available providers.

    Give your provider a **Display Name**.

    Enter the proxy **API Base URL** and **API Key**.

    Click **Fetch Available Models** to load the models currently exposed by your LiteLLM Proxy instance.
  </Step>

  <Step title="Review the Imported Models">
    Onyx stores the model IDs returned by LiteLLM Proxy and makes those models available to your users.

    This is useful when LiteLLM is routing requests to multiple providers through a single gateway.
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# LM Studio
Source: https://docs.onyx.app/admins/ai_models/lm_studio

Using LM Studio with Onyx

## Guide

Configure Onyx to use models served by [LM Studio](https://lmstudio.ai/).

Onyx has a built-in integration with LM Studio that auto-discovers your loaded models,
including their capabilities (vision, reasoning) and context length.

<Steps>
  <Step title="Setup LM Studio and Load Your Models">
    Download LM Studio from [lmstudio.ai](https://lmstudio.ai/) and load the models you want to use.

    Start the LM Studio local server:

    ```bash theme={null}
    lms server start --port 1234
    ```

    LM Studio runs on port `1234` by default.

    <Tip>
      For best results, use a model with strong instruction-following and tool-use capabilities (e.g., Qwen 3.5).
    </Tip>

    If LM Studio is running on a different machine than Onyx,
    make sure the server is accessible from the Onyx host (e.g., `http://<lm-studio-host>:1234`).

    <Info>
      **Running Onyx in Docker on the same machine as LM Studio?**

      By default, LM Studio binds only to `127.0.0.1`, which is unreachable from inside an Onyx container. To fix:

      * In LM Studio's **Developer** tab, enable **"Serve on Local Network"** (or set the host to `0.0.0.0`) and restart the server.
      * Use `http://host.docker.internal:1234` as the **API Base URL** instead of `http://localhost:1234`.

      See [LM Studio's docs](https://lmstudio.ai/docs/developer/core/server/serve-on-network) for more details.
    </Info>
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure LM Studio">
    Select **LM Studio** from the available providers.

    Give your provider a **Display Name**.

    Set the **API Base URL** to your LM Studio server address (e.g., `http://localhost:1234`).

    If Onyx is running in Docker on the same machine as LM Studio,
    use `http://host.docker.internal:1234` instead — `localhost` inside the container points to the container itself,
    not your host.
    Make sure LM Studio is set to **"Serve on Local Network"** (see the Info callout in the previous step).

    Onyx will automatically connect and discover your loaded models.

    <img alt="LM Studio Provider Configuration" />
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Ollama
Source: https://docs.onyx.app/admins/ai_models/ollama

Using Ollama with Onyx

## Guide

Configure Onyx to use models served by [Ollama](https://ollama.com/).

<Steps>
  <Step title="Setup Ollama and Deploy your Models">
    The [Ollama GitHub repository](https://github.com/ollama/ollama?tab=readme-ov-file#ollama)
    details how to download and deploy models on Ollama.

    If self-hosting, Ollama is configured to run on port `11434` by default.

    You can also configure Onyx to use [Ollama's managed cloud service](https://ollama.com/cloud).
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure Ollama">
    Select **Ollama** from the available providers.

    Give your provider a **Display Name**.

    If using Ollama Cloud, enter your Ollama Cloud **API Key**.

    Click the **Fetch Available Models** button to see the models available in your Ollama instance.

    <img alt="Ollama Provider Configuration" />
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# OpenAI
Source: https://docs.onyx.app/admins/ai_models/openai

Configure OpenAI language models for Onyx

## Guide

<Steps>
  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure OpenAI Provider">
    Select **OpenAI** from the available providers.

    Give this configuration a **Display Name**.

    Create an [API key](https://platform.openai.com/api-keys)
    from the OpenAI API dashboard and paste it in the **API Key** field.

    <img alt="OpenAI Provider Configuration" />
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# OpenRouter
Source: https://docs.onyx.app/admins/ai_models/openrouter

Using OpenRouter with Onyx

## Guide

Configure Onyx to use models served by [OpenRouter](https://openrouter.ai/).

<Steps>
  <Step title="Setup OpenRouter and Deploy your Models">
    Log in to your OpenRouter account and create a new API key.
  </Step>

  <Step title="Navigate to Language Models">
    Access the Admin Panel from your user profile icon, then navigate to **Configuration → Language Models**.
  </Step>

  <Step title="Configure OpenRouter">
    Select **OpenRouter** from the available providers.

    Give your provider a **Display Name**.

    Enter your OpenRouter **API Key**.

    Click the **Fetch Available Models** button to see the models currently available on OpenRouter.

    <img alt="OpenRouter Provider Configuration" />
  </Step>

  <Step title="Choose Visible Models">
    In the **Advanced Options**, you will see a list of all models available from this provider.
    You may choose which models are visible to your users in Onyx.

    Setting visible models is useful when a provider publishes multiple models and versions of the same model.
  </Step>

  <Step title="Designate Provider Access">
    Lastly, decide whether the provider should be public to all users in Onyx.

    If set to private,
    the provider's models will be available to Admins and User Groups you explicitly assign the provider to.
  </Step>
</Steps>


# Overview
Source: https://docs.onyx.app/admins/ai_models/overview

Configure language model providers and models in Onyx

<Tip>
  Use this page to configure the language models available for chat, agents, and other text-based workflows in Onyx.
</Tip>

<Note>
  Image generation and voice are configured separately in [Image Generation](/admins/actions/image_generation)
  and [Voice Mode](/admins/actions/voice_mode).
</Note>

## Language Models

Navigate to **Admin Panel → Language Models** to choose which providers your workspace can use,
which models are visible, and which models should be the default or fast option in Onyx.

<img alt="Language Models page overview" />

### Provider Types

<AccordionGroup>
  <Accordion title="Direct Model Providers" icon="cloud">
    These providers give you direct access to a model vendor's hosted API.

    Common choices include **OpenAI** and **Anthropic**.
    This is usually the simplest setup when you want fast access to the provider's latest flagship models.
  </Accordion>

  <Accordion title="Cloud Platforms and Aggregators" icon="server">
    These providers expose language models through a broader cloud or routing layer.

    Common choices include **Azure OpenAI**, **Amazon Bedrock**, **Google Vertex AI**, **OpenRouter**,
    **LiteLLM Proxy**, and **Bifrost**. They are useful when you need enterprise controls, cloud alignment,
    regional hosting options, or access to multiple model families from one integration point.
  </Accordion>

  <Accordion title="Self-Hosted and Local Runtimes" icon="desktop">
    These options let you run open-weight models on your own infrastructure or local hardware.

    Onyx includes built-in integrations for [Ollama](/admins/ai_models/ollama)
    and [LM Studio](/admins/ai_models/lm_studio). This is a good fit when your team needs local development workflows,
    tighter data residency, or lower per-token costs.
  </Accordion>

  <Accordion title="OpenAI-Compatible Custom Providers" icon="cpu">
    If your provider is not listed directly, you can still connect it through an OpenAI-compatible API.

    This covers custom gateways, hosted inference endpoints,
    and internal model platforms that expose an OpenAI-style `/chat/completions` or `/models` interface.
  </Accordion>
</AccordionGroup>

### Choosing a Good Starting Setup

<Note>
  If cloud-hosted models are approved for your organization,
  they are usually the best default choice because they are easier to operate and generally provide the best
  capability-to-cost tradeoff.
</Note>

* Start with one primary provider for most users.
* Use a recent **GPT**, **Claude**,
  or **Gemini** family model as your default if you want the strongest out-of-the-box experience.
* Use **Bedrock**, **Vertex AI**, **Azure OpenAI**, **OpenRouter**, **LiteLLM Proxy**, or **Bifrost** when procurement,
  routing, or cloud alignment matters more than a direct vendor integration.
* Use open-weight families such as **Llama**, **Qwen**, **DeepSeek**, or **gpt-oss** if you are self-hosting.
* Keep the visible model list short so users are choosing between a few intentional options instead of every possible
  version.

<Info>
  Self-hosting is best for advanced teams that already know which models they want to run and how they will operate
  them.
</Info>

## Configure Your Providers

<Columns>
  <Card title="OpenAI" icon="bolt" href="/admins/ai_models/openai" />

  <Card title="Azure OpenAI" icon="microsoft" href="/admins/ai_models/azure_openai" />

  <Card title="Anthropic" icon="brain" href="/admins/ai_models/anthropic" />

  <Card title="AWS Bedrock" icon="aws" href="/admins/ai_models/bedrock" />

  <Card title="Google Vertex AI" icon="google" href="/admins/ai_models/google_ai" />

  <Card title="OpenRouter" icon="robot" href="/admins/ai_models/openrouter" />

  <Card title="Bifrost" icon="server" href="/admins/ai_models/bifrost" />

  <Card title="LiteLLM Proxy" icon="server" href="/admins/ai_models/litellm_proxy" />

  <Card title="Ollama" icon="robot" href="/admins/ai_models/ollama" />

  <Card title="LM Studio" icon="desktop" href="/admins/ai_models/lm_studio" />

  <Card title="OpenAI-Compatible Providers" icon="server" href="/admins/ai_models/custom_inference_provider" />
</Columns>

## Best Practices

* Review the terms, privacy posture, and data processing terms of every provider you enable.
* Limit the visible model list to the models you actually want users to choose from.
* Use private providers and access controls for costly, experimental, or team-specific models.
* Decide on a default model at the organization level before rolling the page out broadly.
* Make sure internal guidance is clear about what data users can send to each provider.


# Custom Analytics
Source: https://docs.onyx.app/admins/analytics/custom_analytics

Configure a custom analytics provider in Onyx

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

Onyx Enterprise Edition allows you to configure a custom analytics provider.

<Steps>
  <Step title="Set the CUSTOM_ANALYTICS_SECRET_KEY environment variable">
    Set the `CUSTOM_ANALYTICS_SECRET_KEY` environment variable to some random string.
    Make sure you have the value saved temporarily somewhere.

    Re-deploy Onyx.
  </Step>

  <Step title="Go to the Custom Analytics tab in the Admin Panel">
    Go to the Custom Analytics tab in the Admin Panel.
  </Step>

  <Step title="Enter in the Javascript snippet provided by your Analytics provider">
    This snippet would normally be placed within the `<head>` tags at the base of your project. For the Secret Key,
    use the value you saved in Step 1.

    <Note>
      The `<script>` tag MUST be removed before being copied into the text box.
    </Note>
  </Step>
</Steps>

For reference: [PostHog's documentation](https://posthog.com/docs/product-analytics/installation)
on how to set up a custom analytics provider.


# Usage Analytics
Source: https://docs.onyx.app/admins/analytics/overview

Analytics and usage monitoring in Onyx

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

Onyx provides comprehensive analytics to help you understand how your users are interacting with the system and monitor
usage patterns across your organization.

## Usage Statistics

On the Usage Statistics page, you can see a summary graph of the active users and number of queries sent to Onyx.

Additionally, you view the thumbs up and thumbs down feedback your users are giving their AI answers.

<img alt="Usage Statistics" />


# Query History
Source: https://docs.onyx.app/admins/analytics/query_history

View and export query history in Onyx

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

On the Query History page, you can see a log of all messages sent to Onyx.
This includes messages sent to the Slack bot and through API keys.

<img alt="Query History" />

## Exporting Query History

You can export your query history to a CSV file.
This export can be time consuming depending on the size of your query history.


# Audit Logs & SIEM Integration
Source: https://docs.onyx.app/admins/auditing/audit_logs

Forward Onyx's structured audit-event stream to your SIEM for security monitoring and compliance

<Note>
  Audit logging is available in **Onyx v4.3 and later**,
  on **self-hosted** deployments where you control the log pipeline.
</Note>

## Overview

Onyx emits a normalized, structured **audit-event stream** for security-relevant actions — authentication,
user and access-control changes, admin configuration changes, and credential access.
Every event is a single JSON object, so you can forward the stream to any SIEM — **Splunk, Microsoft Sentinel, Elastic,
Google Chronicle, AWS Security Lake** — with no Onyx-side integration to build.
You point your log shipper at Onyx's logs, filter the audit stream, and parse the JSON.

Field names and the action taxonomy are shaped toward [**OCSF**](https://schema.ocsf.io)
(the Open Cybersecurity Schema Framework), so events map cleanly onto the event classes most SIEMs already understand.

This maps directly onto common compliance controls — **SOC 2 CC7** and the **NIST 800-53 / FedRAMP AU** family (AU-2
auditable events, AU-3 record content, AU-6 review, AU-12 generation).

## What gets captured

<AccordionGroup>
  <Accordion title="Authentication">
    Login success, login failure, logout, registration, password forgot, password reset, and email verification.
  </Accordion>

  <Accordion title="User & access management">
    User creation (admin invites), deletion, deactivation, reactivation, role changes,
    and user-group membership changes.
  </Accordion>

  <Accordion title="Configuration & resources">
    Create / update / delete of LLM providers, connectors, connector-credential pairs, API keys,
    and credentials — plus credential-access (decrypt) events.
  </Accordion>
</AccordionGroup>

Each event records **who** did **what**, to **which resource**, **when**, from **where**,
and whether it **succeeded** — the core of an audit trail.

## How it works

Audit events are emitted as `INFO` log records on a dedicated **`onyx.audit`** logger.
The message body of each record is a single JSON object — Onyx serializes the event itself,
so the audit line is identical regardless of your log format.

Emission is **fail-safe**: it never interrupts a user request or a connector run,
even if context gathering or logging fails. High-volume event classes are de-duplicated within a short (10-minute)
window using Redis. De-duplication is **fail-open** — if Redis is unavailable,
the dedup check is skipped and the event is still emitted,
so an audit event is never silently dropped due to infrastructure trouble (you may just see a duplicate).

The subsystem is **always on** — there is no enable/disable flag, output-format, or destination setting,
and the de-duplication window is fixed. The only related knob is `LOG_FORMAT` (below),
which shapes the *surrounding* log records; the audit JSON body itself is identical either way.

<Tip>
  Run Onyx with `LOG_FORMAT=json` so that *all* log records — not just audit events — are machine-parseable,
  and request/tenant context is promoted to top-level fields.
  This makes filtering and parsing in your shipper much simpler.
</Tip>

## Event schema

| Field                  | Type           | Description                                                                                 |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `audit_schema_version` | string         | Schema version (currently `"1.0"`).                                                         |
| `ts`                   | number         | Event time, epoch seconds.                                                                  |
| `action`               | string         | Action taxonomy value, `<domain>.<verb>` (e.g. `llm_provider.update`). Stable, append-only. |
| `ocsf_class`           | string         | `authentication`, `account_change`, or `api_activity`.                                      |
| `outcome`              | string         | `success`, `failure`, or `denied`.                                                          |
| `tenant_id`            | string \| null | Tenant the action occurred in.                                                              |
| `actor`                | object \| null | `{ user_id, email, api_key_id, auth_type }`. Never contains a secret.                       |
| `resource_type`        | string \| null | Affected resource type (e.g. `llm_provider`, `user`, `api_key`).                            |
| `resource_id`          | string \| null | Affected resource identifier.                                                               |
| `request_id`           | string \| null | Correlates the event with the rest of that request's logs.                                  |
| `endpoint`             | string \| null | Route that produced the event.                                                              |
| `source_ip`            | string \| null | Client IP (from `X-Forwarded-For`).                                                         |
| `extra`                | object \| null | Additional non-secret context.                                                              |

The `action` values are a stable, append-only contract — safe to filter and build dashboards against.
New actions may be added over time; existing ones do not change meaning.

### Example event

```json theme={null}
{
  "audit_schema_version": "1.0",
  "ts": 1750000000.123,
  "action": "llm_provider.update",
  "ocsf_class": "api_activity",
  "outcome": "success",
  "tenant_id": "tenant_abc",
  "actor": { "user_id": "u-42", "email": "admin@example.com", "api_key_id": null, "auth_type": "oauth" },
  "resource_type": "llm_provider",
  "resource_id": "7",
  "request_id": "01J...",
  "endpoint": "PUT /admin/llm/provider",
  "source_ip": "203.0.113.5",
  "extra": null
}
```

## Forward to your SIEM

Because audit events are just JSON log lines on a known logger prefix, any log shipper works.

<Steps>
  <Step title="Run Onyx with JSON logging">
    Set `LOG_FORMAT=json` so every log record is structured and carries a `logger` and `message` field.
  </Step>

  <Step title="Ship Onyx's logs">
    Point Fluent Bit, Vector, the CloudWatch agent, Filebeat,
    or your existing collector at the Onyx container stdout (or the mounted log files).
  </Step>

  <Step title="Isolate and parse the audit stream">
    Keep only records whose `logger` starts with `onyx.audit`,
    then parse each record's `message` field as JSON to recover the event fields above.
  </Step>

  <Step title="Route to your SIEM">
    Send the parsed events to your SIEM's ingest endpoint. The OCSF-shaped fields map onto Authentication,
    Account Change, and API Activity event classes.
  </Step>
</Steps>

### Shipper examples

<CodeGroup>
  ```toml Vector theme={null}
  # Keep only audit records, then replace the event with the parsed JSON payload.
  [transforms.onyx_audit]
  type = "filter"
  inputs = ["onyx_logs"]
  condition = '''starts_with(string!(.logger), "onyx.audit")'''

  [transforms.onyx_audit_parsed]
  type = "remap"
  inputs = ["onyx_audit"]
  source = '. = parse_json!(.message)'
  ```

  ```ini Fluent Bit theme={null}
  # Match the audit stream by logger prefix.
  [FILTER]
    Name    grep
    Match   onyx.*
    Regex   logger ^onyx\.audit
  ```
</CodeGroup>

<Info>
  Filter on the `onyx.audit` **prefix** to capture everything.
  The stream is also split into per-class child loggers — `onyx.audit.authentication`, `onyx.audit.account_change`,
  `onyx.audit.api_activity`,
  and `onyx.audit.credential_access` — if you want to route classes to different destinations.
</Info>

## Event reference

Every `action` value, what triggers it, and the fields most useful for building SIEM detection rules. `actor`,
`tenant_id`, `request_id`, `endpoint`, `source_ip`,
and `outcome` are present on every event (see [Event schema](#event-schema)) and are omitted from the tables below.

### Authentication

`ocsf_class: authentication`

| `action`               | Triggered when                            | Notes                                                           |
| ---------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| `auth.login`           | A user successfully signs in              |                                                                 |
| `auth.login_failure`   | A sign-in attempt fails                   | `outcome` is `failure`, or `denied` for a non-interactive login |
| `auth.logout`          | A user signs out                          |                                                                 |
| `auth.register`        | A new account is registered (self-signup) |                                                                 |
| `auth.password_forgot` | A password-reset email is requested       |                                                                 |
| `auth.password_reset`  | A password reset is completed             |                                                                 |
| `auth.email_verify`    | An email-verification email is requested  |                                                                 |

### User & access management

`ocsf_class: account_change` — `resource_type` is `user` (or `user_group`).

| `action`            | Triggered when                    | `resource_id` | Key `extra` fields                     |
| ------------------- | --------------------------------- | ------------- | -------------------------------------- |
| `user.create`       | An admin invites new users        | —             | `invited_emails`                       |
| `user.delete`       | A user is deleted                 | user id       | `target_email`                         |
| `user.deactivate`   | A user is deactivated             | user id       | `target_email`                         |
| `user.reactivate`   | A user is reactivated             | user id       | `target_email`                         |
| `user.role_change`  | A user's role is changed          | user id       | `target_email`, `old_role`, `new_role` |
| `user.group_change` | A user group's membership changes | user-group id | `added_user_ids`, `removed_user_ids`   |

### Configuration & resources

`ocsf_class: api_activity`

| `action`                                      | Triggered when                                                               | `resource_type` | `resource_id`                | Key `extra` fields                                                                    |
| --------------------------------------------- | ---------------------------------------------------------------------------- | --------------- | ---------------------------- | ------------------------------------------------------------------------------------- |
| `llm_provider.create` / `.update` / `.delete` | An LLM provider is created, updated, or deleted                              | `llm_provider`  | provider id                  |                                                                                       |
| `connector.create` / `.update` / `.delete`    | A connector is created, updated, or deleted                                  | `connector`     | connector id                 | `source` (on create)                                                                  |
| `cc_pair.create` / `.update` / `.delete`      | A connector is linked to a credential, its status changes, or it is unlinked | `cc_pair`       | connector-credential-pair id | `connector_id`, `credential_id`; `status` (on update)                                 |
| `api_key.create` / `.regenerate` / `.delete`  | An API key is created, regenerated, or revoked                               | `api_key`       | API-key id                   |                                                                                       |
| `credential.create` / `.update` / `.delete`   | A stored credential is created, updated, or deleted                          | `credential`    | credential id                | `source` (on create)                                                                  |
| `credential.access`                           | A stored credential is decrypted for use                                     | —               | —                            | Emitted on a **different schema** — see [Credential access](#credential-access) below |

### Credential access

`onyx.audit.credential_access`

Credential-decrypt events predate the generalized schema and are emitted on a **flat,
legacy field set** for backward compatibility.
They share the `onyx.audit` logger tree and the same fail-safe / fail-open behavior,
but do **not** carry the generalized fields — there is no `action`, `ocsf_class`, `outcome`,
`resource_type`/`resource_id`, `extra`, or nested `actor` object, and the client IP is `client_ip` (not `source_ip`).
Parse this stream separately; detection rules written against the generalized schema will not match it.

| Field             | Type           | Description                                                      |
| ----------------- | -------------- | ---------------------------------------------------------------- |
| `ts`              | number         | Event time, epoch seconds.                                       |
| `tenant_id`       | string \| null | Tenant the decrypt occurred in.                                  |
| `credential_type` | string         | Coarse category, e.g. `llm_provider` or `connector`.             |
| `provider`        | string \| null | Provider / source name if known (e.g. `openai`, `google_drive`). |
| `row_id`          | number \| null | DB row id of the credential / LLM provider.                      |
| `user_id`         | string \| null | Acting user id, if available (may be null for background jobs).  |
| `auth_type`       | string \| null | How the actor authenticated, if known.                           |
| `request_id`      | string \| null | Correlates with the rest of that request's logs.                 |
| `endpoint`        | string \| null | Route that produced the event.                                   |
| `client_ip`       | string \| null | Client IP (from `X-Forwarded-For`).                              |

<Tip>
  The taxonomy is **append-only**: new `action` values may be added in future releases,
  but existing ones never change meaning — so detection rules and dashboards built against these values keep working
  across upgrades.
</Tip>

## Notes

* **Secrets are never logged.** Actor objects and `extra` context are scrubbed
  of credential values by design.
* **Credential-access events** (`onyx.audit.credential_access`) use a separate,
  flat field set than the generalized schema for backward compatibility — see [Credential access](#credential-access)
  for the full field list. They share the same logger tree and fail-safe behavior.
* For **Onyx Cloud** (multi-tenant) deployments, audit-log forwarding is handled
  differently since you don't control the log pipeline — [contact us](/security/contact_us)
  to discuss SIEM delivery options.


# Manage Your Subscription
Source: https://docs.onyx.app/admins/billing/manage

Update seats, manage licenses, and access the Stripe portal

Once you have an active subscription, you can manage it from **Admin Panel > Plans & Billing**.

The billing page shows your plan, next payment date, and current seat usage.

## Managing Seats

Every active user in your workspace counts as a seat, including Slack bot accounts.
You can adjust your seat count at any time.

<Steps>
  <Step title="Open seat management">
    Click **Update Seats** on the billing page.
  </Step>

  <Step title="Set the new count">
    Enter your desired number of seats.
    You cannot go below the number of seats currently in use (active users + pending invitations).

    <Note>
      Need to reduce seats below current usage? [Remove users](/admins/user_management/users_and_groups) first,
      then adjust the seat count.
    </Note>
  </Step>

  <Step title="Review the billing impact">
    * **Adding seats** — you'll be billed a pro-rated amount immediately.
    * **Removing seats** — the change takes effect at the end of your current billing cycle.
  </Step>

  <Step title="Confirm">
    Click **Confirm Change** to apply.
  </Step>
</Steps>

## Stripe Customer Portal

Click **Manage Plan** on the billing page to open the Stripe customer portal. From there you can:

* Update your payment method
* View and download invoices
* Cancel or modify your subscription

## Air-Gapped License Activation

For self-hosted deployments without internet access,
you can activate a license manually instead of going through Stripe checkout.

Contact the Onyx team at **[support@onyx.app](mailto:support@onyx.app)** to request a license file.
You will receive a file containing your signed license in this format:

```
-----BEGIN ONYX LICENSE-----
eyJwYXlsb2FkIjogeyJ2ZXJzaW9...
-----END ONYX LICENSE-----
```

<Steps>
  <Step title="Open Plans & Billing">
    Navigate to **Admin Panel > Plans & Billing** from the sidebar.
  </Step>

  <Step title="Open the license form">
    Click **Activate License Key** at the bottom of the billing page.
  </Step>

  <Step title="Upload your license">
    Paste the contents of your license file, or use the file upload button to attach it directly.
  </Step>

  <Step title="Activate">
    Click **Activate License**. Your license will be validated and paid features will be enabled immediately.
  </Step>
</Steps>

To update an existing license (e.g., after renewal or a seat change),
click **Update License Key** instead and follow the same steps.


# Plans & Billing
Source: https://docs.onyx.app/admins/billing/overview

Understand Onyx plans and how billing works for Cloud and Self-Hosted deployments

Onyx offers multiple plans to fit your team's needs.
How you subscribe and manage billing depends on whether you're using **Onyx Cloud** or a **Self-Hosted** deployment.

## Plans

Onyx's core features — connectors, AI chat, agents, search, and more — are free and open-source.
Paid plans unlock additional capabilities for teams and organizations.

<CardGroup>
  <Card title="Business" icon="users">
    Everything in the free edition, plus:

    * Inherit Document Permissions
    * Query History and Usage Dashboard
    * Role Based Access Control (RBAC)
    * Encryption of Secrets
    * Service Account API Keys
    * Self-hosting (Optional)
    * Custom Theming
  </Card>

  <Card title="Enterprise" icon="building">
    Everything in Business, plus:

    * SCIM / Group Sync
    * Full White-labeling
    * Custom Roles and Permissions
    * Configurable Usage Limits
    * Custom Deployments
    * Region-Specific Data Processing
    * Enterprise SLAs and Priority Support
  </Card>
</CardGroup>

Visit [onyx.app/pricing](https://www.onyx.app/pricing) for current pricing,
or [contact sales](https://www.onyx.app/contact-sales) for Enterprise.

## Cloud vs Self-Hosted

|                        | Onyx Cloud                                | Self-Hosted                                                                           |
| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
| **How you subscribe**  | Subscribe via Stripe from the admin panel | Subscribe via Stripe from the admin panel — a license is then issued to your instance |
| **License needed**     | No                                        | Yes — stored and validated locally                                                    |
| **Air-gapped support** | N/A                                       | Supported via manual license upload                                                   |

<Tip>
  Not sure which deployment is right for you? Try [Onyx Cloud](https://cloud.onyx.app)
  free for 2 weeks — no credit card required.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Subscribe" icon="credit-card" href="/admins/billing/subscribing">
    Set up a paid plan on Cloud or Self-Hosted.
  </Card>

  <Card title="Manage Your Subscription" icon="gear" href="/admins/billing/manage">
    Update seats, manage licenses, and access the Stripe portal.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/admins/billing/troubleshooting">
    Locked out, seat limit hit, or Stripe issues? Start here.
  </Card>
</CardGroup>


# Subscribe to a Plan
Source: https://docs.onyx.app/admins/billing/subscribing

How to subscribe to a paid Onyx plan on Cloud or Self-Hosted

## Getting Started

<Steps>
  <Step title="Open Plans & Billing">
    Navigate to **Admin Panel > Plans & Billing** from the sidebar.
  </Step>

  <Step title="Select a plan">
    Click **Get Business Plan** to continue, or **Contact Sales** for Enterprise pricing.
  </Step>

  <Step title="Choose your billing cycle">
    Select **Monthly** or **Annual** billing.
  </Step>

  <Step title="Set your seat count">
    Enter the number of seats you need. The minimum is based on your current active users and Slack bot accounts.
  </Step>

  <Step title="Complete payment">
    Click **Continue to Payment** to open Stripe checkout. After payment, you'll be redirected back to Onyx.
  </Step>
</Steps>

<Tip>
  New Business subscriptions include a **2 week free trial**. You won't be charged until the trial ends.
</Tip>

Once subscribed, paid features like RBAC, analytics, and query history are enabled right away.

## Self-Hosted License Activation

On **Onyx Cloud**, your subscription is active immediately after checkout — there's nothing else to do.

On **self-hosted** deployments, a **license** is automatically claimed and stored on your instance after checkout.
The license is cryptographically signed and validated locally,
so your instance does not need to phone home on every request.

<Note>
  If your self-hosted deployment cannot reach the internet,
  you can [upload a license file manually](/admins/billing/manage#air-gapped-license-activation)
  instead of going through Stripe checkout.
</Note>


# Troubleshooting
Source: https://docs.onyx.app/admins/billing/troubleshooting

Common billing and licensing issues and how to resolve them

## "Access Restricted" — Locked Out of the Application

If users see an **Access Restricted** page, the workspace is locked.
This happens when a subscription expires or when the seat limit is exceeded.

Only **admins** can resolve this. Non-admin users will see a message asking them to contact their administrator.

Even when locked out, admins can still access:

* **Admin Panel > Plans & Billing** — to renew or resubscribe
* **Admin Panel > Users** — to manage users and free up seats

### Subscription expired

**Cloud**: Go to **Plans & Billing** and resubscribe through Stripe.

**Self-hosted**:
Go to **Plans & Billing** and either renew your subscription or [upload an updated license
file](/admins/billing/manage#air-gapped-license-activation).

Access is restored immediately after renewal. No data is lost.

### Seat limit exceeded

Your workspace has more active users than your plan allows. **All users** are blocked — not just the most recent ones.

To fix this, either increase your seat count from **Plans & Billing**,
or remove users from **Admin Panel > Users** until usage is within the limit. Access is restored immediately.

## Enterprise Features Unavailable

If you see an error when trying to access features like analytics, user groups, or query history,
your workspace does not have an active paid plan.

These features require a Business or Enterprise subscription:

* User Groups and access controls
* Analytics and usage dashboards
* Query History
* Usage Reports
* Standard Answers
* Token Rate Limits

Navigate to **Admin Panel > Plans & Billing** to [subscribe](/admins/billing/subscribing).

## Cannot Invite or Add Users

If inviting users, new sign-ups, or reactivating users fails, your seat limit has likely been reached.

Either increase your seat count from the [billing page](/admins/billing/manage),
or remove users from **Admin Panel > Users** to free up seats.

## Unable to Connect to Stripe (Self-Hosted)

If your self-hosted instance cannot reach Stripe, you'll see a banner on the billing page:

> "Unable to connect to Stripe payment portal."

Click **Connect to Stripe** to retry. If your instance is permanently offline or behind a firewall,
you can [upload a license file manually](/admins/billing/manage#air-gapped-license-activation) instead.

## License File Fails to Validate (Self-Hosted)

If uploading a license file returns an error:

* Make sure you are using the **complete** file contents, including the `-----BEGIN ONYX LICENSE-----`
  and `-----END ONYX LICENSE-----` delimiters
* Check for extra whitespace or line breaks that may have been introduced when copying
* Ensure the file was issued for your specific Onyx instance

Contact **[support@onyx.app](mailto:support@onyx.app)** if the issue persists.


# Airtable
Source: https://docs.onyx.app/admins/connectors/official/airtable

Access tables from Airtable

## How it works

The Airtable connector indexes records from your Airtable bases. Each record becomes a searchable document in Onyx,
with field names and values preserved.

You can choose to index **all bases and tables** accessible by your API token,
or a **specific table** by pasting its URL.

Table updates are pulled every 24 hours by default.

## Setting up

### 1. Create a Personal Access Token

<Steps>
  <Step title="Open the Builder Hub">
    In Airtable, click on your **profile icon** in the top-right corner and select **Builder Hub**.
  </Step>

  <Step title="Go to Personal Access Tokens">
    In the Builder Hub sidebar, click **Personal access tokens**, then click **Create new token**.
  </Step>

  <Step title="Configure scopes">
    Give your token a name (e.g. "Onyx") and add the following scopes:

    * `data.records:read` — read record data
    * `data.recordComments:read` — read record comments
    * `schema.bases:read` — read base and table schemas
    * `user.email:read` — read user email addresses (for collaborator fields)
  </Step>

  <Step title="Grant access to your bases">
    Under **Access**, grant the token access to all the bases you want indexed in Onyx.

    If you plan to use the **Everything** option, make sure the token has access to every base you want included.
  </Step>

  <Step title="Create and copy the token">
    Click **Create token** and copy it. You won't be able to see it again.
  </Step>
</Steps>

### 2. Add the connector in Onyx

<Steps>
  <Step title="Open the Airtable connector">
    Navigate to the Admin Panel and select the **Airtable** connector.
  </Step>

  <Step title="Create a credential">
    Create a new credential and paste your Personal Access Token.
  </Step>

  <Step title="Choose what to index">
    You have two options:

    **Everything** — Automatically discovers and indexes all bases and tables that your token has access to.
    No additional configuration needed.

    **Specific Table** — Indexes a single table. To use this option:

    * Open the table you want in Airtable in your browser.
    * Copy the URL from the address bar (it looks like `https://airtable.com/appXXX/tblYYY/viwZZZ`).
    * Paste it into the **Airtable URL** field.

    The base ID, table ID, and view ID are automatically extracted from the URL.
  </Step>
</Steps>

### Advanced options

* **Treat all fields except attachments as metadata** — When enabled, text fields (like "Title" or "Description")
  are stored as metadata key-value pairs instead of searchable document content.
  Only attachment file contents become the searchable body of the document.
  Use this when the primary content you care about is in file attachments,
  and the other columns are just labels or categories.

* **Share ID** (Specific Table only) — If you want record links in Onyx to use a shared view URL, enter the share ID here (e.g. `shrkfjEzDmLaDtK83`). You can find this by creating a shared view in Airtable.


# Asana
Source: https://docs.onyx.app/admins/connectors/official/asana

Index tasks and comments from Asana projects

## How it works

The Asana connector pulls in tasks and their associated comments from specified projects or all projects in a workspace.

## Setting up

### Authorization

<Steps>
  <Step title="Create Personal Access Token">
    * Log in to your Asana account and go to [https://app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)
    * Click "Create New Personal Access Token"
    * Give it a name (e.g., "Onyx Integration") and create the token
    * Copy the token — you'll need to provide this to Onyx
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Asana connector">
    Navigate to the Admin Panel and select the **Asana** Connector
  </Step>

  <Step title="Provide configuration">
    * **Asana API Token**: Paste the Personal Access Token you created earlier
    * **Workspace ID**: Enter your Asana workspace ID. You can find this at [https://app.asana.com/api/1.0/workspaces](https://app.asana.com/api/1.0/workspaces). It's a number that looks like 1234567890123456.
    * **Project IDs** (optional): If you want to index specific projects, enter their IDs separated by commas. Leave this empty to index all projects in the workspace. Example: 1234567890123456,2345678901234567. You can find a project ID by clicking on a project in Asana. In the URL, it will look like [https://app.asana.com/0/1208338159336610/1208338159510597](https://app.asana.com/0/1208338159336610/1208338159510597), where "1208338159336610" is the project ID.
    * **Team ID** (optional): If you want to index team-visible tasks in addition to public tasks,
      enter a team ID. Leave this empty if you don't need this feature.
  </Step>

  <Step title="Start indexing">
    Click "Connect" to start the indexing process
  </Step>
</Steps>

Note: The connector will respect the permissions of the user associated with the provided API token.
Ensure that this user has access to all the projects you want to index.


# Bitbucket Connector
Source: https://docs.onyx.app/admins/connectors/official/bitbucket

Access knowledge from your Bitbucket Repositories (Cloud only)

## How it works

The Bitbucket Connector indexes all Pull Requests from a specified Bitbucket Cloud repository, project,
or entire workspace.

* It indexes `OPEN`, `MERGED`, and `DECLINED` pull requests, including their titles and descriptions.
* It also captures key metadata such as the author, reviewers, current state, creation/update timestamps,
  and a direct link back to the original pull request in Bitbucket.

## Setting up

<Note>
  This connector can only be used with Bitbucket Cloud.
</Note>

### Authorization

The Bitbucket Connector uses an API Token for authentication.

To create an API token:

<Steps>
  <Step title="Log in to Bitbucket">
    Log in to your Bitbucket account.
  </Step>

  <Step title="Open account settings">
    Select the **Settings** cog in the upper-right corner of the top navigation bar.
  </Step>

  <Step title="Access Atlassian account settings">
    Under **Personal settings**, select **Atlassian account settings**.
  </Step>

  <Step title="Go to the Security tab">
    Select the **Security** tab on the top navigation bar.
  </Step>

  <Step title="Manage API tokens">
    Select **Create and manage API tokens**.
  </Step>

  <Step title="Create a scoped token">
    Select **Create API token with scopes**.
  </Step>

  <Step title="Name the token">
    Give the API token a name and an expiry date,
    usually related to the application that will use the token and select **Next**.
  </Step>

  <Step title="Choose Bitbucket">
    Select **Bitbucket** as the app and select **Next**.
  </Step>

  <Step title="Select scopes">
    Select the scopes (permissions) the API token needs and select **Next**.

    * **Projects**: `read:project:bitbucket`
    * **Repositories**: `read:repository:bitbucket`
    * **Pull Requests**: `read:pullrequest:bitbucket`
  </Step>

  <Step title="Create the token">
    Review your token and select the *Create token* button. The page will display the new API token.
  </Step>

  <Step title="Save the token">
    Copy the generated API token and either record or paste it into the application you want to give access.
  </Step>
</Steps>

<Note>
  The token is only displayed once and can't be retrieved later.
</Note>

For the most up-to-date instructions,
refer to the [official Bitbucket
documentation](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/).

### Indexing

<Steps>
  <Step title="Open the Bitbucket connector">
    Navigate to the Admin Dashboard and select the **Bitbucket** Connector.
  </Step>

  <Step title="Create credentials">
    Click **Create new credentials** and provide the following:

    * **Name**: A descriptive name for your credentials.
    * **Email**: The email address for your Bitbucket account.
    * **API token**: The API token you created in the previous step.

      <img alt="BitbucketConnector" />
  </Step>

  <Step title="Configure connector details">
    Fill in the connector details:

    * **Name**: A descriptive name for the connector.
    * **Workspace name**: The `WORKSPACE_NAME` from your Bitbucket URL (`https://bitbucket.org/{WORKSPACE_NAME}/...`).
    * **Repositories or Projects (Optional)**: A comma-separated list of repository slugs or project keys to index.

      <img alt="BitbucketConnector" />
  </Step>
</Steps>

This configuration will index all pull requests from the specified repositories.
You can also configure it to index all repositories within a project or an entire workspace.


# BookStack
Source: https://docs.onyx.app/admins/connectors/official/bookstack

Access knowledge from your own BookStack instance

## How it works

The BookStack connector fetches all shelves, books, chapters and pages from the connected instance upon connector setup.
From that point on, the connector will pull in everything updated since last sync every **10** minutes.

## Setting up

### Authorization

You will need API credentials for a user in your BookStack instance. To do this:

<Steps>
  <Step title="Create/select connection user">
    Find or create a user you'd want to use as the connection user.

    * Visibility of BookStack contents will depend on this user's permissions.
    * This user must have a role assigned that has the "Access system API" system permission.
  </Step>

  <Step title="Open API Tokens">
    Edit that user using an admin account, and find the "API Tokens" section at the bottom of the view.

    <img alt="BookStack API Tokens List View" />
  </Step>

  <Step title="Create and copy token">
    Click the "Create Token" button, then enter a name and (optionally) an expiry date for the token. Then press save.
    Copy the shown "Token ID" and "Token Secret" values for the "Indexing" section below.

    <img alt="BookStack API Token View" />
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open BookStack connector">
    Navigate to the Admin Panel and select the **BookStack** connector.
  </Step>

  <Step title="Enter URL and tokens">
    In **Step 1**, provide the base URL of your BookStack instance,
    along with the API **Token ID** and the API **Token Secret** you obtained in the "Authorization" steps above:

    <img alt="BookStack connector step 1 view" />
  </Step>

  <Step title="Start indexing">
    Click the `Connect` button! Your content will then be pulled into Onyx every **10** minutes.

    <img alt="BookStack connector step 2 view" />
  </Step>
</Steps>


# Box
Source: https://docs.onyx.app/admins/connectors/official/box

Index files and web links from Box

The Box connector indexes files that a Box service account or managed user can access.
You can index everything visible to that identity or limit indexing to specific folders.

## How it works

| Content     | Behavior                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| Files       | Onyx extracts and indexes supported document types, their Box links, owners, timestamps, and folder paths.          |
| Folders     | Onyx preserves the folder hierarchy for browsing and filtering.                                                     |
| Web links   | Optional. Onyx indexes the bookmark name, description, and destination URL; it does not crawl the destination page. |
| Permissions | Optional on Onyx Cloud and Enterprise Edition. Onyx can sync Box owners, collaborations, groups, and shared links.  |

On each refresh, the connector recursively lists every folder in its configured scope,
then downloads and processes only files and web links modified during the indexing window. For a large Box tree,
select specific folders and choose a refresh frequency that fits your Box API capacity.

## Before you begin

You need:

* Access to the [Box Developer Console](https://app.box.com/developers/console)
* A Box Admin or Co-Admin who can authorize a server-authenticated Platform App
* An Onyx administrator account
* The email address of a Box managed user if you plan to index as that user

<Note>
  A regular Box Individual account does not provide the enterprise features required for this setup.
  Use a Box enterprise account, developer account, or developer sandbox.
</Note>

## Choose the Box content identity

The connector can access Box content in either of these ways:

| Identity                | When to use it                                                                | Box preparation                                                                                          |
| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Managed user**        | Index the files and folders visible in an existing user's **All Files** view. | Enter the user's email in Onyx and enable **Generate user access tokens** for the Box app.               |
| **App service account** | Index only content deliberately shared with the integration.                  | Leave the user email blank and add the app's service account as a collaborator on every starting folder. |

Folder ID `0` means the root folder of the selected content identity.
It is not a global root containing every user's private Box files.

## Configure Box

<Steps>
  <Step title="Create a Platform App">
    In the [Box Developer Console](https://app.box.com/developers/console), select **Platform Apps → New App**.
    Create a **Custom App** that uses **Server Authentication (Client Credentials Grant)**. Give it a recognizable name,
    such as `Onyx Connector`.
  </Step>

  <Step title="Set the access level and scopes">
    On the app's **Configuration** tab, set **App Access Level** to **App + Enterprise Access**.

    Enable scopes according to the features you will use:

    | Box setting                                  | Required when                                       |
    | -------------------------------------------- | --------------------------------------------------- |
    | **Read all files and folders stored in Box** | Always                                              |
    | **Manage users**                             | Using a managed user email or Auto Sync Permissions |
    | **Manage groups**                            | Using Auto Sync Permissions                         |

    <Note>
      These scopes allow the app to call the required APIs.
      The selected service account or managed user still must be able to access each file and folder that you want Onyx
      to index.
    </Note>
  </Step>

  <Step title="Enable managed-user access">
    If you will enter a managed user's email in Onyx,
    enable **Generate user access tokens** under the app's advanced or additional configuration.
    You can leave this disabled when using only the app service account.
  </Step>

  <Step title="Save and authorize the app">
    Save the configuration. Authorize the app from the Developer Console,
    or submit it for authorization to a Box Admin or Co-Admin.

    An admin can also authorize it from **Admin Console → Integrations → Platform Apps Manager → Server Authentication
    Apps** by adding the app's Client ID.

    <Warning>
      Box authorization captures the app configuration at that moment. If you later change its scopes or access level,
      an admin must reauthorize the app before the changes take effect.
    </Warning>
  </Step>

  <Step title="Copy the credentials">
    From the app's settings, copy the **Client ID**, **Client Secret**, and **Enterprise ID**.

    Box requires two-factor authentication on your account before it reveals the client secret.
    Treat the secret as sensitive and do not place it in source control.
  </Step>
</Steps>

For more detail on these Box settings,
see Box's [Client Credentials Grant setup
guide](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/)
and [Platform App approval guide](https://developer.box.com/guides/authorization/platform-app-approval/).

## Configure Onyx

<Steps>
  <Step title="Open the Box connector">
    In Onyx, go to **Admin Panel → Add Connector** and select **Box**.
  </Step>

  <Step title="Enter the Box credentials">
    Create a credential and enter the values copied from Box:

    | Onyx field                                      | Value                                                                            |
    | ----------------------------------------------- | -------------------------------------------------------------------------------- |
    | **Box Client ID**                               | The Platform App's Client ID                                                     |
    | **Box Client Secret**                           | The Platform App's Client Secret                                                 |
    | **Box Enterprise ID**                           | Your Box enterprise ID                                                           |
    | **Email of Box user to impersonate (optional)** | The exact login email of a managed user, or blank to use the app service account |
  </Step>

  <Step title="Choose the folders to index">
    Give the connector a name. In **Folders**, enter one or more Box folder IDs or full folder URLs,
    such as `https://app.box.com/folder/123456789`.

    Leave **Folders** empty to index everything visible from the selected identity's root folder.
    Every configured folder is indexed recursively.
  </Step>

  <Step title="Choose indexing and access options">
    Under **Advanced Configuration**,
    enable **Include Web Links** if you want Box bookmarks indexed as lightweight documents.

    Select the connector access type:

    * **Public** makes all indexed Box content visible to every Onyx user.
    * **Private** limits the entire connector to selected Onyx users and groups.
    * **Auto Sync Permissions** mirrors supported Box access controls and is available on Onyx Cloud and Enterprise
      Edition.
  </Step>

  <Step title="Connect and verify">
    Select **Connect**. Then open **Admin Panel → Existing Connectors**, select the connector,
    and confirm its initial indexing attempt completes.
  </Step>
</Steps>

## Auto Sync Permissions

With **Auto Sync Permissions**, Onyx maps accepted,
read-capable Box collaborations to matching Onyx user emails and Box groups.
It also handles inherited folder access and shared links:

* A non-password-protected **People with the link** link is treated as public.
* A **People in your company** link is available to synced users in the Box enterprise.
* An upload-only collaboration does not grant read access in Onyx.
* Box login emails must match the users' email addresses in Onyx.

The Box app must have **Manage users** and **Manage groups**,
and an admin must reauthorize the app after adding those scopes.

<Warning>
  Review the access type before connecting.
  Choosing **Public** does not preserve Box permissions and can expose indexed content to every Onyx user.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The app is unauthorized or the credentials are rejected">
    An error such as `unauthorized_client:
            The "box_subject_type" value is unauthorized for this client_id` means the app is not authorized for enterprise
    access: set **App Access Level** to **App + Enterprise Access** and have a Box Admin or Co-Admin authorize the app.
    Also confirm that the Client ID, Client Secret, and Enterprise ID belong to the same Platform App.
    If any app setting changed, reauthorize it in the Box Admin Console.
  </Accordion>

  <Accordion title="The managed user cannot be found or authenticated">
    Enter the user's exact Box login email. Confirm the user is managed by the same enterprise,
    **App + Enterprise Access** and **Manage users** are enabled, and **Generate user access tokens** is enabled.
    Reauthorize the app after correcting any setting.
  </Accordion>

  <Accordion title="A folder is not found or indexes no files">
    Confirm the folder ID or URL and verify that the selected managed user can open the folder.
    If you left the user email blank, add the app service account as a collaborator on the folder.
    An empty service-account root does not include existing enterprise content automatically.
  </Accordion>

  <Accordion title="Permission sync fails">
    Confirm **Manage users** and **Manage groups** are enabled and the app was reauthorized afterward.
    Also confirm you are using Onyx Cloud or Enterprise Edition.
  </Accordion>

  <Accordion title="Refreshes are slow or use many Box API calls">
    Each refresh walks the full configured folder tree, with folder contents listed in pages of up to 200 entries.
    Permission sync makes additional calls for folder and file collaborations, users, and groups.
    Limit **Folders** to the required subtrees or increase the refresh frequency for very large Box deployments.
  </Accordion>

  <Accordion title="A file or web link is missing">
    Confirm the content identity can access the item.
    Onyx skips unsupported file types and files larger than the configured Box connector size limit,
    which defaults to 20 MB. Web links require **Include Web Links** and only their bookmark metadata is indexed;
    the destination page is not fetched.
  </Accordion>
</AccordionGroup>


# ClickUp
Source: https://docs.onyx.app/admins/connectors/official/clickup

'Access tasks from ClickUp'

## How it works

The ClickUp connector will pull in all tasks from the ClickUp workspace, or specific space(s), list(s), folder(s)
specified by the user.

Tasks are updated every **10** minutes.

## Understanding ClickUp Hierarchy

In ClickUp, there are multiple containers which contain task(s). These could be -

* Entire Workspace
* Spaces
* Folders
* Lists

Detailed information on the hierarchy of above mentioned objects is available
[here](https://help.clickup.com/hc/en-us/articles/13856392825367-Intro-to-the-Hierarchy)

<img alt="ClickUp workspace hierarchy illustrating spaces, folders, and lists" />

## Setting up

### Authorization

<Steps>
  <Step title="Log in to ClickUp">
    Log into ClickUp.
  </Step>

  <Step title="Open Apps settings">
    In ClickUp 2.0, click your avatar in the lower-left corner and select **Apps**. In ClickUp 3.0,
    click your avatar in the upper-right corner, select **Settings**, and scroll down to click **Apps** in the sidebar.
  </Step>

  <Step title="Generate API token">
    Under API Token, click **Generate**. A Personal API token will be generated and displayed!

    <img alt="Clickup token generation" />
  </Step>
</Steps>

<img alt="Clickup token generation" />

### Indexing

<Steps>
  <Step title="Open ClickUp connector">
    Navigate to the Admin Panel and select the **ClickUp** Connector
  </Step>

  <Step title="Enter API token and Team ID">
    In **Step 1**, provide your **API Token** and the **Team ID** from above.

    <img alt="Clickup connector authentication" />
  </Step>

  <Step title="Select connector type">
    Select the type of connector you want to pull in tasks from.

    **Notes**

    * This could be Entire Workspace, Space(s), List(s), or Folder(s).
    * To pull tasks from entire workspace, just select Entire Workspace from the dropdown,
      and do not add any ID(s).
    * To pull tasks from specific space(s), folder(s), or lists(s),
      select the respective option from the dropdown, and add the ID(s) below.
      At least one ID needs to be added in this case.
    * The space id(s), folder id(s), list id(s) could be found in the web url in Clickup.
      For example, if you open a **list** in the ClickUp UI, you will see the list id in the url address bar as follows -

    <img alt="Clickup list id" />
  </Step>

  <Step title="Enter IDs as needed">
    If any of the Space(s), List(s), or Folder(s) connector type is selected,
    add one or more respective IDs to index the tasks from.
  </Step>

  <Step title="Choose comment indexing">
    Check **Retrieve Task Comments?** to also retrieve and index all comments for each indexed task.
    Leave this unchecked if you don't want to index task comments.
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing.
  </Step>
</Steps>


# Confluence
Source: https://docs.onyx.app/admins/connectors/official/confluence

Access knowledge from your company Wiki

The Confluence connector pulls in all pages and comments from the specified spaces/pages once at the beginning and then
pulls updates every 10 minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Get access token">
    Follow the guide described
    [here](https://docs.searchunify.com/Content/Content-Sources/Atlassian-Jira-Confluence-Authentication-Create-API-Token.htm)
    to get an access token.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Navigate to connector">
    Navigate to the Admin Panel and select the **Confluence** Connector
  </Step>

  <Step title="Provide credentials">
    For your credentials, provide the **Access Token** and the **Username** (typically an email) it belongs to:
  </Step>

  <Step title="Configure Confluence setup">
    For Confluence setup, you must provide:

    * **Wiki Base URL**: The base URL of your Confluence instance (e.g., [https://your-domain.atlassian.net/wiki](https://your-domain.atlassian.net/wiki))
    * **Whether you're using Confluence Cloud or Datacenter**: Check the `Is Cloud` box if you are using a Confluence Cloud instance, uncheck for Confluence Server/Data Center
  </Step>

  <Step title="Choose indexing scope">
    Then choose how you'd like this connector to index your Confluence instance:

    * Everything:
    * If you select this option, the connector will index everything the provided credentials
      have access to.
    * Space:
    * Input the key of the space you'd like to index (e.g., `KB`)
    * Page:
    * Page ID: Specific page ID to index - leave empty to index the entire space (e.g., `131368` for a specific page)
    * Index Recursively: Check this box to index the specified page AND all of its children.
    * CQL Query:
    * If you'd like finer control over what is indexed, you can use a CQL query. The query must contain 'type=page' and any lastmodified filters will be overwritten. See the [CQL documentation](https://developer.atlassian.com/server/confluence/advanced-searching-using-cql/) for more information.
  </Step>

  <Step title="Connect">
    Click the `Connect` button!
    All the specified spaces/pages and related comments will now be pulled into Onyx every **10** minutes.
  </Step>
</Steps>

#### Permission Syncing

If you are an enterprise customer connecting to Confluence Server/Data Center and you would like to enable permission
syncing, the provided credentials must be from an admin user.


# Discord
Source: https://docs.onyx.app/admins/connectors/official/discord

'Access knowledge from your Messages'

## How it works

The Discord connector indexes all channels for all servers(guilds) mentioned.

## Setting up a Bot User

<Steps>
  <Step title="Open Discord developer portal">
    Login to your discord's developer portal [https://discord.com/developers/applications](https://discord.com/developers/applications)
  </Step>

  <Step title="Create application">
    Click on the “New Application” button.
  </Step>

  <Step title="Name and create">
    Give the application a name and click “Create”.
  </Step>

  <Step title="Configure Bot tab">
    Navigate to the “Bot” tab to configure it.
  </Step>

  <Step title="Public Bot option">
    Make sure that Public Bot is ticked if you want others to invite your bot.
  </Step>

  <Step title="Enable privileged intents">
    Under the `Privileged Gateway Intents` make sure `MESSAGE CONTENT INTENT` is checked.
  </Step>

  <Step title="Copy bot token">
    Copy the token using the “Copy” button. If you have lost your token, you can click on `Reset Token`.
  </Step>
</Steps>

## Inviting the Bot User to server(s)

So you've made a Bot User but it's not actually in any server. To add the bot user in your server follow the steps:

<Steps>
  <Step title="Open application">
    Open your application at [https://discord.com/developers/applications](https://discord.com/developers/applications) .
  </Step>

  <Step title="Open Installation tab">
    Head over to the `Installation` tab.
  </Step>

  <Step title="Enable Guild Install">
    Check the `Guild Install` under the Installation contexts.
  </Step>

  <Step title="Add bot scope">
    Add `bot` scope under the scopes for `Guild Install`.
  </Step>

  <Step title="Set minimum permissions">
    Under the permissions section for `Guild Install`, give these minimum permissions `Manage Messages`,
    `Read Message History` and `View Channels`.
  </Step>

  <Step title="Install bot with link">
    Use the `Discord Provided Link` to install the bot to the server(s) you want.
    Make sure you have `Manager server` permissions on that guild or server
  </Step>

  <Step title="Add bot to servers">
    Open the link in the browser and add the bot to your server(s)
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Discord connector">
    Navigate to the Connector Dashboard and select the **Discord** Connector.
  </Step>

  <Step title="Enter Bot Token">
    Enter the **Bot Token** under credentials you fetched from `Setting up a Bot User` step 6.
  </Step>

  <Step title="Enter server IDs">
    Enter the server IDs.
    By default all channels of all servers/guilds in which the bot user is added will be indexed or processed.
  </Step>

  <Step title="Find server ID">
    To fetch server ID of a particular server,
    right click on the name of the server located on the top right corner and click on `Copy Server ID`
  </Step>

  <Step title="Enter channel names">
    Enter the channel names. By default all channel names under the server(s)
    from step 3 that the bot user has access to will be indexed or processed.
  </Step>

  <Step title="Find channel name">
    To get the channel name, hit on the settings icon next to the channel name.
    You will find the channel name in the `Overview` section
  </Step>

  <Step title="Optional Start Date">
    Optionally you can set a `Start Date` in the format of `YYYY-MM-DD`.
    Only messages after this date will be indexed or processed.
  </Step>
</Steps>


# Discourse
Source: https://docs.onyx.app/admins/connectors/official/discourse

Access knowledge from your Discourse **Topics**

## How it works

The Discourse connector indexes documents from your Discourse **Topics**.

## Setting up

### Authorization

<Steps>
  <Step title="Log in to Discourse">
    Log into your Discourse account

    <Info>
      This Discourse user must have admin privileges
    </Info>
  </Step>

  <Step title="Open API keys">
    Click the **Admin** menu from the home page. Open the **Advanced** sub-menu and select **API keys**.

    <img alt="Discourse admin navigation to the API keys page" />
  </Step>

  <Step title="Create API key">
    Click **New API Key**, name it "Onyx". Select "All Users" for **User Level** and "Read-only" for **Scope**.

    <img alt="Create and fill out API key" />
  </Step>

  <Step title="Save and copy key">
    Click **Save**. Copy the key and put it into Onyx.

    <img alt="Create and copy API key" />
  </Step>

  <Step title="Set API key username">
    For the API Key Username,
    enter the username of the Discourse account which has access to the information you'd like to index.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Name the connector">
    Input a name for a connector (if you plan on creating multiple Discourse connectors,
    this will be used by you to tell between them)
  </Step>

  <Step title="Provide base URL">
    Provide your Discourse's base url.

    <img alt="Fill out Onyx connector" />
  </Step>

  <Step title="Enter Topics to index">
    Enter the **Topics** you wish to index. If left blank, all topics available will be indexed.
  </Step>

  <Step title="Start indexing">
    Click connector to begin indexing the indicated **topics**.
  </Step>
</Steps>


# Document360
Source: https://docs.onyx.app/admins/connectors/official/document360

'Access wiki articles from Document360'

## How it works

The Document360 connector will pull in all the articles given the workspace and categories that the user specifies.
Articles in Document360 can be saved in either HTML or Markdown format.
Currently the implementation only handles HTML format. If HTML format is desired,
please submit an issue [here](https://github.com/onyx-dot-app/onyx/issues)

Articles are updated every **10** minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Open API tokens">
    Go to Settings > Knowledge base portal > API tokens.
  </Step>

  <Step title="Generate token">
    Click Generate. Enter a token name and select the allowed request methods. Click Generate again.
    Your portal ID and API key will be displayed.
  </Step>
</Steps>

<img alt="Document360 token generation" />

### Indexing

<Steps>
  <Step title="Open Document360 connector">
    Navigate to the Admin Panel and select the **Document360** Connector
  </Step>

  <Step title="Enter Portal ID and API Key">
    In **Step 1**, provide your **Portal ID** and the **API Key** from above.

    <img alt="Document360 connector authentication with Portal ID and API Key" />
  </Step>

  <Step title="Set workspace and categories">
    Set the **Workspace ID** (see below) and **Categories**. To include all categories, leave the categories empty.
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing
  </Step>
</Steps>

<img alt="Document360 connector authentication" />


# Dropbox
Source: https://docs.onyx.app/admins/connectors/official/dropbox

Access knowledge from Dropbox

## How it works

The Dropbox connector ingests all documents from your Dropbox account into Onyx.

The connector recursively pulls all files from the root directory of your Dropbox account.
It is currently not possible to pull files only from specific directories.

The connector will only pull once upon initialization. If you would like to pull more documents,
you must generate a new access token (step 6 below), put that token into the connector, and re-initialize the connector.

## Setting up

### Authorization

<Steps>
  <Step title="Create Dropbox app">
    Head over to [https://www.dropbox.com/developers/apps](https://www.dropbox.com/developers/apps) and click the `Create app` button on the top right.
    Select `Scoped access` and `Full Dropbox` as the type of access.
    Give your app a name like 'Onyx Connector' and click `Create app`.

    <img alt="DropboxStep1" />
  </Step>

  <Step title="Open Permissions">
    Click on the `Permissions` tab.

    <img alt="DropboxStep2" />
  </Step>

  <Step title="Grant required scopes">
    Check the `files.content.read` and `sharing.write` permissions so the files can be read and links for the documents
    can be created. Click `Submit` to save the changes.

    <img alt="DropboxStep3" />
  </Step>

  <Step title="Generate access token">
    Navigate to the `Settings` tab and scroll down to the `OAuth 2` section.
    Click `Generate` to generate an access token.

    <Warning>
      You must complete granting permissions before generating an access token.
      Changing permissions will not affect existing access tokens, and Onyx will be unable to index your Dropbox.
    </Warning>

    <img alt="DropboxStep4" />
  </Step>

  <Step title="Copy access token">
    Copy the access token.

    <Info>
      Refresh the page if you need to regenerate your access token
    </Info>

    <img alt="DropboxStep5" />
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Dropbox connector">
    In the Onyx UI, navigate to the Admin Panel and select the **Dropbox** Connector
  </Step>

  <Step title="Enter access token">
    Provide the access token from the previous step
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing your Dropbox files
  </Step>
</Steps>


# Drupal Wiki
Source: https://docs.onyx.app/admins/connectors/official/drupal_wiki

Access knowledge from your Drupal Wiki instance

## How it works

The Drupal Wiki connector indexes content from your Drupal Wiki instance including spaces, pages,
and optionally attachments.
The connector fetches all accessible content upon initial setup and then performs incremental updates to keep your
knowledge base synchronized.

The connector respects the permissions of the provided API token, indexing only content that the token has access to,
whether public or private.

## Setting up

### Authorization

You will need an API access token for your Drupal Wiki instance.
The token must start with `pat:` (Personal Access Token).

<Steps>
  <Step title="Navigate to your Drupal Wiki instance">
    Navigate to your Drupal Wiki instance
  </Step>

  <Step title="Generate an access token">
    Follow the documentation to generate an access token:
    [https://help.drupal-wiki.com/node/605#2-Zugriffs-Token-generieren](https://help.drupal-wiki.com/node/605#2-Zugriffs-Token-generieren)
  </Step>

  <Step title="Ensure REST API is available">
    Ensure the REST API interface is available in your Drupal instance
  </Step>

  <Step title="Copy the API token">
    Copy the generated API token (it should start with `pat:`)
  </Step>
</Steps>

<Info>
  The API token determines which content will be accessible to Onyx.
  Only content that the token user has permission to access will be indexed.
</Info>

### Indexing

<Steps>
  <Step title="Navigate to the Admin Dashboard">
    Navigate to the Admin Dashboard and select the **Drupal Wiki** connector
  </Step>

  <Step title="Provide your Drupal Wiki configuration">
    In **Step 1**, provide your Drupal Wiki configuration:

    * **API Token**: The access token you generated (starting with `pat:`)
  </Step>

  <Step title="Choose your indexing scope">
    In **Step 2**, choose your indexing scope:

    * **Base URL**: The base URL of your Drupal Wiki instance (e.g., `https://help.drupal-wiki.com`)
    * **All Content**: Index all spaces and pages accessible to your API token
    * **Specific Spaces**: Enter specific Space IDs to index only certain areas
    * To find Space IDs, refer to: [https://help.drupal-wiki.com/node/606](https://help.drupal-wiki.com/node/606)
    * **Specific Pages**: Enter specific Page (Node) IDs to index only certain pages
  </Step>

  <Step title="Configure additional options">
    Configure additional options:

    * **Include Attachments**: Check this to also index file attachments (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT,
      HTML, MD, CSV)
  </Step>

  <Step title="Connect and start indexing">
    Click the `Connect` button!
    Your Drupal Wiki content will be indexed and kept up to date with incremental synchronization.
  </Step>
</Steps>

<img alt="Onyx Drupal Wiki configuration" />

## Supported Content Types

The Drupal Wiki connector indexes the following content:

* **Spaces**: Organizational units within your Drupal Wiki
* **Pages**: Individual wiki pages with HTML content (converted to plain text)
* **Attachments** (optional): Various document formats up to 10MB

## Technical Details

* **API Usage**: Uses Drupal Wiki's REST API endpoints
* **Synchronization**: Supports incremental updates for efficient syncing
* **Content Limits**: 10MB for attachments, 600,000 characters for text content
* **Deployment Support**: Works with both self-hosted and cloud-hosted Drupal Wiki instances

## Permission Syncing

The connector automatically respects your Drupal Wiki's permission system.
Content access is determined by the API token's permissions,
ensuring that only authorized content is indexed and searchable within Onyx.


# Egnyte
Source: https://docs.onyx.app/admins/connectors/official/egnyte

Access files stored in Egnyte

## How it works

The Egnyte connector pulls in files stored in Egnyte. The Egnyte connector indexes the file name, file type,
and contents of the file.

New files are pulled every **10** minutes.

## Setup

### Configure your Egnyte Application + Onyx env variables

<Info>
  This is only necessary if self-hosting Onyx. If using [Onyx Cloud](https://cloud.onyx.app), you can skip this step.
</Info>

<Steps>
  <Step title="Create Egnyte Application">
    Create an Egnyte Application.
    Check out the [Egnyte API documentation](https://developers.egnyte.com/docs/read/introduction) for more information.
  </Step>

  <Step title="Set environment variables">
    Set the following environment variables on your Onyx instance:

    ```bash theme={null}
    EGNYTE_DOMAIN=something like "app4onyx"
    EGNYTE_CLIENT_ID=
    EGNYTE_CLIENT_SECRET=
    ```
  </Step>

  <Step title="Restart Onyx">
    Restart your Onyx instance as you normally would to apply the changes.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Egnyte connector">
    In the Onyx UI, navigate to the Admin Panel and select the **Egnyte** Connector
  </Step>

  <Step title="Authorize via OAuth">
    Click the `Create New` button to go through the OAuth flow.
  </Step>

  <Step title="Return to Onyx">
    Once you've authorized the application, you'll be redirected back to Onyx.
  </Step>

  <Step title="Complete configuration">
    Finish the setup, optionally specifying a folder path to index.
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing Egnyte files!
  </Step>
</Steps>


# File
Source: https://docs.onyx.app/admins/connectors/official/file

Index files from a local or network drive

## How it works

The File Connector indexes user uploaded files. Currently supports `.txt`, `.pdf`, `.docx`, `.pptx`, `.xlsx`, `.csv`,
`.md`, `.mdx`, `.conf`, `.log`, `.json`, `.tsv`, `.xml`, `.yml`, `.yaml`, `.eml`, and `.epub` files.
You can also upload a `.zip` containing these files - If there are other file types in the zip,
the other file types are ignored. There is also an optional metadata line that supports links, document owners,
and time updated as metadata for Onyx's retrieval and AI Answer.

## Adding Metadata

The metadata line should be placed at the very top of the file and can take one of two formats:

* `#ONYX_METADATA={"link": "<LINK>"}`
* `<!-- ONYX_METADATA={"link": "<LINK>"} -->`

Where ONYX\_METADATA= is followed by a json. The valid json keys are:

* link
* primary\_owners
* secondary\_owners
* doc\_updated\_at
* file\_display\_name

You can also include arbitrary key/value pairs which will be understood as "tags".
These tags can then be used in the UI as a filter if you want to constrain your search / conversation to only documents
with certain tag(s) attached

For example:

```
#ONYX_METADATA={"link": "https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md", "primary_owners": ["yuhong@onyx.app", "chris@onyx.app"], "secondary_owners": ["founders@onyx.app"], "doc_updated_at": "2023-11-30T13:06:08.589616-08:00", "file_display_name": "Desired File Name!", "tag_of_your_choice": "tag_value"}
```

Full file example:

```
#ONYX_METADATA={"link": "https://www.onyx.com/captcha", "file_display_name": "Captcha Setup"}
How to set up captcha
Follow the example below to set up a captcha
like you saw when you visited this page!
By including a captcha, this page is able to
prevent web scrapers from reading it.
```

As we can see, there are many web pages or internal tools that aren't directly scrape-able.
In addition to handling local file uploads,
the file connector is offered as an option for these tools which may have APIs for accessing the contents.

Alternatively, if you are uploading a `.zip` filled with files,
you can define a `.onyx_metadata.json` file and include that in the root of the zip file.
If your zip file structure looks like:

```
| file1.txt
| file2.txt
| .onyx_metadata.json
```

then your `.onyx_metadata.json` file might look like:

```json theme={null}
[
  {
    "filename": "file1.txt",
    "link": "<LINK_TO_FILE1>",
    "file_display_name": "<WHAT_YOU_WANT_THE_NAME_OF_FILE1_TO_BE_IN_THE_UI>"},
    "primary_owners": ["<FILE1_OWNER>"],
    // this is an arbitrary tag, can be any key/value pair and can be used in the UI as
    // a filter if you want to constrain your search / conversation to only documents with
    // this tag attached
    "status": "<SOME_STATUS>"
  },
  {
    "filename": "file2.txt",
    "link": "<LINK_TO_FILE2>",
    "file_display_name": "<WHAT_YOU_WANT_THE_NAME_OF_FILE2_TO_BE_IN_THE_UI>"},
    "primary_owners": ["<FILE2_OWNER>"],
    // this is an arbitrary tag, can be any key/value pair and can be used in the UI as
    // a filter if you want to constrain your search / conversation to only documents with
    // this tag attached
    "status": "<SOME_OTHER_STATUS>"
  }
]
```

## Setting up

### Authorization

* No external auth flows required.
* Admins can upload files and make them available to everyone
* \[WIP] Admins or normal users will be able to upload files via personal connectors and make
  them accessible for just themselves.

### Indexing

<Steps>
  <Step title="Open File connector">
    Navigate to the Admin Panel and select the **File** Connector.
  </Step>

  <Step title="Upload file">
    Select a `.txt` file or a `.zip` file and click

    <img alt="FileConnector" />
  </Step>
</Steps>


# Fireflies
Source: https://docs.onyx.app/admins/connectors/official/fireflies

Access meeting transcripts from Fireflies

## How it works

The Fireflies connector indexes meetings from your Fireflies account.

## Setting up

### Authorization

<Steps>
  <Step title="Log in to Fireflies">
    Login to Fireflies (user must be authorized).
  </Step>

  <Step title="Open settings">
    Click on your profile avatar and select **Settings**, or click on **Settings** in the sidebar.

    <img alt="FirefliesConnectorAuth" />
  </Step>

  <Step title="Open Developer Settings">
    Select **Developer Settings**.

    <img alt="FirefliesConnectorAuth" />
  </Step>

  <Step title="Copy API Key">
    Copy the **API Key**.

    <img alt="FirefliesConnectorAuth" />
  </Step>

  <Step title="Authorize connector">
    Use the API key to authorize your Fireflies connector in Onyx.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Fireflies connector">
    Navigate to the Admin Panel. In the sidebar select **Add Connector** and click on the **Fireflies** tile.
  </Step>

  <Step title="Create credentials">
    Select **Create New** and then provide your **API Key**, along with an optional name for your credentials.
    Click **Create**; your credentials will be saved and automatically selected.
  </Step>

  <Step title="Configure connector">
    Click **Continue**, choose a name, determine the document access, and assign groups for your connector.
  </Step>

  <Step title="Create connector">
    Click **Create Connector**. Onyx will automatically begin indexing your meetings.
  </Step>
</Steps>


# Freshdesk
Source: https://docs.onyx.app/admins/connectors/official/freshdesk

Access tickets and conversations from Freshdesk

## How it works

The Freshdesk connector indexes tickets from your Freshdesk account.

## Setting up

### Authorization

<Steps>
  <Step title="Log in to Freshdesk">
    Login to Freshdesk

    * The Freshdesk user must be a verified agent, admin, or owner.
  </Step>

  <Step title="Open profile settings">
    Click the profile avatar and choose profile settings.

    <img alt="FreshdeskConnectorAuth" />
  </Step>

  <Step title="View API Key">
    Select **View API Key**.

    <img alt="FreshdeskConnectorAuth" />
  </Step>

  <Step title="Authorize Onyx">
    Once you have the API key, you can use it (as well as your domain) to authorize your Onyx connector.
    The [password field is unused when the API key is provided](https://developers.freshdesk.com/api/#authentication)
    and will be removed in a future version of Onyx. For now, please enter abc into the password field.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Freshdesk connector">
    Navigate to the Admin Panel.
  </Step>

  <Step title="Add connector">
    In the sidebar select **Add Connector** and click on the **Freshdesk** tile.
  </Step>

  <Step title="Create credentials">
    Select **Create New** and then provide your **Domain**, **Password** and **API Key**,
    along with an optional name for your credentials.
  </Step>

  <Step title="Save credentials">
    Click **Create** and your credentials will be saved and automatically selected.
  </Step>

  <Step title="Create connector">
    After selecting **Continue** you can choose a name for your connector and then click **Create Connector**.
  </Step>

  <Step title="Start indexing">
    Once you have created your connector Onyx will automatically begin indexing your tickets.
  </Step>
</Steps>


# GitBook
Source: https://docs.onyx.app/admins/connectors/official/gitbook

Access documentation from GitBook

## How it works

The GitBook connector will pull in all the documentation content from your specified GitBook spaces.

## Setting up

### Authorization

<Steps>
  <Step title="Open Developer settings">
    Go to your GitBook account settings and navigate to 'Developers' section ([https://app.gitbook.com/account/developer](https://app.gitbook.com/account/developer))
  </Step>

  <Step title="Create API token">
    Click on 'Create new token'. Give your token a name and select the appropriate scopes.
    Click 'Create' to generate your API token.
  </Step>

  <Step title="Copy and store token">
    Copy and save your token securely — you won't be able to see it again.
  </Step>
</Steps>

<img alt="GitBook Developer Page" />

### Indexing

<Steps>
  <Step title="Open GitBook connector">
    Navigate to the Admin Panel and select the **GitBook** Connector
  </Step>

  <Step title="Enter API token">
    In **Step 1**, paste your **API Token** from the previous step

    <img alt="GitBook API Configuration" />
  </Step>

  <Step title="Enter Space ID and connect">
    Enter your **Space ID** - you can find this in the URL of your GitBook space (e.g.,
    `https://app.gitbook.com/o/<organization>/s/<space-id>`). Click 'Connect' to begin indexing your GitBook content.

    <img alt="GitBook Space Configuration" />
  </Step>
</Steps>


# GitHub Connector
Source: https://docs.onyx.app/admins/connectors/official/github

Access knowledge from your GitHub Repositories

## How it works

The Github Connector picks up all of the Pull Requests and Issues in a specified repository.

* It will index both Open and Closed PRs. This includes the Title and Summary.
* It will index Issues and comments both Open and Closed
* Includes certain other metadata such as the URL, creator, etc.

## Permission Sync Feature

The GitHub connector supports permission synchronization,
which ensures that users can only access documents they have permissions to view in GitHub. When enabled, this feature:

* Syncs user permissions from GitHub repositories and organizations
* Ensures that users only see search results for repositories they have access to
* Maintains consistent access control between GitHub and Onyx

<Note>
  Permission sync is available only on Cloud and the Enterprise Edition of Onyx,
  and it requires additional token permissions beyond those needed for basic indexing.
</Note>

### ⚠️ CRITICAL REQUIREMENT: Public Email Profile

<Info>
  **VERY IMPORTANT:** For permission sync to work,
  users must have their email address publicly visible in their GitHub profile. If a user's email is set to private,
  they will not get access to any documents through Onyx.
</Info>

<Accordion title="How to make your email public on GitHub">
  <Steps>
    <Step title="Log in to GitHub">
      Log in to your GitHub account
    </Step>

    <Step title="Access profile settings">
      Click on your profile picture in the top-right corner and select **Settings** from the dropdown menu
    </Step>

    <Step title="Navigate to email settings">
      In the left sidebar, click on **Emails**
    </Step>

    <Step title="Enable public email">
      Scroll down to **Keep my email addresses private** and **uncheck this option**
    </Step>

    <Step title="Configure public profile">
      Now go back to the left sidebar and click on **Public profile**
    </Step>

    <Step title="Set public email">
      Scroll down to the **Public email** section and select your email address from the dropdown
    </Step>

    <Step title="Save changes">
      Click **Update profile** to save the changes
    </Step>
  </Steps>
</Accordion>

**Why is this required?**

Onyx uses the public email to match GitHub users with Onyx users for permission synchronization. Without a public email,
the system cannot identify which GitHub permissions apply to which Onyx user.

## Setting up

### Authorization

This Connector uses a GitHub Access Token.
The required permissions depend on whether you're using the permission sync feature.

#### Basic Setup (Indexing Only)

For basic indexing without permission sync:

<Steps>
  <Step title="Review detailed guide">
    [This
    guide](https://docs.github.com/en/enterprise-server@3.4/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
    shows the following steps in detail.
  </Step>

  <Step title="Log in to GitHub">
    Log in to GitHub.
  </Step>

  <Step title="Access settings">
    In the upper right corner, expand your profile and click on **Settings**
  </Step>

  <Step title="Navigate to developer settings">
    On the bottom, go to **Developer settings** -> **Personal access tokens** -> **Tokens (classic)**
  </Step>

  <Step title="Generate new token">
    Click on **Generate new token**
  </Step>

  <Step title="Grant permissions">
    Grant the following permissions:

    * **Repository permissions:**
    * `repo` (Full control of private repositories) - to access PRs and issues

    <Accordion title="Fine-Grain Access Token Requirements">
      If you're using a fine-grain access token instead of a classic token:

      <Steps>
        <Step title="Open repository permissions">
          In the token configuration page, go to **Repository permissions**
        </Step>

        <Step title="Add permissions">
          Click **Add permission**, then add the following with **Read access**:

          * **Pull requests** - to access PR data
          * **Metadata** - for repository metadata
          * **Issues** - to access issues and comments
          * **Contents** - to access repository contents
        </Step>
      </Steps>
    </Accordion>
  </Step>
</Steps>

#### Permission Sync Setup

Pick the token type you're using:

<Tabs>
  <Tab title="Fine-grained access token">
    <Steps>
      <Step title="Select the organization (resource owner)">
        When creating a **fine-grained** GitHub access token for **permission sync**,
        make sure you select the correct **Resource owner organization** (the GitHub **organization** that owns the
        repositories you want to create the connector for).
        Fine-grained tokens scoped to a personal user account do **not** allow granting **Organization permissions**
        (like **Members**), so permission sync requires selecting an organization as the resource owner.
      </Step>

      <Step title="Add required permissions">
        Add these in the token configuration page using **Repository permissions** -> **Add permission** and
        **Organization permissions** -> **Add permission**:

        <img alt="GitHub fine-grained token permissions: Repository permissions and Organization permissions" />

        * **Repository permissions** (Read access): **Administration**, **Issues**, **Metadata**, **Pull requests**
        * **Organization permissions** (Read only): **Administration**, **Members**
      </Step>
    </Steps>
  </Tab>

  <Tab title="Classic token">
    <Steps>
      <Step title="Add the org read scope">
        If you're using a **classic** GitHub personal access token (PAT) and want **permission sync**,
        you must also grant:

        * `read:org`
      </Step>

      <Step title="Keep indexing scopes enabled">
        Keep the basic indexing permission enabled as well:

        * `repo` (Full control of private repositories) - to access PRs and issues
      </Step>
    </Steps>
  </Tab>
</Tabs>

#### Token Configuration

<Steps>
  <Step title="Set expiration time">
    Set any expiration time.
    A new token will have to be provided to Onyx to continue updating the Onyx index once this one expires.
  </Step>

  <Step title="Verify permissions">
    **Important:** If you plan to use permission sync,
    ensure all the above permissions are granted when creating the token.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Navigate to connector">
    Navigate to the Admin Panel and select the **GitHub** Connector
  </Step>

  <Step title="Configure connector">
    For [https://github.com/onyx-dot-app/onyx](https://github.com/onyx-dot-app/onyx), it would look like:
  </Step>
</Steps>

<img alt="Onyx GitHub connector credentials entry screen" />

<img alt="Onyx GitHub connector repository configuration example" />


# GitLab
Source: https://docs.onyx.app/admins/connectors/official/gitlab

Index repositories and issues from GitLab

## How it works

The GitLab Connector picks up all of the Merge Requests and Issues in a specified repository.

* It will index both Open and Closed MRs. This includes the Title and Summary.
* It will index Issues (and Incidents) including comments both Open and Closed.
* Includes certain other metadata such as the URL, creator, etc.

## Setting up

### Authorization

<Steps>
  <Step title="Use GitLab Access Token">
    This Connector uses a GitLab Access Token.
  </Step>

  <Step title="Create personal access token">
    Log in to GitLab. On the left sidebar, select your avatar. Select Edit **profile**. Select **Add new token**.

    <img alt="Creating a GitLab personal access token with required scopes" />
  </Step>

  <Step title="Set token details">
    Enter a name and expiry date for the token.

    * The token expires on that date at midnight UTC.
    * If you do not enter an expiry date,
      the expiry date is automatically set to 365 days later than the current date.
    * By default, this date can be a maximum of 365 days later than the current date.
  </Step>

  <Step title="Select scopes and create">
    Select the desired scopes,
    further details
    [here](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-token-scopes).
    Then select **Create personal access token**.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open GitLab connector">
    Navigate to the Admin Panel and select the **GitLab** Connector
  </Step>

  <Step title="Confirm GitLab URL">
    If you're using GitLab Cloud and not self-hosting, keep the GitLab URL as the default
  </Step>

  <Step title="Configure project">
    For a project with a url such as "[https://gitlab.com/onyx-ai/onyx](https://gitlab.com/onyx-ai/onyx)", configure it as below:
  </Step>
</Steps>

<img alt="Onyx GitLab connector project configuration example" />


# Gmail OAuth
Source: https://docs.onyx.app/admins/connectors/official/gmail/oauth

Set up Gmail OAuth for the connector

This section walks through setting up the Gmail connector using a OAuth-enabled Google App.
Anyone can do this (even without a paid Google Workspace)!

If you're an organization with a Google Workspace, and you'd rather use a Service Account to access Gmail,
checkout the section [here](./service_account).

### Authorization

<Steps>
  <Step title="Create Google Cloud Project">
    * [https://console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)
  </Step>

  <Step title="Enable Gmail API">
    * On the left panel, open **APIs & services**
    * Go to **Enabled APIs and services**
    * On the top click **+ENABLE APIS AND SERVICES**
    * Search for **Gmail API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/apis/enableflow?apiid=gmail.googleapis.com), select your project and enable the **Gmail API**
  </Step>

  <Step title="Set up OAuth consent screen">
    * Under **APIs & services**, select the **OAuth consent screen** tab
    * If you don't have a **Google Organization** select **External** for **User Type**
    * Call the app Onyx (or whatever you want)
    * For the required emails, use any email of your choice or `founders@onyx.app` if you wish for the Onyx team to help handle issues.
    * Click **SAVE AND CONTINUE**
  </Step>

  <Step title="Set up scopes">
    * Add the scope `.../auth/gmail.readonly` for `Gmail API`

    <Info>
      To enable permission syncing for this connector:

      * Enable the **Admin SDK API** (visit this link: [https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com](https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com)) and enable it for your project.
      * Add the scope `.../auth/admins.directory.user.readonly` for `Admin SDK API`.
      * Add the scope `.../auth/admins.directory.group.readonly` for `Admin SDK API`.
      * The account performing the OAuth flow must have an Admin role in the Google Workspace that
        has access to the "Groups > Read" privilege.
        This can be set in the Google Admin Console under Account > Admin roles.
    </Info>

    <img alt="Google Cloud OAuth consent screen with Gmail readonly scope selected" />
  </Step>

  <Step title="Set up test users">
    * This is only applicable for users without a Google Organization.
    * Add at least one test user email.
      Only the email accounts added here will be allowed to run the OAuth flow to index new emails.
    * Click **SAVE AND CONTINUE**, review the changes and click **BACK TO DASHBOARD**
  </Step>

  <Step title="Create OAuth credentials">
    * Go to the **Credentials** tab and select **+ CREATE CREDENTIALS** -> **OAuth client ID**

    <img alt="Creating OAuth client ID in Google Cloud Console for Gmail" />

    * Choose **Web application** and give it some name like `OnyxConnector`
    * Add an **Authorized JavaScript origins**
    * `http://localhost:3000` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>` if you have setup Onyx for production use
    * `https://cloud.onyx.app` if you are using the Onyx Cloud service
    * Add an **Authorized redirect URIs**
    * `http://localhost:3000/admin/connectors/gmail/auth/callback` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>/admin/connectors/gmail/auth/callback` if you have setup Onyx for production use
    * `https://cloud.onyx.app/admin/connectors/gmail/auth/callback` if you are using the Onyx Cloud service

    <img alt="Authorized origins and redirect URIs for Gmail OAuth client" />

    * Click create and on the right hand side next to **Client secret**,
      there is an option to download the credentials as a JSON. Download the JSON for use in the next step.

    <img alt="Download OAuth client JSON credentials from Google Cloud Console" />
  </Step>
</Steps>

### Indexing

First, navigate to the Admin Panel and select the Gmail connector.

Then, click **Create New**. Under **Option 1: OAuth app**, upload (or paste) the OAuth app JSON you downloaded above,
then click **Authenticate with Gmail**, then continue with the account you want to use to index Gmail.

Once complete, select the newly created credential, and click the **Continue** button to configure the connector!

<Note>
  The app JSON is stored on the credential it creates, so each OAuth credential carries its own app.
  To add more connectors for the same account,
  select the existing credential from the list instead of creating a new one.
  An instance can hold multiple Gmail credentials.
</Note>


# Gmail Overview
Source: https://docs.onyx.app/admins/connectors/official/gmail/overview

Overview of the Gmail connector

## How it works

The Gmail connector ingests your mails. It syncs the latest information from your Gmail every 10 minutes.

* Currently supports plain text emails.

## Setting up

Note: This Connector is relatively involved to set up.

* If you want to setup the connector via individual account OAuth, follow the guide [here](./oauth).
  This does not require a business Google Workspace.

* If you want to setup the connector via a Service Account, follow the guide
  [here](./service_account).

* If you have any questions about the setup / which approach is best for you, don't hesitate to
  reach out to [founders@onyx.app](mailto:founders@onyx.app)
  OR `@Yuhong Sun` / `@Chris Weaver` in
  [Slack](https://join.slack.com/t/onyx-dot-app/shared_invite/zt-34lu4m7xg-TsKGO6h8PDvR5W27zTdyhA) if you need help.

<Note>
  You can set up more than one Gmail connector on a single Onyx instance,
  each with its own credential and service account.
  This lets you index multiple Google Workspaces from one Onyx deployment.
</Note>


# Gmail Service Account
Source: https://docs.onyx.app/admins/connectors/official/gmail/service_account

Set up Gmail Service Account for the connector

This section walks through setting up the Gmail connector using a Service Account.
More info on Service Accounts can be found [here](https://cloud.google.com/iam/docs/service-account-overview).
A Google Workspace is required.

If you'd rather use an individuals account + OAuth to access Gmail, checkout the section [here](./oauth).

### Authorization

<Steps>
  <Step title="Create Google Cloud Project">
    * [https://console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)
  </Step>

  <Step title="Enable Gmail API and Admin SDK">
    * On the left panel, open **APIs & services**
    * Go to **Enabled APIs and services**
    * On the top click **+ENABLE APIS AND SERVICES**
    * Search for **Gmail API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com), select your project and enable the **Gmail API**
    * Also enable **Admin SDK API** (search and enable)

    <img alt="Google Cloud Console enabling Gmail and Admin SDK APIs" />
  </Step>

  <Step title="Create Service Account">
    * Go to the [Service Account management page](https://console.cloud.google.com/iam-admin/serviceaccounts) in Google Cloud.
    * Click `Create Service Account` button and fill out the fields in step 1. You can ignore steps 2 and 3.
    * Go to the `Keys` section, and click `Add Key`. Download this key. You will provide it when creating the credential in Onyx later.

    Note for Google Organizations created after April 2024:

    * To give the service account the proper permissions you will have to navigate to this [link](https://console.cloud.google.com/iam-admin/orgpolicies/iam-disableServiceAccountKeyCreation)
    * Then select `Manage`, select `Override parent's policy` and then select `Not enforced` under `Rules`.
    * Finally, select `SET POLICY`

    <iframe
      title="YouTube video
player"
    />
  </Step>

  <Step title="Grant domain-wide delegation">
    Give this **Service Account** read-only access to Gmail

    * Copy the `Unique ID` of the Service Account
    * Go to the [Domain-wide Delegation page](https://admin.google.com/ac/owl/domainwidedelegation) in the Google Admin Console.
    * Click `Add new`, fill in the client ID with the `Unique ID` of the Service account
    * Copy this comma separated list of scopes and paste it into field `OAuth scopes`:
      `https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly`
  </Step>
</Steps>

### Indexing

First, navigate to the Admin Panel and select the Gmail connector.

Then, create a new credential. In the **Authenticate with Onyx** step,
upload the service account key you downloaded when creating the service account.
Each credential holds its own service account key,
so the key is provided here rather than as a single instance-wide upload. For the **Primary Admin Email**,
use the email of a user that has an Admin role in the Google Workspace with access to the **Users > Read** and \*\*Groups

> Read\*\* privileges. This can either be an existing admin, or a brand new account created specifically for Onyx (e.g.
> `onyx-robot@your-domain.com`). Note that this should *NOT* be the service account email.
> This can be configured by an admin in the admin panel of the Google Workspace under Account > Admin roles.

Click **Create Credential**, and then close the dialog. From there,
click the **Continue** button and configure the connector!

<Note>
  You can create more than one Gmail credential on a single Onyx instance, each with its own service account.
  This lets you index multiple Google Workspaces from one Onyx deployment.
  Create a separate credential and connector for each workspace you want to index.
</Note>


# Gong
Source: https://docs.onyx.app/admins/connectors/official/gong

Access call transcripts from Gong

## How it works

The Gong connector pulls in the transcripts of calls recorded via Gong. The Gong connector indexes the call title,
call description, and contents of the actual transcript.

New transcripts are pulled every **10** minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Obtain API credentials">
    Get an **Access Key** and **Access Key Secret** to pull in Gong transcripts
  </Step>

  <Step title="Open Company Settings">
    As an admin, go to `Company Settings` on the right of the top options bar

    <img alt="Gong menu" />
  </Step>

  <Step title="Open Ecosystem → API">
    Next, find the **Ecosystem** block and select `API`

    <img alt="Gong ecosystem" />
  </Step>

  <Step title="Generate API keys">
    Once there, select `API KEYS` (it's right next to `INTEGRATIONS`).
    Click `GET API KEY` and note down the ACCESS KEY and ACCESS KEY SECRET
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Gong connector">
    In the Onyx UI, navigate to the Admin Panel and select the **Gong** Connector
  </Step>

  <Step title="Provide credentials">
    Provide the Access Key and Access Key Secret from the previous step
  </Step>

  <Step title="Choose workspaces">
    Add a list of workspaces to index or leave empty to index all workspaces
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing Gong call transcripts
  </Step>
</Steps>


# Google Drive OAuth
Source: https://docs.onyx.app/admins/connectors/official/google_drive/oauth

Set up Google Drive OAuth for the connector

This section walks through setting up the Google Drive connector using a OAuth-enabled Google App.
Anyone can do this (even without a paid Google Workspace)!

If you're an organization with a Google Workspace, and you'd rather use a Service Account to access Google Drive,
checkout the section [here](./service_account).

### Authorization

<Steps>
  <Step title="Create Google Cloud Project">
    * [https://console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)
  </Step>

  <Step title="Enable Google Drive API">
    * On the left panel, open **APIs & services**
    * Go to **Enabled APIs and services**
    * On the top click **+ENABLE APIS AND SERVICES**
    * Search for **Google Drive API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com),
      select your project and enable the **Google Drive API**
  </Step>

  <Step title="Enable Admin SDK API">
    * Click on **+ENABLE APIS AND SERVICES** again.
    * Search for **Admin SDK API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com),
      select your project and enable the **Admin SDK API**
  </Step>

  <Step title="Enable Google Sheets API">
    * Click on **+ENABLE APIS AND SERVICES** again.
    * Search for **Google Sheets API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/flows/enableapi?apiid=sheets.googleapis.com),
      select your project and enable the **Google Sheets API**
  </Step>

  <Step title="Enable Google Docs API">
    * Click on **+ENABLE APIS AND SERVICES** again.
    * Search for **Google Docs API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/flows/enableapi?apiid=docs.googleapis.com),
      select your project and enable the **Google Docs API**

    <img alt="Google Cloud Console enabling Google Docs API for the project" />
  </Step>

  <Step title="Set up OAuth consent screen">
    * Under **APIs & services**, select the **OAuth consent screen** tab
    * If you don't have a **Google Organization** select **External** for **User Type**
    * Call the app Onyx (or whatever you want)
    * For the required emails, use any email of your choice or `founders@onyx.app`
      if you wish for the Onyx team to help handle issues.
    * Click **SAVE AND CONTINUE**
  </Step>

  <Step title="Set up scopes">
    * Add the scope `.../auth/drive.readonly` for `Google Drive API`
    * Add the scope `.../auth/drive.metadata.readonly` for `Google Drive API`
    * Add the scope `.../auth/admin.directory.user.readonly` for `Admin SDK API`
    * Add the scope `.../auth/admin.directory.group.readonly` for `Admin SDK API`

    <img alt="OAuth consent screen scopes for Google Drive, Admin SDK, Sheets, and Docs" />
  </Step>

  <Step title="Set up test users">
    * This is only applicable for users without a Google Organization.
    * Typically for a company, Onyx would be set up as an internal app so this step would
      not apply.
    * Add at least one test user email. Only the email accounts added here will be allowed to
      run the OAuth flow to index new documents.
    * Click **SAVE AND CONTINUE**, review the changes and click **BACK TO DASHBOARD**
  </Step>

  <Step title="Create credentials">
    * Go to the **Credentials** tab and select **+ CREATE CREDENTIALS** -> **OAuth client ID**

    <img alt="Creating OAuth client ID in Google Cloud Console" />

    * Choose **Web application** and give it some name like `OnyxConnector`
    * Add a **Authorized JavaScript origins**
    * `http://localhost:3000` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>` if you have setup Onyx for production use
    * `https://cloud.onyx.app` if you are using the Onyx Cloud service
    * Add a **Authorized redirect URIs**
    * `http://localhost:3000/admin/connectors/google-drive/auth/callback` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>/admin/connectors/google-drive/auth/callback` if you have setup Onyx for production use
    * `https://cloud.onyx.app/admin/connectors/google-drive/auth/callback` if you are using the Onyx Cloud service

    <img alt="Configuring authorized origins and redirect URIs for Google Drive OAuth client" />

    * Click create and on the right hand side next to **Client secret**, there is an option to
      download the credentials as a JSON. Download the JSON for use in the next step.

    <img alt="Download OAuth client JSON credentials from Google Cloud Console" />
  </Step>
</Steps>

### Indexing

First, navigate to the Admin Panel and select the Google Drive connector.

Then, click **Create New**. Under **Option 1: OAuth app**, upload (or paste)
the OAuth app JSON you downloaded in the final step above,
then click **Authenticate with Google Drive** and continue with the account you want to use to index Google Drive.

<img alt="Onyx Google Drive credential modal showing the OAuth app and service account options" />

Once complete, select the newly created credential, and click the **Continue** button to configure the connector!

<Note>
  The app JSON is stored on the credential it creates, so each OAuth credential carries its own app.
  To add more connectors for the same account,
  select the existing credential from the list instead of creating a new one.
  An instance can hold multiple Google Drive credentials,
  including ones using different OAuth apps or different Google Workspaces.
</Note>

<Note>
  If you plan on using permission syncing for this connector,
  the account performing the OAuth flow must have an Admin role in the Google Workspace that has access to the
  following:

  * Admin console privileges -> Services -> Drive and Docs -> Settings
  * Admin API privileges -> Users -> Read
  * Admin API privileges -> Groups -> Read
  * Admin API privileges -> Organization Units -> Read

  This can be set by an admin in the admin panel of the Google Workspace under Account > Admin roles.
</Note>


# Google Drive Overview
Source: https://docs.onyx.app/admins/connectors/official/google_drive/overview

Overview of the Google Drive connector

## How it works

The Google Drive connector indexes documents in your Drive. Currently, it supports:

* Google: Docs, Sheets, and Slides
* Microsoft: Word, Excel, and PowerPoint
* PDF, CSV, and TXT files
* Certain other document, plaintext, and image files

## Setting up

Note: This Connector is relatively involved to set up.

* **\[Recommended]** If you want to setup the connector via Service Accounts, follow the guide
  [here](./service_account). This does require a business Google Workspace / access to the Admin panel.
  If you are an organization that meets these pre-requisites, then this is likely the preferred approach.

* If you want to setup the connector via individual account OAuth, follow the guide [here](./oauth).
  This does not require a business Google Workspace.

* If you have any questions about the setup / which approach is best for you, don't hesitate to
  reach out to [founders@onyx.app](mailto:founders@onyx.app)
  OR `@Yuhong Sun` / `@Chris Weaver` in
  [Slack](https://join.slack.com/t/onyx-dot-app/shared_invite/zt-34lu4m7xg-TsKGO6h8PDvR5W27zTdyhA) if you need help.

<Note>
  You can set up more than one Google Drive connector on a single Onyx instance,
  each with its own credential and service account.
  This lets you index multiple Google Workspaces from one Onyx deployment.
</Note>


# Google Drive Service Account
Source: https://docs.onyx.app/admins/connectors/official/google_drive/service_account

Set up Google Drive Service Account for the connector

This section walks through setting up the Google Drive connector using a Service Account.
More info on Service Accounts can be found [here](https://cloud.google.com/iam/docs/service-account-overview).
A Google Workspace is required.

If you'd rather use an individuals account + OAuth to access Google Drive, checkout the section [here](./oauth).

### Authorization

<Steps>
  <Step title="Create Google Cloud Project">
    * [https://console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)
  </Step>

  <Step title="Enable required APIs">
    Enable the **Google Drive API**, the **Admin SDK API**, the **Google Docs API**, and the **Google Sheets API**

    * On the left panel, open **APIs & services**
    * Go to **Enabled APIs and services**
    * On the top click **+ENABLE APIS AND SERVICES**
    * Search for **Google Drive API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com), select your project and enable the **Google Drive API**
    * Search and enable: **Admin SDK API**, **Google Sheets API**, **Google Docs API**

    <img alt="Google Cloud Console enabling Drive, Admin SDK, Docs, and Sheets APIs" />
  </Step>

  <Step title="Create Service Account">
    * Go to the [Service Account management page](https://console.cloud.google.com/iam-admin/serviceaccounts) in Google Cloud.
    * Click `Create Service Account` button and fill out the fields in step 1. You can ignore steps 2 and 3.
    * Go to the `Keys` section, and click `Add Key`. Download this key. You will provide it when creating the credential in Onyx later.

    Note for Google Organizations created after April 2024:

    * To give the service account the proper permissions you will have to navigate to this [link](https://console.cloud.google.com/iam-admin/orgpolicies/iam-disableServiceAccountKeyCreation)
    * Then select `Manage`, select `Override parent's policy` and then select `Not enforced` under `Rules`.
    * Finally, select `SET POLICY`

    <iframe
      title="YouTube video
player"
    />
  </Step>

  <Step title="Grant domain-wide delegation">
    Give this **Service Account** read-only access to Google Drive

    * Copy the `Unique ID` of the Service Account
    * Go to the [Domain-wide Delegation page](https://admin.google.com/ac/owl/domainwidedelegation) in the Google Admin Console.
    * Click `Add new`, fill in the client ID with the `Unique ID` of the Service account
    * Copy this comma separated list of scopes and paste it into field `OAuth scopes`:
      `https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly`

    <iframe
      title="YouTube video
player"
    />
  </Step>
</Steps>

### Indexing

First, navigate to the Admin Panel and select the Google Drive connector.

Then, create a new credential. In the **Authenticate with Onyx** step,
upload the service account key you downloaded when creating the service account.
Each credential holds its own service account key,
so the key is provided here rather than as a single instance-wide upload. For the **Primary Admin Email**,
use the email of a user that:

* Has access to `Drive and Docs` in Google Workspace
* Has the following admin permissions:
  * Admin console privileges -> Services -> Drive and Docs -> Settings
  * Admin API privileges -> Users -> Read
  * Admin API privileges -> Groups -> Read
  * Admin API privileges -> Organization Units -> Read

This can either be an existing admin, or a brand new account created specifically for Onyx (e.g.
`onyx-robot@your-domain.com`). Note that this should *NOT* be the service account email.
This can be configured by an admin in the admin panel of the Google Workspace under Account > Admin roles.

<img alt="Onyx Google Drive connector with Service Account credential and Primary Admin Email" />

Click **Create Credential**, and then close the dialog. From there,
click the **Continue** button and configure the connector!

<Note>
  You can create more than one Google Drive credential on a single Onyx instance, each with its own service account.
  This lets you index multiple Google Workspaces from one Onyx deployment.
  Create a separate credential and connector for each workspace you want to index.
</Note>


# Google Sites
Source: https://docs.onyx.app/admins/connectors/official/google_sites

Access sites and pages from Google Sites

## How it works

Export your Google Site using [Google Takeout](https://takeout.google.com/), and then upload the zip to Onyx.
We'll then index all your pages, and allow you to ask questions based on the site's content!

## Setting up

### Exporting Your Google Site

<Steps>
  <Step title="Export with Takeout">
    Follow the guide [here](https://www.steegle.com/google-sites/how-to/export-with-takeout) to export your Google Site.
    Be sure to include ONLY the Google Site in the folder.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Google Sites connector">
    Navigate to the Admin Panel and select the **Google Sites** Connector.
  </Step>

  <Step title="Enter base URL">
    Find and enter the base URL of your Google Site. This is the URL used to access the root page of the site.
  </Step>

  <Step title="Upload export ZIP">
    Upload the Zip file downloaded in the export step.
  </Step>

  <Step title="Start indexing">
    Click the **Upload** button. Your site will be indexed and searchable upon completion.
  </Step>
</Steps>

<img alt="Onyx Google Sites connector configuration UI" />


# Google Cloud Storage
Source: https://docs.onyx.app/admins/connectors/official/google_storage

Access files from Google Cloud Storage buckets

## How it works

The Google Cloud Storage connector pulls in all documents from the specified GCS bucket.
It supports various file formats including PDF, DOC, DOCX, TXT, and more.

Documents are updated every **1** day.

## Setting up

### Authorization

<Steps>
  <Step title="Open Interoperability settings">
    Log into your [Google Cloud Console](https://console.cloud.google.com/).
    Navigate to "Cloud Storage" > "Settings" > "Interoperability".

    <img alt="Google Cloud Storage Interoperability" />
  </Step>

  <Step title="Create service account key">
    Click "Create a key for a service account".
    Click "Create new account" (or select an existing account and click Create key).

    <img alt="New service account" />
  </Step>

  <Step title="Set service account details">
    Set a name for the new service account (e.g., "onyx-gcs-connector") and click "Create and continue".

    <img alt="Service account configuration" />
  </Step>

  <Step title="Assign role and finish">
    Click "Select a role" and select Storage Object Viewer or another, more permissive role. Click "Done".

    <img alt="Service account permissions" />
  </Step>

  <Step title="Record HMAC keys">
    Back on the Interoperability page you should see the new credentials. Record both `Access key` and `Secret`.

    <img alt="HMAC keys" />
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Google Storage connector">
    Navigate to the Admin Panel > Add Connector > **Google Storage**.
  </Step>

  <Step title="Create credentials">
    Click Create New to create a new credential.

    <img alt="Onyx Google Cloud Storage credentials" />
  </Step>

  <Step title="Enter keys and connect">
    Paste your Access key and Secret in the form. Click Create and Continue. Name your connector,
    specify the GCS bucket you would like to index, and click Create Connector.

    <img alt="Onyx Connector creation" />
  </Step>
</Steps>

## Understanding Google Cloud Storage Structure

Google Cloud Storage organizes data into buckets. Each bucket can contain an unlimited number of objects (files).
You can think of a bucket as a root directory, and the objects as files within that directory.

For more information on Google Cloud Storage structure,
visit the [Google Cloud Storage documentation](https://cloud.google.com/storage/docs).


# Guru
Source: https://docs.onyx.app/admins/connectors/official/guru

Access cards and collections from Guru

## How it works

The Guru connector pulls in all the Cards your user has access to based on a User Access Token.

Cards are updated every **10** minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Obtain access token">
    Obtain a User Access Token.
    Follow the Guru API guide described [here](https://developer.getguru.com/docs/getting-started) for more details.
  </Step>
</Steps>

<img alt="Guru API dashboard steps to create a User Access Token" />

### Indexing

<Steps>
  <Step title="Open Guru connector">
    Navigate to the Admin Panel and select the **Guru** Connector
  </Step>

  <Step title="Enter credentials">
    In **Step 1**, provide your **Username** (most likely your email) and the **Access Token** from above.

    <img alt="Onyx Guru connector credentials form with username and access token" />
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing
  </Step>
</Steps>


# Highspot
Source: https://docs.onyx.app/admins/connectors/official/highspot

Access sales content from Highspot

## How it works

The Highspot connector indexes documents from your Highspot instance.
It can index either specific spots you add or all spots where you have view access and download permissions.

## Setting up

### Authorization

> **IMPORTANT:** Highspot Platform Plus is an add-on feature that provides access to the API. Without Platform Plus, users cannot access the API features required for this connector. Please ensure your organization has purchased the Platform Plus add-on before proceeding.

#### Enabling Developer Options

<Steps>
  <Step title="Open company settings">
    Log into your Highspot account as an administrator.
    Click on your profile icon in the top right corner and select "Settings".
    Select "your company" under company settings.
  </Step>

  <Step title="Enable API access">
    Navigate to "Access and Privacy" and click on "API Access". Add the user(s)
    who will need to generate API keys and secrets. Confirm "API Access for Users" is enabled.
  </Step>
</Steps>

<img alt="Highspot company settings showing Access and Privacy with API access" />

#### Generating API Credentials

<Steps>
  <Step title="Open Developer settings">
    Log in as the user who has been granted API access.
    Click on the profile icon in the top right corner and select "Settings".
    Look for the "Developer" tab under user settings.
  </Step>

  <Step title="Generate API key">
    Navigate to the developer section and generate a new API key. After generation, you'll receive a key and secret.

    <img alt="Highspot user Developer settings generating an API key and secret" />
  </Step>

  <Step title="Record credentials">
    Make a note of your API key, secret and base URL as you will need them for indexing.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Highspot connector">
    Navigate to the Admin Panel and select the **Highspot** Connector Tile
  </Step>

  <Step title="Enter credentials">
    Provide your **API Key**, **Secret**, and **Base URL** from the steps above
  </Step>

  <Step title="Choose indexing options">
    Choose one of the following:

    * Enter specific spots you want to index
    * Index all spots where your user has view access and download permissions
  </Step>

  <Step title="Start indexing">
    Click "Connect" to begin indexing your Highspot content
  </Step>
</Steps>


# HubSpot
Source: https://docs.onyx.app/admins/connectors/official/hubspot

Access CRM data from HubSpot

## How it works

The HubSpot connector pulls in data from your HubSpot CRM, including:

* **Tickets** - Support tickets with their title, content, associated emails and notes
* **Companies** - Company records with associated data and relationships
* **Deals** - Sales opportunities with pipeline information and associated contacts
* **Contacts** - Contact records with their information and associated activities

You can configure which object types to index based on your needs.
All selected data types are updated every **10** minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Create Private App">
    Create a Private App Integration (see below).

    <img alt="Creating a Private App in HubSpot settings" />
  </Step>

  <Step title="Select scopes">
    Under **Scopes** (top bar), select the appropriate scopes based on what data you want to index:

    * For **Tickets**: Select the `Tickets` scope
    * For **Companies**: Select the `Companies` scope
    * For **Deals**: Select the `Deals` scope
    * For **Contacts**: Select the `Contacts` scope

    <img alt="Selecting HubSpot OAuth scopes for Contacts, Companies, Deals, and Tickets" />
  </Step>

  <Step title="Copy Access Token">
    Copy the Access Token that is shown when the App is created.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open HubSpot connector">
    Navigate to the Admin Panel and select the **HubSpot** Connector
  </Step>

  <Step title="Enter Access Token">
    In **Step 1**, provide the Access Token from above
  </Step>

  <Step title="Choose object types">
    In **Step 2**, select which object types you want to index:

    * **Companies** - Index company records and their associated data
    * **Deals** - Index sales opportunities and pipeline information
    * **Contacts** - Index contact records and their activities
    * **Tickets** - Index support tickets and related communications
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing your selected HubSpot data types
  </Step>
</Steps>

<Note>
  Make sure your HubSpot Access Token has the appropriate scopes enabled for the object types you want to index.
  The connector will only be able to access data for which you've granted the necessary permissions.
</Note>


# Jira
Source: https://docs.onyx.app/admins/connectors/official/jira

Access issues and projects from Jira

## How it works

The Jira connector pulls in all tickets from the specified projects every **10** minutes.

For every jira issue this connector will pull:

* Title
* Description
* [Common fields](#indexed-metadata)
* Comments

## Setting up

### Authorization

<Steps>
  <Step title="Jira Cloud token">
    **Jira Cloud**:
    follow the guide described
    [here](https://docs.searchunify.com/Content/Content-Sources/Atlassian-Jira-Confluence-Authentication-Create-API-Token.htm)
    to get an access token.
  </Step>

  <Step title="Jira Server token">
    **Jira Server**:
    follow the guide described
    [here](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html)
    to get a personal access token.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Jira connector">
    Navigate to the Admin Panel and select the **Jira** Connector
  </Step>

  <Step title="Provide credentials">
    For Cloud, provide the **Access Token** and the **Username** it belongs to:

    <img alt="Onyx Jira Cloud connector authentication form" />

    For Server, provide the **Personal Access Token**:

    <img alt="Onyx Jira Server connector personal access token form" />
  </Step>

  <Step title="Choose projects and filters">
    For each project you want to index, provide a single URL to any page in the project.
    Optionally specify users whose comments should not be indexed (useful to ignore certain bots). For example:

    <img alt="Jira indexing configuration showing project URLs and excluded commenters" />
  </Step>

  <Step title="Start indexing">
    Click the `Connect` button! All your Jira tickets in that space will now be pulled into Onyx every **10** minutes.
  </Step>
</Steps>

### Indexed metadata

```
- Project ID
- Issue Type
- Issue Key
- Summary
- Description
- Priority
- Labels
- Assignee
- Reporter
- Comments
- Status
- Resolution
- Created
- Updated
```


# Linear
Source: https://docs.onyx.app/admins/connectors/official/linear

Access issues and projects from Linear

## How it works

The Linear connector pulls in all the Linear issues and the associated comments.

Issues are updated every **10** minutes.

## Setup

### Configure your Linear Application + Onyx env variables

<Info>
  This is only necessary if self-hosting Onyx. If using [Onyx Cloud](https://cloud.onyx.app), you can skip this step.
</Info>

<Steps>
  <Step title="Create Linear application">
    [Create a Linear OAuth Application.](https://linear.app/settings/api)
    This step must be completed by an admin of the Linear workspace you wish to connect to Onyx.
    The application callback URLs should include `<your onyx host>/connector/oauth/callback/linear`. For example,
    for a local deployment with default configurations one of the lines should be
    `http://localhost:3000/connector/oauth/callback/linear`.
  </Step>

  <Step title="Set environment variables">
    Set the following environment variables on your Onyx instance using the Client ID and Signing Secret provided by
    Linear for your new app:

    ```bash theme={null}
    LINEAR_CLIENT_ID=
    LINEAR_CLIENT_SECRET=
    ```
  </Step>

  <Step title="Restart Onyx">
    Restart your Onyx instance as you normally would to apply the changes.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Linear connector">
    In the Onyx UI, navigate to the Admin Panel and select the **Linear** Connector
  </Step>

  <Step title="Authorize via OAuth">
    Click the `Create New` button to go through the OAuth flow.
  </Step>

  <Step title="Return to Onyx">
    Once you've authorized the application, you'll be redirected back to Onyx.
  </Step>

  <Step title="Select credential and configure">
    Select the new credential and click Continue. Enter connector name and permissions information.
  </Step>

  <Step title="Create connector">
    Click `Create Connector` to begin indexing Linear issues and comments!
  </Step>
</Steps>


# Notion
Source: https://docs.onyx.app/admins/connectors/official/notion

Access pages and databases from Notion

## How it works

The Notion connector uses the Notion search API to fetch all pages that the connector has access to within a workspace.
For follow up indexing runs, the connector only retrieves pages that have been updated since the last indexing attempt.
Indexing is configured to run every **10 minutes**, so page updates should appear within 10 minutes.

## Setting up

### Authorization

In order to authorize Onyx to connect to your Notion workspace, you'll need to create a new integration in Notion,
which will then provide you with a secret token.

These steps are pulled from [this Notion guide](https://developers.notion.com/docs/create-a-notion-integration)
which you can also follow.

#### Step 1: Create an integration

<Steps>
  <Step title="Visit integrations page">
    Visit [https://www.notion.com/my-integrations](https://www.notion.com/my-integrations) in your browser.
  </Step>

  <Step title="Create new integration">
    Click the + New integration button.
  </Step>

  <Step title="Name the integration">
    Name the integration (something like "Onyx" could work).
  </Step>

  <Step title="Set capabilities">
    Select "Read content" as the only capability required for Onyx.
  </Step>

  <Step title="Submit">
    Click Submit to create the integration.
  </Step>
</Steps>

On the next page, you'll find your Notion integration token, also called an API key.
You'll need this token to configure Onyx to index Notion, so make a copy of it.

The integration has been added to the workspace, so any member can share pages and databases with it.
There's no requirement to be an Admin to share information with an integration.

<img alt="Creating a Notion internal integration in the Notion settings" />

#### Step 2: Share pages/databases with your integration

Now that you've created an integration, you need to grant it access to Notion pages/databases.
To keep your information secure, integrations don't have access to any pages or databases in the workspace at first.
You must share specific pages with an integration in order for Onyx to access those pages.

To share a page/database with your integration:

<Steps>
  <Step title="Navigate to page">
    Go to the page/database in your workspace.
  </Step>

  <Step title="Access page menu">
    Click the `•••` on the top right corner of the page.
  </Step>

  <Step title="Add connections">
    Scroll to the bottom of the pop-up and click Add connections.
  </Step>

  <Step title="Select integration">
    Search for and select the new integration in the `Search for connections...` menu.
  </Step>

  <Step title="Note about child pages">
    If you've added a page, all child pages also become accessible to Onyx.
  </Step>
</Steps>

If you've added a database, all rows (and their children) become accessible to Onyx.

<img alt="Adding the Onyx integration to a Notion workspace or page" />

Once you've granted access to a page/database, you can start configuring Onyx to index those databases.

### Indexing

<Steps>
  <Step title="Open Notion connector">
    Navigate to the Admin Panel and select the **Notion** connector.
  </Step>

  <Step title="Enter Integration Token">
    In **Step 1**, provide the **Integration Token Secret** you obtained in the "Authorization" steps above:

    <img alt="Onyx Notion connector authentication step to connect integration" />
  </Step>

  <Step title="Connect and index">
    Click the `Connect` button! Your content will then be pulled into Onyx every **10** minutes.

    <img alt="Onyx Notion connector indexing options and selection screen" />
  </Step>
</Steps>

Note - As mentioned, the Notion connector currently indexes everything it has access to.
If you want to limit specific content being indexed, simply unshare the database from Notion with the integration.


# Oracle Cloud Storage
Source: https://docs.onyx.app/admins/connectors/official/oci_storage

Access files from Oracle Cloud Storage buckets

## How it works

The Oracle Cloud Infrastructure (OCI) Storage connector pulls in all documents from the specified OCI bucket.
It supports various file formats including PDF, DOC, DOCX, TXT, and more.

Documents are updated every **1** day.

## Setting up

### Authorization

<Steps>
  <Step title="Open Oracle Cloud Console">
    Log into your Oracle Cloud Console.
  </Step>

  <Step title="Open User Settings">
    Click on the user icon in the top-right corner and select "User Settings".

    <img alt="OCI user settings" />
  </Step>

  <Step title="Open Customer Secret Keys">
    Under "Resources", click on "Customer Secret Keys".

    <img alt="OCI customer secret keys" />
  </Step>

  <Step title="Generate Secret Key">
    Click "Generate Secret Key".
  </Step>

  <Step title="Name the key">
    Enter a friendly name for your key (e.g., "OnyxOCIConnector").
  </Step>

  <Step title="Generate and copy key">
    Click "Generate Secret Key". You will see your Secret Key. Make sure to copy the key immediately,
    as you won't be able to retrieve it later.
  </Step>

  <Step title="Verify keys list">
    You should now be taken to the "Customer Secret Keys" page and see a list of keys (including the name of the key you
    just generated). The corresponding access key should be present.

    <img alt="OCI secret keys list" />

    <img alt="Hover key to view access key" />
  </Step>

  <Step title="Find Object Storage namespace">
    To find your tenancy's Object Storage namespace, click on the user icon in the top-right corner and select "Tenancy:
    \[your tenancy name]". In the tenancy details, you'll find the Object Storage namespace.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open OCI Storage connector">
    Navigate to the Admin Panel and select the **Oracle Cloud Infrastructure Storage** Connector.
  </Step>

  <Step title="Enter OCI credentials">
    In **Step 1**, provide your OCI credentials:

    <img alt="OCI credentials input" />

    * Provide your OCI Access Key, Secret Key, Namespace, and Region for authentication.
    * These credentials will be used to access your OCI buckets.
  </Step>

  <Step title="Save credentials">
    Click "Update" to save your credentials.
  </Step>

  <Step title="Select bucket">
    In **Step 2**, specify which OCI bucket you want to make searchable:

    <img alt="OCI bucket selection" />
  </Step>

  <Step title="Start indexing">
    Click "Connect" to begin indexing.
  </Step>
</Steps>

## Understanding Oracle Cloud Infrastructure Object Storage Structure

Oracle Cloud Infrastructure Object Storage organizes data into buckets.
Each bucket can contain an unlimited number of objects (files). You can think of a bucket as a root directory,
and the objects as files within that directory.

For more information on OCI Object Storage structure,
visit the [Oracle Cloud Infrastructure Object Storage
documentation](https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/objectstorageoverview.htm).


# Productboard
Source: https://docs.onyx.app/admins/connectors/official/productboard

Access product feedback and features from Productboard

## How it works

The Productboard connector pulls in all the `Features`, `Components`, `Products`, and `Objectives` into Onyx.
At this time, the Productboard APIs does not support pulling in `Releases` or `Notes`.

Everything is updated every **10** minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Get access token">
    Follow the `Getting a token` guide
    [here](https://developer.productboard.com/#section/Authentication/Public-API-Access-Token) to get an Access Token.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Productboard connector">
    Navigate to the Admin Panel and select the **Productboard** Connector
  </Step>

  <Step title="Enter access token">
    In **Step 1**, provide your **Access Token**
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing
  </Step>
</Steps>


# Cloudflare R2
Source: https://docs.onyx.app/admins/connectors/official/r2

Access files from Cloudflare R2 buckets

## How it works

The R2 connector pulls in all documents from the specified Cloudflare R2 bucket.
It supports various file formats including PDF, DOC, DOCX, TXT, and more.

Documents are updated every **1** day.

## Setting up

### Authorization

<Steps>
  <Step title="Open R2 dashboard">
    Log into your Cloudflare dashboard. Navigate to "R2" in the sidebar and click on "Manage R2 API Tokens".

    <img alt="Manage API" />
  </Step>

  <Step title="Create API token">
    Click "Create API token".

    <img alt="Create API token" />
  </Step>

  <Step title="Set permissions">
    Give your token a name (e.g., "OnyxR2Connector") and select the appropriate permissions (Object Read only).

    <img alt="Read only" />
  </Step>

  <Step title="Copy keys and Account ID">
    Click "Create API Token". On the next screen, copy your Access Key ID and Secret Access Key immediately. Then,
    to find your Account ID, go to the Overview page; the Account ID is listed in the URL as the final substring.

    <img alt="R2 credentials" />
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open R2 connector">
    Navigate to the Admin Panel and select the **R2** Connector.
  </Step>

  <Step title="Enter credentials">
    In **Step 1**, provide your R2 credentials (Access Key ID, Secret Access Key, and Account ID).

    <img alt="R2 credentials input" />
  </Step>

  <Step title="Save credentials">
    Click "Update" to save your credentials.
  </Step>

  <Step title="Select bucket">
    In **Step 2**, specify which R2 bucket you want to make searchable.

    <img alt="R2 bucket selection" />
  </Step>

  <Step title="Start indexing">
    Click "Connect" to begin indexing.
  </Step>
</Steps>

## Understanding R2 Structure

Cloudflare R2 organizes data into buckets, similar to Amazon S3.
Each bucket can contain an unlimited number of objects (files). You can think of a bucket as a root directory,
and the objects as files within that directory.

For more information on R2 structure, visit the [Cloudflare R2 documentation](https://developers.cloudflare.com/r2/).


# RequestTracker
Source: https://docs.onyx.app/admins/connectors/official/requesttracker

Access tickets from RequestTracker

## How it works

The Request Tracker connector will pull in all tickets updated within the last 10 minutes into the dataset.

Tickets are updated every **10** minutes.

Only Request Tracker REST API 1.0 is supported at this time. REST API 1.0 is implemented in Request Tracker 4.x,
Request Tracker 5.x is not supported currently.

## Setting up

### Create or use a Request Tracker user who has the appropriate permissions

* Create a Request Tracker user that has read access to all queues Onyx should read.

### Configure Request Tracker connector and begin indexing

<Steps>
  <Step title="Open Request Tracker connector">
    Navigate to the Admin Panel and select the **Request Tracker** Connector
  </Step>

  <Step title="Enter credentials">
    In **Step 1**, provide your Request Tracker **username**, **password**, and **RT installation base url**.

    <img alt="Onyx Request Tracker connector credentials form" />
  </Step>

  <Step title="Start indexing">
    In **Step 2**, click `Connect` to begin indexing

    <img alt="Onyx Request Tracker connector indexing step" />
  </Step>
</Steps>


# S3 Access Keys
Source: https://docs.onyx.app/admins/connectors/official/s3/access-keys

Authorize the S3 connector using AWS Access Keys.

## AWS Access Keys Authorization

<Steps>
  <Step title="Open AWS Console">
    Log into your AWS Management Console.
  </Step>

  <Step title="Open IAM">
    Navigate to the IAM (Identity and Access Management) dashboard.
  </Step>

  <Step title="Create user">
    In the left sidebar, click on "Users" and then "Create user".

    <img alt="AWS IAM dashboard with Users section for creating a user" />
  </Step>

  <Step title="Set user details">
    Set a name for the new user (e.g., "OnyxS3Connector") and click "Next".
  </Step>

  <Step title="Attach policy">
    Click "Attach policies directly" and search for "AmazonS3ReadOnlyAccess" or a similarly permissive policy.
    Select this policy and click "Next".
  </Step>

  <Step title="Create user">
    Add any tags if needed, then click "Create user".
  </Step>

  <Step title="Create access key">
    On the users page, click on the user you just created. In the summary section,
    click "Create access key" and choose "Third-party service" as the use case. Confirm the disclaimer and continue.
  </Step>

  <Step title="Copy keys">
    Optionally set a description tag and then press "create access key".
    Copy the Access Key ID and Secret Access Key immediately; you won't be able to view the secret again.

    <img alt="AWS security credentials page" />
  </Step>
</Steps>

### Credential Entry in Onyx

When configuring the S3 connector in Onyx, you'll enter your credentials as follows:

* **AWS Access Key ID**: Paste the Access Key ID you copied from AWS
* **AWS Secret Access Key**: Paste the Secret Access Key you copied from AWS

<img alt="Onyx S3 connector configuration with Access Key ID and Secret fields" />

Once you have your AWS Access Keys, proceed to the [indexing steps in the overview](./overview#indexing)
to configure your S3 connector.


# S3 Assume Role
Source: https://docs.onyx.app/admins/connectors/official/s3/assume-role

This method automatically uses the IAM role attached to your EC2 instance to access S3 buckets. No manual credential entry is required.

### Prerequisites

* Ensure your EC2 instance has an IAM role attached.
* Verify the instance profile is properly configured via AWS Console under **EC2 › Instance Settings
  › Attach/Replace IAM role**.

### Updating the Existing IAM Role

Since your EC2 instance already has an IAM role attached, you need to update it with the necessary S3 permissions:

<Steps>
  <Step title="Open role in IAM">
    In AWS Console, go to **IAM › Roles** and find your EC2 instance's existing role.
  </Step>

  <Step title="Attach S3 policy">
    Click on the role and go to the **Permissions** tab. Click **Add permissions › Attach policies**.
    Search for and select **AmazonS3ReadOnlyAccess** policy. Click **Attach policies**.
  </Step>
</Steps>

Alternatively, for more granular control, you can create a custom inline policy:

<Steps>
  <Step title="Create inline policy">
    In the same role's **Permissions** tab, click **Add permissions › Create inline policy**.
    Switch to JSON and add this policy (replace `your-source-bucket-name`):

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:GetObject",
            "s3:ListBucket"
          ],
          "Resource": [
            "arn:aws:s3:::your-source-bucket-name",
            "arn:aws:s3:::your-source-bucket-name/*"
          ]
        }
      ]
    }
    ```

    Name the policy (e.g., `OnyxS3Access`) and click **Create policy**.
  </Step>
</Steps>

The connector will automatically detect and use the EC2 instance's IAM role for accessing your S3 buckets.

### Credential Entry in Onyx

When configuring the S3 connector in Onyx, you'll need to:

<Steps>
  <Step title="Open Assume Role tab">
    Click on the **Assume Role** tab
  </Step>

  <Step title="No credentials required">
    No credentials need to be entered — the connector automatically uses your EC2 instance's attached role.
  </Step>
</Steps>

<img alt="Screenshot of Onyx S3 assume role configuration" />

Once you have updated your EC2 instance's role with S3 permissions,
proceed to the [indexing steps in the overview](./overview#indexing) to configure your S3 connector.


# S3 IAM Role
Source: https://docs.onyx.app/admins/connectors/official/s3/iam-role

Authorize the S3 connector using an AWS IAM Role with assume role policy.

### When to use this method

* When you need to segregate permissions, granting specific S3 access without modifying your EC2
  instance's main role
* When you require temporary, frequently rotated credentials for S3 access, without managing
  long-lived access keys
* When working in multi-account AWS environments, enabling cross-account S3 access through role
  assumption

### Setting up the IAM Role

<Steps>
  <Step title="Create the S3 Access Role">
    * In AWS Console, go to **IAM › Roles** and click **Create role**
    * For **Trusted entity type**, select **Custom trust policy**
    * In the Custom trust policy JSON editor, configure who can assume this role.
      You can choose from:
    * **IAM Role**: `"AWS": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YourExistingEC2Role"`
    * **AWS Service**: `"Service": "ec2.amazonaws.com"` (for EC2 instances)

    Example for EC2 role (replace `YOUR_AWS_ACCOUNT_ID` and `YourExistingEC2Role`):

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YourExistingEC2Role"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }
    ```

    * Click **Next**
    * Attach **AmazonS3ReadOnlyAccess** policy or create a custom policy for specific buckets:

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:GetObject",
            "s3:ListBucket"
          ],
          "Resource": [
            "arn:aws:s3:::your-source-bucket-name",
            "arn:aws:s3:::your-source-bucket-name/*"
          ]
        }
      ]
    }
    ```

    * Name it (e.g., `OnyxS3AccessRole`) and click **Create role**
    * Copy the **Role ARN** from the role summary page (e.g., `arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_CREATED_ROLE_NAME`)

    <img alt="Diagram of page where role arn can be copied" />
  </Step>

  <Step title="Grant AssumeRole to EC2 instance role">
    * Go back to **IAM > Roles** and find your EC2 instance's existing role
    * Click on the role and go to the **Permissions** tab
    * Click **Add permissions > Create inline policy**
    * Switch to JSON and add this policy (replace with your actual account ID and role name):

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "sts:AssumeRole",
          "Resource": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_CREATED_ROLE_NAME"
        }
      ]
    }
    ```

    * Name the policy (e.g., `AllowAssumeOnyxS3Role`) and click **Create policy**

    <img alt="Diagram of IAM role assignment" />

    Your EC2 instance now uses its existing instance profile to obtain temporary credentials for the OnyxS3AccessRole,
    which can then securely interact with your designated S3 buckets.
  </Step>
</Steps>

### Credential Entry in Onyx

When configuring the S3 connector in Onyx, you'll need to:

<Steps>
  <Step title="Open IAM Role tab">
    Click on the **IAM Role** tab
  </Step>

  <Step title="Enter Role ARN">
    Enter the **Role ARN** you copied earlier (e.g., `arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_CREATED_ROLE_NAME`)
  </Step>
</Steps>

<img alt="Screenshot of Onyx S3 IAM role configuration with tabs" />

Once you have your IAM Role ARN, proceed to the [indexing steps in the overview](./overview#indexing)
to configure your S3 connector.


# S3 Overview
Source: https://docs.onyx.app/admins/connectors/official/s3/overview

Overview of the S3 connector

## How it works

The S3 connector pulls in all documents from the specified Amazon S3 bucket.
It supports various file formats including PDF, DOC, DOCX, TXT, and more.

Documents are updated every **1** day.

## Setting up

### Authorization

We support three authorization methods—pick one that fits your environment:

* [AWS Access Keys](./access-keys) - Uses traditional access key credentials
* [IAM Role-Based Authorization](./iam-role) - Uses AWS IAM roles for secure access
* [Assume Role](./assume-role) - Automatically uses the EC2 instance's attached role for S3 access

### Indexing

Once you've set up your authorization method, follow these steps to index your S3 bucket:

<Steps>
  <Step title="Open S3 connector">
    Navigate to the Onyx Admin Panel and select the **S3** Connector.
  </Step>

  <Step title="Configure authorization">
    In **Step 1**, configure your authorization:

    * If you have existing credentials, select them from the list
    * If you don't have existing credentials, click **Create New** to add new authorization:
    * **Access Keys**: Enter your AWS Access Key ID and Secret Access Key
    * **IAM Role**: Click the IAM Role tab and enter your Role ARN
    * **Assume Role**: Click the Assume Role tab (no credentials required)
  </Step>

  <Step title="Save configuration">
    Click **Create** to save your configuration.
  </Step>

  <Step title="Continue with selected credential">
    Ensure your chosen credential is selected, then click **Continue**
  </Step>

  <Step title="Specify bucket details">
    In **Step 2**, specify your S3 bucket details:

    * **Connector Name**: Enter a name for the connector (e.g., "MyS3Connector")
    * **Bucket Name**: Specify the name of the S3 bucket you want to index
    * **Prefix (Optional)**: Provide a prefix to limit indexing to a specific folder or path
    * **Access Type**: Choose whether documents are **Public** or **Private**
  </Step>

  <Step title="Create connector">
    Click **Create Connector** to begin indexing.
  </Step>
</Steps>

The connector will start indexing your S3 bucket and you can add more buckets or modify settings as needed.

<img alt="Onyx S3 connector details page" />

## Understanding S3 Structure

Amazon S3 organizes data into buckets. Each bucket can contain an unlimited number of objects (files).
You can think of a bucket as a root directory, and the objects as files within that directory.

For more information on S3 structure,
visit the [Amazon S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html).


# Salesforce
Source: https://docs.onyx.app/admins/connectors/official/salesforce

Access CRM data from Salesforce

## How it works

The Salesforce connector indexes documents from your Salesforce.
These documents organized around the **Objects** that you indicate. Examples are below.

## Setting up

### Authorization

<Steps>
  <Step title="Log in to Salesforce">
    Log into Salesforce.
    The Salesforce user must be an organization member or have admin access to the data you would like to index.
  </Step>

  <Step title="Open Settings">
    Click the profile avatar and choose Settings.

    <img alt="Salesforce user menu showing path to Settings" />
  </Step>

  <Step title="Reset security token">
    Select **My Personal Information** → **Reset My Security Token**.

    <img alt="Salesforce settings highlighting Reset My Security Token" />
  </Step>

  <Step title="Check email for token">
    Check your email for the security token.

    <img alt="Email example showing Salesforce security token message" />
  </Step>

  <Step title="Use credentials in Onyx">
    Once the token has been regenerated, you can use it (as well as your username and password)
    to authorize your Onyx connector.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Create a new Salesforce Connector">
    Navigate to the Admin Panel and select the **Salesforce** Connector Tile.
  </Step>

  <Step title="Create a new credential">
    Click on the **Create New** button and provide your **Username**,
    **Password** and the **Security Token** received from the above steps.

    Select the new credential and click **Continue**.
  </Step>

  <Step title="Define the Salesforce Object(s) you wish to index">
    <Accordion title="Simple">
      Enter the [Salesforce
      Object(s)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm)
      you wish to index and organize your Onyx documents by.

      * Make sure to use the singular version of object name (e.g. Opportunity instead of
        Opportunities)
      * If no objects are indicated, it will default to indexing by **Account**
      * Each Onyx Document extracted from Salesforce contains all fields and associations of each
        object. For example,
        when indexing each Account we include the fields of the AccountFeed and AccountShare objects as well (but not the
        associations of those objects).
        This can lead to bloated queries and memory intensive indexing in larger salesforce instances.

      <Tip>
        Use the Advanced mode to have finer grain control over what is indexed.
      </Tip>
    </Accordion>

    <Accordion title="Advanced">
      Specify which objects, fields, and associations get indexed with a json object.

      Top level keys are Salesforce Objects, each value is a JSON object specifying:

      * `fields`: a list of strings describing the fields of the object to index
      * `associations`: a JSON object mapping a Salesforce Object associated with the parent object to a list of fields to be indexed for the child object

      ```json Example theme={null}
      {
        "Account": {
          "fields": ["Id", "Name", "Industry", "CreatedDate", "lastModifiedDate"],
          "associations": {
              "Contact": ["Id", "FirstName", "LastName", "Email"],
              "Opportunity": ["Id", "Name", "StageName", "Amount", "CloseDate"]
          }
        },
        "Lead": {
          "fields": ["Id", "FirstName", "LastName", "Company", "Status"],
          "associations": {}
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Click on the **Connect** button.">
    Click on the **Connect** button and your connector will be created.
    Onyx will automatically begin indexing your Salesforce data.
  </Step>
</Steps>

### An Example

You indicate you'd like to organize information by **Account** and click connect

<img alt="Onyx Salesforce connector example configuration using Account object" />

Onyx will generate a document for every single **Account** in your Salesforce.
Attached to each document will be all the information associated with that **Account**.
This information would also include information from the **Account**'s children objects (E.g.
all associated **Contacts**, **Notes**, etc.).
This means indicating **Account** means that all **Contact**s that are attached to an account will also be grabbed

If you want to index any **Contacts** that aren't attached to any **Accounts**, (as well as **Accounts**),
you would indicate that like so:

<img alt="Onyx Salesforce connector advanced JSON configuration for Account and Contact objects" />


# Certificate-Based Authentication
Source: https://docs.onyx.app/admins/connectors/official/sharepoint/certificate

Set up SharePoint connector using certificate-based authentication with optional permission sync support

## Certificate-Based Authentication

Certificate-based authentication provides a secure way to connect to SharePoint and supports both basic integration and
permission sync functionality.

**Use certificate authentication when:**

* You need permission sync capabilities
* You prefer certificate-based security over client secrets
* Your organization requires certificate-based authentication

**For basic SharePoint integration without permission sync**,
you can also use [client secret authentication](/admins/connectors/official/sharepoint/client-secret).

## Setting up

### Step 1: Create Azure App Registration

<Steps>
  <Step title="Open Azure Portal">
    Log in to [Azure Portal](https://portal.azure.com/#home) for your organization.
  </Step>

  <Step title="Open App registrations">
    Navigate to "App registrations" using the search bar.
  </Step>

  <Step title="Create registration">
    Click **New Registration**.
  </Step>

  <Step title="Name and register app">
    Name it something like "Onyx SharePoint Connector - Certificate", leave everything else as default,
    and click **Register**.
  </Step>

  <Step title="Save IDs">
    Under "Essentials" in the overview tab, you will find the **Application (client) ID** and **Directory (tenant) ID**.
    Save those for later.
  </Step>
</Steps>

### Step 2: Generate and Upload Certificate

#### Option A: Generate Self-Signed Certificate

```bash theme={null}
# Generate private key
openssl genrsa -out sharepoint-cert.key 2048

# Generate certificate signing request
openssl req -new -key sharepoint-cert.key -out sharepoint-cert.csr

# Generate self-signed certificate (valid for 1 year)
openssl x509 -req -days 365 -in sharepoint-cert.csr -signkey sharepoint-cert.key -out sharepoint-cert.crt

# Convert to PFX format
openssl pkcs12 -export -out sharepoint-cert.pfx -inkey sharepoint-cert.key -in sharepoint-cert.crt
```

#### Option B: Use Organization Certificate

Obtain a certificate from your organization's Certificate Authority (CA) following your internal security policies.

<Note>
  We only support PFX format for certificate uploads in Azure.
</Note>

### Step 3: Upload Certificate to Azure

<Steps>
  <Step title="Open Certificates & secrets">
    In your Azure App Registration, navigate to the "Certificates & secrets" tab.
  </Step>

  <Step title="Upload certificate">
    Click **Upload certificate**.
  </Step>

  <Step title="Select file">
    Select your certificate file (.crt, .pem, or .cer format).
  </Step>

  <Step title="Add certificate">
    Add a description and click **Add**.
  </Step>
</Steps>

### Step 4: Configure API Permissions

<Steps>
  <Step title="Open API Permissions">
    Navigate to the "API Permissions" tab in the Azure Portal.
  </Step>

  <Step title="Add a permission">
    Click **Add a permission**.
  </Step>
</Steps>

#### Basic Permissions (No Permission Sync)

If you are **not** planning to enable permission sync, you only need basic permissions:

<Steps>
  <Step title="Choose Microsoft Graph">
    Click **Microsoft Graph**, then click on **Application permissions**.
  </Step>

  <Step title="Select Sites.Read.All">
    Navigate to the "Sites" permission group. Select the checkbox for **Sites.Read.All**.

    * *Advanced:* If you want to limit the sites this app has access to, select **Sites.Selected**.
      However, if you do this, you will need to add the App you are currently registering to each site you want to index.

    <Accordion title="How to grant site-specific access">
      If you selected **Sites.Selected**, you need to grant your app **read** access to each site you want to index.

      The steps below use [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer),
      but you can also grant site permissions using:

      * [PnP PowerShell](https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html) (`Grant-PnPAzureADAppSitePermission` cmdlet)
      * [Resource Specific Consent guide](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online)

      To use Graph Explorer, complete these steps:

      <Steps>
        <Step title="Sign in">
          Sign in with a **Global Admin** or **SharePoint Admin** account.
        </Step>

        <Step title="Consent to permissions">
          Click your profile icon → **Consent to permissions** → enable **Sites.FullControl.All**.
          This grants Graph Explorer (not your Onyx app) permission to manage site access.
        </Step>

        <Step title="Get the site ID">
          Run a **GET** request, replacing `{tenant}` and `YourSiteName`:

          ```
          GET https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/YourSiteName?$select=id
          ```

          Copy the `id` from the response (format: `onyx.sharepoint.com,guid1,guid2`).
        </Step>

        <Step title="Grant Read permission">
          Change the method to **POST**:

          ```
          POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
          ```

          Request body:

          ```json theme={null}
          {
            "roles": ["read"],
            "grantedToIdentitiesV2": [{
              "application": {
                "id": "<Onyx App Client ID>",
                "displayName": "Onyx SharePoint Connector"
              }
            }]
          }
          ```
        </Step>

        <Step title="Verify">
          Change the method to **GET**:

          ```
          GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
          ```

          Confirm `"roles": ["read"]` appears for the Onyx app.
        </Step>
      </Steps>

      Repeat steps 3–5 for each site you want to index.
    </Accordion>
  </Step>

  <Step title="Add and grant">
    Click **Add permissions**. Finally, click **Grant admin consent for \<Organization name>** and click **Confirm**.
  </Step>
</Steps>

#### Extended Permissions (With Permission Sync)

If you plan to enable permission sync, you'll need additional permissions:

<Steps>
  <Step title="Add another permission">
    Click **Add a permission** again.
  </Step>

  <Step title="Microsoft Graph application permissions">
    Click **Microsoft Graph**, then click on **Application permissions**.
    Add the following additional Microsoft Graph permissions:

    * **Directory.Read.All** - Used to query the overall organizational directory structure, including how users,
      groups, organizational units, and other directory objects relate to each other.
    * **Group.Read.All** - Used to read detailed group-specific information such as group properties, settings,
      types (Security vs Microsoft 365), and configurations.
    * **GroupMember.Read.All** - Used to retrieve and expand all members within a group,
      including nested group memberships.
      This allows Onyx to determine which users have access to SharePoint content through group membership.
    * **Member.Read.Hidden** - Allows reading memberships of security groups that are marked as "hidden" in Entra ID.
    * **User.Read.All** - Used to retrieve complete user profiles and enumerate all users in the directory.
      Click **Add permissions**.
  </Step>

  <Step title="Microsoft Graph delegated permission">
    Click **Add a permission** again in API Permissions tab. Click **Microsoft Graph**,
    then click on **Delegated permissions**. Add the following delegated permission:

    * **User.Read** - This delegated permission allows the application to sign in on behalf of a user and read the
      signed-in user's basic profile information. Unlike application permissions which work without a user context,
      this delegated permission is required when the app needs to establish an authenticated identity context for making
      API calls to Microsoft Graph and SharePoint. It provides the minimum required access for user authentication flows.
      Click **Add permissions**.
  </Step>

  <Step title="SharePoint application permissions">
    Click **Add a permission** again in API Permissions tab. Click **SharePoint**,
    then click on **Application permissions**. Add the following SharePoint permissions:

    * **Sites.FullControl.All** - Despite the name, Onyx only uses this to retrieve details about permissions.
      No write operations are performed.
      If you selected **Sites.Selected** and need to grant fullcontrol only for specific sites,
      see the **Using Sites.Selected with Permission Sync** section below.
    * **User.Read.All** - Used to list all users within the directory for permission mapping.
      Click **Add permissions**.
  </Step>

  <Step title="Grant admin consent">
    Finally, click **Grant admin consent for \<Organization name>** and click **Confirm**.
  </Step>
</Steps>

<Accordion title="Using Sites.Selected with Permission Sync">
  If you selected **Sites.Selected** instead of **Sites.Read.All** and plan to enable permission sync,
  you need to grant your app **fullcontrol** access to each site.

  The steps below use [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer),
  but you can also grant site permissions using:

  * [PnP PowerShell](https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html) (`Grant-PnPAzureADAppSitePermission` cmdlet)
  * [Resource Specific Consent guide](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online)

  To use Graph Explorer, complete these steps:

  <Steps>
    <Step title="Sign in">
      Sign in with a **Global Admin** or **SharePoint Admin** account.
    </Step>

    <Step title="Consent to permissions">
      Click your profile icon → **Consent to permissions** → enable **Sites.FullControl.All**.
      This grants Graph Explorer (not your Onyx app) permission to manage site access.
    </Step>

    <Step title="Get the site ID">
      Run a **GET** request, replacing `{tenant}` and `YourSiteName`:

      ```
      GET https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/YourSiteName?$select=id
      ```

      Copy the `id` from the response (format: `onyx.sharepoint.com,guid1,guid2`).
    </Step>

    <Step title="Grant FullControl permission">
      Change the method to **POST**:

      ```
      POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
      ```

      Request body:

      ```json theme={null}
      {
        "roles": ["fullcontrol"],
        "grantedToIdentitiesV2": [{
          "application": {
            "id": "<Onyx App Client ID>",
            "displayName": "Onyx SharePoint Connector"
          }
        }]
      }
      ```
    </Step>

    <Step title="Verify">
      Change the method to **GET**:

      ```
      GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
      ```

      Confirm `"roles": ["fullcontrol"]` appears for the Onyx app.
    </Step>
  </Steps>

  Repeat steps 3–5 for each site you want to index.
</Accordion>

### Step 5: Configure in Onyx

<Steps>
  <Step title="Open SharePoint connector">
    Navigate to the Onyx Admin Panel and select the **SharePoint** Connector.
  </Step>

  <Step title="Create Certificate credential">
    Click **Create New** credential and select the **Certificate** tab.
  </Step>

  <Step title="Enter credential details">
    * **Application (client) ID** from Step 1
    * **Directory (tenant) ID** from Step 1
    * **Certificate File**: Upload your certificate file (.pfx file)
    * **Certificate Password**: Enter password which you used to export the certificate file
  </Step>

  <Step title="Save credentials">
    Click **Create** to save your credentials.
  </Step>
</Steps>

### Step 6: Enable Permission Sync (Optional)

When creating your SharePoint connector with certificate authentication:

<Steps>
  <Step title="Locate Permission Sync option">
    In the connector configuration, you'll see a **Permission Sync** option.
  </Step>

  <Step title="Enable Permission Sync">
    Enable this option to synchronize SharePoint permissions with Onyx.
  </Step>
</Steps>

<Note>
  Permission sync is available only on Cloud and the Enterprise Edition of Onyx.
</Note>

## Permission Sync Details

When permission sync is enabled:

* **Document-level permissions**: Onyx will respect SharePoint document permissions
* **Site-level permissions**: Users will only see documents from sites they have access to
* **Group permissions**: SharePoint group memberships are synchronized
* **Real-time sync**: Permissions are updated regularly to reflect SharePoint changes

For basic SharePoint integration without permission sync,
you can use [client secret authentication](/admins/connectors/official/sharepoint/client-secret).


# Client Secret Authentication
Source: https://docs.onyx.app/admins/connectors/official/sharepoint/client-secret

Set up SharePoint connector using client secret authentication

## Client Secret Authentication

Client secret authentication uses traditional Azure App Registration credentials to connect to SharePoint.
This method is suitable for most basic SharePoint integrations.

**Note:** Permission sync is not available with client secret authentication.
Use [certificate-based authentication](/admins/connectors/official/sharepoint/certificate)
if you need permission sync functionality.

## Setting up

### Step 1: Create Azure App Registration

More detailed instructions can be found following the video below.

<Steps>
  <Step title="Open Azure Portal">
    Log in to [Azure Portal](https://portal.azure.com/#home) for your organization.
  </Step>

  <Step title="Open App registrations">
    Navigate to "App registrations" using the search bar.
  </Step>

  <Step title="Create registration">
    Click **New Registration**.
  </Step>

  <Step title="Name and register app">
    Name it something like "Onyx SharePoint Connector", leave everything else as default, and click **Register**.
  </Step>

  <Step title="Save IDs">
    Under "Essentials" in the overview tab, you will find the **Application (client) ID** and **Directory (tenant) ID**.
    Save those for later.
  </Step>
</Steps>

### Step 2: Create Client Secret

<Steps>
  <Step title="Open Certificates & secrets">
    Navigate to the "Certificates & secrets" tab in Azure Portal.
  </Step>

  <Step title="Create secret">
    Click **New client secret**.
  </Step>

  <Step title="Set expiration">
    Fill out the description, set the expiration to 24 months, and click **Add**.
  </Step>

  <Step title="Copy secret value">
    Copy the secret value in the **Value** column for later.
  </Step>
</Steps>

**Important:** Make sure to copy the secret value immediately as it won't be visible again.

### Step 3: Configure API Permissions

Two separate API permissions are required:

| Permission              | Provider        | Type        | Purpose                                       |
| ----------------------- | --------------- | ----------- | --------------------------------------------- |
| `Sites.Read.All`        | Microsoft Graph | Application | Read documents and site pages                 |
| `Sites.FullControl.All` | SharePoint      | Application | Read document role assignments during pruning |

<Note>
  Despite its name, `Sites.FullControl.All` is read-only in Onyx. No write operations are performed.
</Note>

<Steps>
  <Step title="Open API Permissions">
    Navigate to the "API Permissions" tab in the Azure Portal.
  </Step>

  <Step title="Add Microsoft Graph permission">
    Click **Add a permission** → **Microsoft Graph** → **Application permissions**.

    Navigate to the "Sites" permission group and select **Sites.Read.All**.

    * *Advanced:* If you want to limit the sites this app has access to, select **Sites.Selected**.
      However, if you do this, you will need to add the App you are currently registering to each site you want to index.

    <Accordion title="How to grant site-specific access">
      If you selected **Sites.Selected**, you need to grant your app **read** access to each site you want to index.

      The steps below use [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer),
      but you can also grant site permissions using:

      * [PnP PowerShell](https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html) (`Grant-PnPAzureADAppSitePermission` cmdlet)
      * [Resource Specific Consent guide](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online)

      To use Graph Explorer, complete these steps:

      <Steps>
        <Step title="Sign in">
          Sign in with a **Global Admin** or **SharePoint Admin** account.
        </Step>

        <Step title="Consent to permissions">
          Click your profile icon → **Consent to permissions** → enable **Sites.FullControl.All**.
          This grants Graph Explorer (not your Onyx app) permission to manage site access.
        </Step>

        <Step title="Get the site ID">
          Run a **GET** request, replacing `{tenant}` and `YourSiteName`:

          ```
          GET https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/YourSiteName?$select=id
          ```

          Copy the `id` from the response (format: `contoso.sharepoint.com,guid1,guid2`).
        </Step>

        <Step title="Grant Read permission">
          Change the method to **POST**:

          ```
          POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
          ```

          Request body:

          ```json theme={null}
          {
            "roles": ["read"],
            "grantedToIdentitiesV2": [{
              "application": {
                "id": "<Onyx App Client ID>",
                "displayName": "Onyx SharePoint Connector"
              }
            }]
          }
          ```
        </Step>

        <Step title="Verify">
          Change the method to **GET**:

          ```
          GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
          ```

          Confirm `"roles": ["read"]` appears for the Onyx app.
        </Step>
      </Steps>

      Repeat steps 3–5 for each site you want to index.
    </Accordion>

    Click **Add permissions**.
  </Step>

  <Step title="Add SharePoint permission">
    Click **Add a permission** again → **SharePoint** → **Application permissions**.

    Navigate to the "Sites" permission group and select **Sites.FullControl.All**.

    Click **Add permissions**.
  </Step>

  <Step title="Grant admin consent">
    Click **Grant admin consent for \<Organization name>** (located next to **Add a permission**)
    and click **Confirm**.
  </Step>
</Steps>

### Step 4: Configure in Onyx

<Steps>
  <Step title="Open SharePoint connector">
    Navigate to the Onyx Admin Panel and select the **SharePoint** Connector.
  </Step>

  <Step title="Create Client Secret credential">
    Click **Create New** credential and select the **Client Secret** tab.
  </Step>

  <Step title="Enter credential details">
    * **Application (client) ID** from Step 1
    * **Directory (tenant) ID** from Step 1
    * **Client Secret Value** from Step 2
  </Step>

  <Step title="Save credentials">
    Click **Create** to save your credentials.
  </Step>
</Steps>

For permission sync capabilities,
consider using [certificate-based authentication](/admins/connectors/official/sharepoint/certificate).


# Overview
Source: https://docs.onyx.app/admins/connectors/official/sharepoint/sharepoint

Access files and notes from your SharePoint Sites

## How it works

The SharePoint connector will go through all configured sites belonging to an organization and index all the documents
attached to that site. Note, it currently does not parse the site page contents, only the attached files.

This includes:

* Word Doc, Excel, PDF, PowerPoints, and all plaintext files like .txt, .mdx, etc.

## Setting up

### Authorization

We support two authorization methods—pick one that fits your environment:

* [Client Secret Authentication](/admins/connectors/official/sharepoint/client-secret)
  * Uses traditional client
    secret credentials
* [Certificate-Based Authentication](/admins/connectors/official/sharepoint/certificate)
  * Uses certificate-based
    authentication (required for permission sync)

**Note:** Permission sync is only available with certificate-based authentication.

### Indexing

Once you've set up your authorization method, follow these steps to index your SharePoint sites:

<Steps>
  <Step title="Open SharePoint connector">
    Navigate to the Onyx Admin Panel and select the **SharePoint** Connector.
  </Step>

  <Step title="Configure authorization">
    In **Step 1**, configure your authorization:

    * If you have existing credentials, select them from the list
    * If you don't have existing credentials, click **Create New** to add new authorization:
    * **Client Secret**: Enter your Application ID, Directory ID, and Client Secret
    * **Certificate**: Upload your certificate file and enter Application/Directory IDs
  </Step>

  <Step title="Save configuration">
    Click **Create** to save your configuration.
  </Step>

  <Step title="Continue with selected credential">
    Ensure your chosen credential is selected, then click **Continue**
  </Step>

  <Step title="Specify SharePoint configuration">
    In **Step 2**, specify your SharePoint configuration:

    * **Connector Name**: Enter a name for the connector (e.g., "MySharePointConnector")
    * **Sites**: Select a list of sites to pull from or leave blank to pull everything (Note:
      this option only works for English, Spanish, and German Sharepoint instances.
      Contact us if you require further language support)
    * **Permission Sync** (Certificate auth only): Enable to sync SharePoint permissions with Onyx
  </Step>

  <Step title="Create connector">
    Click **Create Connector** to begin indexing.
  </Step>
</Steps>

The connector will start indexing your SharePoint sites and you can add more sites or modify settings as needed.

## Understanding SharePoint Structure

SharePoint organizes content into sites, which can contain document libraries, lists, and pages.
Each site can contain an unlimited number of documents.
The connector focuses on indexing documents stored in document libraries across your selected sites.

For more information on SharePoint structure,
visit the [Microsoft SharePoint documentation](https://docs.microsoft.com/en-us/sharepoint/).


# Slab
Source: https://docs.onyx.app/admins/connectors/official/slab

Access documentation from Slab

## How it works

Slab is a wiki tool where the pages are called Posts. Onyx indexes the post **titles** and **contents**.

The Posts are pulled in and updated every **10** minutes.

## Setting up

### Authorization

<Steps>
  <Step title="Fetch Slab Bot Token">
    Follow the video below to fetch your **Slab Bot Token**.

    <img alt="SlabBotToken" />
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Slab connector">
    Navigate to the Admin Panel and select the **Slab** Connector
  </Step>

  <Step title="Enter Bot Token">
    In **Step 1**, provide the **Slab Bot Token** from above
  </Step>

  <Step title="Enter Slab URL">
    In **Step 2**, provide the Slab URL (e.g., `onyxai.slab.com`)
  </Step>

  <Step title="Start indexing">
    Click `Connect` to begin indexing
  </Step>
</Steps>


# Slack Federated
Source: https://docs.onyx.app/admins/connectors/official/slack/slack_federated

Set up the Slack Federated connector

## Jan 2026 Update

In June 2025, Slack introduced ToS and API changes that restricted customers from indexing their own data.
Onyx introduced the Slack Federated connector that uses the Search APIs as an alternative to the indexing connector.
However, Slack has recently reversed these API restrictions, which allows the indexing connector to work again.

We have found that the Indexed Connector performs signficantly better than the Slack Search APIs at finding relevant
results. We strongly recommend using the [Slack Indexed Connector](/admins/connectors/official/slack/slack_indexed)
if possible.

## Setting up

### Authorization

<Steps>
  <Step title="Prerequisite">
    You must be an admin of the Slack workspace to set up the connector.
  </Step>

  <Step title="Open Slack apps">
    Navigate and sign in to [https://api.slack.com/apps](https://api.slack.com/apps).
  </Step>

  <Step title="Create new app">
    Click the **Create New App** button in the top right. Select **From an app manifest** option.
    Select the relevant workspace from the dropdown and click **Next**.

    <img alt="Slack app creation flow with manifest option selected" />
  </Step>

  <Step title="Paste manifest">
    Select the "YAML" tab, paste the following manifest into the text box, and click **Next**:
  </Step>
</Steps>

```
display_information:
  name: Onyx Search Assistant
  description: Search your Slack data as yourself
  background_color: "#4A154B"

oauth_config:
  redirect_urls:
    - https://<YOUR_ONYX_DOMAIN>/federated/oauth/callback
  scopes:
    user:
      - channels:read
      - groups:read
      - im:read
      - mpim:read
      - search:read
      - channels:history
      - groups:history
      - im:history
      - mpim:history
      - users:read

settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
```

<Info>
  For Onyx Cloud, the `redirect_urls` value should be `https://cloud.onyx.app/federated/oauth/callback`.
</Info>

<Warning>
  We do not currently support token rotation, so `token_rotation_enabled: false` is necessary.
</Warning>

<Steps>
  <Step title="Create app">
    Click the **Create** button.
  </Step>

  <Step title="Open Basic Information">
    In the app page, navigate to the **Basic Information** tab under the **Settings** header.
  </Step>

  <Step title="Copy client credentials">
    Copy the **Client ID** and **Client Secret**. Store those somewhere safe for the next step.
  </Step>
</Steps>

<img alt="Slack Basic Information page with Client ID and Client Secret" />

### Indexing

<Steps>
  <Step title="Open Slack connector">
    Navigate to the Connector Dashboard and select the **Slack** Connector.
  </Step>

  <Step title="Enter client credentials">
    Enter the **Client ID** and **Client Secret** from step 7.
  </Step>

  <Step title="Configure search scope">
    Configure the search scope for the federated connector. The following configuration options are available:

    **Channel Selection:**

    * **Search All Channels**: Enable to search all accessible channels. When enabled, the Channels field is disabled.
    * **Channels**: Specify which channels to search (only used if Search All Channels is disabled). Supports glob patterns (e.g., `general`, `eng*`, `product-*`).
    * **Exclude Channels**: Exclude specific channels from search. Supports glob patterns (e.g., `secure-channel`, `private-*`, `customer*`).

    **Message Types:**

    * **Include Direct Messages**: Include user direct messages (1:1 DMs) in search results.
    * **Include Group Direct Messages**: Include multi-person direct messages (MPIMs) in search results.
    * **Include Private Channels**: Include private channels in search results (user must have access).

    **Search Parameters:**

    * **Default Search Days**: Maximum number of days to search back (default: 30).
      Increasing this value may degrade answer quality.
    * **Max Messages Per Query**: Maximum number of messages to retrieve per search query (default: 25).
      Higher values provide more context but may be slower.

    Once configured, click the **Create/Update** button.

    <img alt="Onyx Slack Federated connector settings showing client credentials" />
  </Step>

  <Step title="Complete OAuth">
    Head back to the main Chat page and go through the OAuth flow!
  </Step>
</Steps>

<Info>
  Every user will need to go through this OAuth flow. The searchable content depends on:

  * The connector configuration settings (channels, DMs, private channels, etc.)
  * The OAuth scopes granted during setup
  * The user's individual access permissions in Slack

  If certain OAuth scopes are missing (e.g., `mpim:read`, `im:history`),
  the connector will gracefully continue searching other available channel types and log warnings about the missing
  scopes.
</Info>

<img alt="Slack OAuth consent screen for Onyx Search Assistant" />


# Slack Indexed
Source: https://docs.onyx.app/admins/connectors/official/slack/slack_indexed

Set up the Slack Indexed connector

## How it works

The Slack connector indexes all public channels for a given workspace.

To index private channels, add the Slack App to the private channel.

For Slack Enterprise Grid orgs, a single install covers every workspace in the org.
See [Enterprise Grid setup](#enterprise-grid-setup) below.

## Setting up

### Authorization

<Steps>
  <Step title="Admin requirement">
    **Note: You must be an admin of the Slack workspace to set up the connector**
  </Step>

  <Step title="Navigate to Slack Apps">
    Navigate and sign in to [https://api.slack.com/apps](https://api.slack.com/apps).
  </Step>

  <Step title="Create new Slack app">
    Create a new Slack app:

    * Click the **Create New App** button in the top right.
    * Select **From an app manifest** option.
    * Select the relevant workspace from the dropdown and click **Next**.

    <img alt="Slack app creation flow with manifest option selected" />
  </Step>

  <Step title="Configure app manifest">
    Select the "YAML" tab, paste the following manifest into the text box, and click **Next**:

    ```
    display_information:
      name: OnyxConnector
      description: ReadOnly Connector for indexing Onyx
    features:
      bot_user:
        display_name: OnyxConnector
        always_online: false
    oauth_config:
      scopes:
        bot:
          - channels:history
          - channels:read
          - groups:history
          - groups:read
          - channels:join
          - im:history
          - users:read
          - users:read.email
          - usergroups:read
    settings:
      org_deploy_enabled: false
      socket_mode_enabled: false
      token_rotation_enabled: false
    ```
  </Step>

  <Step title="Create the app">
    Click the **Create** button.
  </Step>

  <Step title="Navigate to OAuth permissions">
    In the app page, navigate to the **OAuth & Permissions** tab under the **Features** header.
  </Step>

  <Step title="Copy OAuth token">
    Copy the **Bot User OAuth Token**, this will be used to access Slack.
  </Step>
</Steps>

<img alt="Slack OAuth & Permissions page showing Bot User OAuth Token" />

### Indexing

<Steps>
  <Step title="Navigate to connector">
    Navigate to the Connector Dashboard and select the **Slack** Connector.
  </Step>

  <Step title="Provide credentials">
    Place the **Bot User OAuth Token** under **Step 1 Provide Credentials**

    <img alt="Onyx Slack connector settings showing Bot User OAuth Token input" />
  </Step>

  <Step title="Set workspace ID and connect">
    Set the **Workspace ID** (see below) and click **Connect**.
  </Step>
</Steps>

<img alt="Locating the Slack workspace ID in the app configuration" />

**Note:** The first indexing pulls all of the public channels and takes longer than future updates.

## Enterprise Grid setup

If your Slack instance is an [Enterprise Grid](https://slack.com/help/articles/360000281563)
org with multiple workspaces,
you go through the app-creation flow once at the org level and use a single org-level bot token in Onyx.
Slack still requires the org admin to choose which workspaces the bot is deployed to (it is not auto-deployed to every
workspace just because the app is approved at the org level).
Onyx detects Grid automatically from the bot token and indexes every workspace the bot has been deployed to.

<Note>
  You must be an **Org Owner** or **Org Admin** of the Slack Enterprise Grid org to do the org-level install.
</Note>

### What changes vs the single-workspace setup

* The app manifest must enable org-level deploys and include the `team:read` scope.
* You install the app to the **organization** once (a single OAuth approval as Org Admin), but you must also pick
  which workspaces in the org the bot is deployed to — Onyx can only index the workspaces the bot is actually a member
  of.
* Channel links in indexed documents resolve to the correct per-workspace URL.
* Document permissions for public channels are scoped to the users in the workspaces the channel is shared into
  (not the entire org), so a user in Workspace A cannot see Workspace B's public channel documents in Onyx.

### Authorization (Grid)

<Steps>
  <Step title="Create a new Slack app">
    On [https://api.slack.com/apps](https://api.slack.com/apps), click **Create New App** → **From an app manifest**.
    Select **any** workspace inside your Grid org as the development workspace (the manifest below promotes the app to
    org-level on install).
  </Step>

  <Step title="Use the Grid manifest">
    Paste the following manifest. The two differences from the single-workspace manifest are `org_deploy_enabled:
            true` and the added `team:read` bot scope:

    ```yaml theme={null}
    display_information:
      name: OnyxConnector
      description: ReadOnly Connector for indexing Onyx
    features:
      bot_user:
        display_name: OnyxConnector
        always_online: false
    oauth_config:
      scopes:
        bot:
          - channels:history
          - channels:read
          - groups:history
          - groups:read
          - channels:join
          - im:history
          - users:read
          - users:read.email
          - usergroups:read
          - team:read
    settings:
      org_deploy_enabled: true
      socket_mode_enabled: false
      token_rotation_enabled: false
    ```
  </Step>

  <Step title="Install to the organization">
    Open **OAuth & Permissions** and click **Install to Organization** (not "Install to Workspace").
    Approve the request as an Org Admin.
    This is a single OAuth approval — it does **not** deploy the bot to any workspace yet.
  </Step>

  <Step title="Deploy the bot to each workspace you want indexed">
    Slack does not auto-deploy org-approved apps to every workspace.
    Open the Grid org admin panel (`https://<your-org>.enterprise.slack.com/admin`) → **Apps** → **Onyx Connector**,
    and select the workspaces the bot should be deployed to.
    Without this step `auth.teams.list` returns zero workspaces and Onyx will only see the workspace the app was
    developed in.
  </Step>

  <Step title="Copy the org-level bot token">
    Back on the app's **OAuth & Permissions** page, copy the **Bot User OAuth Token**.
    The token starts with `xoxb-` just like a regular bot token but carries org-level permissions.
  </Step>
</Steps>

### Indexing (Grid)

The connector setup in Onyx is identical to the single-workspace flow — paste the bot token and click **Connect**.
Onyx inspects `auth.test()` on the token; if `enterprise_id` is present it switches to Grid mode automatically:

* Enumerates workspaces via `auth.teams.list`
* Lists channels per workspace via `conversations.list?team_id=...` and dedupes org-shared channels
* Resolves the per-workspace URL via `team.info` for channel link building
* Builds per-workspace user-email sets for public-channel permission scoping

### Permission scoping behavior

| Channel type                                      | ACL on Onyx                                                  |
| ------------------------------------------------- | ------------------------------------------------------------ |
| Public channel in one workspace                   | Granted to users of that workspace                           |
| Org-shared public channel (`is_org_shared: true`) | Granted to the union of users across all `shared_team_ids`   |
| Private channel                                   | Granted to the channel's actual members (workspace-agnostic) |
| Union exceeds 5000 users or all teams unknown     | Falls back to `is_public=true` so the doc stays searchable   |

### Troubleshooting (Grid)

<AccordionGroup>
  <Accordion title="Validation error: missing `team:read` scope">
    The Grid path requires `team:read` to enumerate workspaces. Add the scope to the manifest,
    reinstall the app to the organization, and copy the new bot token into Onyx.
  </Accordion>

  <Accordion title="Onyx only indexes channels from one workspace">
    `auth.teams.list` only returns workspaces the bot has been added to.
    Open the Grid org admin panel → **Apps** → **Onyx Connector** and add it to every workspace you want indexed,
    then trigger a new index attempt.
  </Accordion>

  <Accordion title="A user from another workspace can search a workspace's public-channel content">
    Only happens when the per-workspace user union exceeds `5000`.
    Above that limit Onyx falls back to marking the doc public so it stays accessible;
    the same fallback applies when none of the channel's workspaces are in Onyx's cache (for example a workspace added
    to the Grid org after the connector was set up). Re-saving the credential re-builds the workspace cache.
  </Accordion>
</AccordionGroup>


# Microsoft Teams
Source: https://docs.onyx.app/admins/connectors/official/teams

Access messages and files from Microsoft Teams

## How it works

The Teams connector will go through all requested sites belonging to an organization and index all the files available
to that site.

## Setting up

### Authorization

<Steps>
  <Step title="Open Azure Portal">
    Log in to azure portal for your organization: [https://portal.azure.com/#home](https://portal.azure.com/#home)
  </Step>

  <Step title="Create app registration">
    Navigate to “app registrations” using the search bar. Click **New Registration**.
    Name it something like “Onyx Teams Connector”, leave everything else as default, and click **Register**.
  </Step>

  <Step title="Copy IDs">
    Under “Essentials” in the overview tab, copy the client ID and Directory ID and paste into the Onyx connector later.
  </Step>

  <Step title="Create client secret">
    Navigate to the “Certificates & secrets” tab in Azure Portal and click **New client secret**.
    Fill out the description, set the expiration to 24 months, and click **Add**.
    Copy the secret value in the **Value** column.
  </Step>

  <Step title="Add API permissions">
    Navigate to the "API Permissions" tab and click **Add a permission**.
    Click **Microsoft Graph** > **Application permissions**. Add:

    * **Team.ReadBasic.All** (Team)
    * **TeamSettings.ReadWrite.All** (TeamsSettings)
    * **Channel.ReadBasic.All** (Channel)
    * **ChannelSettings.ReadWrite.All** (ChannelSettings)
    * **ChannelMessage.Read.All** (ChannelMessage)
    * **ChannelMember.Read.All** (ChannelMember)
      Click **Add permissions**, then click **Grant admin consent for \<Organization name>** and **Confirm**.
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Teams connector">
    Navigate to the Admin Panel and select the **Teams** Connector Tile.
  </Step>

  <Step title="Enter credentials">
    Provide the **Application (client) ID**, **Directory (tenant) ID** and **Client Secret Value** from steps above.
  </Step>

  <Step title="Select teams and connect">
    Select a list of teams to pull from or leave blank and click **Connect** to pull everything.
  </Step>
</Steps>


# Web
Source: https://docs.onyx.app/admins/connectors/official/web

Index public or internal web pages

## How it works

The Web Connector scrapes sites based on a base URL.

* It only indexes files from the same domain and containing the same base path.
* It will index pages reachable via hyperlinks from the base URL.
* The text contents are cleaned up via some heuristics and some metadata such as the page Title
  is extracted.

## Setting up

### Authorization

* As long as the page is reachable, no additional authorization is necessary.

### Indexing

<Steps>
  <Step title="Open Web connector">
    Navigate to the Admin Panel and select the **Web** Connector.
  </Step>

  <Step title="Enter base URL and index">
    Input the base URL to index and click on Index.

    <img alt="Onyx Web connector form to enter base URL for indexing" />
  </Step>
</Steps>

To see the status of the indexing, visit the Connectors Status page (top left).

<img alt="Onyx Connectors Status page showing web crawl progress" />


# XenForo
Source: https://docs.onyx.app/admins/connectors/official/xenforo

Access forum posts from XenForo

## How it works

The Xenforo Connector scrapes forums or threads from the specified URL.
It currently does not support incremental updates ... this is planned for a future release.

## Setting up

### Authorization

* As long as the page is reachable, no additional authorization is necessary.

### Indexing

<Steps>
  <Step title="Open Xenforo connector">
    Navigate to the Admin Panel and select the **Xenforo** Connector.
  </Step>

  <Step title="Enter base URL and create">
    Input the base URL to index (either a forum or thread URL) and click "Create Connector".
  </Step>
</Steps>


# Zendesk
Source: https://docs.onyx.app/admins/connectors/official/zendesk

Access tickets and conversations from Zendesk

## How it works

The Zendesk Connector can sync content from your Zendesk instance, supporting two content types:

* **Articles**: Syncs all published Articles from your company's Help Center
* **Tickets**: Syncs Support Tickets with their comments and metadata

The connector supports incremental updates and maintains author information, content tags, and other metadata.

## Content Types

### Articles

* Syncs all published articles from Zendesk Help Center
* Includes article content, labels, and content tags
* Tracks author information and update timestamps
* Skips draft articles and articles with specific skip labels (configurable)

### Tickets

* Syncs support tickets with full comment threads
* Includes ticket metadata (status, priority, tags, type)
* Tracks submitter and commenter information
* Excludes deleted tickets
* **Note**: Requires active Zendesk Support Product

## Current Limitations

* Articles: Does not allow filtering by specific categories or sections
* Tickets: Requires Zendesk Support Product to be active

## Setting up

### Authorization

The Zendesk Connector requires 3 things to connect:

* **Subdomain**: Your Zendesk subdomain (e.g., `your-company` from `your-company.zendesk.com`)
* **Email**: Email address of the API token owner
* **API Token**: Zendesk API token for authentication

See below for instructions on getting the API token:

<img alt="Zendesk settings page showing how to generate an API token" />

### Indexing

<Steps>
  <Step title="Add Zendesk connector">
    Navigate to the **Admin Panel** and select `Add Connector` followed by the Zendesk tile
  </Step>

  <Step title="Choose content type">
    Choose your content type (Articles or Tickets)
  </Step>

  <Step title="Provide authentication">
    Provide the authentication information from the section above
  </Step>

  <Step title="Start syncing">
    Click connect to start syncing content from Zendesk
  </Step>
</Steps>

The connector will perform incremental syncs to keep content up to date,
using cursor-based pagination for articles and timestamp-based retrieval for tickets.

## Metadata

The connector extracts and indexes the following metadata:

### Articles

* Labels (article labels)
* Content tags
* Author information
* Update timestamps

### Tickets

* Status (open, pending, solved, etc.)
* Priority level
* Tags
* Ticket type
* Submitter information
* Comment history with authors and timestamps


# Zulip
Source: https://docs.onyx.app/admins/connectors/official/zulip

Access messages from Zulip streams

## How it works

The Zulip connector pulls in all streams and topics according to the permissions assigned to the bot user.

## Setting up

### Authorization

<Steps>
  <Step title="Understand Zulip bot auth">
    Onyx interfaces with Zulip as a Zulip Bot which is authenticated using the `zuliprc` config format.
    For more context directly from Zulip, refer to the following docs:

    * [https://zulip.com/api/running-bots](https://zulip.com/api/running-bots)
    * [https://zulip.com/api/configuring-python-bindings](https://zulip.com/api/configuring-python-bindings)
  </Step>

  <Step title="Create a Zulip Bot">
    Start by creating a Zulip Bot.

    <img alt="Creating a bot user in Zulip settings" />
  </Step>

  <Step title="Copy zuliprc contents">
    Copy the Bot authentication info (`zuliprc` contents), see red arrow below:

    <img alt="Zulip bot page highlighting the zuliprc configuration download" />

    Keep this copied text to provide to Onyx in the next step
  </Step>
</Steps>

### Indexing

<Steps>
  <Step title="Open Zulip connector">
    Navigate to the Admin Panel and select the **Zulip** Connector
  </Step>

  <Step title="Paste zuliprc">
    In **Step 1**, paste in the copied `zuliprc` value
  </Step>

  <Step title="Get Realm/URL">
    Grab your Zulip Realm/URL info, see below:

    <img alt="Zulip UI showing Realm and URL details" />
  </Step>

  <Step title="Enter Realm and URL">
    In **Step 2**, provide the values for the Realm and URL

    <img alt="Onyx Zulip connector configuration with realm, URL, and zuliprc" />
  </Step>
</Steps>


# Overview
Source: https://docs.onyx.app/admins/connectors/overview

Managing connectors and data sources in Onyx

Onyx's Connectors create a bridge between your organization's data sources and generative AI features in Onyx.
Nearly all connectors are persistent and regularly sync changes from your source.

<Note>
  Both the data that is retrieved from the source and the data that your users can access through Onyx can be customized
  to your needs!
</Note>

To find specific instructions for each Connector, see the [Supported Connectors](#supported-connectors) section.

<img alt="Onyx Add Connector page" />

## Adding a Connector

To add a new connector, navigate to the **Admin Panel** and click **Add Connector** in the sidebar.
This page shows all officially supported connectors.

<Info>
  You can see unofficial, community-supported connectors by setting `SHOW_EXTRA_CONNECTORS=true` in your environment.
</Info>

Click on any of the tiles to begin creating a new Connector.

### Credentials

Most Connectors require some form of authentication for Onyx to access your source.
This authentication is called a Credential and differs by Connector.

<img alt="Onyx Connector Credentials page" />

### Configuration

Each connector must be given a Name. Additionally,
each Connector has its own configuration options to specify the data that should be indexed.

<img alt="Onyx Connector Configuration page" />

### Document Access Controls

Connectors can be configured to be **Private**, **Public**, or **Auto Sync Permissions**.

**Private**: Only the user who created the Connector may see data from this Connector in Onyx.
You may also assign specific Users and User Groups access to this Connector's data.

**Public**: All Onyx users may see data from this Connector.

<Warning>
  If you configure the Connector to access private data in the source, all Onyx users will be able to see this data.
</Warning>

#### Permission-Syncing Connectors

If you set your Connector's access type to **Auto Sync Permissions**,
Onyx will maintain an access control list from the source and restrict users to only see data they have access to.

Permission-syncing is only available for the following Connectors:

* Confluence
* Jira
* Google Drive (must use service account or Google Workspace Admin OAuth credentials)
* Gmail (must use service account or Google Workspace Admin OAuth credentials)
* Slack (see Federated Slack documentation)
* Salesforce
* GitHub
* Box
* SharePoint (must use certificate-based authentication)

<Note>
  Permission-syncing connectors are an Enterprise Edition feature.
</Note>

### Advanced Configuration

Clicking **Advanced Configuration** on the bottom left of the Connector configuration page will reveal additional,
optional settings for indexing.

**Prune Frequency**: The frequency at which old data (that no longer exists in the source) should be removed from Onyx.
This is set to 30 days by default.

**Refresh Frequency**: The frequency at which new data should be retrieved from the source.
This is set to 30 minutes by default.

**Indexing Start Date**:
The date and time from which data should be indexed (data created or updated before this date will not be indexed).
This is set to the earliest possible date in the source by default.

<img alt="Onyx Connector Advanced Configuration page" />

## Managing Existing Connectors

To see your existing Connectors, navigate to the **Admin Panel** and click **Existing Connectors** in the sidebar.
This page will show an overview of your Connectors, their status, and the amount of data they have indexed.

<img alt="Onyx Existing Connectors page showing connector statuses" />

### Connector Status

The status of a Connector can be:

#### Active

| Status                          | Description                                                                                                                 |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Indexed**                     | The Connector is fully functional and all data is synced as of the last indexing attempt.                                   |
| **Scheduled**                   | Newly created Connectors or Connectors that have reached their refresh frequency but have not begun a new indexing attempt. |
| **Indexing / Initial Indexing** | The Connector is currently retrieving data from the source.                                                                 |

#### Inactive or Semi-Active

| Status     | Description                                                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Paused** | The Connector has been paused and will not retrieve new data until un-paused. Users can still access the indexed data.                                                                                       |
| **Error**  | The Connector has encountered an error during indexing. Any data indexed prior to the error will remain available. Onyx will attempt to index again. If too many errors occur, the Connector will be paused. |

<Note>
  Most Error statuses are temporary and will resolve themselves naturally within a few hours.
  If you see an Error status that persists, please reach out.
</Note>

### Connector Details

Clicking on an existing Connector will show you details about its configuration, status, and indexing attempts.

In the **Manage** menu, you can pause, resume, delete, or initiate a complete re-indexing of the Connector.

Under the **Advanced** section, you can see the prune and refresh settings, as well as the history of indexing attempts.

<img alt="Onyx Connector details page showing connector details" />

<img alt="Onyx Connector details page showing indexing attempts and failures" />

### Indexing Failures

Rarely, you will see a **Completed with errors** indexing attempt. If this happens,
you can click the **Resolve all errors** button to kickoff a complete re-indexing of the Connector.

## Supported Connectors

<Warning>
  Can't find the connector you're looking for?
  Let us know via [GitHub Discussions](https://github.com/onyx-dot-app/onyx/discussions)!
</Warning>

### Knowledge Base & Wikis

<Columns>
  <Card title="Confluence" icon="confluence" href="/admins/connectors/official/confluence" />

  <Card title="SharePoint" icon="microsoft" href="/admins/connectors/official/sharepoint" />

  <Card title="Notion" icon="notion" href="/admins/connectors/official/notion" />

  <Card title="BookStack" icon="book" href="/admins/connectors/official/bookstack" />

  <Card title="Document360" icon="file-text" href="/admins/connectors/official/document360" />

  <Card title="Discourse" icon="comments" href="/admins/connectors/official/discourse" />

  <Card title="GitBook" icon="book-open" href="/admins/connectors/official/gitbook" />

  <Card title="Slab" icon="book" href="/admins/connectors/official/slab" />

  <Card title="Outline" icon="book" href="/admins/connectors/official/outline" />

  <Card title="Google Sites" icon="google" href="/admins/connectors/official/google_sites" />

  <Card title="Guru" icon="lightbulb" href="/admins/connectors/official/guru" />
</Columns>

### Cloud Storage

<Columns>
  <Card title="Google Drive" icon="google-drive" href="/admins/connectors/official/google_drive/overview" />

  <Card title="Dropbox" icon="dropbox" href="/admins/connectors/official/dropbox" />

  <Card title="Box" icon="box" href="/admins/connectors/official/box" />

  <Card title="AWS S3" icon="aws" href="/admins/connectors/official/s3/overview" />

  <Card title="Google Storage" icon="google" href="/admins/connectors/official/google_storage" />

  <Card title="Egnyte" icon="cloud" href="/admins/connectors/official/egnyte" />

  <Card title="Oracle Storage" icon="cloud" href="/admins/connectors/official/oci_storage" />

  <Card title="Cloudflare R2" icon="cloud" href="/admins/connectors/official/r2" />
</Columns>

### Ticketing & Task Management

<Columns>
  <Card title="Jira" icon="jira" href="/admins/connectors/official/jira" />

  <Card title="Zendesk" icon="headset" href="/admins/connectors/official/zendesk" />

  <Card title="Airtable" icon="table" href="/admins/connectors/official/airtable" />

  <Card title="Linear" icon="linear" href="/admins/connectors/official/linear" />

  <Card title="Freshdesk" icon="headset" href="/admins/connectors/official/freshdesk" />

  <Card title="Asana" icon="check" href="/admins/connectors/official/asana" />

  <Card title="ClickUp" icon="mouse-pointer" href="/admins/connectors/official/clickup" />

  <Card title="ProductBoard" icon="trello" href="/admins/connectors/official/productboard" />
</Columns>

### Messaging

<Columns>
  <Card title="Slack" icon="slack" href="/admins/connectors/official/slack/slack_indexed" />

  <Card title="Microsoft Teams" icon="microsoft" href="/admins/connectors/official/teams" />

  <Card title="Gmail" icon="envelope" href="/admins/connectors/official/gmail/overview" />

  <Card title="Discord" icon="discord" href="/admins/connectors/official/discord" />

  <Card title="XenForo" icon="comments" href="/admins/connectors/official/xenforo" />

  <Card title="Zulip" icon="zulip" href="/admins/connectors/official/zulip" />
</Columns>

### Sales

<Columns>
  <Card title="Salesforce" icon="salesforce" href="/admins/connectors/official/salesforce" />

  <Card title="HubSpot" icon="hubspot" href="/admins/connectors/official/hubspot" />

  <Card title="Gong" icon="phone" href="/admins/connectors/official/gong" />

  <Card title="Fireflies" icon="microphone" href="/admins/connectors/official/fireflies" />

  <Card title="Highspot" icon="chart-line" href="/admins/connectors/official/highspot" />
</Columns>

### Code Repository

<Columns>
  <Card title="GitHub" icon="github" href="/admins/connectors/official/github" />

  <Card title="GitLab" icon="gitlab" href="/admins/connectors/official/gitlab" />

  <Card title="Bitbucket" icon="bitbucket" href="/admins/connectors/official/bitbucket" />
</Columns>

### Other

<Columns>
  <Card title="Web Scraper" icon="globe" href="/admins/connectors/official/web" />

  <Card title="File Upload" icon="upload" href="/admins/connectors/official/file" />
</Columns>


# Enterprise Edition
Source: https://docs.onyx.app/admins/getting_started/enterprise_edition

Enterprise Edition administration features

Onyx Enterprise Edition unlocks additional features centered on security, user management, and site customization.
Enterprise Edition is designed for larger organizations and teams.

<Tip>
  Onyx Cloud has all Enterprise Edition features!
</Tip>

## Enterprise Edition Features

<CardGroup>
  <Card title="OIDC/SAML" icon="sitemap" href="/deployment/authentication/oidc">
    SSO authentication with OpenID Connect and SAML 2.0 providers
  </Card>

  <Card title="Permission Sync Connectors" icon="sitemap" href="/admins/connectors/overview#permission-syncing-connectors">
    Automatically inherit user permissions from external systems
  </Card>

  <Card title="Whitelabeling" icon="brush" href="/admins/advanced_configs/white_labeling">
    Customize branding, logos, and styling to match your organization
  </Card>

  <Card title="User Groups & RBACs" icon="users" href="/admins/user_management/users_and_groups">
    Organize users and maintain fine-grained RBACs
  </Card>

  <Card title="Group-Based Permissions" icon="users" href="/admins/permissions/understanding_permissions">
    Fine-grained, group-based access control for Connectors, Document Sets, and Agents. Available in v4.7+.
  </Card>

  <Card title="Usage Analytics" icon="chart-line" href="/admins/analytics/overview">
    Detailed insights into user queries and system usage
  </Card>

  <Card title="Encrypted Secrets" icon="key" href="/deployment/configuration/configuration">
    Enterprise-grade encryption for all sensitive credentials and API keys
  </Card>

  <Card title="Enterprise Edition APIs" icon="computer" href="/developers/overview">
    Extended API access for Enterprise Edition features
  </Card>

  <Card title="Priority Support" icon="headphones" href="/deployment/miscellaneous/contact_us">
    Dedicated support with guaranteed response times and white-glove deployment assistance
  </Card>

  <Card title="Hook Extensions" icon="webhook" href="/admins/advanced_configs/hook_extensions">
    Inject custom logic into Onyx's pipeline at defined stages without modifying source code
  </Card>

  <Card title="And More..." icon="ellipsis" href="/deployment/miscellaneous/contact_us">
    Contact us to learn more about Enterprise Edition features!
  </Card>
</CardGroup>

## Who needs Enterprise Edition?

Enterprise Edition is best suited for:

* Organizations with more than 100 users
* Environments requiring SSO integration
* Companies with strict security and compliance requirements
* Teams requiring centralized user management and analytics
* Deployments needing permission inheritance from external systems

## Interested in Enterprise Edition?

If you're unsure whether Enterprise Edition is right for your organization,
we're happy to help you choose the right approach.

If you'd like to try Enterprise Edition, try [Onyx Cloud](https://cloud.onyx.app) for free!

<Note>
  There are no limitations to the features or usage of the Cloud trial.
</Note>

Alternatively, contact us at [hello@onyx.app](mailto:hello@onyx.app) for a free self-hosted trial.


# Slack Bot
Source: https://docs.onyx.app/admins/getting_started/slack_bot_setup

How to set up a Slack bot connected to Onyx

## Overview

Onyx can connect to your Slack workspace and answer questions like an expert teammate.

You can configure OnyxBot to respond to certain types of messages, in specific channels,
and with selected data from your index.

<img alt="Onyx Slack Bot" />

## Setup

<Note>
  You must be an admin of the Slack workspace to set up the Slack bot.
</Note>

<Steps>
  <Step title="Create a new Slack App">
    Navigate to the [Slack App Dashboard](https://api.slack.com/apps)
    and click **Create New App** → **From a manifest**.

    Select the workspace you want to connect to Onyx.
  </Step>

  <Step title="Use the YAML manifest">
    Click the **YAML** tab and paste the following manifest into the box:

    ```yaml YAML Manifest expandable theme={null}
    display_information:
      name: OnyxBot
      description: I help answer questions in Slack!
    features:
      app_home:
        home_tab_enabled: false
        messages_tab_enabled: true
        messages_tab_read_only_enabled: false
      bot_user:
        display_name: OnyxBot
        always_online: true
      slash_commands:
        - command: /onyx
          description: Get back a private answer!
          usage_hint: Put your question here!
          should_escape: false
    oauth_config:
      scopes:
        bot:
          - app_mentions:read
          - channels:history
          - channels:join
          - channels:read
          - chat:write
          - commands
          - groups:history
          - groups:read
          - im:history
          - im:read
          - mpim:history
          - reactions:write
          - reactions:read
          - usergroups:read
          - users:read.email
          - users:read
        user:
          - channels:history
          - channels:read
          - groups:read
          - im:read
          - mpim:history
          - mpim:read
          - search:read
    settings:
      event_subscriptions:
        bot_events:
          - app_mention
          - message.channels
          - message.groups
          - message.im
          - message.mpim
      interactivity:
        is_enabled: true
      org_deploy_enabled: false
      socket_mode_enabled: true
      token_rotation_enabled: false
    ```

    Click **Create** and you will be taken to the app page.
  </Step>

  <Step title="Generate an App Token">
    Scroll down to the **App-Level Tokens** section and click **Generate Token and Scopes**.

    Give your token a name, add the `connections:write` scope to the app-level token and click **Generate**.
    Save this token for later.

    <Tip>
      You can customize your Slack bot's name, description, and icon in the **Display Information** section.
    </Tip>

    <img alt="Onyx Slack Bot App Token" />
  </Step>

  <Step title="Install the Slack App">
    Navigate to the **OAuth & Permissions** tab, click **Install to Workspace**,
    and follow the instructions to install the app.

    Copy the **Bot User OAuth Token** and **User OAuth Token** (Recommended) and save it for later.

    <Note>
      Onyx does not currently support token rotation.
    </Note>

    <img alt="Onyx Slack Bot Bot Token" />
  </Step>

  <Step title="Setup Onyx for the Slack Bot">
    Navigate to the Onyx Admin Panel and select the **Slack Bots** tab.

    Enter the **Bot Token**, **App Token**, and **User Token** (Recommended) and click **Create!**

    <img alt="Onyx Slack Bot Onyx Setup" />
  </Step>

  <Step title="Configure the Slack Bot's Behavior">
    Once your Slack bot is created, you can configure it's universal behavior through the **Default Configuration**.

    You can also set channel-specific behavior using **Channel Configurations**.

    <img alt="Onyx Slack Bot Configuration" />
  </Step>
</Steps>

### How to use the Onyx Slack Bot

There are a few ways to chat with the Onyx Slack bot:

<Tip>
  Your admin may enable any or all of these methods in your Slack workspace. Additionally,
  the configurations may change based on the channel you are in.
</Tip>

<AccordionGroup>
  <Accordion title="Tag the bot with your question">
    ```
    @onyxbot What is the best practice for handling 429 errors in connectors?
    ```

    OnyxBot will respond in a thread to your message.
  </Accordion>

  <Accordion title="Use a slash command">
    ```
    /onyx How many PTO days do I get per year? Do they roll over?
    ```

    OnyxBot will send an ephemeral message. This means only you will see the response.
  </Accordion>

  <Accordion title="Send a message in a channel with the bot added">
    ```
    What were the takeaways from Katie's meeting with our big prospect last week?
    ```

    OnyxBot may be configured to answer any question in Slack even if you didn't tag it. In this case,
    it will respond in a thread to your message.
  </Accordion>

  <Accordion title="Direct message the bot">
    ```
    Look for conversations about this stack trace...
    ```

    You can direct message the OnyxBot app to ask private questions.
  </Accordion>
</AccordionGroup>

OnyxBot may also be configured with none, some, or all of your indexed data.
Ask your admin what is available through your OnyxBot.

## Advanced Configuration

There are a set of advanced configuration options available via environment variables that control your Slack bot's
behavior.

You can find the full list of configuration options [in the Onyx
GitHub](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/onyxbot_configs.py).

<Warning>
  These configuration options are rarely needed and should be used with caution.
</Warning>

<AccordionGroup>
  <Accordion title="ONYX_BOT_NUM_RETRIES">
    Number of retry attempts for generating an answer before failing.

    Default: `5 (int)`
  </Accordion>

  <Accordion title="ONYX_BOT_NUM_DOCS_TO_DISPLAY">
    Number of documents shown under "Reference Documents".

    Default: `5 (int)`
  </Accordion>

  <Accordion title="ONYX_BOT_DISABLE_DOCS_ONLY_ANSWER">
    Disable responses that only show "Reference Documents" when the LLM cannot answer.

    Default: `false (bool)`
  </Accordion>

  <Accordion title="ONYX_BOT_REACT_EMOJI">
    Emoji reaction shown while Onyx considers a message.

    Default: `eyes (str)`
  </Accordion>

  <Accordion title="ONYX_BOT_FOLLOWUP_EMOJI">
    Emoji used to suggest that the user may need more help.

    Default: `sos (str)`
  </Accordion>

  <Accordion title="ONYX_BOT_FEEDBACK_VISIBILITY">
    Visibility for AI answer feedback submitted to OnyxBot. Options: `private` (only the clicking user),
    `anonymous` (public but anonymous), `public` (public with username).

    Default: `private (str)`
  </Accordion>

  <Accordion title="NOTIFY_SLACKBOT_NO_ANSWER">
    If enabled, OnyxBot sends a brief apology message when it cannot find an answer, so users aren't left wondering.

    Default: `false (bool)`
  </Accordion>

  <Accordion title="ONYX_BOT_DISPLAY_ERROR_MSGS">
    Show brief error explanations when something goes wrong answering a question (useful for debugging).

    Default: `false (bool)`
  </Accordion>

  <Accordion title="ONYX_BOT_RESPOND_EVERY_CHANNEL">
    Respond in all channels by default, instead of only those configured in the UI.

    Default: `false (bool)`
  </Accordion>

  <Accordion title="ONYX_BOT_MAX_QPM">
    Maximum questions per minute the bot can answer. Set to `0` or leave unset for uncapped.

    Default: `uncapped (int)`
  </Accordion>

  <Accordion title="ONYX_BOT_MAX_WAIT_TIME">
    Maximum time in seconds a question will wait in the queue before timing out.

    Default: `180 (seconds; 3 minutes)`
  </Accordion>

  <Accordion title="ONYX_BOT_FEEDBACK_REMINDER">
    Minutes after which a reminder DM is sent to request feedback on an answer. Set to `0` to disable.

    Default: `0 (disabled; 0 minutes)`
  </Accordion>

  <Accordion title="ONYX_BOT_REPHRASE_MESSAGE">
    Rephrase Slack user messages before sending to the LLM (may improve clarity for the model).

    Default: `false (bool)`
  </Accordion>

  <Accordion title="ONYX_BOT_RESPONSE_LIMIT_PER_TIME_PERIOD">
    Number of responses OnyxBot can send within a time window. Set to `0` to disable the limit.

    Default: `5000 (int)`
  </Accordion>

  <Accordion title="ONYX_BOT_RESPONSE_LIMIT_TIME_PERIOD_SECONDS">
    Length of the response limit window in seconds.

    Default: `86400 (seconds; 24 hours)`
  </Accordion>
</AccordionGroup>


# Chat UI
Source: https://docs.onyx.app/admins/managing_features/chat

Managing the Chat UI experience across your organization

**Chat Preferences** page in the Admin Panel defines default chat contexts, settings,
and capabilities for your organization.
These defaults apply to all users unless they have customized overrides in their own settings.

<img alt="Chat Preferences in the Admin Panel" />

## Feature Controls

You can enable or disable core chat behaviors for your organization:

* **Search Mode**: UI mode for quick document search across your organization.
* **Multi-Model Generation**: When enabled, multiple models can generate responses in parallel in chat.
* **Deep Research**: Agentic research across the web and connected sources.
  This uses significantly more tokens per query than typical chat.
* **Chat Auto-Scroll**: When enabled,
  the chat view automatically scrolls to new content as the model generates responses.
  Users can override this in their personal settings.

<img alt="Chat Preferences feature switches for Search Mode, Multi-Model Generation, Deep Research, and Chat Auto-Scroll" />

## Team Information

* **Team Name**: This is added to all chat sessions as extra context to tailor responses (e.g.
  your team or company name).
* **Team Context**: Use this for a short description of your team or company.
  It is included as additional context alongside the team name.

<Info>
  Users can also add **individual context** in personal settings on top of these organization-level fields.
</Info>

<img alt="Team Name and Team Context fields on Chat Preferences" />

## System Prompt

This is the base instruction set for chats, [agents](/admins/agents/overview), and projects.
You can edit the prompt in the editor or use reset to restore the default.

<Warning>
  Changing this prompt can significantly affect answer quality and behavior across your workspace.
  Review changes carefully before saving.
</Warning>

The full default system prompt:

```text theme={null}
You are an expert assistant who is truthful, nuanced, insightful, and efficient. Your goal is to deeply understand the user's intent, think step-by-step through complex problems, provide clear and accurate answers, and proactively anticipate helpful follow-up information. Whenever there is any ambiguity around the user's query (or more information would be helpful), you use available tools (if any) to get more context.

The current date is {{CURRENT_DATETIME}}.{{CITATION_GUIDANCE}}

# Response Style
You use different text styles, bolding, emojis (sparingly), block quotes, and other formatting to make your responses more readable and engaging.
You use proper Markdown and LaTeX to format your responses for math, scientific, and chemical formulas, symbols, etc.: '$$\n[expression]\n$$' for standalone cases and '\( [expression] \)' when inline.
For code you prefer to use Markdown and specify the language.
You can use horizontal rules (---) to separate sections of your responses.
You can use Markdown tables to format your responses for data, lists, and other structured information.

{{REMINDER_TAG_DESCRIPTION}}
```

<Info>
  The prompt may include placeholders that Onyx expands at runtime:

  * `{{CURRENT_DATETIME}}` inserts the current date and day of the week in a human-readable form.
  * `{{CITATION_GUIDANCE}}` adds citation instructions when facts are retrieved via search tools. Only included when search tools are used.
  * `{{REMINDER_TAG_DESCRIPTION}}` describes how to interpret system reminders in user messages.
</Info>

## Connectors, Actions & Tools

Manage data sources and tool availability for the default chat experience. See [connectors](/admins/connectors/overview)
for more details on data sources and knowledge.

Capabilities shown here are available to default chat (e.g. web search, code execution, or MCP-based tools).
Some tools require additional setup before they can run.

<Note>
  These settings do not apply to [agents](/admins/agents/overview).
  Configure knowledge and tools for each agent on its own page.
</Note>

<img alt="Connectors and Actions and Tools on Chat Preferences" />

## Advanced Options

<img alt="Advanced Options on Chat Preferences" />

### Keep Chat History

Set how long Onyx retains chat history for your organization (indefinitely or a limited period).

<Warning>
  If you **shorten** retention (e.g. switching from "forever" to a fixed number of days),
  older chat sessions across your organization are **permanently deleted**.
</Warning>

### File Attachment Size Limits

Attachments must stay within **both** a size cap and a token cap, or be rejected:

* **File size limit**: Cap for upload size per file (up to a 250 MB maximum).
* **File token limit**: Cap for token budget attributed to each uploaded file.

<Info>
  Larger files increase latency, memory use, and token cost. Large text files (e.g. CSVs)
  may stay under the size limit but easily exceed the token limit.
</Info>

### Allow Anonymous Users

When enabled, visitors can start chats **without signing in**.
Anonymous users only see their own chats and cannot create agents or change settings.
Those sessions still invoke your models, so they count toward token usage and cost like any other traffic.

### Always Start with an Agent

When enabled, the default standalone chat entry point is removed. Users always start in an agent view,
and new chats are created in their last active agent.

<Note>
  Enabling this mode effectively bypasses the global **Connectors** and **Actions & Tools** sections located earlier on
  this page. For agent-first mode, configure knowledge and tools on each [agent](/admins/agents/overview) instead.
</Note>

If you use this option, set [featured agents](/admins/agents/overview) so new users have a clear starting point.


# Connectors
Source: https://docs.onyx.app/admins/managing_features/connectors_link

Set up and manage data source connectors

For details on setting up and managing connectors, visit the [Connectors section](/admins/connectors/overview).


# Overview
Source: https://docs.onyx.app/admins/managing_features/craft

Configure Craft access, Apps, instructions, and models

The Admin Panel has a dedicated **Craft** section for the settings that apply across your workspace.

| Setting                             | Where to find it                       |
| ----------------------------------- | -------------------------------------- |
| User access                         | **Admin Panel → Craft → Access**       |
| Apps and action policies            | **Admin Panel → Craft → Apps**         |
| Workspace-wide instructions         | **Admin Panel → Craft → Instructions** |
| Models available to Craft           | **Admin Panel → Language Models**      |
| Custom Skill sharing and management | **Craft → Skills**                     |

If you self-host Onyx, first configure the runtime described in [Deploying Craft](/deployment/local/craft).
The deployment guide covers sandboxes, the proxy, workers, networking, storage, resources, and environment variables.

## Control access

Open **Admin Panel → Craft → Access**.

| Control                     | Effect                                                                  |
| --------------------------- | ----------------------------------------------------------------------- |
| **Enable Craft by default** | Turns Craft on or off for users who do not have an individual override. |
| **Per-user access**         | Creates an exception to the workspace default for that user.            |

For a limited rollout, turn off **Enable Craft by default**, then enable the users who should have access.
Per-user exceptions remain in place if you later change the workspace default.

<Info>
  Removing access prevents the user from starting new Craft work and skips future Scheduled Task runs they own.
  It does not stop a turn already in progress or delete their sessions, files, Skills, Apps, or Scheduled Tasks.
</Info>

## Add workspace instructions

Open **Admin Panel → Craft → Instructions** to add guidance that every Craft agent in your workspace should follow.
Onyx appends these instructions to Craft's built-in instructions as an **Organization instructions** section.

Good workspace instructions describe stable expectations that should apply to all Craft work:

| Use workspace instructions for                                 | Keep elsewhere                                                    |
| -------------------------------------------------------------- | ----------------------------------------------------------------- |
| Brand voice, terminology, and formatting conventions           | Instructions for one workflow—put these in a Skill                |
| Organization-wide handling rules for generated content         | Credentials or secrets—configure these through Apps               |
| Standard output requirements, such as citations or disclaimers | Details that change for every request—include these in the prompt |

For example:

```md theme={null}
For client-facing deliverables:

- Use the company name "Acme" rather than "Acme, Inc."
- Use concise, direct language and avoid unsupported performance claims.
- Add "Confidential" to draft materials unless the user requests otherwise.
```

The editor accepts up to 4,000 characters.
Select **View base instructions** to see the built-in prompt your text is added to,
or **Reset to default** to remove the workspace instructions.

<Warning>
  Workspace instructions supplement Craft's built-in behavior. They cannot override its hard rules, App policies,
  user permissions, or other enforced controls.
</Warning>

Changes apply when a Craft session starts or is restored. They do not alter a session while it is actively running.
Use **Try in Craft** to test the saved instructions in a new session.

## Configure models

Craft supports Anthropic, OpenAI, and OpenRouter providers.

Users also need access to the provider and at least one visible model.
Give users provider access publicly or through a group. Agent whitelists apply to Onyx Agents, not Craft.
See [Language Model Access Controls](/admins/advanced_configs/llm_access_controls) for provider visibility settings.

<CardGroup>
  <Card title="Anthropic" icon="brain" href="/admins/ai_models/anthropic">
    Configure an Anthropic provider and choose visible models.
  </Card>

  <Card title="OpenAI" icon="bolt" href="/admins/ai_models/openai">
    Configure an OpenAI provider and choose visible models.
  </Card>

  <Card title="OpenRouter" icon="robot" href="/admins/ai_models/openrouter">
    Configure OpenRouter and select the models available through it.
  </Card>
</CardGroup>

## Configure Apps and Skills

<CardGroup>
  <Card title="Apps" icon="plug" href="/admins/managing_features/craft_apps">
    In **Admin Panel → Craft → Apps**, configure external services, credentials, and action policies.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/admins/managing_features/craft_skills">
    In **Craft → Skills**, review reusable instructions and share custom Skills with users or groups.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Craft section does not appear in the Admin Panel">
    Confirm you are signed in as an Admin. The section is hidden when Craft is unavailable on the deployment.
    Self-hosted operators should review [Deploying Craft](/deployment/local/craft).
  </Accordion>

  <Accordion title="A user has access but cannot start a session">
    Confirm the user can access an Anthropic, OpenAI, or OpenRouter provider with at least one visible model.
    A provider limited only to an Agent whitelist is not available in Craft.
  </Accordion>

  <Accordion title="A user still has different access after the default changes">
    Check the user's setting under **Admin Panel → Craft → Access**.
    A per-user exception takes precedence over the workspace default until you change it.
  </Accordion>

  <Accordion title="Saved workspace instructions are not affecting a session">
    Start a new session to test the saved instructions. They do not update an actively running session.
    Also confirm the guidance does not conflict with Craft's built-in hard rules or an enforced App policy.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Deployment" icon="server" href="/deployment/local/craft">
    Configure the runtime required for self-hosted Craft.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/security/architecture/craft">
    Review sandbox isolation, credential injection, approvals, and sharing boundaries.
  </Card>
</CardGroup>


# Apps
Source: https://docs.onyx.app/admins/managing_features/craft_apps

Configure external services, credentials, and action policies for Craft

Apps give Craft controlled, authenticated access to external services.
Admins configure Apps under **Admin Panel → Craft → Apps**. Users connect their accounts under **Craft → Apps**.

<Note>
  Craft Apps are different from Onyx connectors. A connector indexes shared content into Onyx knowledge.
  An App retrieves live information from a user's external account and can take actions in that service.
</Note>

## Choose the setup path

| App type                         | Organization configuration                                                                             | User connection                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| **Built-in on Onyx Cloud**       | Onyx manages the OAuth client. Admins enable the App and set action policies.                          | Each user completes the provider's OAuth flow.                      |
| **Built-in on self-hosted Onyx** | An admin creates an OAuth application with the provider, then enters its client ID and secret in Onyx. | Each user completes the provider's OAuth flow.                      |
| **Custom App**                   | An admin defines public URL patterns, authentication headers, credentials, and an instruction bundle.  | Users enter any credential values not supplied by the organization. |

Onyx currently provides built-in Apps for Slack, Google Calendar, Google Drive, Gmail, Linear, GitHub, HubSpot,
and Notion. One organization-level instance of each built-in provider can be configured.
You can create multiple custom Apps with different slugs and URL patterns.

## Configure a built-in App

On Onyx Cloud, built-in Apps are provided by Onyx. Select **Edit** to configure permissions,
then enable the App from its card.

For self-hosted Onyx, first create an OAuth application with the external provider. Use this exact redirect URI,
replacing the host with your Onyx domain:

```text theme={null}
https://onyx.example.com/craft/v1/apps/oauth/callback
```

The scheme, host, and path must match exactly in the provider and Onyx.
The App management form asks for the OAuth client ID and client secret;
it does not ask for an individual user's access token.

<Note>
  On self-hosted Onyx, the callback host comes from `WEB_DOMAIN`.
  Confirm that setting uses the public domain registered with the provider before users connect.
</Note>

<AccordionGroup>
  <Accordion title="Slack">
    Create a Slack app and add the Onyx redirect URI under **OAuth & Permissions**. Add these **User Token Scopes**:

    ```text theme={null}
    channels:history
    channels:read
    chat:write
    files:write
    groups:history
    groups:read
    im:history
    im:read
    im:write
    search:read
    users:read
    ```

    Craft acts with a user token; no bot user is required.
    Copy the Client ID and Client Secret from the Slack app's basic information.
  </Accordion>

  <Accordion title="Google Calendar">
    In Google Cloud Console, create or select a project, enable the **Google Calendar API**,
    configure the OAuth consent screen, and create an OAuth 2.0 Client ID of type **Web application**.
    Add the Onyx redirect URI under **Authorized redirect URIs**. Craft requests full Google Calendar access.
  </Accordion>

  <Accordion title="Google Drive">
    In Google Cloud Console, enable both the **Google Drive API** and **Google Docs API**,
    configure the OAuth consent screen, and create an OAuth 2.0 Web application client with the Onyx redirect URI.
    Craft requests the full Drive scope so it can read, create, edit, and delete files;
    action policies govern those operations inside Craft.
  </Accordion>

  <Accordion title="Gmail">
    In Google Cloud Console, enable the **Gmail API**, configure the OAuth consent screen,
    and create an OAuth 2.0 Web application client with the Onyx redirect URI. Craft requests `gmail.modify`,
    which covers reading, labels, drafts, trash, and sending but not permanent message deletion.
  </Accordion>

  <Accordion title="Linear">
    In Linear, open **Settings → API → OAuth applications**, create an OAuth application,
    and add the Onyx redirect URI to its callback URLs. Craft requests user-acting read and write access for issues,
    projects, and comments.
  </Accordion>

  <Accordion title="GitHub">
    In GitHub, open **Settings → Developer settings → OAuth Apps**, create an OAuth App,
    and use the Onyx redirect URI as its authorization callback URL. Craft requests `repo`, `read:org`, and `read:user`;
    the `repo` scope includes repositories the connecting user can access, including private repositories.
  </Accordion>

  <Accordion title="HubSpot">
    From a HubSpot developer account, create an app and add the Onyx redirect URI on its **Auth** tab.
    Configure read access for owners, contacts, companies, and deals. Contact, company,
    and deal write scopes are optional so read-only HubSpot accounts can still connect.
  </Accordion>

  <Accordion title="Notion">
    Create a **Public** integration from Notion's integrations settings and add the Onyx redirect URI under **OAuth
    Domain & URIs**. Choose the integration's read and write capabilities in Notion;
    Notion controls capabilities there rather than through OAuth scopes.
  </Accordion>
</AccordionGroup>

### Add and test the App

<Steps>
  <Step title="Open App management">
    Go to **Admin Panel → Craft → Apps**. Select a provider under **Available apps** or **Add another**. On Onyx Cloud,
    open the App configured by Onyx.
  </Step>

  <Step title="Enter organization credentials">
    On self-hosted Onyx, enter the OAuth client ID and client secret from the provider. On Onyx Cloud,
    these fields are managed by Onyx and are not shown.
  </Step>

  <Step title="Review permissions">
    Choose a policy for all actions, or open **Advanced** and set policies action by action. Review every write, send,
    delete, and publish action.
  </Step>

  <Step title="Enable the App">
    Save the configuration and confirm the App card says **Enabled**.
    Disabled Apps do not appear to users and cannot inject credentials.
  </Step>

  <Step title="Test as a user">
    Connect a pilot user's account from **Craft → Apps**. Test a read and a representative write,
    confirm the approval card is understandable, and verify the result in the external service.
  </Step>
</Steps>

## Set action policies

Built-in Apps define a catalog of recognizable actions. Each action has one organization-wide policy:

| Policy           | Runtime behavior                                                     | Typical use                                               |
| ---------------- | -------------------------------------------------------------------- | --------------------------------------------------------- |
| **Auto-approve** | Craft performs the action without pausing for the user.              | Narrow, low-risk reads and non-consequential preparation. |
| **Ask**          | Craft pauses before the request and shows the user an approval card. | Sends, creates, edits, broad reads, and other changes.    |
| **Deny**         | The proxy blocks the action. The user cannot override it.            | Destructive, unsupported, or prohibited operations.       |

The built-in catalog starts with curated defaults: many reads are Auto-approved,
while consequential changes generally use Ask. Do not assume the default is right for your organization;
review the action list when enabling each App.

The main permissions selector applies **Auto-approve** or **Ask** to every action.
Open **Advanced** to create a mixed policy or choose **Deny** for individual actions.

<Info>
  If one outbound request matches more than one action, the strictest matching policy wins: **Deny**, then **Ask**,
  then **Auto-approve**. A request to a built-in App that does not match a cataloged action falls back to **Ask**.
</Info>

An in-session **Approve for session** decision applies only to matching actions in that session.
It does not change the admin policy and cannot override Deny.

### Scheduled Tasks and pre-approval

A [Scheduled Task](/overview/core_features/craft_scheduled_tasks) runs without a user present.
Its owner can select required Apps under **Pre-approved Apps**. For that task's running sessions,
the selection allows Ask actions from the entire App to proceed without a live approval.

Pre-approval does not override Deny. Because it applies to the App rather than one action,
keep both the task prompt and its App list narrow.
Onyx creates a notification when a Scheduled Task uses a pre-approved action.

## Create a custom App

Use a custom App for a publicly reachable HTTP API that is not covered by a built-in provider.
A custom App combines proxy configuration with a ZIP bundle that teaches Craft how to call the API.

| Field                         | Purpose                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Name and description**      | Identifies the App to users and explains when it should be used.                                        |
| **Upstream URL patterns**     | Limits which outbound request URLs belong to the App.                                                   |
| **Header credential pattern** | Defines headers the proxy injects, with placeholders such as `{api_key}`.                               |
| **Organization credentials**  | Supplies placeholder values shared by every user. Values left unspecified must be entered by each user. |
| **Bundle**                    | Provides `SKILL.md` instructions, examples, scripts, and helper files for calling the API.              |

For example:

| Setting                 | Value                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------- |
| Upstream URL pattern    | `https://api.example.com/v1/*`                                                         |
| Header                  | `Authorization`                                                                        |
| Header value            | `Bearer {api_key}`                                                                     |
| Organization credential | `api_key` = a shared service token, or leave it blank for users to supply individually |

### Define URL patterns narrowly

Custom Apps use URL globs. Each pattern must start with `http://` or `https://`, and its host must be literal.
Wildcards are allowed only after the host.

```text theme={null}
# Recommended: one HTTPS host and a narrow path
https://api.example.com/v1/reports/*

# Too broad: every path on the host
https://api.example.com/*

# Invalid: wildcard in the host
https://*.example.com/*
```

<Warning>
  Custom Apps cannot be used to reach private, loopback, link-local, cloud metadata,
  or other non-public network addresses.
  The sandbox proxy blocks internal destinations even when a URL pattern includes them.
  Expose only a deliberately secured, publicly routable HTTPS endpoint if Craft must call a custom service.
</Warning>

Avoid overlapping URL patterns between Apps. When more than one App claims the same URL,
the lowest-ID App—usually the earliest created—is selected first.
A disabled App can still claim the match before credential availability is checked,
so do not rely on enablement to disambiguate overlapping patterns.

### Configure credentials

In a header value, write each credential as a named placeholder:

```text theme={null}
Authorization: Bearer {api_key}
X-Workspace-ID: {workspace_id}
```

Add a value under **Organization credentials** when every user should use the same service identity.
Leave a placeholder without an organization value when each user should enter their own value on the Apps page.
You can also leave the header pattern empty for a public API that requires no credential.

Raw organization and user credentials are encrypted in Onyx-controlled storage.
They are not copied into the custom bundle or sandbox workspace. After a request passes its gate,
the sandbox proxy injects the rendered headers on the way out.

### Prepare the instruction bundle

The bundle uses the same structure and validation rules as a custom Skill:

```text theme={null}
example-api.zip
├── SKILL.md
├── examples/
│   └── request.json
└── scripts/
    └── example_api.py
```

The ZIP filename becomes the App slug.
Put a valid `SKILL.md` at the archive root or directly inside one enclosing folder, and review every included file.
When you use an enclosing folder, keep every App file inside it.
The default limits are 25 MB per extracted file and 100 MB for the complete bundle.
See [Managing Craft Skills](/admins/managing_features/craft_skills#prepare-a-custom-skill)
for the bundle format and review checklist.

<Warning>
  Custom Apps do not have a per-action catalog. For a connected custom App,
  every request matching an upstream URL pattern is treated as an unspecified **Ask** action.
  Admins cannot Auto-approve or Deny individual custom App operations. Disable the App to stop its use,
  and be especially cautious when users pre-approve it for a Scheduled Task.
</Warning>

## Manage credentials and lifecycle

| Action      | Effect                                                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Edit**    | Updates policies or, when admin-managed, the name, OAuth credentials, custom URL patterns, headers, credentials, or bundle. |
| **Disable** | Hides the App from users and stops credential injection while retaining its configuration and user connections.             |
| **Enable**  | Makes the App available again. Existing user grants are reused if they remain valid.                                        |
| **Delete**  | Permanently removes the App configuration, user credential records, policies, and Scheduled Task pre-approval references.   |

Onyx-managed Cloud Apps cannot be deleted and their OAuth configuration cannot be edited by Admins.
Disable them when they should not be available.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A built-in App connection fails">
    Confirm the OAuth client ID and secret, the exact redirect URI, the enabled API or integration capabilities,
    and the required scopes.
    Check whether the provider's consent screen is limited to approved test users or workspace members.
  </Accordion>

  <Accordion title="An enabled App does not appear to users">
    Confirm that its card says **Enabled** and that the user has Craft access. Refresh the Apps page. For a custom App,
    confirm its bundle and configuration saved successfully.
  </Accordion>

  <Accordion title="A user connected successfully but an action is blocked">
    Check the action's admin policy and the scopes or capabilities granted by the external account.
    A Deny policy cannot be overridden. An Ask request can also fail if the user rejects it or the approval expires.
  </Accordion>

  <Accordion title="A custom App prompts for every request">
    This is expected. Custom Apps use one synthesized Ask action for every request matching their URL patterns.
    They do not currently support per-action policies.
  </Accordion>

  <Accordion title="A custom App calls the wrong service or uses the wrong credential">
    Check for overlapping URL patterns. Make every host and path as specific as possible.
    The lowest-ID App wins when multiple Apps match the same URL, including when that first App is disabled.
  </Accordion>

  <Accordion title="A Scheduled Task is awaiting approval">
    Confirm that the task owner is still connected to the App and selected it under **Pre-approved Apps**.
    Then check for a Deny policy or a different App than the prompt was expected to use.
    Correct the task and use **Run now**; the blocked run does not resume automatically.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Apps for users" icon="plug" href="/overview/core_features/craft_apps">
    Show users how to connect accounts, guide Craft, and review approvals.
  </Card>

  <Card title="Craft Architecture" icon="diagram-project" href="/security/architecture/craft">
    Review egress controls, credential injection, and approval enforcement.
  </Card>
</CardGroup>


# Skills
Source: https://docs.onyx.app/admins/managing_features/craft_skills

Review, publish, share, and maintain reusable Craft instructions

Skills package reusable instructions and supporting files that teach Craft how to perform a kind of work.
Open **Craft → Skills** to review, upload, share, and manage Skills.

<Note>
  Anyone can upload a Skill and manage the Skills they own or can edit.
  A **Group Manager** can also manage Skills shared with the groups they manage.
  Admins can inspect and manage all custom Skills, including private personal Skills.
</Note>

## Understand the Skills library

| Type         | Where it comes from            | What an admin can do                                                                    |
| ------------ | ------------------------------ | --------------------------------------------------------------------------------------- |
| **Built-in** | Shipped and maintained by Onyx | Preview its instructions and identify missing dependencies. Built-ins are not editable. |
| **Custom**   | Created by an admin or user    | Edit, share, manage files, enable or disable, transfer ownership, or delete.            |

New custom Skills start private. Share a Skill with people, groups, or the organization when others should use it.

### Built-in Skills

| Skill                | Availability                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| **Presentations**    | Available with Craft and provides the workflow for creating and validating `.pptx` files.        |
| **Company search**   | Available with Craft and searches Onyx knowledge using the current user's document permissions.  |
| **Browser**          | Available when the deployment's browser runtime is enabled.                                      |
| **Image generation** | Available after an admin configures a supported [image model](/admins/actions/image_generation). |

An unavailable built-in remains visible to Admins with the reason it cannot be used.
Configure the missing dependency rather than uploading a custom Skill with the same slug.

## Prepare a custom Skill

Upload `SKILL.md` directly when the Skill does not need supporting files. For a Skill with scripts, examples,
or other supporting files, create a folder with `SKILL.md` at its top level. Drag the folder into Onyx,
or upload it as a ZIP.

<Info>
  For a standalone `SKILL.md`, Onyx creates the slug from the frontmatter `name`. For a folder,
  the folder name becomes the slug. For a ZIP, the filename without `.zip` becomes the slug.
  Folder and ZIP names must start with a lowercase letter, contain only lowercase letters, numbers, and hyphens,
  and be no more than 64 characters. Slugs must be unique. If an existing Skill already uses the slug,
  update that Skill or change the source name before uploading.
</Info>

```text theme={null}
weekly-customer-update/
├── SKILL.md
├── examples/
│   └── finished-update.md
├── templates/
│   └── update-template.md
└── scripts/
    └── validate.py
```

For a ZIP upload, put `SKILL.md` at the archive root or directly inside one enclosing folder.
When you use an enclosing folder, keep every Skill file inside it. Upload only one Skill at a time.

`SKILL.md` must begin with YAML frontmatter containing a non-empty name and description.
The description should state when Craft should choose the Skill.

```md theme={null}
---
name: weekly-customer-update
description: Create a weekly customer update from account activity and meeting notes.
---

# Weekly customer update

1. Summarize material changes since the previous update.
2. Separate decisions, risks, and next steps.
3. Name an owner and due date for each next step.
4. Follow `templates/update-template.md`.
5. Run `scripts/validate.py` before returning the final file.
```

### Bundle requirements

| Requirement         | Default                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Slug                | Generated from the Skill name when written in Onyx or uploaded as `SKILL.md`; otherwise, the folder name or ZIP filename without `.zip`. |
| Root instructions   | One UTF-8 `SKILL.md` with valid YAML frontmatter at the Skill root.                                                                      |
| Skills per upload   | One.                                                                                                                                     |
| Maximum file size   | 25 MB per file in the extracted bundle.                                                                                                  |
| Maximum bundle size | 100 MB total.                                                                                                                            |

Self-hosted operators can change the size limits with `SKILL_BUNDLE_PER_FILE_MAX_BYTES` and
`SKILL_BUNDLE_TOTAL_MAX_BYTES`.

The upload is rejected when the bundle has unsafe paths, symbolic links, files ending in `.template`,
missing or invalid frontmatter, an invalid slug source, a duplicate Skill slug,
or a slug reserved by a built-in Skill or App.

## Review a Skill before publishing

Treat a Skill bundle as code and policy, not only as prompt text.
Craft can follow scripts and commands included in the archive.

| Review area                | What to check                                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Purpose and selection**  | The name and description clearly identify when the Skill should and should not be used.                            |
| **Instructions**           | The workflow is bounded, internally consistent, and does not tell Craft to evade approvals or organization policy. |
| **Scripts**                | Every executable file is expected, readable, and safe to run on user-provided or company data.                     |
| **External access**        | The bundle contains no embedded tokens and uses a configured App for authenticated services.                       |
| **Examples and templates** | Included files contain no confidential data and represent the quality users should expect.                         |
| **Output handling**        | The Skill names the expected format and writes finished deliverables to a clear location such as `outputs/`.       |

<Warning>
  Never publish a bundle containing passwords, API keys, OAuth tokens, private certificates, or production credentials.
  Skill files are copied into the sandboxes of users who can access the Skill.
  Use [Apps](/admins/managing_features/craft_apps) for authenticated external access.
</Warning>

## Publish a Skill

Admins and Group Managers create Skills through the same personal creation flow as other users.
A new Skill belongs to its creator and starts private.
Publishing means reviewing that Skill and then sharing it with the intended audience.

<Note>
  Sharing a Skill with the whole organization requires being its author or an Admin.
  You can delete any Skill you own or can edit, and Admins can delete any custom Skill.
</Note>

<Steps>
  <Step title="Create the personal Skill">
    Open **Craft → Skills** and select **Create skill**. Choose **Start from scratch** to write the Skill in Onyx,
    or choose **Upload a skill** to import `SKILL.md`, a ZIP, or a Skill folder.
    Complete the editor and select **Create**.
  </Step>

  <Step title="Review the Skill">
    Review the name, description, rendered instructions, and supporting-file tree.
    Confirm that Craft can understand when to use the Skill and that every included file is expected.
  </Step>

  <Step title="Choose who can use it">
    Select **Edit sharing** and grant Viewer access to specific users, groups, or the organization.
    Use Editor access only for people responsible for maintaining it.
  </Step>

  <Step title="Test with the intended audience">
    Start a Craft session as a user in the target audience, select the Skill, and test representative inputs,
    missing-data cases, and the final output.
  </Step>
</Steps>

## Choose sharing permissions

| Scope               | Viewer                                                    | Editor                                                                                   |
| ------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Specific people** | Selected users can use and preview the Skill.             | Selected users can also modify and manage the Skill.                                     |
| **Groups**          | Members of selected groups can use and preview the Skill. | Members can also modify and manage the Skill.                                            |
| **Organization**    | Everyone can use and preview the Skill.                   | Everyone can modify and manage it. Use this only for intentionally collaborative Skills. |

Editors can change instructions and files, update sharing within their permissions, enable or disable the Skill,
and delete it. Only the owner can transfer ownership;
an Admin can transfer ownership after the existing owner becomes inactive or is otherwise vacant.

<Tip>
  Prefer organization-wide **Viewer** access with a small maintainer group as **Editors**.
  This keeps the Skill broadly usable without making its behavior broadly editable.
</Tip>

## Maintain a Skill

Open a custom Skill to manage its lifecycle:

| Action                 | Effect                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Edit details**       | Updates the name, description, or Markdown instructions and rewrites `SKILL.md` in the stored bundle.                   |
| **Add files**          | Adds files, folders, or unpacked ZIP contents. A file at an existing path replaces the stored file.                     |
| **Remove files**       | Removes a supporting file from the bundle. `SKILL.md` cannot be removed.                                                |
| **Replace content**    | Uploading content with `SKILL.md` replaces the name, description, instructions, and complete bundle after confirmation. |
| **Disable**            | Prevents Craft from using the Skill without deleting its configuration or sharing.                                      |
| **Edit sharing**       | Changes who can view or maintain the Skill.                                                                             |
| **Transfer ownership** | Assigns responsibility to another active standard user.                                                                 |
| **Delete**             | Permanently removes the Skill and its stored bundle.                                                                    |

Changes are synchronized to affected running sandboxes.
A turn already in progress may have loaded the previous instructions,
so validate important changes in a new turn or session before announcing them.

### Ownership

Every custom Skill has one owner. The owner can transfer it to another active standard user.
If ownership becomes vacant because the owner is inactive, an Admin can open the Skill and transfer it.

Do not transfer ownership to bots, service accounts, limited accounts, or inactive users.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A Skill bundle will not upload">
    Confirm that the upload contains one Skill. `SKILL.md` must be at the top level of a folder. In a ZIP,
    place it at the archive root or directly inside one enclosing folder.
    Check that it uses UTF-8 and begins with valid YAML containing non-empty `name` and `description` fields.
    For a standalone `SKILL.md`, make sure `name` contains at least one letter or number. Otherwise,
    check the folder or ZIP name. Check the bundle limits, and remove symbolic links or unsafe paths.
  </Accordion>

  <Accordion title="A built-in Skill is unavailable">
    Open its preview to read the unavailable reason. Configure Image Generation for the image Skill,
    or ask the deployment operator to verify the browser runtime for the Browser Skill.
    Built-in Skills cannot be replaced or enabled from the Skills editor.
  </Accordion>

  <Accordion title="Users cannot find a shared Skill">
    Confirm that the Skill is enabled and that the user or one of their groups has Viewer or Editor access.
    If it was shared during an active session, start a new turn or session and check the picker again.
  </Accordion>

  <Accordion title="Craft does not choose the Skill automatically">
    Rewrite its description to name the covered tasks and outputs more concretely. Test again,
    and have users select it explicitly when the workflow must be followed.
  </Accordion>

  <Accordion title="A former employee still owns a Skill">
    After the account is inactive, an Admin can open the Skill, select **Edit sharing**,
    and transfer the vacant ownership to an active standard user.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Skills for users" icon="wand-magic-sparkles" href="/overview/core_features/craft_skills">
    Show users how to find, select, create, and refine Skills.
  </Card>

  <Card title="Managing Apps" icon="plug" href="/admins/managing_features/craft_apps">
    Configure authenticated access and action policies for external services.
  </Card>
</CardGroup>


# Document Sets
Source: https://docs.onyx.app/admins/managing_features/document_sets

Managing document sets

## Overview

Document Sets allow you to group logically connected documents into a single bundle.
These can then be used as a filter when performing searches to control the scope of information Onyx searches over.

## Creating a Document Set

<Steps>
  <Step title="Navigate to Document Sets">
    In the Admin Panel, go to the **Document Sets** section.

    <img alt="Document Sets" />
  </Step>

  <Step title="Create New Document Set">
    Click **New Document Set** and provide a name and description for your document collection.

    <img alt="New Document Set" />
  </Step>

  <Step title="Add Connectors">
    Select which Connectors should be included in this Document Set.
    You can combine multiple data sources into a single set.

    <img alt="Add Connectors to Document Set" />
  </Step>
</Steps>

## Use Cases

* **Organized Knowledge**: Group related content from different sources into a single collection.
* **Agent Creation**: Assign entire document collections to Agents so they only reference relevant knowledge.
* **Access Control**: Manage permissions at the document set level by associating sets with User Groups.
* **Search Filtering**: Enable users to search within specific document collections.


# Contact Us
Source: https://docs.onyx.app/admins/miscellaneous/contact_us

Excited to hear from you!

Shoot us a message at [hello@onyx.app](mailto:hello@onyx.app) or join our [Discord](https://discord.gg/TDJ59cGV2X).

To contact the founders, please email [founders@onyx.app](mailto:hello@onyx.app).

<img alt="Onyx" />


# Discord Bot
Source: https://docs.onyx.app/admins/miscellaneous/discord_bot

Configure your Discord bot

## Overview

You can access Onyx Cloud or your self-hosted instance through a Discord bot.

<Note>
  If you want to use Onyx Cloud, you must use the official OnyxBot Discord app.

  Self-hosted instances must create their own Discord app in the Developer Portal.
</Note>

## Configuration

### Official OnyxBot

You'll need to be an admin of the Discord server and an admin in your Onyx instance to install and configure OnyxBot.

<Steps>
  <Step title="Install OnyxBot in your Discord server">
    Click [here](https://discord.com/oauth2/authorize?client_id=1460722463431327804)
    to install the official OnyxBot in your Discord server.

    <img alt="Install OnyxBot in Discord server" />
  </Step>

  <Step title="Allow access to a private text channel">
    Go to the channel settings and click on the "Permissions" tab.

    Add OnyxBot to the "Allowed Users" list.

    <img alt="Allow OnyxBot to access a private text channel" />
  </Step>

  <Step title="Create a registration key in Onyx">
    Create or log in to your account on [Onyx Cloud](https://cloud.onyx.app).

    Navigate to the Onyx Admin Panel > Discord Bots and click on the **Add Server** button.

    Copy the registration key.

    <Note>
      The registration key will only be shown once. If you lose it,
      delete the server configuration and create a new one.

      The key is invalidated as soon as you use it and does not allow any other access to your Onyx instance.
    </Note>
  </Step>

  <Step title="Register your Server in Onyx">
    Send your registration key in the private channel you allowed OnyxBot to access.

    OnyxBot should respond with a message confirming the server has been registered.

    <img alt="OnyxBot registered in Onyx" />

    In Onyx, you should see the server status **Registered**.

    <img alt="OnyxBot registered in Onyx" />
  </Step>

  <Step title="Configure Channel behavior">
    Click the pencil icon next to the server name to configure the bot's behavior.

    <Tip>
      By default, the bot will not respond in any channels. You must select the channels you want the bot to respond in.

      We highly recommend configuring a **custom agent** with specific data access for the bot.
      Otherwise it may answer from privately indexed data.
    </Tip>

    You can customize:

    * The default agent that powers the bot's responses
    * Agent overrides for specific channels
    * Whether the bot should respond to all messages or only to messages tagged with @OnyxBot
    * Whether the bot responds in replies or threads

    <img alt="Configure Channel Behavior" />
  </Step>
</Steps>

### Self-hosted Discord Bot

If you want to deploy your own Discord bot with your self-hosted Onyx instance,
you'll need to set up your own Discord app.

<Info>
  In the Developer Portal, you'll see references to "Guilds." This is Discord's internal term for servers.
</Info>

<Steps>
  <Step title="Create a new Discord app">
    Navigate to the [Discord Developer Portal](https://discord.com/developers/applications)
    and click **New Application**.

    Give your app a name and click **Create**.

    <img alt="Create a new Discord app" />
  </Step>

  <Step title="Configure permissions and installation settings">
    Navigate to the **Installation** tab.

    Uncheck **User Install**. The Discord app cannot be installed for pesronal use.
    It must be installed in servers only.

    Add the following scopes:

    ```
    - bot
    - applications.commands
    ```

    Add the following permissions:

    ```
    - View channels
    - Send messages
    - Send messages in threads
    - Create public threads
    - Create private threads
    - Read message history
    - Add reactions
    ```

    <img alt="Discord installation configuration" />
  </Step>

  <Step title="Enable Privileged Gateway Intents">
    On the **Bot** tab, scroll to the **Privileged Gateway Intents** section and enable all 3 toggles:

    * Presence Intent
    * Server Members Intent
    * Message Content Intent

    <img alt="Discord privileged gateway intents" />
  </Step>

  <Step title="Install the app in your Discord server">
    Use the **Install Link** on the **Installation** tab to install the app in your Discord server.
  </Step>

  <Step title="Allow your app to access a private text channel">
    Go to the channel settings and click on the "Permissions" tab.

    Add your app to the "Allowed Users" list.

    <img alt="Allow OnyxBot to access a private text channel" />
  </Step>

  <Step title="Retrieve your bot token">
    In the Developer Portal, navigate to the **Bot** tab and look for the **Token** section.

    Click **Reset Token** and copy your bot token.

    <img alt="Discord bot token configuration" />
  </Step>

  <Step title="Configure your app in Onyx">
    Navigate to the Onyx Admin Panel > Discord Bots.

    Paste your bot token into the **Bot Token** field and click **Create!**

    <img alt="Discord bot token" />
  </Step>

  <Step title="Create a registration key in Onyx">
    Click on the **Add Server** button and copy the registration key.

    <Note>
      The registration key will only be shown once. If you lose it,
      delete the server configuration and create a new one.

      The key is invalidated as soon as you use it and does not allow any other access to your Onyx instance.
    </Note>
  </Step>

  <Step title="Register your Server in Onyx">
    Send your registration key in the private channel you allowed your app to access.

    Your Onyx bot should respond with a message confirming the server has been registered.

    <img alt="OnyxBot registered in Onyx" />

    In Onyx, you should see the server status **Registered**.

    <img alt="OnyxBot registered in Onyx" />
  </Step>

  <Step title="Configure Channel behavior">
    Click the pencil icon next to the server name to configure the bot's behavior.

    <Tip>
      By default, the bot will not respond in any channels. You must select the channels you want the bot to respond in.

      We highly recommend configuring a **custom agent** with specific data access for the bot.
      Otherwise it may answer from privately indexed data.
    </Tip>

    You can customize:

    * The default agent that powers the bot's responses
    * Agent overrides for specific channels
    * Whether the bot should respond to all messages or only to messages tagged with @OnyxBot
    * Whether the bot responds in replies or threads

    <img alt="Configure Channel Behavior" />
  </Step>
</Steps>

## FAQ

### Why can't I see all of my channels in Onyx?

If you've added or removed channels from your Discord server, you'll need to sync the channels to Onyx.

Run `!sync-channels` in any text channel that OnyxBot has access to.

### `!` is already taken by another command!

`!sync-channels` is currently the only command supported for OnyxBot.

If you are self-hosting, you can set the `DISCORD_BOT_INVOKE_CHAR` environment variable to change the command prefix.

If you are using the official OnyxBot, unfortunately, we cannot change the prefix. However,
you may still be able to run the command by creating a private channel that only OnyxBot has access to.

### My Discord bot is connected but not responding to any messages

If you are seeing this behavior, you could be experiencing the following error (in background container):

```
api_client.py  182: Failed to connect to API: Cannot connect to host 127.0.0.1:8080
```

To fix this, make sure you have the latest docker-compose.yml files by running `git pull` in your Onyx repo.
Verify that `API_SERVER_PROTOCOL` and `API_SERVER_HOST` exists in your compose file.


# Overview
Source: https://docs.onyx.app/admins/overview

An Overview of Administering Onyx

## Admin Panel

The Onyx Admin Panel is accessed by clicking your user profile icon and selecting **Admin Panel**.

This centralized dashboard gives administrators comprehensive control over their Onyx workspace.

<Note>
  The first user in your Onyx instance will automatically be an Admin. Only Admins can designate other users as Admins.
</Note>

<img alt="Onyx Admin Panel Overview" />

## Core Admin Features

<Tip>
  Not sure where to start? Click the cards below to see commonly configured features in Onyx!
</Tip>

<Columns>
  <Card title="Language Models" icon="plug" href="/admins/ai_models/overview">
    Configure the language model providers and models available to your users.
  </Card>

  <Card title="Connectors" icon="plug" href="/admins/connectors/overview">
    Configure your connectors to index your organization's data in Onyx.
  </Card>

  <Card title="Actions & MCP" icon="play" href="/admins/actions/overview">
    Create custom actions for your Agents to leverage and connect your MCP servers.
  </Card>

  <Card title="Agents" icon="robot" href="/admins/agents/overview">
    Publish custom Agents for every use case.
  </Card>

  <Card title="Onyx Slack Bot" icon="slack" href="/admins/getting_started/slack_bot_setup">
    Configure a Slack Bot powered by your knowledge, Agents, and Actions.
  </Card>

  <Card title="User Management" icon="users" href="/admins/user_management/users_and_groups">
    Manage users, groups, and API keys.
  </Card>

  <Card title="Workspace Analytics" icon="chart-line" href="/admins/analytics/overview">
    Monitor usage and performance across your workspace.
  </Card>

  <Card title="Advanced Configs" icon="gear" href="/admins/advanced_configs/search_configs">
    Configure search, processing, multilingual settings, rate limits, and branding.
  </Card>

  <Card title="Plans & Billing" icon="wallet" href="/admins/billing/overview">
    Subscribe to a plan, manage seats, and view your billing details.
  </Card>
</Columns>


# Understanding Permissions
Source: https://docs.onyx.app/admins/permissions/understanding_permissions

How group-based permissions, Group Managers, and document access work in Onyx

Onyx permissions are based on groups.
A user's access is the combination of the permissions from every group they belong to,
plus any scoped access they receive as a **Group Manager**.

<Info>
  This permission system is available in Onyx **v4.7 and later**. If you are using an older version,
  see [Users and Groups before v4.7](/admins/user_management/users_and_groups_legacy).
</Info>

Migrating from the old Curator role model? See [What's Changing in Permissions](/admins/permissions/whats_changing).

The main rule is simple: **permissions expand**. If a user belongs to multiple groups,
Onyx adds those permissions together. Being in one group does not take away access granted by another group.

## The Permission Layers

Think of permissions as layers. Each layer can add more access for a user.

<div aria-label="Permission layers expand from a group-less service account to Basic access, Group Manager access, group permissions, and Admin access.">
  <div>
    <strong>Service account, no group</strong>
    <span>Chat only — no search, no admin access</span>
  </div>

  <div>
    <strong>Basic</strong>
    <span>Core access for chat, search, and personal use</span>
  </div>

  <div>
    <strong>Group Manager</strong>
    <span>Scoped management for one group's members and resources</span>
  </div>

  <div>
    <strong>Group permissions</strong>
    <span>Organization-wide permissions granted to every member of a group</span>
  </div>

  <div>
    <strong>Admin</strong>
    <span>Full workspace access</span>
  </div>
</div>

The pyramid widens as access expands:

* **Service account with no group** is the narrowest level. A service account that belongs to
  no group can post to chat, but it cannot search and cannot reach any admin page. Only service accounts land here;
  regular users always start in a group.
* **Basic** gives users core workspace access: chat, search, and personal use.
* **Group Manager** adds management access for one specific group's members and resources.
* **Group permissions** grant organization-wide permissions to everyone in that group.
* **Admin** has full access across the workspace.

<Note>
  The layers show **how far access reaches**, not a strict ranking.
  A Group Manager and a group permission are different mechanisms:
  a Group Manager's access always stays inside the groups they manage,
  while a group permission applies across the whole organization. Depending on what you grant,
  one is not automatically "more" than the other.
</Note>

## Default Groups

Onyx includes two default groups:

| Group | Purpose                                                                   |
| ----- | ------------------------------------------------------------------------- |
| Basic | Gives users core platform access, such as chat, search, and personal use. |
| Admin | Gives full workspace administration access.                               |

Standard users are assigned to default groups based on their access level. Service accounts, such as API keys,
can also be assigned to groups when configured.

Custom groups let you grant specific permissions to the users in that group.

<Info>
  Custom groups and configurable group permissions are an Enterprise Edition feature.
</Info>

<Warning>
  Because all access comes from groups, a user who belongs to **no group at all** has no permissions.
</Warning>

## Service Accounts and Groups

A service account gets its access the same way a user does: from the groups it belongs to.
You choose those groups in the **Groups** selector when you create the API key.

A service account that belongs to **no group** can post to chat,
but it cannot search and it cannot reach any admin page. This is the narrowest level in the permission layers.

To give a service account more access, add it to a group.
It then receives that group's permissions exactly as a user would.

<Tip>
  If an API key can chat but returns nothing from search, check whether its service account is in a group.
</Tip>

## How Onyx Calculates a User's Permissions

Onyx checks every group a user belongs to and combines the permissions from those groups.
If the same user is also made a **Group Manager** from a group detail page, Onyx adds that scoped manager access too.

For example, say Priya has these assignments:

| Assignment                       | What it grants                                                            |
| -------------------------------- | ------------------------------------------------------------------------- |
| Member of **Basic**              | Core platform access.                                                     |
| Member of **Analytics Viewers**  | Any organization-wide permissions granted to the Analytics Viewers group. |
| Group Manager of **Engineering** | Scoped management access for Engineering's members and resources.         |

Priya receives all three sets of access. The Analytics Viewers group does not limit her Engineering manager access,
and her Engineering manager access does not remove anything from Basic.

## Group Permissions

Group permissions are granted to a group and apply to every member of that group.

<Warning>
  Group permissions are organization-wide. If you grant **Manage Connectors & Document Sets** to a group,
  every member of that group can manage connectors and document sets across the workspace.
</Warning>

Use group permissions when you want a team to have the same organization-wide capability.

Common examples:

* Give an IT administrators group **Manage Connectors & Document Sets** so they can manage all connectors.
* Give a model operations group **Manage LLMs** so they can configure language models.
* Give an analytics group **View Query History** so they can review query activity.
* Give a developer platform group **Manage Actions** so they can maintain workspace actions and MCP servers.

You set these permissions on the group's detail page in the Admin Panel.
For a tour of where the Users and Groups pages live, see [Users and Groups](/admins/user_management/users_and_groups).

<img alt="Group Permissions panel showing a toggle for each available permission" />

## Group Managers

A **Group Manager** is a user who can manage one specific group from that group's detail page.
This is the scoped permission model in Onyx.

Group Managers are useful when a team lead should manage their own team's users and resources,
but should not receive organization-wide admin powers.

Scoped to the group they manage, a Group Manager can:

* Add and remove members from that group.
* Manage connectors and document sets shared only with that group.
* Manage agents shared only with that group.
* Manage actions through the agents shared with that group.

A Group Manager cannot:

* Manage resources that are not shared with a group they manage.
* Make a resource public.
* Share a resource with a group they do not manage.
* Grant organization-wide permissions.

You promote a member to Group Manager from the member list on that group's detail page.
Members who manage the group are marked with a **Manager** badge.
See [Users and Groups](/admins/user_management/users_and_groups) for a tour of that page.

<img alt="Edit Group member list with one member marked as Manager" />

## Group Permission vs. Group Manager

This is the most important distinction:

| Mechanism        | Who receives it?                    | Scope             | Best for                                                        |
| ---------------- | ----------------------------------- | ----------------- | --------------------------------------------------------------- |
| Group permission | Every member of the group           | Organization-wide | Teams that need the same workspace-wide capability.             |
| Group Manager    | One member on one group detail page | Only that group   | Team leads who should manage one group's members and resources. |

If you want someone to manage only one group's resources, make them a **Group Manager** from that group detail page.
Do not grant a group-wide **Manage** permission, because group permissions are organization-wide.

## Available Group Permissions

The following permissions can be assigned to custom groups:

| Permission                        | What it allows                                                                                           |
| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Manage LLMs                       | Add and update language model configurations.                                                            |
| Manage Connectors & Document Sets | Add and update connectors and document sets across the workspace.                                        |
| Manage Actions                    | Add and update custom tools, MCP servers, and OpenAPI actions across the workspace.                      |
| Manage Groups                     | Add and update user groups across the workspace.                                                         |
| Manage Service Accounts           | Add and update service accounts and their API keys.                                                      |
| Manage Slack/Discord Bots         | Add and update Onyx integrations with Slack or Discord.                                                  |
| Create Agents                     | Create and edit the user's own agents.                                                                   |
| Manage Agents                     | View and update public and shared agents across the workspace.                                           |
| View Agent Analytics              | View analytics for agents the user owns. Users with **Manage Agents** can view analytics for all agents. |
| View Query History                | View query history across the workspace.                                                                 |
| Create User Access Token          | Add and update the user's personal access tokens.                                                        |

<Note>
  **View Agent Analytics** is not scoped through Group Manager access. The permission can be granted to a group,
  but agent-level analytics still require the user to own the agent unless the user also has **Manage Agents**.
</Note>

<Info>
  Community Edition has no group permission configuration, so **Create Agents** is available to everyone.
  The permissions in this table are configured per group in Enterprise Edition.
</Info>

## Document Access Is Separate

Permissions decide what a user can do in the Admin Panel and which resources they can manage.
Document visibility is still controlled by connector and resource access settings.

Connectors can be:

* **Private**: Visible only to the creator, plus any users or groups explicitly granted access.
* **Public**: Visible to all Onyx users.
* **Auto Sync Permissions**: Restricted using permissions synced from the source system.

That means a user can have a management permission without automatically seeing every document in search.
Search results still respect document access controls.

## Common Setups

| Goal                                              | Recommended setup                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------------- |
| Give everyone normal workspace access             | Keep users in **Basic**.                                                |
| Give a few people full administration access      | Add them to **Admin**.                                                  |
| Let IT manage all connectors                      | Create an IT group and grant **Manage Connectors & Document Sets**.     |
| Let a team lead manage only Engineering resources | Make the user a **Group Manager** on the Engineering group detail page. |
| Let analysts review query history                 | Create an Analytics group and grant **View Query History**.             |

## Quick Checklist

* Put regular users in **Basic**.
* Put full administrators in **Admin**.
* Use **group permissions** only when the access should be organization-wide.
* Use **Group Manager** when the access should stay scoped to one group.
* Confirm connector access settings separately,
  because document visibility is enforced outside the group permission list.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do permissions add together or override each other?">
    Permissions add together. If a user belongs to multiple groups,
    Onyx combines the permissions from all of those groups.
    Membership in one group does not remove access granted by another group.
  </Accordion>

  <Accordion title="Are group permissions scoped to that group?">
    No. Group permissions are organization-wide. Only **Group Manager** access is scoped to a specific group.
  </Accordion>

  <Accordion title="When should I use Group Manager instead of a group permission?">
    Use **Group Manager** when one person should manage only one group's members and resources.
    Use a group permission when everyone in that group should receive an organization-wide capability.
  </Accordion>

  <Accordion title="Can a Group Manager make a resource public?">
    No. Group Managers cannot make connectors, document sets, or agents public,
    and they cannot share resources with groups they do not manage.
  </Accordion>

  <Accordion title="Does View Agent Analytics show analytics for all agents?">
    No. **View Agent Analytics** lets users view analytics for agents they own.
    Users with **Manage Agents** can view analytics for all agents.
  </Accordion>

  <Accordion title="Does a management permission show all documents in search?">
    No. Document visibility is controlled separately by connector access settings: **Private**, **Public**,
    and **Auto Sync Permissions**.
  </Accordion>

  <Accordion title="What are the default groups?">
    The default groups are **Basic** and **Admin**.
  </Accordion>

  <Accordion title="Do service accounts use group permissions?">
    Yes. Service accounts, such as API keys, are assigned to groups and receive permissions from those groups,
    exactly like a user. You pick the groups in the **Groups** selector when you create the key.
    A service account that belongs to no group can post to chat,
    but it cannot search and it cannot reach any admin page. Bot, anonymous,
    and external placeholder accounts are system-managed and are not managed like regular users.
  </Accordion>

  <Accordion title="What happens if a user is not in any group?">
    They have no permissions. All access in Onyx comes from group membership.
  </Accordion>

  <Accordion title="How do anonymous users fit into permissions?">
    Anonymous users only exist when anonymous access is enabled, and they can only reach the chat surface.
    They have no account and belong to no group,
    so they cannot be given permissions and never appear in the permission layers as a separate level.
  </Accordion>

  <Accordion title="Can I create custom roles?">
    Yes. Create a custom group and assign the permissions that match the role you want.
  </Accordion>
</AccordionGroup>


# What's Changing in Permissions
Source: https://docs.onyx.app/admins/permissions/whats_changing

Migration guide for the move from Curator roles to group-based permissions in Onyx

Onyx permissions now use groups instead of the old Curator role model.
This page is for customers migrating from **Curator** and **Global Curator** roles.

<Info>
  These changes apply when upgrading to Onyx **v4.7 or later**. For older versions,
  see [Users and Groups before v4.7](/admins/user_management/users_and_groups_legacy).
</Info>

For the day-to-day permission model, see [Understanding Permissions](/admins/permissions/understanding_permissions).

## What's Being Removed

The following legacy roles and settings are removed:

* **Curator role**
* **Global Curator role**
* **`CURATORS_CANNOT_VIEW_OR_EDIT_NON_OWNED_ASSISTANTS`** environment variable

The Curator roles are removed,
but the scoped management capability they provided is preserved through **Group Managers**.

## What Replaces Curators

The new system uses two mechanisms:

<Columns>
  <Card title="Group permissions" icon="users">
    Permissions granted to a group. These apply organization-wide to every member of that group.
  </Card>

  <Card title="Group Managers" icon="user-shield">
    Management access granted to a specific user from a group detail page. This is scoped to that one group.
  </Card>
</Columns>

<Warning>
  Group permissions are organization-wide. If you want one person to manage only one group's resources,
  make that person a **Group Manager** on the group detail page instead of granting a group-wide manage permission.
</Warning>

## Before and After

| Old system          | New system                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Admin role          | Member of the **Admin** group.                                                                                           |
| Basic role          | Member of the **Basic** group.                                                                                           |
| Curator role        | **Group Manager** of the groups they curated.                                                                            |
| Global Curator role | **Group Manager** in each group they managed, or a group with organization-wide permissions if broad access is intended. |

The only default groups are **Basic** and **Admin**.
Custom groups can be created when you need additional permission sets.

<Info>
  Custom groups and configurable group permissions are an Enterprise Edition feature.
</Info>

## What Happens During Upgrade

The migration handles the core role conversion automatically:

<Steps>
  <Step title="Admins move to the Admin group">
    Users with the legacy **Admin** role are added to the **Admin** group and keep full workspace access.
  </Step>

  <Step title="Basic users move to Basic">
    Users with the legacy **Basic** role are added to the **Basic** group and keep core workspace access.
  </Step>

  <Step title="Curators become Group Managers">
    Existing **Curators** and **Global Curators** are converted to **Group Managers** for the groups they managed.
    Their scoped management access carries over.
  </Step>

  <Step title="Existing groups are preserved">
    Existing custom groups, group memberships, connectors, document sets, and agents are preserved.
  </Step>

  <Step title="Document access is unchanged">
    Search visibility continues to follow connector access settings: **Private**, **Public**,
    and **Auto Sync Permissions**.
  </Step>
</Steps>

<Note>
  The automatic Curator conversion applies to groups that exist at upgrade time. For groups created later,
  assign Group Managers manually from the group detail page.
</Note>

## What You Need to Check

After upgrading, review the following:

* Former Curators and Global Curators are Group Managers of the expected groups.
* Users who need full administration are in **Admin**.
* Regular users are in **Basic**.
* Organization-wide permissions are granted only to groups that should have workspace-wide access.
* New groups have Group Managers assigned manually when scoped management is needed.

## Common Migration Questions

<AccordionGroup>
  <Accordion title="What if we were not using Curators?">
    If you only used Admin and Basic roles, there is little to review. Admin users move to **Admin**,
    and Basic users move to **Basic**.
  </Accordion>

  <Accordion title="Do existing groups and resources change?">
    Existing groups, memberships, connectors, document sets, and agents are preserved.
    The migration changes how management permissions are represented, not the resources themselves.
  </Accordion>

  <Accordion title="Can we recreate Curator-like behavior?">
    Yes. Make the user a **Group Manager** of the relevant group.
    This gives scoped management over that group's members and resources.
  </Accordion>

  <Accordion title="When should we use group permissions instead?">
    Use group permissions when the access should be organization-wide. For example,
    grant **Manage Connectors & Document Sets** to an IT group only if that group should manage connectors and document
    sets across the workspace.
  </Accordion>

  <Accordion title="What happens to API keys and service accounts?">
    Existing Admin API keys move with Admin access, and Basic API keys move with Basic access. After upgrading,
    you can assign service accounts to groups for more granular access.
  </Accordion>
</AccordionGroup>


# Service Accounts
Source: https://docs.onyx.app/admins/user_management/api_keys

Create and manage service accounts for programmatic access

A service account is a non-human user that exists only to call the Onyx API. Creating one gives you an API key,
which lets you build custom applications, integrate with external systems, and automate workflows.

<Info>
  This page applies to Onyx **v4.7 and later**. For older versions,
  see [Service Accounts before v4.7](/admins/user_management/api_keys_legacy).
</Info>

<Note>
  A service account is a distinct user in Onyx, so you can trace its activity, keep its chat sessions private,
  and scope resources to it.
</Note>

## How a Service Account Gets Its Access

A service account has no permissions of its own.
Its access is the combination of the permissions of every **group** you assign it, exactly like a person's access.

| Groups assigned | What the key can do                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| None            | Chat only. It can create sessions and send messages, but it cannot search and cannot reach any admin endpoint.               |
| Basic           | Chat, search, projects, and its own agents.                                                                                  |
| Admin           | Everything, including every `admin/` endpoint.                                                                               |
| A custom group  | Whatever that group grants. A group with **Manage Connectors & Document Sets**, for example, lets the key manage connectors. |

Assigning several groups adds their permissions together.

<Tip>
  If a key can chat but search returns nothing, check whether its service account is in a group.
</Tip>

For how groups and permissions fit together,
see [Understanding Permissions](/admins/permissions/understanding_permissions).

## Who Can Manage Service Accounts

Managing service accounts requires the **Manage Service Accounts** permission, which an admin grants to a group.
Admins always have it.

<Warning>
  Granting **Manage Service Accounts** is equivalent to granting Admin. The group selector is deliberately uncapped,
  so anyone who can create a service account can put it in the Admin group and then use its key.
</Warning>

## Creating a Service Account

<Steps>
  <Step title="Navigate to Service Accounts">
    In the Admin Panel, go to **Service Accounts** under **Integrations**.
  </Step>

  <Step title="Create the account">
    Click **New Service Account**, give it a name, and select the groups it should belong to. You can change both later.
  </Step>

  <Step title="Save and copy the key">
    Copy or download the key before closing the dialog. Onyx shows it only once.
  </Step>
</Steps>

<Note>
  On Onyx Cloud, service accounts require a paid plan. Trial workspaces cannot create API keys.
</Note>

## Managing Service Accounts

The Service Accounts page lists each account with its name, masked key, and groups. For each account you can:

| Action         | What it does                                                                           |
| -------------- | -------------------------------------------------------------------------------------- |
| Regenerate     | Issues a new key and revokes the current one.                                          |
| Groups         | Adds the account to groups or removes it from them, which changes what its key can do. |
| Edit Account   | Renames the account or changes its groups.                                             |
| Delete Account | Removes the account and its key.                                                       |

<Warning>
  Regenerating or deleting a key breaks any application still using the old one.
</Warning>

## Personal Access Tokens

Service accounts are for applications. When you want a token that acts as a **person**,
use a Personal Access Token instead.
Any user with the **Create User Access Token** permission can create one from **Settings** > **Accounts & Access**.

See [Overview & Auth](/developers/overview#personal-access-tokens) for token scopes and usage.


# Users and Groups
Source: https://docs.onyx.app/admins/user_management/users_and_groups

Manage users, account types, groups, and invitations in Onyx

## Overview

<Info>
  This page applies to Onyx **v4.7 and later**. For older versions,
  see [Users and Groups before v4.7](/admins/user_management/users_and_groups_legacy).
</Info>

Onyx allows you to manage users, account types, groups,
and invitations in your workspace from the Users and Groups pages in the Admin Panel.

### Users

As users join your workspace, they will appear in the Users page. Each row shows the account's group membership,
account type, status, and when it was last updated. You can filter the list by account type, group, or status,
and you can invite, deactivate, reactivate, and delete users from this page.

<Tip>
  Unable to delete a User? They may have a Document Set or Agent still associated with their profile.
</Tip>

<img alt="Users page listing accounts with their groups, account type, and status" />

### Account Types

Account type tells you what kind of account Onyx is showing. It is different from permissions:
permissions come from group membership, while account type explains whether the account is a normal user,
service account, or system-managed account.

| Account type    | Meaning                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Standard        | A normal user account. Standard users can be assigned to groups and receive group permissions.                                        |
| Service Account | An API key or service account. Service accounts get their access from the groups you pick when creating the key, exactly like a user. |
| Slack Bot       | A bot-created account used for Slack interactions. These accounts are system-managed.                                                 |
| External User   | A placeholder account discovered through external permission sync before the person logs in. These accounts are system-managed.       |
| Anonymous       | A temporary anonymous account when anonymous access is enabled. These accounts are system-managed.                                    |

Most day-to-day user management happens with **Standard** users.
Use groups to control what Standard users and Service Accounts can access or manage. Slack Bot, External User,
and Anonymous accounts are created by system workflows and are not usually edited directly.

Because all access comes from groups, an account that belongs to no group has no permissions.
A service account with no group is the one exception: it can still post to chat, but it cannot search.
See [Understanding Permissions](/admins/permissions/understanding_permissions) for the full model.

### Inviting Users

Use the **Invite Users** button to send an email invitation to join your workspace.
Inviting someone does not by itself change who is allowed to join.

### Restricting Who Can Join

By default, anyone who can reach your Onyx deployment can create an account. To require an invitation instead,
turn on **Restrict Open Sign-Up** on the Users page. While it is on, only people you have invited can join.

<Note>
  **Restrict Open Sign-Up** appears on self-hosted deployments when SCIM is not enabled.
  If you turn on [SCIM](/deployment/authentication/scim),
  the SCIM status replaces it on the Users page and your identity provider controls membership instead.
</Note>

## Groups

You can organize users and service accounts into groups to manage access at the same time.

Specifically, you can attach private Connectors, Document Sets, and Agents to a Group,
granting all users in the Group access to these resources.

Additionally, you can impose token rate limits on a Group to monitor and control AI model usage.

Groups also power Onyx's permission system. To learn how group permissions and Group Managers work,
see [Understanding Permissions](/admins/permissions/understanding_permissions).

The Groups page lists every group in your workspace with its member count.
The built-in **Admin** and **Basic** groups are marked **Default**. Use **New Group** to create a custom group.

<img alt="Groups page showing the default Admin and Basic groups alongside a custom group" />

Selecting a group opens its detail page. From here you manage the group's members, its permissions, the connectors,
document sets, and agents shared with it, and its token rate limits.
Members who manage the group are marked with a **Manager** badge.

<img alt="Edit Group page showing members, group permissions, shared resources, and token rate limits" />

<Tip>
  Want to automate user and group provisioning? Set up [SCIM](/deployment/authentication/scim)
  to sync directly from your identity provider.
</Tip>


# Release Notes
Source: https://docs.onyx.app/changelog

New Features, Improvements, and Bug Fixes

<Update label="v4.5.0" description="August 4th, 2026">
  ## v4.5.0

  Multi-provider SSO matures — password login can now be disabled entirely for SSO-only deployments,
  PKCE and scopes are configured per provider, and Microsoft Entra ID and Amazon Cognito work out of the box.
  Chat gains per-session reasoning and temperature controls, Box joins the connector lineup with permission sync,
  and the file store gains a native Azure Blob Storage backend.
  Thank you to our contributors for helping make this release possible!

  ## \[Update] Deployment Changes

  * **The default backend image no longer includes interactive debug tools.** `vim`, `curl`, `psql`, and `ps` are removed from `onyxdotapp/onyx-backend`; every backend tag now has a `-dev` twin (`v4.5.0-dev`, `latest-dev`) that restores them for container debugging.
  * **Helm chart 0.8.x retunes resource defaults from production fleet evidence.** API server, model server, and heavy worker requests and limits change on upgrade, the OpenSearch PVC default grows to 64Gi (existing PVCs are not resized), and the previously ignored `codeInterpreter:` resource values now live under `code-interpreter:`. A new SIZING.md documents small/medium/large tuning. Chart 0.7.0 pairs the model server with the distroless image from v4.4.0 — upgrade the image and chart together.
  * **The AWS Terraform module gains t-shirt sizing.** A `size` input (small/medium/large) sets fleet-calibrated defaults for EKS, RDS, Redis, and OpenSearch. The default medium tier keeps today's node shapes, but the new OpenSearch default is a single-node domain — applying it to an existing stack replaces the domain and its index data unless you pin the old shape — and RDS storage defaults change to gp3.
  * **Token rate limits are now enforced in whole UTC days.** Existing hour-based windows are automatically rounded up,
    and enforcement is backed by per-user daily accounting instead of scanning chat history.
  * **Self-hosted instances report a daily version heartbeat.** The existing `DISABLE_TELEMETRY` opt-out applies.

  ## Key Improvements

  ### SSO-Only Login

  Password authentication can now be disabled entirely for SSO-only deployments.
  A new toggle under Security Hardening removes the email/password form and signup links from the login page while SSO
  login and provisioning continue, with lockout guards: enabling it requires an enabled SSO provider,
  and the last enabled provider can't be disabled while password auth is off.
  PKCE and OAuth scope overrides also move from deployment-wide env vars onto each SSO provider row,
  and OIDC now works out of the box with Microsoft Entra ID (a missing `email_verified` claim is tolerated,
  with a per-provider strict opt-in)
  and Amazon Cognito (`offline_access` is only auto-requested when the IdP advertises it).

  ### Reasoning and Temperature, Per Chat

  The model selector now exposes per-model controls:
  a reasoning-effort slider (off up to extra-high where the model supports it), a temperature slider,
  and a context-window gauge. Choices persist per chat session. If a provider rejects a tuning parameter,
  Onyx retries the request without it instead of failing the chat.

  ### Box Connector

  A new [Box connector](https://docs.onyx.app/admins/connectors/official/box) indexes files, web links,
  and folder hierarchy, authenticating via Client Credentials Grant with optional user impersonation.
  Permission sync mirrors Box collaborations and shared links into document ACLs, alongside enterprise group sync.

  ### Native Azure Blob Storage File Store

  The file store gains a first-class Azure Blob Storage backend (`FILE_STORE_BACKEND=azure`),
  so pure-Azure deployments no longer need MinIO or an S3 translation proxy.
  Authentication resolves from a connection string, an account name and key,
  or `DefaultAzureCredential` — covering AKS Workload Identity and managed identities — and all file paths (user
  uploads, connector document batches, generated files) go through it.

  ## Contributor Highlights

  * [@Oht8wooWi8yait9n](https://github.com/Oht8wooWi8yait9n) extended the **SharePoint connector to OneDrive for Business and personal sites**!
  * [@markk-ns](https://github.com/markk-ns) landed two long-standing fixes: BookStack documents updated the same day now index, and the citation processor no longer corrupts code fences in streamed answers.
  * [@swissmike-zh](https://github.com/swissmike-zh) made XLSX files index their calculated cell values instead of raw formula strings.
  * [@CE11-Kishan](https://github.com/CE11-Kishan) made SharePoint indexing retry transient Graph API responses instead of aborting the attempt.
  * [@juliennonin](https://github.com/juliennonin) fixed the selected agent resetting after a page refresh.
  * [@mvanhorn](https://github.com/mvanhorn) fixed embedding models with uppercase names failing OpenSearch index creation.

  ## Additional Improvements

  ### Auth and SSO

  * IdP directory-profile enrichment extends to SAML attributes and multi-tenant deployments,
    and logins through multiple IdPs merge per-provider claim snapshots instead of overwriting each other.

  ### Connectors

  * Confluence: a per-connector toggle skips attachment indexing,
    and attachment links are fixed on Data Center instances.
  * GitHub: documents can be indexed from a specific branch (for example `gh-pages`).
  * Google Drive:
    fixed a checkpoint bug that could loop initial indexing forever (already-corrupted checkpoints self-heal on
    upgrade),
    and permission sync falls back to impersonating the retrieving user when the file owner can't be impersonated.
  * Notion: pruning streams document IDs instead of materializing the whole workspace,
    bounding worker memory on large workspaces.
  * SharePoint and OneDrive, BookStack, and XLSX parsing fixes — see Contributor Highlights above.

  ### LLM Providers

  * Portkey joins as a built-in provider with three API modes (Chat Completions, Responses, Messages);
    Bifrost providers gain the same mode selector,
    and the responses bridge is hardened against real-world gateway streaming variants.
  * Model refusals surface as "Model Declined to Respond" with the provider's reason instead of a generic empty-response
    error.

  ### MCP

  * Shared API keys support custom header templates (defaulting to `Authorization: Bearer {api_key}`).
  * Per-user OAuth "connected" status now requires stored tokens,
    token refresh is single-flighted so concurrent callers can't invalidate each other's rotating refresh tokens,
    and form-encoded token responses are accepted.
  * Servers with zero discovered tools no longer render as empty cards in the agent editor.

  ### Chat and Web

  * Disabling web search now also puts `open_url` in indexed-only mode — pasted links still resolve against connected knowledge, but nothing is fetched from the live internet.
  * Attachments with no extractable text (such as scanned PDFs)
    are explained to the model instead of handed over silently empty.
  * Chat auto-naming uses the session's model instead of the global default.
  * Slack bot answers render links, email addresses, inline code, and ordered lists correctly.

  ### Search and Indexing

  * Re-indexing shows a live progress banner with per-connector failure details;
    units that fail repeatedly auto-pause and can be resumed by an operator.
  * Documents and hierarchy nodes from private connectors now appear in the knowledge pane for users with access through
    ownership or groups.

  ### Observability and Deployment

  * Admins on Enterprise self-hosted deployments can download a zip of API server logs from the new Export Logs page.

  ### Security

  * Hook endpoint validation now follows the SSRF Protection setting,
    so hooks can target private-network services when the level allows it.
  * LLM and image-generation test-endpoint errors redact credentials.

  ### Performance

  * Opening a chat and listing chat history are backed by new database indexes,
    improving load times for large deployments.
  * The admin user list loads much faster, and chat-history search no longer blocks the event loop — under load,
    first-token latency for concurrent chats dropped from \~354ms to \~54ms in benchmarks.

  ### Notable Bug Fixes

  * Fixed a raw "Loading..." flash in the connector access selector.
  * Fixed the Linux desktop Alt-menu toggle and the missing icon in the Linux About dialog.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v4.4.0" description="July 21st, 2026">
  ## v4.4.0

  Multi-provider SSO lands — Google, OIDC,
  and SAML configured from the admin UI and served side by side on the login page — search gains time-based filtering,
  admins get broadcast announcements,
  and Google Drive and Gmail support multiple connectors with independent credentials.
  Thank you to our contributors for helping make this release possible!

  ## \[Update] Action May Be Required

  ### `AUTH_TYPE` has been removed — SSO moves to the admin panel

  SSO is now configured from **Admin Panel → Organization → [SSO
  Providers](https://docs.onyx.app/deployment/authentication/sso_providers)** instead of environment variables.
  On the first upgraded startup,
  a one-time migration seeds your existing `AUTH_TYPE` / OAuth / OIDC configuration into a provider row that keeps the
  exact redirect and ACS URLs your identity provider already allowlists — no OAuth client changes are needed.
  **Keep the legacy variables in place through the upgrade** so the migration can read them.

  After upgrading, confirm the provider appears under **SSO Providers** and that logins still work,
  then remove `AUTH_TYPE` and the legacy SSO variables — they are now inert and only emit a startup warning (the value
  still shipped in `env.template` is likewise inert).
  See the [OIDC upgrade notes](https://docs.onyx.app/deployment/authentication/oidc) for a full before/after.

  <Warning>
    If you previously ran SSO-only, the login page now also renders an email/password form alongside your SSO button(s).
    To stop un-invited people from registering,
    enable **Restrict Open Sign-Up** under **Admin Panel → Permissions → Users** — un-invited emails are then rejected
    at sign-in until an admin invites them.
  </Warning>

  ### Hardened, non-root model server and web images

  The model server and web frontend now build on distroless, hardened images: no shell or package manager,
  and they run as a non-root user.

  <Note>
    The latest versions of the Docker Compose files and Helm chart (≥ `0.7.0`)
    include these changes and can be used instead of migrating.
    The steps below can be used to update legacy deployments in place.
  </Note>

  * **Drop `command:` / `entrypoint:` overrides for these two images.** Both the web and model-server images now bake
    in their own entrypoint and can no longer run a `command:` / `entrypoint:` that wraps startup in `/bin/sh -c`.
    Remove any such override from your customized files so the image's own entrypoint runs;
    this includes the old model-server `DISABLE_MODEL_SERVER` gate, now handled inside the image.
    The API server and background images are not hardened and still rely on their stock `/bin/sh -c` commands — leave
    those as-is.
  * **Custom CA roots on the model server.** The old shell `update-ca-certificates` step is gone. Mount your
    certificates into a directory and set `ONYX_CUSTOM_CA_CERTS_DIR` to that path (files must end in `.crt` or `.pem`);
    they are merged on top of the public roots when the model server starts. On Helm, upgrade the chart (≥ `0.7.0`)
    and the image **together** — the chart mounts the certs and sets the variable for you. After upgrading,
    confirm the `Trusting N custom CA file(s)` line in the model-server logs.
    The API server and background containers are unchanged (they still read `/etc/ssl/certs/custom-ca.crt`).

  ## Key Improvements

  ### Multi-Provider SSO

  [SSO configuration](https://docs.onyx.app/deployment/authentication/sso_providers)
  has been rebuilt from the ground up. Google, OIDC, and SAML providers are managed from a new admin page — create,
  edit, and enable them without redeploying,
  with each provider showing the redirect/ACS URL to paste into your IdP console.
  The login page offers every enabled provider,
  and the OIDC client is hardened to require verified emails and issuer-owned discovery.
  A single enabled provider is available on every tier, including Community;
  running multiple providers simultaneously requires Business or above.

  ### Time-Based Search Filtering

  LLM search can now filter by time — both when a document was created and when it was last updated,
  with either bound open. Documents carry a new `created_at` field populated by connectors,
  and the filter is surfaced in the search UI alongside the source filters from v4.3.0.

  ### System Announcements

  Admins can broadcast an announcement to every user from a new System Announcement section under Appearance & Theming —
  a markdown notice with an optional pop-up on first visit. All banners (announcements, license expiry, trial notices)
  now queue in a single bottom-left stack instead of competing for space.

  ### Multiple Google Drive and Gmail Connectors

  Google service-account keys and OAuth app credentials are now stored per credential rather than per deployment,
  so you can run multiple Google Drive and Gmail connectors with independent credentials — for example,
  separate connectors per Workspace domain.

  ## Contributor Highlights

  * [@siriusfreak](https://github.com/siriusfreak) — after adding Tavily
    and Nebius Token Factory in v4.3.0 — contributed a full **LumApps connector** with checkpointed incremental indexing
    of published intranet content!
  * [@jack-watroba](https://github.com/jack-watroba) fixed MCP OAuth
    public-client PKCE registration in their first contribution!

  ## Additional Improvements

  ### Auth and Sessions

  * Session tokens now embed issue and expiry timestamps, so rejections
    are classified and the logout modal can tell you why you were signed out instead of failing generically.
  * Service-account API keys no longer 500 on `/me`, and LIMITED keys
    regain chat access.

  ### Search and Indexing

  * Indexing resumes on graceful worker shutdown — rolling deploys and
    scale-downs mark the attempt resumable instead of failed.
  * Connector creation rolls back cleanly on validation failure.

  ### Connectors

  * New LumApps connector.
  * New Canvas connector with permission sync.
  * Google Drive: domain-wide shares are scoped to a domain group
    instead of instance-public, and group sync streams folders to bound memory.
  * SharePoint: fixed group permissions and localized role names on
    non-English tenants.
  * GitHub: empty repositories no longer raise.

  ### MCP

  * Group and public access control for MCP servers — users only see and
    attach tools from servers they can access.
  * OAuth tokens refresh proactively on SSE transport, preventing
    tool-call failures on expired tokens.

  ### LLM Providers

  * Providers are grouped into labeled sections in the admin UI.
  * Claude Sonnet 5 support with adaptive thinking; Fable 5 and Sonnet 5
    join the recommended models.
  * Vision and reasoning support for dynamic providers resolves from the
    LiteLLM cost map instead of hardcoded lists.
  * Recommended model lists update automatically from the OpenRouter
    catalog.
  * Gemini `embedding-2` (GA) available for cloud embedding.
  * Image generation supports Vertex AI Workload Identity auth.

  ### Chat and Web

  * Export any chat as text or markdown from its menu.
  * Shared chats render the full multi-model comparison.
  * XLSX chat attachments render through the backend-parsed spreadsheet
    preview.
  * Voice: silent audio is gated out of chunked STT, eliminating
    hallucinated transcripts.
  * `open_url` resolves pasted Google Drive links to their indexed
    documents instead of re-crawling them from the web.
  * Dark mode persists across reloads.
  * Onyx Lite gains the Open URL tool.

  ### Desktop and Deployment

  * Windows ARM64 desktop builds, a `--version` flag, configurable
    window title, and correct sizing and title-bar behavior per platform.
  * External CloudNativePG operators supported via
    `postgresqlOperator.enabled`.
  * Worker `/metrics` serves on a dual-stack socket.

  ### Notable Bug Fixes

  * Fixed the Code Interpreter tool name colliding with OpenAI's
    reserved "python" function name.
  * Fixed the model selector losing selection across identically-named
    models and the default chip not rendering.
  * Fixed the agent editor keeping rejected file uploads in state.
  * Fixed the empty OAuth credential modal for zero-kwargs OAuth
    connectors.
  * Fixed onboarding not scrolling at small viewports.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v4.3.0" description="July 6th, 2026">
  ## v4.3.0

  SIEM-exportable audit logging, TLS and mutual TLS across the entire data plane, conversation-aware search scoping,
  hardened indexing for large files,
  and two new providers — Tavily and Nebius Token Factory — both from a first-time community contributor.
  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### Audit Logging

  Onyx now emits a normalized, SIEM-exportable audit-event stream — Splunk, Sentinel, Elastic, Chronicle,
  and AWS Security Lake can ingest it with no per-SIEM integration. Coverage spans authentication (login, logout,
  register, password reset, verification), admin configuration (LLM providers, connectors, credentials, API keys),
  access control (roles, user creation, group membership), and impersonation.
  Events are OCSF-shaped and emitted fail-safe, so audit logging can never take down a request path.

  ### TLS Across the Data Plane

  Every backend connection can now be encrypted and authenticated. Postgres:
  server certificate verification (`POSTGRES_SSLMODE` / `POSTGRES_SSLROOTCERT`)
  and mutual TLS (`POSTGRES_SSLCERT` / `POSTGRES_SSLKEY`). Redis:
  mutual TLS (`REDIS_SSL_CERTFILE` / `REDIS_SSL_KEYFILE`), covering the Celery workers too. OpenSearch:
  opt-in server certificate verification (`OPENSEARCH_VERIFY_CERTS` / `OPENSEARCH_CA_CERTS`), mutual TLS,
  and IAM (AWS SigV4) authentication. Redis Sentinel is also now supported for highly-available Redis.

  ### Conversation-Aware Search Scoping

  Internal search now decides, per call,
  which connected sources to cover based on the agent's routing instructions and the current request.
  Tell an agent "check Zendesk first, then Confluence" and the search walks those sources in order,
  falling back to everything if needed. Scoped searches show it in the timeline:
  "Searching Zendesk" instead of "Searching internal documents."

  ### Hardened Indexing for Large Files

  Large spreadsheets are now streamed row-by-row through a file-backed pipeline instead of being rendered into memory,
  so an oversized workbook can no longer OOM an indexing worker. PDF text extraction runs in an isolated subprocess,
  so a pathological PDF can't take the worker down with it.

  ### New Providers: Tavily and Nebius Token Factory

  [Tavily](https://tavily.com) joins the web-search providers as both a search and content-extraction provider.
  [Nebius Token Factory](https://tokenfactory.nebius.com)
  joins the built-in LLM providers with automatic model-catalog fetching.
  Both contributed by first-time contributor [@siriusfreak](https://github.com/siriusfreak)!

  ## Contributor Highlights

  * [@siriusfreak](https://github.com/siriusfreak) added both the Tavily
    and Nebius Token Factory providers in their first contributions!
  * [@greymoth-jp](https://github.com/greymoth-jp) fixed Enter during IME
    composition submitting list inputs — a long-standing annoyance for Japanese, Chinese, and Korean text entry!

  ## Additional Improvements

  ### Security and Hardening

  * Connector read endpoints are restricted to curators and admins;
    previously any authenticated user could read connector configs.
  * Persona owner emails and internal MCP server URLs are hidden from
    basic users.
  * Curator group writes are scoped to the groups they actually curate.
  * Optional strict CSP directives behind `WEB_STRICT_CSP_ENABLED`.
  * Helm no longer defaults the model servers and Celery workers to
    `privileged: true`.

  ### Chat and Web

  * Full-width chat mode: a per-browser toggle so messages use the whole
    window instead of the fixed reading column.
  * Chat and new-agent text bars save per-session drafts, so navigating
    away no longer loses in-progress text.
  * Code blocks highlight the full highlight.js language set, not just the
    37 most common languages.
  * Knowledge hierarchy items have copyable links, disambiguating entries
    with identical titles.

  ### Indexing and Connectors

  * A failed prune no longer re-fires on the scheduler and floods the
    cleanup queue.
  * Repeated-error connector notifications reach every active admin
    instead of a single system inbox.
  * The admin stage-metrics view covers previously untimed pipeline
    stages, exposing lock-wait and contention.
  * Jira connectors without permission sync no longer require
    permission-reading credential scopes.
  * Notion hierarchies parent correctly when children index before their
    parents; standalone databases are no longer orphaned.
  * GitHub connector setup surfaces the actual validation error instead of
    a generic failure.
  * SCIM group-membership removals from Microsoft Entra ID now sync
    correctly.

  ### Deployment

  * API-server workers, connection limit, and threadpool size are
    configurable in Helm enabling concurrency headroom for clusters that lean on long-running agent features.
  * Model-server torch threads are capped to the cgroup CPU quota,
    eliminating CFS throttling on large hosts.
  * New Celery `clear_revoked` control command wipes the fleet-wide
    revoked-task set without restarts.

  ### Notable Bug Fixes

  * Chat retention (enterprise TTL) keys off the last message time, so
    active old sessions are no longer auto-deleted.
  * Fixed files accumulating in Code Interpreter sessions.
  * Fixed identically-named MCP tools colliding.
  * Fixed Confluence group sync not receiving scoped tokens.
  * Fixed custom branding not applying to the browser tab title and
    favicon on hard refresh.
  * DOCX files are no longer duplicated as plaintext now that the frontend
    renders DOCX natively.
  * Fixed the agent claiming it lacks tools after web search when Open URL
    is disabled.
  * Fixed desktop app content rendering under the macOS title bar.
  * License expiry banner dismissals persist server-side, surviving
    cleared browser storage.
  * Secondary LLM flows are bounded by a configurable timeout, so a
    stalled provider can't hang workers.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v4.2.0" description="June 26nd, 2026">
  ## v4.2.0

  Chat runs are now durable — close the tab mid-answer and reconnect to the live stream — agent sharing gets per-share
  permissions and ownership transfer, security settings move into a runtime-configurable admin page,
  and a large indexing-memory hardening effort lands.
  Thank you to our contributors for helping make this release possible!

  ## \[Update] Defaults that Changed

  * **The API docs and OpenAPI schema are no longer publicly served.** Set
    `ENABLE_PUBLIC_DOCS=true` to restore the previous behavior.
  * **`USER_AUTH_SECRET` is now required on non-dev deployments** instead
    of silently falling back to a default.
  * **Default MinIO/S3 object-storage credentials have been hardened** —
    set explicit credentials if you relied on the previous defaults.

  ## Key Improvements

  ### Durable Chat Runs

  A chat or Deep Research run no longer lives and dies with your browser connection.
  Runs now execute to completion on the server regardless of client disconnects,
  and the stream records itself as it goes — reopen the chat from any tab and it replays what you missed,
  then continues live until the answer finishes.
  Works on both Redis and [Lite Mode](https://docs.onyx.app/deployment/getting_started/resourcing#onyx-lite)'s Postgres
  cache.

  ### Granular Agent Sharing

  Agent sharing has been rebuilt around per-share permissions. Agents now have explicit owners,
  ownership can be transferred, shares carry their own permission level,
  and editors are guarded from attaching knowledge they can't access. The share dialog was redesigned to match.

  ### Runtime Security Settings

  Security controls are moving out of environment variables and into a new admin Security page,
  backed by runtime-configurable settings. The first controls to land: **Sync Session Expiry with Identity Provider**,
  which ties session lifetime to your IdP, and **Full User Directory Visibility**,
  which controls whether non-admins can see the user directory — previously only configurable via environment variable.

  ### Flexible Chat Retention

  Chat history retention now supports a 60-day preset and a fully custom duration in days,
  so admins can match any org retention policy instead of choosing from fixed presets.

  ## Additional Improvements

  ### Security and Hardening

  * Web connector URL validation applied across all fetch paths.
  * DOCX preview output is sanitized in the file preview modal.

  ### Indexing Memory and Reliability

  * PDF text extraction switched to pypdfium2 (with pypdf fallback),
    eliminating heartbeat-timeout deaths on large PDFs.
  * Google Doc parsing is size-bounded, fixing OOM crash-loops on tenants
    with very large docs.
  * Google Drive streams documents in sub-batches to bound connector
    memory, and indexing worker memory is capped.

  ### Connectors

  * New Braintrust connector.
  * Google Drive follows shortcuts during indexing.
  * SharePoint supports targeted reindex of individual failed documents.
  * Slack: channel exclude list with optional regex, and permission sync
    scoped to configured channel filters.
  * Gong: configurable API base URL for non-US data residency.
  * Fireflies re-scans an overlap window so late transcripts aren't
    dropped.
  * Salesforce retries connections closed due to inactivity.
  * Confluence attachment links anchor to the web UI instead of a raw
    download path.
  * Notion traversal is iterative, preventing RecursionError on deeply
    nested pages.

  ### Chat and Web

  * The browser tab shows the active conversation name.
  * Context-window overflows on long threads surface a clear error
    instead of a generic failure, with a token safety margin to prevent them.
  * Pre-tool narration and tool calls render in their correct places when
    emitted in the same LLM cycle.
  * The file "Processing…" indicator stays until uploaded files finish
    indexing.
  * Chats inside a Project search only that Project's files.
  * Deleted files referenced in chat history no longer break the session.
  * Voice: markdown is stripped before TTS on the backend, and Azure STT
    failures are properly logged.

  ### Admin and Operations

  * Custom CA certificates can be mounted on all outbound-TLS pods in Helm.
  * API startup migrations can be disabled in Helm for coordinated deploys.
  * Background tabs stop polling the API forever; several admin pages
    poll only while relevant work is active.

  ### Notable Bug Fixes

  * Fixed unreachable Ollama and OpenAI-compatible model servers returning
    502 instead of a clear 400.
  * Fixed vision support detection for Bifrost, LiteLLM Proxy, and other
    dynamic providers, with a clearer error on oversized images.
  * Fixed Claude Fable 5 / Mythos 5 routing through adaptive thinking.
  * Fixed the model selector being clickable when no models exist.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v4.1.1" description="June 12th, 2026">
  ## v4.1.1

  A focused security-hardening release. Several defaults are now stricter,
  and some existing self-hosted deployments will require configuration changes before upgrading.

  ## \[Update] Action May Be Required

  ### `USER_AUTH_SECRET` is now required

  <Warning>
    On non-development deployments, the API server now **refuses to start** when `USER_AUTH_SECRET` is empty;
    previously this condition only produced a warning.
    Generate a value with `openssl rand -hex 32` and set it before upgrading.
    Fresh installs performed through `install.sh` generate one automatically.
  </Warning>

  ### Hardened default object-storage credentials

  Self-hosted MinIO/S3 no longer ships with the well-known `minioadmin` default.
  New installs through `install.sh` now generate random credentials,
  and the backend logs a warning on startup when the default is still in use. If you maintain your `.env` manually,
  set strong,
  unique values for `MINIO_ROOT_USER`/`MINIO_ROOT_PASSWORD` and the matching
  `S3_AWS_ACCESS_KEY_ID`/`S3_AWS_SECRET_ACCESS_KEY` before deploying to production.

  ### SSRF protection moved to the Security & Hardening admin page

  SSRF protection for outbound requests is now consolidated into a single **SSRF Protection** control on the **Security
  & Hardening** admin page (single-tenant deployments).
  It replaces the per-path environment variables `OPEN_URL_VALIDATE_SSRF`, `MCP_SERVER_ALLOW_PRIVATE_NETWORK`,
  `MCP_SERVER_ALLOW_LOOPBACK`, and `WEB_CONNECTOR_VALIDATE_URLS`.
  Deployments that already set any of these variables retain their behavior,
  as the setting is initialized from the matching level.
  Deployments running on the defaults move to the strictest level, Validate All, which validates every outbound path,
  including web connectors. Because web connectors were not validated by default previously,
  a connector that reached an internal or private host may now be blocked;
  select a less restrictive level on the admin page to restore that access.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v4.1.0" description="June 11th, 2026">
  ## v4.1.0

  Personal Access Tokens gain user-selectable scopes, MCP servers from known providers can be connected via OAuth,
  voice moves to OpenAI's GA Realtime API, and six new community contributors land improvements across connectors, auth,
  and LLM providers. Thank you to our contributors for helping make this release possible!

  ## \[Update] Deployment Changes

  * **The backend image has been upgraded from Python 3.11 to Python 3.13.**
    If you build custom images or install additional packages on top of the Onyx image,
    verify compatibility before upgrading.
  * **The Helm chart now fails fast on 0.4.x → 0.5.x upgrades that would
    lose Vespa data**, protecting deployments that haven't completed the OpenSearch migration from accidental data loss.

  ## Key Improvements

  ### Scoped Personal Access Tokens

  Personal Access Tokens now support permission scopes.
  Tokens can be restricted to coarse API surfaces — including `read:chat`, `write:chat`,
  and `read:search` — and users select scopes when creating a token from the settings UI.
  Existing tokens continue to work unchanged.

  ### OAuth for Known MCP Providers

  MCP servers from known providers can now be connected via OAuth directly from the authentication modal,
  with a guided connect-and-callback flow instead of manual credential entry.

  ### Voice on the GA Realtime API

  OpenAI streaming speech-to-text has been migrated from the deprecated Realtime Beta API to the GA Realtime API,
  putting voice mode on a supported foundation going forward.

  ## Contributor Highlights

  This release includes six first-time contributors!

  * [@ppomes](https://github.com/ppomes) fixed the ingestion API overriding
    document sources, corrected default temperature selection for the search tool,
    and optimized Google Drive indexing to skip unnecessary shared-drive lookups!
  * [@fejesd](https://github.com/fejesd) enabled prompt caching and sticky
    routing for OpenRouter and wired user identifiers into OpenRouter activity tracking!
  * [@amanda-nathan](https://github.com/amanda-nathan) added support for
    unauthenticated SMTP relays!
  * [@dimanjet](https://github.com/dimanjet) and
    [@mjakubowskimtt](https://github.com/mjakubowskimtt) both fixed ClickUp connector API URL handling!
  * [@psyray](https://github.com/psyray) fixed an nginx config typo in the
    no-letsencrypt compose file!

  And returning contributor [@beraterkanelcelik](https://github.com/beraterkanelcelik) made job timeouts,
  per-call MCP tool timeouts, and admin query-history visibility configurable via environment variables!

  ## Additional Improvements

  ### Connectors

  * SharePoint skips per-site Graph failures (including HTTP 423 locked
    sites) instead of aborting the entire run.
  * GitHub connector can now index repository documents.
  * S3 connector supports an optional AWS region for non-default partitions.
  * Confluence skips image attachments in the slim-doc pass when images are
    disabled, and permission sync handles draft-page 404s.
  * Jira Data Center v9 permission sync support.

  ### Auth and Security

  * CSV exports are sanitized against spreadsheet formula injection.
  * Login and signup use a native password field for proper browser
    integration.
  * Gmail addresses with dots can sign in via Google OAuth.

  ### LLM Providers

  * Claude Opus 4.8 support with adaptive thinking and corrected sampling
    parameters.
  * OpenRouter prompt caching and sticky routing.
  * Fixed embedding model staging when connecting LiteLLM and Azure
    providers.
  * Personal default models fall back to the global default when their
    provider is removed.

  ### Performance

  * Chat file bytes are lazy-loaded, eliminating an api-server OOM under
    heavy file usage.
  * Billing information and LLM provider listings are cached per tenant.
  * Frontend polling tuned: document sets only poll while syncing, and
    several SWR fetches were deduplicated.

  ### Deployment and Observability

  * Optional External Secrets Operator support in the Helm chart.
  * Opt-in structured JSON logs via `LOG_FORMAT=json`.
  * The bundled redis-operator can be disabled independently in Helm.
  * Helm child resource names are truncated to the 63-character limit.
  * Connectors page is now available in Lite mode.

  ### Notable Bug Fixes

  * Fixed empty LLM response packets causing chat failures.
  * Fixed raw answers being lost when citation processing stripped the
    content empty.
  * Fixed `doc_updated_at` being incorrectly derived from HTTP
    Last-Modified headers in the web connector.
  * Fixed search settings failing on null embedding prefixes.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v4.0.0" description="May 26th, 2026">
  ## v4.0.0

  Vespa is gone, OpenSearch is now the only document index. We're shipping an opt-in Coding Agent,
  end-to-end visibility into indexing failures, permission sync inspection tooling, a public Search API,
  and Slack Enterprise Grid support.

  Thank you to our contributors for helping make this release possible!

  ## \[Breaking] Vespa is Removed

  <Warning>
    **Do not upgrade to this release if you want to preserve your existing indexed documents but have not yet run the
    document index migration,
    which can be done from any version v3.x.** Vespa has been removed entirely in v4.0.0 and upgrading without first
    migrating will result in the loss of indexed documents and Project files,
    for which the only solution is re-indexing.

    If you are still on Vespa, upgrade to a v3.x release first, run the migration to completion, and then upgrade to v4.
    The full walkthrough remains in the [Vespa to OpenSearch migration
    guide](https://docs.onyx.app/admins/advanced_configs/opensearch_document_index_migration).
  </Warning>

  ## \[Update] Defaults that Changed

  * **DALL·E 3 has been dropped as an image generation provider.** Move to GPT
    Image 2 (added in v3.3.0) or another configured provider.
  * **Search-time image processing has been removed.** Image processing now
    happens at indexing time only.

  ## Key Improvements

  ### Coding Agent (opt-in)

  v4.0.0 introduces a new Coding Agent — a sandboxed agent with file download and bash tool access,
  available as a standalone agent and as a tool that the regular chat agent can invoke.
  The Coding Agent ships **disabled by default**;
  admins can enable and configure it from a new section of the Admin Panel.
  [More information can be found in our documentation](https://docs.onyx.app/admins/actions/coding_agent#coding-agent).

  ### End-to-End Indexing Visibility

  Admins can now see exactly what failed during indexing and resolve it without rerunning entire connectors.
  Failed documents are surfaced with the underlying error,
  individual documents have a "Resolve" button that triggers a targeted reindex for just that document,
  and a "Resolve All" action handles bulk recovery. Indexing metrics are now always visible rather than gated,
  and the indexing errors modal supports pagination through large failure lists.

  <img alt="Hook Extensions Page" />

  ### Permission Sync Visibility

  Permission sync now has dedicated admin tooling. Admins can see the state of each sync,
  inspect what was synced and what failed, and capture exception traces when syncs error.

  ### Slack Enterprise Grid

  The Slack connector now supports Slack Enterprise Grid, including cross-workspace indexing.

  ### Public Search API

  A new public `POST /api/search` endpoint and `onyx-cli agentic search` command let external systems and command-line
  workflows run searches against Onyx programmatically.

  ## Contributor Highlights

  * [@beraterkanelcelik](https://github.com/beraterkanelcelik) made
    `MAX_LLM_CYCLES` environment-configurable and fixed OIDC token refresh so it works for any OIDC provider,
    not just Google!
  * [@mikew](https://github.com/mikew) expanded LiteLLM capability support and
    added reasoning flow support for models that expose it!
  * [@k-kasajima](https://github.com/k-kasajima) fixed the LiteLLM
    embedding test model name payload!

  ## Additional Improvements

  ### Indexing and Search

  * Documents whose content hasn't changed since the last indexing run are no
    longer re-indexed.
  * Cohere `embed-v4.0` and Gemini `embedding-2-preview` are supported as
    embedding providers.
  * Query embeddings are cached for repeated queries.
  * OpenSearch bulk updates are used on the indexing hot path with
    retry-on-transient-failure semantics.
  * Oversized documents now surface a clear error instead of silently failing,
    and the `MAX_DOCUMENT_CHARS` limit has been raised.
  * Image processing has moved entirely to index time.

  ### Chat

  * The chat input bar is now `contentEditable` and supports paste-as-tile for
    attachments.
  * Queued messages now wait until the previous answer has fully rendered before
    submitting.
  * Typewriter streaming finishes faster after the LLM stream completes.
  * Tool calls can now access a `bash` tool (used by the Coding Agent).
  * All CSVs are passed to Code Interpreter for analysis.

  ### Connectors

  * **Slack Enterprise Grid** support.
  * HubSpot: search API for incremental polls and `batch_read` to eliminate N+1
    association fetches.
  * Confluence: Data Center websudo support, REST space permissions for 9.1,
    attachment downloads with non-scoped tokens, and pagination fixes.
  * Freshdesk: handle null `due_by` and paginate past 300 pages.
  * GitLab: fall back to username when GitLab masks the author name.
  * Asana: stop dropping teamless projects from explicit allowlists.
  * Jira: permission sync support for Data Center v10.

  ### Auth, Security, and Licensing

  * OIDC access tokens now refresh on every authenticated request, for any OIDC
    provider (not just Google).
  * New Business tier with unified gating middleware.
  * `OPEN_URL_VALIDATE_SSRF` opt-out flag for trusted networks.

  ### LLM Providers

  * LiteLLM capability expansion and reasoning-flow support.
  * Custom LLM providers can have optional display names and be renamed.
  * Vertex AI can use Application Default Credentials via LiteLLM.
  * GCS storage supports Workload Identity.

  ### Notable Bug Fixes

  * Fixed a tabular chunker crash on Google Sheets with multi-line cells.
  * Fixed the indexing pipeline not stopping after a document raised an error.
  * Fixed several DB-session-held-too-long issues in chat, indexing, deletion,
    and embedding paths.
  * Fixed asyncpg `statement_cache_size` regressions with pgbouncer and similar
    pool managers.
  * Fixed MCP per-user multi-header handling and OAuth token refresh.
  * Multiple Helm, OpenSearch, and tier-management fixes.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v3.3.0" description="May 4th, 2026">
  ## v3.3.0

  Spreadsheets and CSVs become first-class searchable content, and a substantial round of observability, hardening,
  and polish. Thank you to our contributors for helping make this release possible!

  ## \[Update] Defaults that Changed

  A few defaults changed in v3.3.0 that operators should be aware of before upgrading:

  * **`DANSWER_RUNNING_IN_DOCKER` was renamed to `ONYX_RUNNING_IN_DOCKER`.** If
    you set this environment variable explicitly, update it.
  * **`POSTGRES_POOL_PRE_PING` now defaults to `true`.** This makes database
    connection handling more resilient by default; set it to `false` to restore the previous behavior.

  ## Key Improvements

  ### Tabular File Indexing

  Spreadsheets and CSVs are now indexed as structured tabular content rather than flattened text.
  A new section-based chunking pipeline emits field-value chunks, per-sheet descriptors, and whole-file summary chunks,
  so questions more accurately choose the right XLSX or CSV document, which the llm can then interpret.
  Tabular files are supported across the file upload path and the Google Drive, Blob, and SharePoint connectors.

  ### Smoother Chat Streaming

  Chat responses now stream at the character level for a noticeably smoother reading experience,
  with live LaTeX rendering as math streams in. If you prefer the previous behavior,
  smooth streaming can be turned off in chat preferences.

  ## Contributor Highlights

  * [@jaffarkeikei](https://github.com/jaffarkeikei) fixed inverted
    `already_existed` logic in the ingestion API response!
  * [@aserafin-mtt](https://github.com/aserafin-mtt) fixed MCP Langfuse
    tracing and Jira ADF parsing!
  * [@Mberga14](https://github.com/Mberga14) fixed a `Button`/`button`
    case-split that broke Linux builds and added support for extra manifests in the Helm chart!

  ## Additional Improvements

  ### Authentication and Security

  * Chat file downloads have hardened authorization.
  * New `USER_DIRECTORY_ADMIN_ONLY` flag to restrict non-admins from sharing
    agents with individual users.

  ### Indexing and Search

  * Image extraction from PDF files.
  * Indexing is more resilient: staged-file handling, orphan file cleanup,
    and document processing that no longer dies mid-run on individual failures.
  * Option to run Onyx with OpenSearch only, fully disabling Vespa.

  ### Chat

  * Queued messages — send a follow-up while a response is still generating.
  * Multi-model chat refinements: inline citation chips in panels, isolated
    streaming errors per panel, and numerous UI polish fixes.
  * Scrollable tables with an overflow fade in chat responses.
  * GPT Image 2 support for image generation.
  * Anthropic Opus 4.7 added to the recommended models.

  ### Connectors

  * Gong connector converted from polling to checkpointed indexing.
  * HubSpot connector made significantly more efficient with fewer API calls.
  * Confluence: 504 retry with smaller page size, plus `/Date` macro and
    Cyrillic encoding fixes.
  * Google Drive: handles refresh errors for removed Workspace users and skips
    redundant folder walks during pruning.
  * SharePoint: several pruning crash and permission-validation fixes.

  ### Notable Bug Fixes

  * Fixed XLSX handling: streaming extraction to reduce peak memory, a hard cell
    limit, XLSM support, and several formatting issues.
  * Fixed the LLM selector to show each provider instance as its own group.
  * Fixed model reasoning fields unexpectedly returning `None`.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v3.2.0" description="April 9th, 2026">
  ## v3.2.0

  Multi-model chat lets you run a prompt across several models at once and pick the best response,
  a generic OpenAI-compatible provider opens the door to any LLM endpoint,
  the indexing pipeline gets a significant performance rework,
  and the Hook system matures with a second hook point and admin status views.
  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### Multi-Model Chat

  You can now send a single prompt to multiple models in parallel and compare their responses side by side.
  Pick the response you like best to continue the conversation with that model, or deselect to keep exploring.
  Multi-model is wired through the chat UI and the Chrome extension.

  <img alt="Multi-Modal Chat" />

  ### Generic OpenAI-Compatible Provider

  Onyx now ships a generic "OpenAI Compatible" provider that lets you point at any OpenAI-compatible endpoint — local
  inference servers, gateway proxies, or self-hosted model runners — without needing a dedicated integration.
  The Custom LLM provider configuration was also reworked to support this cleanly.

  ### Hooks: status, logs, and document ingestion

  The Hook system introduced in v3.1.0 has matured. A new admin page lets you create, edit,
  and monitor hooks with live status and logs,
  and a second integration point — document ingestion — joins query processing in the set of hookable lifecycle events.
  Connection-lost states surface clearly in the UI when a hook becomes unreachable.

  <img alt="Hook Extensions Page" />

  ## Contributor Highlights

  * [@alex000kim](https://github.com/alex000kim) added an optional CA
    certificate update step to the api-server startup in the Helm chart,
    making it easier to deploy Onyx behind corporate TLS-inspecting proxies!

  ## Additional Improvements

  ### [Onyx CLI](https://docs.onyx.app/overview/onyx_anywhere/cli)

  * `onyx-cli serve` over SSH for working with remote deployments
  * `onyx install-skill` command
  * Version compatibility check between CLI and backend
  * Streaming markdown rendering in CLI output
  * [Agent-friendly output mode](https://docs.onyx.app/overview/onyx_anywhere/cli#using-as-an-ai-coding-assistant-skill)

  ### Connectors

  * Notion connector now extracts people properties and inline table content
  * Discord connector validates tokens up front

  ### Chat and search

  * Files exceeding the token limit can still be uploaded; only indexing is
    skipped
  * Citation badges in the embedded chat widget

  ### LLM providers

  * Generic OpenAI-Compatible provider type
  * Custom LLM provider configuration revamp, with first-class fields
    extracted from the key-value list
  * Force-delete supported for the last remaining LLM provider

  ### Auth and Security

  * Migrated limited-role checks to account-type-based access control
  * Default Admin and Basic user groups are now seeded automatically

  ### Performance

  * Chat sessions query optimized to prevent cascading DB failures under load
  * Many client-side requests migrated to SWR with a centralized key registry,
    eliminating duplicate fetches and stabilizing revalidation behavior
  * Removed unnecessary user-memory eager loads from auth paths
  * Indexing pipeline streams chunks through a unified iterable-based
    abstraction with batched processing, improving memory usage and throughput on large corpora

  ### Deployment and Observability

  * Grafana dashboard provisioning via Helm, with a dedicated OpenSearch
    retrieval dashboard
  * AWS deployment additions: RDS snapshots, EKS CloudWatch logging, RDS CPU
    / memory / IO alerts, and support for multiple Postgres hosts

  ### Notable Bug Fixes

  * Fixed owner-password-only PDFs being incorrectly rejected as protected
  * Fixed XLSX empty row/column handling
  * Fixed PowerPoint chart conversion failing during indexing
  * Fixed paused file connectors not reindexing correctly
  * Fixed MCP server propagating generic error messages instead of the real
    cause
  * Fixed mobile sidebar overlapping content on medium-sized screens, plus
    several other sidebar and modal responsive issues
  * Fixed default-provider selection when multiple providers share the same
    type

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v3.1.0" description="April 1st, 2026">
  ## v3.1.0

  Voice mode lands, the new Hook system opens up Onyx for extension,
  the Admin Users and Groups pages get a full rewrite, and we've added two new LLM gateway providers.
  Thank you to our contributors for helping make this release possible!

  ## \[Update] Defaults that Changed

  Two default behaviors changed in v3.1.0 that operators should be aware of before upgrading:

  * **OpenSearch admin password default removed.** The standard
    `docker-compose.yml` no longer ships a fallback for `OPENSEARCH_ADMIN_PASSWORD`.
    If you previously relied on the default, set the password explicitly in your environment before upgrading.

  ## Key Improvements

  ### Voice Mode

  [Onyx now supports voice conversations
  end-to-end](https://docs.onyx.app/overview/core_features/voice_mode#voice-mode).
  [Speech-to-text and text-to-speech are configurable from the Admin
  Panel](https://docs.onyx.app/admins/actions/voice_mode#voice-mode),
  and chats can be revisited with their voice playback intact.

  <img alt="Voice Admin Page" />

  ### Hooks

  Onyx now ships a first-party Hook system for extending behavior at well-defined points in the request lifecycle.
  [Hooks are managed from a new admin page](https://docs.onyx.app/admins/advanced_configs/hook_extensions#hooks),
  configured through a connect/manage modal, and currently integrate with the query-processing pipeline,
  with more hook points planned.

  ### Redesigned Admin Users and Groups

  The admin Users page has been rebuilt from the ground up with a stats bar, server-side pagination,
  role/group/status filters, inline role editing, an invite flow, and edit-group-membership.
  The Groups page is also new, with list and create/edit pages, inline renaming, shared resources,
  and token-limit configuration.

  <img alt="Users and Requests Admin Page" />

  ### LiteLLM and Bifrost gateway providers

  Two new LLM gateway integrations join the provider list:
  [**LiteLLM**](https://docs.onyx.app/admins/ai_models/litellm_proxy),
  which auto-fetches available models from your LiteLLM proxy,
  and [**Bifrost**](https://docs.onyx.app/admins/ai_models/bifrost#bifrost),
  configurable from a dedicated provider modal.
  Both make it easier to centralize model access and routing through your existing infrastructure.

  ## Contributor Highlights

  * [@Fizza-Mukhtar](https://github.com/Fizza-Mukhtar) fixed an LLM bug where
    Onyx was sending `tool_choice` even when no tools were provided!
  * [@ciaransweet](https://github.com/ciaransweet) corrected the OpenSearch
    admin password `secretKeyRef` documentation in the Helm values file!
  * [@benwu408](https://github.com/benwu408) contributed the initial scaffold
    for a new Canvas connector!

  ## Additional Improvements

  ### Connectors

  * SharePoint connector gained deduplication, filters/denylists, non-public
    shareable links, and better error logging
  * Notion connector upgraded to the latest API version
  * Confluence client retries on transient failures
  * Jira large-batch JSON decode fix
  * Google Drive: rate-limit retry and fallback access path for externally
    owned items
  * Discord connector now properly cleans up async resources

  ### Agents and Chat

  * Tool call arguments now stream live, with a delta-based jsonriver
    implementation

  * Custom tools have improved error handling and a refreshed timeline UI

  * Configurable file upload size limit, with a frontend precheck for oversized
    uploads. This can be configured in the Admin Panel, under Advanced Options for Chat Preferences.

    <img alt="File Attachment Size Limit" />

  * More file types can be attached to chats, and the file preview supports
    significantly more formats.
    File types which are not explicitly supported/recognized are parsed using a text-detection heuristic.

  * Slackbot now resolves channel references and can filter search results by
    channel

  * Search state machine consolidated for more predictable behavior

  ### Auth and Security

  * PKCE support for OIDC

  ### LLM providers

  * LiteLLM and Bifrost gateways
  * All provider types can now be deleted (previously some were soft-locked)
  * Editing an LLM provider correctly uses the global default model
  * Surface masked OpenAI quota failures so users see a real error
  * Filter embedding models out of LiteLLM model lists

  ### Performance

  * Stop deep-copying during indexing
  * Plaintext file results are now cached in chat
  * OpenSearch tuning continues with configurable shards/replicas, configurable
    Vespa migration page size, configurable hybrid subquery hits, vectors excluded from hybrid/random search payloads,
    and Prometheus metrics for retrieval

  ### Deployment

  * Windows installer
  * Terraform module for OpenSearch on AWS
  * Configurable `api_server` resource limits in Docker
  * Reusable Prometheus metrics server for Celery workers, with queue depth,
    connector health, task lifecycle, and per-connector metrics

  ### Notable Bug Fixes

  * Fixed CSV inline display responsiveness and comma-literal parsing
  * Fixed memories immediately losing focus on click
  * Fixed numerous modal centering, popover, sidebar, and Safari-specific UI
    issues

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v3.0.0" description="March 9th, 2026">
  ## v3.0.0

  The Vespa to OpenSearch migration is here, SCIM 2.0 lands for Enterprise,
  search and chat are unified into a single experience, Code Interpreter ships by default,
  and Onyx Lite and the Onyx CLI debut. v3.0.0 is the largest release we've ever cut.
  Thank you to our contributors for helping make this release possible!

  ## \[Update] OpenSearch Migration

  v3.0.0 ships the full Vespa to OpenSearch migration toolchain.
  OpenSearch now runs alongside Vespa in the standard `docker-compose.yml` and Helm chart,
  and admins get a new Migration tab in the Admin Panel for kicking off and monitoring the migration with live progress.

  Vespa continues to serve all queries throughout the migration by default. Once the migration completes,
  admins can switch Onyx to read from OpenSearch.
  Setup details and guidance live in the [OpenSearch deployment
  guide](https://docs.onyx.app/deployment/local/opensearch),
  and the full migration walkthrough is in the [Vespa to OpenSearch migration
  guide](https://docs.onyx.app/admins/advanced_configs/opensearch_document_index_migration).

  ## Upgrade Path to v4.0.0

  v3.0.0 starts the final stretch of the Vespa to OpenSearch migration.
  **Every deployment must run a v3.x.x release long enough for the migration to complete before upgrading to v4.x.x,
  where Vespa will be fully removed.** If you skip v3 entirely,
  you will lose all of your indexed data and have to re-index from scratch — including re-uploading any Project files.

  ## Key Improvements

  ### SCIM 2.0 User and Group Provisioning

  Onyx Enterprise now ships a complete SCIM 2.0 implementation. Identity providers like Okta and Entra ID can create,
  update, and deactivate users and groups against Onyx via the standard `/scim/v2/*` endpoints with bearer-token auth.
  Admins can mint and rotate SCIM tokens from a new section in the Admin Panel,
  and we've passed Okta's Runscope spec test for OIN submission.
  [More details can be found in our documentation.](https://docs.onyx.app/deployment/authentication/scim#scim)

  ### Unified Search and Chat

  Search and chat are now driven from the same input bar, with smooth animated transitions between modes.
  Whether you're asking a question of an agent or running a quick keyword search across your knowledge base,
  you start in the same place.

  ### Code Interpreter, by default

  Code Interpreter is now part of the default deployment for both Docker and Helm — no extra setup required.
  Sessions stream output as they run, accept file inputs, embed generated images directly into chat,
  and ship with rich preview modals for CSV, PDF, and DOCX outputs.
  The Python tool is also enabled by default on the default agent.
  [More information can be found here.](https://docs.onyx.app/admins/actions/code_interpreter)

  ### Onyx CLI

  A new command-line tool for working with Onyx, distributed as a PyPI package and a Docker image.
  Look for `onyx-cli` to grow over the next few releases.
  [Get started here.](https://docs.onyx.app/overview/onyx_anywhere/cli#cli)

  ### Onyx Lite

  A new "lite" deployment mode for installations that don't need a vector database.
  Onyx Lite runs without the indexing stack and is suitable for chat-only and tooling-focused use cases.

  ## Contributor Highlights

  * [@victoriamreese](https://github.com/victoriamreese) added a configurable
    MCP host setting and continued to harden Helm and KEDA scaling for self-hosted deployments!

  ## Additional Improvements

  ### Connectors

  * SharePoint connector received a major scalability rework, including delta
    sync, more resilient credential refresh, better permission sync,
    and substantially better throughput on large multi-site tenants
  * Slack connector can now optionally include bot messages during indexing
  * Slack bot responses convert markdown tables to a Slack-friendly format and
    sanitize HTML and broken citation links
  * Confluence and Google Drive connectors are now backed by hierarchy nodes for
    more accurate pruning

  ### Agents and Chat

  * Featured agents with labels can be highlighted in the agent picker without
    being public
  * New chat sharing UI with cleaner permissioning
  * Refreshed admin Chat Preferences page
  * Infinite scroll in the chat session sidebar
  * Configurable MCP host setting
  * Tab reading from the Chrome extension side panel
  * Tooltip and timeline polish, including better tool status messages and a fix
    for double-collapse in agent timelines
  * Throughout the codebase and UI, "assistant" identifiers have been renamed to
    "agent" for consistency, and "LLM Models" is now "Language Models"
  * LM Studio is available as a new LLM provider

  ### Auth and Licensing

  * Enterprise license enforcement is now on by default; deployments without a
    valid license fall back to a gated mode
  * Slack users are excluded from seat counts; deactivated Slack users can be
    reactivated when seats are available
  * New invite-whitelist setting with a dedicated "account blocked" page for
    users outside the whitelist

  ### Deployment and Helm

  * Production Prometheus instrumentation for the API server, including
    SQLAlchemy connection pool and per-tenant metrics
  * Code Interpreter is included in the default Docker and Helm deployments
  * New Postgres-backed cache backend abstraction for caches that previously
    required Redis

  ### Notable Bug Fixes

  * Fixed Bedrock tool calling configuration and tool content handling without
    `toolConfig`
  * Fixed Vertex AI Claude Opus 4.6 model selection and sorted Vertex model
    names
  * Fixed Ollama context-window passthrough, content skipping, and DeepSeek
    handling
  * Fixed desktop app link clicking behavior
  * Fixed basic users being unable to share agents
  * Fixed `/llm/provider` returning a filtered set of providers
  * Fixed model configuration not populating during sync
  * Fixed metadata file handling for larger ZIPs
  * Fixed SharePoint credential refresh and `driveItem` permission sync
  * Fixed `open_url` on non-normalized URLs and SearXNG web search
  * Fixed search tool being enabled when no knowledge sources were selected
  * Fixed Google connectors redirecting to an auth error page after disconnect
  * Fixed Gong connector to respect the `Retry-After` header
  * Multiple UI fixes across modals, dropdowns, sidebar, whitelabel logo, code
    blocks, popovers, and the projects modal

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.12.0" description="March 1st, 2026">
  ## v2.12.0

  A redesigned agent message experience, Brave web search, and the OpenSearch migration enters its final stretch.

  Thank you to our contributors for helping make this release possible!

  ## \[Update] OpenSearch Migration

  We've begun migrating Onyx Cloud to OpenSearch! So far,
  the migration has progressed smoothly and we expect it to be completed by the end of the week.

  The v3.0.0 beta tag should be promoted very soon.

  As a reminder, everyone must upgrade to a v3.x.x version before moving on to v4.x.x,
  where Vespa will be fully removed.

  ## Key Improvements

  ### Redesigned Agent Message Timeline

  Agent messages have been refreshed with a new timeline experience.

  When an agent processes your request, you now see a step-by-step,
  expandable timeline showing exactly what the agent is doing.

  <img alt="Agent Message Timeline" />

  ### Brave Web Search

  Brave is now available as a web search provider!

  Configure it via the Web Search page in the Admin Panel with your Brave API key.

  <img alt="Brave Web Search" />

  ### Chat History Compression

  Long conversations now automatically summarize older messages to keep context windows efficient.

  This reduces token consumption for extended chats while preserving the key information from earlier in the
  conversation.

  ## Contributor Highlights

  * [@victoriamreese](https://github.com/victoriamreese) enabled optional host settings and resolved pod label duplication in Helm charts!

  ## Additional Improvements

  ### Chat and Project Search

  You can now search across your chat history and projects directly from the sidebar.

  The new command menu supports keyboard navigation, infinite scroll,
  and fast filtering to quickly find past conversations.

  ### Helm and Infrastructure

  * Added health probes for all containers in Helm charts
  * Fixed Ingress template generation
  * Fixed PostgreSQL operator labeling
  * Improved IRSA support by passing the correct AWS region

  ### Notable Bug Fixes

  * Fixed Bedrock tool calling configuration
  * Fixed Ollama model selection in the UI
  * Fixed desktop app link clicking behavior
  * Fixed LLM provider configuration not syncing model flow data
  * Fixed search tool being enabled when no knowledge sources were selected
  * Fixed private models appearing in Agent creation
  * Fixed LLM read timeout handling
  * Fixed Asana connector workspace/team ID mismatch
  * Fixed Salesforce connector cleanup logic
  * Multiple UI fixes across modals, dropdowns, agent creation, and sidebar rendering

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.11.0" description="February 18th, 2026">
  ## v2.11.0

  Custom chat backgrounds, a refreshed user settings page, the desktop app matures,
  and continued progress on the OpenSearch migration.

  Thank you to our contributors for helping make this release possible!

  ## \[Update] OpenSearch Migration

  Our migration from Vespa to OpenSearch (announced in [v2.8.0 notes](#\[announcement]-vector-database-migration))
  continues to make good progress.

  We've successfully migrated our internal Onyx instance to OpenSearch!
  The migration processed \~200k chunks/hour on a Helm-based cluster with 128GB Vespa (r6i.4xlarge nodes),
  8GB OpenSearch, and 8GB migration worker memory limits.

  Remaining work includes polishing the migration flow, improving performance, and final QA. We expect v3.0.0,
  the stable release of the OpenSearch migration, to be released in the final week of February.

  ## Key Improvements

  ### Custom Chat Backgrounds

  You can now personalize your chat experience with custom backgrounds!
  Choose from a selection of options in the new Appearance section of the User Settings page.

  <img alt="Custom Dark Chat Backgrounds" />

  <img alt="Custom Light Chat Backgrounds" />

  ### Refreshed User Settings Page

  The user settings page has been completely redesigned with a cleaner layout and better organization,
  making it easier to manage your profile, preferences, and backgrounds all in one place.

  <img alt="Refreshed User Settings Page" />

  ### Desktop App Updates

  The Onyx Desktop App received several important updates in this release:

  * **Domain configuration** — You can now configure which Onyx instance the desktop app connects to directly from the
    app
  * **Proper macOS code signing** — The Mac app is now properly signed, so you won't see Gatekeeper warnings on install
  * **Light/dark mode** — The desktop app now correctly reflects your theme preference

  ## Contributor Highlights

  * [@ciaransweet](https://github.com/ciaransweet) clarified the send-chat-message API docs to document the `ChatFullResponse` response model!

  ## Additional Improvements

  ### User MCP Actions

  Users can now attach MCP actions to their agents directly.
  This is an early step toward giving all users the ability to extend their agents with custom tools and integrations.

  ### Allow No System Prompt

  Agents can now be configured with no system prompt,
  giving you full control over the model's behavior for use cases that require an empty system context.

  ### Prompt Shortcuts

  Prompt shortcuts now enforce uniqueness constraints and received several usability enhancements.

  ### Notable Bug Fixes

  * Fixed Azure OpenAI tool calling and LiteLLM Azure model streaming issues
  * Fixed streaming text appearing in bursts after citations
  * Fixed citation sidebar not appearing for web\_search-only assistants
  * Fixed Ollama model selection in the UI
  * Fixed Asana connector workspace/team ID mismatch
  * Fixed Salesforce connector cleanup logic
  * Improved Slack query expansion to filter garbage from person names
  * Added Redis TTLs to prevent potential memory issues
  * Multiple UI fixes across modals, dropdowns, LLM provider configuration, and agent creation

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.10.0" description="January 31st, 2026">
  ## v2.10.0

  An update on the OpenSearch migration, Onyx in your Discord server, expanded image generation support,
  and multilingual Deep Research.

  Thank you to our contributors for helping make this release possible!

  ## \[Update] Vector Database Migration

  A small change in plans for our migration from Vespa to OpenSearch (announced in [v2.8.0
  notes](#\[announcement]-vector-database-migration)).

  Instead of v2.11.0, the migration version will be **v3.0.0**. Vespa will be deprecated in **v4.0.0**.

  Our intention is that everyone must upgrade to a **v3.x.x** version before moving on to **v4.x.x**. Additionally,
  we do not anticipate many minor versions of v3 before moving to v4.

  <Note>
    If you skip a v3 version, you will lose all of your indexed data!
    This means re-indexing all of your data and re-uploading your files in Projects.
  </Note>

  Everything else remains the same. When you upgrade to a v3 version,
  admins will be prompted to start the migration process and Vespa will continue to power your search until v4.0.0.

  To accomodate this change, our timeline has been pushed by 2 weeks:

  * **v3.0.0 Beta** will be released in the second week of February
  * **v3.0.0 Stable** is slated for the third week of February

  We will continue to share details, migration guides, and any changes to the plan moving forward!

  ## Key Improvements

  ### Onyx Discord Bot

  You can now chat with your agents and search your knowledge base directly from Discord!

  OnyxBot is available in our [Discord server](https://discord.gg/4NA5SbzrWb).
  Just tag `@onyxbot` in your message to start a conversation.

  You can install our [official OnyxBot Discord app](https://discord.com/oauth2/authorize?client_id=1460722463431327804)
  or deploy your own Discord bot with your self-hosted Onyx instance.

  Check out the [Discord Bot documentation](/admins/miscellaneous/discord_bot) to get started!

  <img alt="Onyx Discord Bot" />

  ### Nano Banana Image Generation

  You can now configure Nano Banana as an image generation provider.

  Add Vertex AI credentials in the **Image Generation** page of the Admin Panel to use Gemini 2.5 Flash Image (Nano
  Banana) and Gemini 3 Pro Image (Nano Banana Pro).

  <img alt="Nano Banana Image Generation" />

  ### Multilingual Deep Research

  Our Deep Research mode was previously biased toward English responses.
  We've tuned it to work and respond in the language you ask your question in,
  making Deep Research more accessible for international users.

  <img alt="Multilingual Deep Research" />

  ## Additional Improvements

  ### Slack Connector Restored

  Slack has rolled back changes to their API that previously prevented indexing. For the time being,
  we recommend using the indexing connector if possible, as the search quality is significantly better.

  If you don't see the indexing connector, make sure you've removed all Slack Federated connectors first.

  <Info>
    Note that if you switch from the federated connector,
    you will lose access to searching group DMs and direct messages.
  </Info>

  Read more about the [Slack connector](/admins/connectors/official/slack/slack_indexed)
  and [Slack Federated connector](/admins/connectors/official/slack/slack_federated) in our documentation.

  ### Agent Access Controls Restored

  User and group access configuration was briefly removed from the Agent configuration page during refactoring.
  This interface has been restored!

  <Info>
    Pre-existing agents that had access controls configured continued to respect those settings during this period.
  </Info>

  ### Empty Packets Fix

  If you've encountered an error like "message failed due to empty packet," we've implemented a fix and you should no
  longer see this issue. This fix was particularly targeted at models hosted with vLLM.

  ### Chat Naming Fix for Long Messages

  Previously, if your very first interaction was too long,
  the chat session could be renamed to an error message about exceeding context limits.
  We've adjusted this behavior and chat naming now works correctly regardless of message length.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.9.0" description="January 21st, 2026">
  ## v2.9.0

  Two brand new ways to access Onyx and a bumper crop of bug fixes!

  Thank you to our contributors for helping make this release possible.

  ## Key Improvements

  ### Onyx Chrome Extension

  Chrome(-ium) users can now have Onyx in every tab! The Onyx Chrome Extension brings your Agents, chat,
  and search to where you are.

  Features include:

  * **Quick-access address bar** - Type your question directly in the address bar
  * **New-tab page** - Start every browsing session with Onyx
  * **Contextual insights** - Highlight any text on a webpage and birng it into your chat
  * **Always-on sidebar** - Open Onyx as a sidebar on any webpage

  Check out the [Chrome Extension](/overview/onyx_anywhere/chrome_extension) page to get started!

  <img alt="Onyx Chrome Extension" />

  ### Onyx Widget

  You can now embed an Onyx chatbot into any website!
  Easily add an AI agent or knowledge search to your website with a single line of code.

  The widget abstracts our chat API and can be configured to use our Cloud or your self-hosted instance of Onyx.

  <Info>
    Requests from the widget must use an Onyx API key.
    We recommend using a Limited API key and monitoring usage to avoid unexpected costs.
  </Info>

  Read more about [deploying the widget here](/deployment/configuration/website_widget)
  or check out the [widget README](https://github.com/onyx-dot-app/onyx/blob/main/widget/README.md)!

  <img alt="Onyx Widget" />

  ## Contributor Highlights

  * [@coreyauger](https://github.com/coreyauger) updated some out-of-date links in our READMEs!

  ## Additional Improvements

  ### In-app Notifications System

  We've added a new notifications system to Onyx! You'll see in-app release notifications and feature announcements.

  We have no intentions to spam 😅! Depending on feedback, we can add or remove notification frequency.

  \--

  Editor's note: Apologies for the belated release of the v2.9 notes.
  It's been a busy start to 2026 and we'll try to resume our regular schedule of releases.

  As always, our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.8.0" description="January 13th, 2026">
  ## v2.8.0

  Big cost savings, better cost tracking (and observability), and a heads up for v2.11!

  Thank you to our contributors for helping make this release possible!

  ## \[Announcement] Vector Database Migration

  We've recently made the decision to migrate the Onyx vector database from Vespa to OpenSearch.
  OpenSearch is a FOSS fork of ElasticSearch, and will be deployed similarly to the existing `index` container.
  We expect OpenSearch to be easier to develop with, provide equal if not better search performance, and, importantly,
  have a smaller memory footprint.

  <Note>
    The official migration from Vespa to OpenSearch will begin in February, 2026, with the **v2.11.0** release.
  </Note>

  In v2.11.0, admins will be prompted to start a migration process,
  which will copy over all indexed data from Vespa to OpenSearch.
  Onyx will remain fully functional with Vespa in this version.

  Following v2.11.0, we plan to release v3.0.0, which will use OpenSearch exclusively.

  This timeline is not set in stone.
  We will publish a detailed migration guide in the coming weeks and communicate any changes!

  <img alt="Onyx X OpenSearch" />

  ## Key Improvements

  ### Prompt Caching Cost savings

  We've added prompt caching support for providers that require explicit caching parameters.

  This could reduce total LLM costs by up to 50-90%, depending on your usage patterns and your models/providers.
  Anthropic, Gemini, and Bedrock users should see the largest savings.

  <Info>
    You may not see any cost reduction if you are using OpenAI or Azure OpenAI,
    since they implicitly cache prompts for models newer than GPT-4o.
  </Info>

  ### Cost Tracking

  We've added LLM cost tracking and time to first token metrics for tracing providers like Braintrust.

  See our [deployment configuration docs](/deployment/configuration/configuration#observability)
  for how to set up observability for your deployment.

  ## Additional Improvements

  ### Azure Image Generation Models

  Added support for Azure image generation models for GPT Image 1.5 and GPT Image 1.

  ### Various Bug Fixes and Improvements

  * Agents can now "open" PDF files to read their contents in the internal search flow
  * Fixed a web connector bug where certain pages served as raw bytes were not being parsed as text
  * Fixed Mistral model tool calling support
  * Multiple fixes to frontend styling, component rendering, markdown formatting, and performance

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.7.0" description="January 7th, 2026">
  ## v2.7.0

  A brand new Agent creation page, LLM configuration forms saw some love, and a new Image Generation page!

  Thank you to our contributors for helping make this release possible!

  <Warning>
    v2.7.0 introduces [a new API](/developers/guides/chat_new_guide) for sending messages to Onyx.

    The old `/chat/send-message` and `/chat/send-message-simple-api` endpoints will be removed by Feb 1st, 2026.
  </Warning>

  ## Key Improvements

  ### Agent Creation

  The Agent creation page received a makeover!

  The form is now simpler, more intuitive, and matches the (sleek and beautiful)
  design of the rest of the Onyx interface.

  <img alt="Agent Creation Page" />

  ### Image Generation Configuration

  Gone are the days of setting environment variables for image generation.
  There's a new page for configuring image generation models in the Admin Panel.

  You can re-use your existing OpenAI API key or setup new OpenAI or Azure providers.
  Nano Banana support is coming soon!

  <Info>
    If you've previously set up an image generation model via environment variables,
    you will need to create a new configuration via the Admin Panel to continue generating images.
  </Info>

  <img alt="Image Generation Configuration Page" />

  ### New LLM Configuration Forms

  The LLM configuration form also received a refresh in this release.

  If you're using OpenAI, Anthropic, Vertex/Gemini, or OpenRouter,
  you can now set the providers to "auto-update" and display the latest, most recommended models.

  <Note>
    The auto-update feature requires an internet connection to GitHub to fetch our recommended models list.
  </Note>

  <img alt="LLM Configuration Forms" />

  ## Additional Improvements

  ### MCP Server Deployment

  The Onyx MCP Server is now disabled by default in the `docker-compose.yml` file.
  You will no longer see the container start and stop (when disabled) in Docker.

  To deploy the MCP Server,
  you will need to set `MCP_SERVER_ENABLED=true` in your environment and uncomment the MCP Server section in your
  `docker-compose.yml` file.

  ### Model Server Changes

  Multiple custom models were removed from the model server image. As a result,
  Onyx's total disk and memory footprint was reduced!

  ### New Cloud Usage Limits

  We've recently seen a wave of abuse of our Cloud service's free LLM access. Moving forward,
  if you use our provided LLM keys, you'll see a weekly limit on LLM usage cost.

  If you run into this limit, feel free to reach out to us at [hello@onyx.app](mailto:hello@onyx.app), and we'll be happy to help!

  <Tip>
    These changes only apply if you use Onyx-provided LLM keys on [Onyx
    Cloud](https://cloud.onyx.app?utm_source=docs\&utm_content=changelog).
  </Tip>

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.6.0" description="December 30th, 2025">
  ## v2.6.0

  Welcome to the Onyx v2.6.0 release notes!

  This is one of our **largest releases to date**, and it includes a completely rebuilt chat experience,
  the Onyx Desktop App and MCP Server,
  and smarter model management that brings you the latest models from your providers without additional effort.

  Thank you to our contributors for helping make this release possible!

  <Note>
    **Known issue in v2.6.0:** During an embedding model swap,
    you will not be able to search your knowledge base until the swap is complete.
    This functionality will be restored in the next major release.
  </Note>

  ## Key Improvements

  ### Chat Experience Revamped

  In v2.0.0, we overhauled the visual design of Onyx. In this release,
  we've dug into the chat internals to make it more powerful, work with more models,
  and ultimately deliver the best LLM experience possible.

  To do this, we've built custom architecture for managing conversations and context, introduced parallel tool calling,
  and added the ability to invoke agents as tools in the chat.

  The result is an AI chat experience where your agent can find information from your knowledge base and the internet,
  keep only the most relevant information in context, call tools precisely when needed,
  and answer your questions quickly and accurately.

  Our Deep Research mode makes use of all of these new features. Try it out and let us know what you think!

  <img alt="Deep Research with new chat capabilities" />

  ### Dynamic Model management

  No more redeploying to access new models. Onyx now fetches model information dynamically with richer metadata,
  which means:

  * New models are automatically retrieved and work out of the box, including vision-capable models
  * Deprecated models are automatically hidden from your interface
  * When max tokens can't be detected, we now fall back to 32k instead of the previous 4k limit

  Note that admins will still need to make new models visible for end users via the LLM configuration page.

  <img alt="Dynamic model management" />

  ### Onyx MCP Server

  Bring Onyx directly into your development workflow with our new MCP server!

  Connect Onyx to Claude Code, your terminal, or any MCP-compatible client.
  Authenticate with your PAT or API key and access your document index and web search capabilities without leaving your
  tools.

  Upcoming features include OAuth authentication and uploading and managing files.

  <img alt="Onyx MCP Server" />

  ### Onyx Desktop App (Preview)

  We're developing a native desktop application! The Onyx desktop app will be available on Windows, macOS, and Linux.
  If you would like to try it out,
  you can download the app from the [v2.6.0 release
  page](https://github.com/onyx-dot-app/onyx/releases/tag/v2.6.0#:~:text=21%20other%20contributors-,Assets,-10).

  Through the desktop app, you can access Onyx Cloud or your self-hosted instance.

  <img alt="Onyx Desktop App" />

  <Warning>
    The Onyx desktop app is currently published as a development/preview build.
    Please be aware that there may be bugs and issues.
    Documentation will be available when the app is officially published.
  </Warning>

  ## Contributor Highlights

  * [@Django149](https://github.com/Django149) overhauled the file connector. You can now directly upload and remove files from the connector without creating a new one!
  * [@brano-rohlik](https://github.com/brano-rohlik) added Gemini 3 Pro and Claude Opus 4.5 support!
  * [@ethanwater](https://github.com/ethanwater) added a new connector for Coda!
  * [@rexjohannes](https://github.com/rexjohannes) added a Drupal wiki connector!
  * [@emerzon](https://github.com/emerzon) went on a tear this release! He:
    * Hardened markdown link processing to prevent potential security vulnerabilities
    * Removed duplicate DB operations to speed up chat deletion
    * Fixed a connector state bug, resulting in fewer connector failures
    * Added LiteLLM user and session tracking for budget control and observability
  * [@kiwamizamurai](https://github.com/kiwamizamurai) fixed an issue with the DISABLE\_MODEL\_SERVER environment variable not being respected!
  * [@vinitngr](https://github.com/vinitngr) cleaned up the install script to use a consistent root directory!

  ## Additional Improvements

  ### SearXNG Web Search Support

  We've added SearXNG as a web search provider,
  giving you another self-hostable choice for powering your agents' internet access.

  Through SearXNG, you can configure multiple search engines and keep your search results private and secure.

  ### Improved File Handling in Chat

  Files uploaded to chat are now processed more reliably, with the ability to preview them directly in the interface.

  <img alt="Improved File Handling in Chat" />

  ### MCP Passthrough Authentication

  MCP connections now support passthrough authentication for seamless integration with your existing auth systems.

  ### Embedding Model Configuration

  You can now update API keys for embedding models without recreating the configuration.

  ### Bug Fixes

  * Multiple fixes to Confluence, Jira, and web connectors
  * Improved document processing stability, reducing likelihood of OOM errors when using API-based embedding models

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.5.0" description="November 25th, 2025">
  ## v2.5.0

  Welcome to the Onyx v2.5.0 release notes! This update introduces code execution, new web search providers,
  and various improvements across the platform.

  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### Web Search Enhancements

  We've officially released support for new web search providers including Google PSE, Serper, Firecrawl,
  and a built-in Onyx web scraper!

  Configure these providers via the Web Search page in the Admin Panel and give your agents the ability to search the
  internet for real-time information and current events.

  New APIs for web search are also available for developers. Detailed setup and API reference docs will be coming soon!

  <img alt="Web Search Providers" />

  ### Claude Opus 4.5 Support

  Onyx now supports Anthropic's newest, most powerful model: Claude Opus 4.5!
  Configure Claude Opus 4.5 via the LLM Configuration page in the Admin Panel.

  <img alt="Claude Opus 4.5" />

  ### Code Execution (Alpha)

  Onyx's code execution is now in alpha!
  This feature allows your agents to write and execute Python code to solve complex problems, perform data analysis,
  and generate visualizations.

  <img alt="Code Execution Alpha" />

  We built code execution, in-house, to work with any model provider and LLM. It's a secure,
  FastAPI-based service that uses isolated Docker containers with strict resource limits, timeout controls,
  and file handling capabilities for security and reliability.

  Code execution is designed to work with any AI agent, not just Onyx. It's available as a standalone,
  fully open source project:
  [onyx-dot-app/code-interpreter](https://github.com/onyx-dot-app/code-interpreter?utm_source=docs\&utm_content=changelog).
  While Python is the first supported language, all common languages will be supported in the future.

  <Note>
    Code execution is not yet ready for production use. If you enable the feature flag, you may encounter bugs!
    Please bear with us as we continue to develop and improve this feature.
  </Note>

  ## Contributor Highlights

  * [@sashank-rayapudi-ai](https://github.com/sashank-rayapudi-ai) added a new connector for Testrail!
  * [@mristau-alltrails](https://github.com/mristau-alltrails) identified and resolved a vulnerability in our nginx configuration!

  ## Additional Improvements

  ### Default Assistant MCP Tools

  The Default Assistant can now have MCP tools attached,
  making it easier to extend the default experience with custom actions and integrations.

  ### Document Search APIs in Community Edition

  Document search APIs have been moved from Enterprise Edition to Community Edition,
  giving all users access to programmatic document search capabilities.

  ### Auto-Pause for Failing Connectors

  Connectors that continuously fail will now automatically be paused. This helps relieve pressure on the background,
  API, and indexing containers, improving overall system stability.

  ### Kubernetes Affinity and Tolerations

  We've added affinity and tolerations to the Helm deployment templates,
  allowing you to customize where pods are scheduled in your Kubernetes environment.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.4.0" description="November 18th, 2025">
  ## v2.4.0

  Welcome to the Onyx v2.4.0 release notes!
  This release introduces powerful new controls for the Slack Federated connector, fine-grained LLM access controls,
  and various other improvements and bug fixes across the platform.

  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### Advanced Filtering for Slack Federated Connector

  The Slack Federated connector now supports comprehensive, entity-based filtering,
  which gives you precise control over the data available to Onyx users.

  Configure filters such as:

  * Channel selection with glob patterns
  * Message type filtering (1:1 DMs, group DMs, private channels)
  * Date extraction

  <Note>
    If you have an existing Slack Federated Connector,
    you will need to update the app's scopes to use the expanded search functionality (e.g. searching group DMs).

    Additionally,
    each user will need to revoke and re-authorize their OAuth access to the app for the new scopes to take effect.

    See the [Slack Federated Connector](/admins/connectors/official/slack/slack_federated/)
    app manifest documentation for more details.
  </Note>

  <img alt="Slack connector filtering options" />

  ### LLM Access Controls

  Admins can now configure fine-grained access controls for LLM providers.

  This feature allows you to restrict which users or groups can access specific language models.
  Use access controls to better manage and monitor generative AI usage across your organization.

  Read more about LLM access controls in our [admin docs](/admins/advanced_configs/llm_access_controls/).

  <img alt="LLM access controls" />

  ### Disable Default Assistant

  You now have the flexibility to disable the default assistant in your Onyx workspace.
  This is particularly useful for organizations with many custom assistants, each with specific configurations, tools,
  and instructions.

  To disable the Default Assistant,
  go to the **Workspace Settings** page and toggle the **Disable Default Assistant** switch.

  ## Contributor Highlights

  * [@sktbcpraha](https://github.com/sktbcpraha) fixed an issue where the Default Assistant was overriding legacy custom agent prompts!
  * [@alex000kim](https://github.com/alex000kim) fixed a tricky issue with special characters in the Teams connector!

  ## Additional Improvements

  ### Share Chat Button

  We've made sharing chats easier with a dedicated share button in the top right of the chat interface.

  ### Paginated Document Search API

  The document search API now supports pagination for more efficient retrieval of large result sets.

  ### Projects Token Limits

  We've increased the per-file token limit for Projects to 100k. Additionally,
  you can configure this limit with the `SKIP_USERFILE_THRESHOLD` environment variable.

  ### SSO User Provisioning Improvements

  Previously, inviting users to join your Onyx workspace would prevent non-invited users from automatically registering.

  Now, SSO-enabled workspaces can have both invited users and JIT-provisioned users!

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.3.0" description="November 11th, 2025">
  ## v2.3.0

  Welcome to the Onyx v2.3.0 release notes!
  This release brings performance improvements that make Onyx feel significantly faster and more responsive,
  personal access tokens, expanded LLM provider support, and more.

  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### Personal Access Tokens

  Onyx now supports Personal Access Tokens for API authentication. This feature allows all users to have a secure,
  programmatic way to interact with Onyx via the API,
  making it easier to integrate Onyx into your workflows and automation tools.

  <img alt="Personal Access Tokens" />

  ### Massive Frontend Performance Improvements

  We've made extensive performance optimizations across the frontend that deliver a noticeably faster and more
  responsive experience.

  * Typing in the input bar is now lag-free, even during heavy operations.
  * UI updates are significantly faster with improved reactive performance,
    making interactions feel instant and smooth throughout the application.
  * First content load is also much faster with optimizations in data loading.

  <img alt="Frontend Performance Improvements" />

  ### Expanded LLM Provider Support

  We've added support for OpenAI image generation models via Azure,
  bringing more flexibility to your image generation capabilities.

  Additionally, Onyx now supports AWS GovCloud regions for Bedrock.

  ## Additional Improvements

  ### White Labeling Fixes

  We've resolved several issues with white labeling to ensure your custom branding displays correctly across all areas
  of the application.

  ### More Resilient Gmail Connector

  The Gmail connector now uses checkpointing for more resilient indexing.
  This makes the connector more reliable and significantly cheaper to run,
  especially when re-embedding your entire Gmail history.

  ### Air-Gapped Deployment Support

  We've fixed air-gapped deployments by packaging the tokenizer directly with the model server image.
  This ensures Onyx can run in completely isolated environments without requiring external dependencies.

  ### Optimized LLM Interactions

  We've simplified both system prompts and tool prompts,
  resulting in lower token consumption per interaction and more efficient tool calling.
  This reduces your LLM costs while maintaining the same quality of responses.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.2.0" description="November 5th, 2025">
  ## v2.2.0

  Welcome to the Onyx v2.2.0 release notes!
  This release brings major improvements to the agent framework with faster responses and more consistent outputs,
  a completely redesigned onboarding experience, and significant UI performance enhancements.

  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### Complete Agent Framework Revamp

  We've completely rebuilt the agent framework that powers Onyx conversations.
  The new implementation moves away from LangGraph to the Agents SDK,
  resulting in a dramatically simplified flow that delivers more consistent outputs, faster response times,
  and better tool calling accuracy.

  This architectural change also reduces per-message token consumption,
  making your conversations more efficient and cost-effective.

  ### New Login UI and Onboarding Flow

  First-time users now experience a streamlined onboarding journey that guides them through personalizing their
  workspace, setting up their LLMs, and configuring actions like Web Search and Image Generation.

  <img alt="Onboarding flow" />

  ### UI Performance and Polish

  We've made extensive improvements across the UI for performance and visual consistency.

  For example,
  the Assistants navigation page has been completely refreshed with a cleaner layout and improved organization.

  <img alt="Agents navigation" />

  ### LLM Usage Observability

  Onyx now supports integration with [Braintrust](https://usebraintrust.com) or [LangFuse](https://www.langfuse.com)
  for comprehensive LLM observability. Monitor your costs, latency, token usage,
  and more to gain insights into your AI operations.

  Read more about setting up observability in our [deployment configuration
  docs](/deployment/configuration/configuration/).

  <img alt="LLM usage observability" />

  ## Contributor Highlights

  * [@dafeliton](https://github.com/dafeliton) fixed an elusive bug with the web connector not parsing PDF URLs correctly and crashing!

  ## Additional Improvements

  ### Confluence OAuth and Jira Fixes

  We've resolved issues with Confluence OAuth authentication and updated Jira integration to address deprecated API
  endpoints, ensuring reliable connectivity with your Atlassian tools.

  ### Enhanced Provider Support

  Onyx now has improved support for LLM providers like Ollama and OpenRouter,
  giving you more flexibility in choosing the models that work best for your use case.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.1.0" description="October 28th, 2025">
  ## v2.1.0

  Welcome to the Onyx v2.1.0 release notes! This is a minor update with new support for OAuth Actions,
  improvements to the developer experience, and a new FOSS repo.

  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### OAuth Actions

  Onyx now supports Actions that require OAuth authentication. With this new feature,
  Onyx can now invoke many more actions on your behalf.

  Admins can configure OAuth Actions via the OpenAPI tab of the Actions page.

  <img alt="OAuth Actions configuration" />

  ### Improved Code Rendering

  Code blocks in chat now render much more consistently across all languages with proper syntax highlighting.
  This makes it easier to read and understand code generated by Onyx.

  <img alt="Code rendering" />

  ### Fully Open Source (FOSS) Repository

  We're excited to share a completely FOSS version of Onyx!
  All code is MIT licensed and Enterprise Edition code is removed.

  This FOSS repo should make it easier for developers to contribute, audit, and deploy Onyx without licensing concerns.

  We will continue to develop on the main `onyx-dot-app/onyx` repository,
  and `onyx-foss` will automatically sync new changes.

  Check out the repo at this link:
  [onyx-foss](https://github.com/onyx-dot-app/onyx-foss?utm_source=docs\&utm_content=changelog).

  ## Contributor Highlights

  * [@camro](https://github.com/camro) fixed a tricky issue where the app was not redirecting to shared chats on login!

  ## Additional Improvements

  ### Name Personalization

  You can now set your name in the bottom left user icon! Just set your name in the User Settings modal.

  Your name and role are used to better personalize your conversations in Onyx.

  <img alt="Name personalization" />

  ### Theme Preference Persistence

  Your light mode/dark mode preference is now saved across browsers and sessions, even after cache clears.
  Set it once and forget about it!

  ### Image Size Reduction

  We've fixed a bug that was doubling the size of the model server Docker image.
  This reduces disk space requirements significantly for deployments (\~26 GB needed for a fresh deployment).

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="v2.0.0" description="October 20th, 2025">
  ## v2.0.0

  <Note>
    v2.0.0 has breaking changes.
    You may want to test the upgrade in a staging environment before deploying to production.
  </Note>

  Today, we're excited to announce the release of Onyx v2.0.0! This release brings a brand new UI, Projects,
  and many other improvements.

  Thank you to our contributors for helping make this release possible!

  ## Key Improvements

  ### UI Refresh

  Onyx has a brand new UI with updated colors, components, and subtle changes to the layout.
  Check out this release video showcasing the new UI!

  <div>
    <iframe title="YouTube video player" />
  </div>

  ### Single-sign on (SSO) added to Community Edition

  SSO (via OIDC and SAML) is now available in the Community Edition of Onyx!

  All users can now configure basic authentication, Google OAuth,
  or SSO via identity providers like Okta and Azure EntraID.

  Read more about authentication options in our [deployment docs](/deployment/authentication/).
  Read more about our open source philosophy in our [Open Source
  Statement](/overview/miscellaneous/open_source_statement/).

  ### Projects

  Projects allow users to organize files and chats based on a specific context.
  You can think of this as a folder where you upload files, define project-level instructions,
  and work from the same starting point in every chat session.

  <img alt="Projects feature screenshot" />

  Projects is a direct replacement of My Documents, but with added functionality.
  Files you've previously uploaded to My Documents should appear in Projects.

  ### New Docker Compose File

  We've simplified the Docker Compose files to make it easier to deploy Onyx.

  Previously, you may have used `docker-compose.dev.yml`, `docker-compose.prod.yml`, or `docker-compose.gpu-dev.yml`.
  These have been consolidated into a single `docker-compose.yml` file.

  With the new compose file, you can run `docker compose up -d` to start Onyx.

  <Note>
    If you've previously used the old compose files, you will need to add the `-p onyx-stack` flag.

    I.e. `docker compose -p onyx-stack up -d`.

    Additionally, you will need to migrate any changes you may have made to your compose file.
  </Note>

  ### Organization info and personalization

  We've found that questions posed to Onyx often require context on who you are, what you work on,
  and what your company does.
  It is difficult to infer this from search results alone because they are a narrow view into your context.

  To help with this,
  admins can now add information about their organization in the **Workspace Settings** tab of the Admin Panel.
  Additionally, users can add information about themselves in the User Settings page.

  <img alt="Organization info configuration" />

  <img alt="User info configuration" />

  This is a simple, but powerful first step in our organization and personalization features. In the future,
  Onyx will extract and save this information automatically.

  ### Curators can now create actions

  Due to popular demand, Curators and Global Curators can now create Actions via OpenAPI or MCP!

  Read more about Actions in our [admin docs](/admins/actions/overview/).

  <img alt="Curators can now create actions" />

  ### Search filters

  Source filters are back for the Internal Search Action!

  To filter the sources of your search results, click the Actions configuration button in the Input Bar,
  select the arrow next to Internal Search, and select the sources you want to include.

  <img alt="Actions in the Chat Input Bar" />

  <img alt="Source filters" />

  ### Language and Embedding Models

  We've added support for [Claude Sonnet 4.5](https://www.anthropic.com/news/claude-sonnet-4-5),
  [Claude Haiku 4.5](https://www.anthropic.com/news/claude-haiku-4-5),
  and [Gemini Embedding 001](https://developers.googleblog.com/en/gemini-embedding-available-gemini-api/).

  Try them out by configuring Anthropic in the **LLM Configuration** page and Google Vertex AI on the **Search
  Settings** page of the Admin Panel.

  ## Contributor Highlights

  * [@Django149](https://github.com/Django149) added right-to-left language support for the chat interface!
  * [@nsklei](https://github.com/nsklei) added support for indexing Microsoft Teams attachments!
  * [@linkages](https://github.com/linkages) added generation of SHA256 hashes of documents for the Onyx File Store!
  * [@grafke](https://github.com/grafke) fixed a bug in GPT search timestamps!

  ## Additional Improvements

  ### Support for SSE (server-sent events) MCP servers

  Onyx now supports SSE (server-sent events) MCP servers.
  Configure either Streamable HTTP or SSE servers in the Admin Actions page.

  Read more about MCP in our [admin docs](/admins/actions/mcp/).

  ### Permission Sync Status updates

  Permission sync connectors will now display sync status in the Admin Panel.

  ### Ollama Support

  You can now configure both locally-hosted and cloud-hosted models with Ollama.
  Read more about Ollama in our [admin docs](/admins/ai_models/ollama/).

  ### OpenRouter Support

  You can now configure Onyx to use models from OpenRouter.
  Read more about OpenRouter in our [admin docs](/admins/ai_models/openrouter/).

  ### One Line Deployment Script

  We've added a [single line launch script](deployment/getting_started/quickstart) to make it easier to deploy Onyx.
  This script will check your system resources and requirements and guide you through the necessary steps to deploy
  Onyx.

  <Note>
    This script is intended for new users. For existing users,
    we recommend sticking with your existing deployment method.
  </Note>

  ### KEDA Autoscaling

  We've added support for KEDA (Kubernetes Event-Driven Autoscaling) to Onyx Helm charts.
  Kubernetes deployments may choose either HPA (Horizontal Pod Autoscaling) or KEDA for autoscaling.

  ***

  Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page has the full list of changes and bug fixes for each release.
</Update>

<Update label="Prior Changes" description="<v2.0.0">
  ## Release Notes Prior to v2.0.0

  Check out our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases?utm_source=docs\&utm_content=changelog)
  page for details regarding prior changes.

  Additionally, our Discord `#announcements` channel is a great place to stay up to date with Onyx updates.

  Major releases and breaking changes are also announced in the [Discord Server](https://discord.gg/4NA5SbzrWb).
</Update>


# Basic Auth
Source: https://docs.onyx.app/deployment/authentication/basic

Email and password authentication in Onyx

Email/password authentication is always enabled and works out of the box, with no configuration needed.
The first user to sign up becomes an admin.

We recommend adding [Google OAuth](/deployment/authentication/oauth), [OIDC](/deployment/authentication/oidc),
or [SAML](/deployment/authentication/saml) for production deployments. Once SSO works,
password login and sign-up can be [turned off
entirely](/deployment/authentication/sso_providers#turning-off-password-login).

<Note>
  Versions before `v4.4.0` required `AUTH_TYPE=basic`.
  Since `v4.4.0` the variable is inert and it is planned for full removal in `v4.5`.
</Note>

<Tip>
  If you have questions about which authentication approach is best for your organization,
  don't hesitate to [contact us](https://docs.onyx.app/contact_us)

  * we're happy to help you choose the right solution.
</Tip>

## Password Requirements

Passwords must be 8 to 64 characters by default. The length limits and character-class requirements (uppercase,
lowercase, number, special character) are configurable at **Admin Panel** → **Organization** → **Security & Hardening**.

## Email Verification

Enabling email verification blocks your users from signing in until they click their verification email.

**Using Docker:**

Set the following in your `.env` file:

```bash theme={null}
# Enable email verification
REQUIRE_EMAIL_VERIFICATION=true

# Email configuration
SMTP_USER=<EMAIL_TO_SEND_VERIFICATION_EMAILS_FROM>  # e.g. noreply@yourcompany.com
SMTP_PASS=<PASSWORD_FOR_THE_EMAIL_ABOVE>

# Required for non-Gmail accounts
SMTP_SERVER=<YOUR_SMTP_SERVER>
SMTP_PORT=<PORT_YOUR_SMTP_SERVER_LISTENS_ON>  # default: 587
```

**Using Helm:**

Set the following in your `values.yaml` file:

```yaml theme={null}
auth:
  secrets:
      smpt_pass: <PASSWORD_FOR_THE_SMTP_USER>
configMap:
  REQUIRE_EMAIL_VERIFICATION: true
  SMTP_USER: <EMAIL_TO_SEND_VERIFICATION_EMAILS_FROM>

  # Required for non-Gmail accounts
  SMTP_SERVER: <YOUR_SMTP_SERVER>
  SMTP_PORT: <PORT_YOUR_SMTP_SERVER_LISTENS_ON>
```

## Next Steps

<CardGroup>
  <Card title="Set up Google OAuth" icon="google" href="/deployment/authentication/oauth">
    Google OAuth is a secure and easy way to authenticate users with their Google accounts.
  </Card>

  <Card title="Other Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    There are many other configuration options available for Onyx.
  </Card>
</CardGroup>


# JWT Header Auth
Source: https://docs.onyx.app/deployment/authentication/jwt

Authenticate API requests with JWTs minted by your own identity provider

Onyx can accept a JWT that your identity provider or API gateway mints, and use it to authenticate a request.
This is useful when another system already holds the user's identity and calls Onyx on their behalf — for example an API
gateway, a portal, or a service that fronts Onyx for its own users.

Set `JWT_PUBLIC_KEY_URL` to a URL that serves the public key material for your token issuer. When the variable is set,
Onyx accepts a signed JWT in the `Authorization` header:

```
Authorization: Bearer <JWT>
```

<Note>
  This option is part of Onyx Community Edition. It needs no Enterprise license,
  and it works the same way in both editions. See [Support and stability](#support-and-stability) below.
</Note>

## Setup

<Steps>
  <Step title="Publish your public key">
    Your identity provider must serve the verification key at a URL that the Onyx API server can reach.
    Onyx accepts two formats:

    * **JWKS** — a JSON document with a `keys` array. This is what Microsoft Entra ID, Okta, Auth0,
      and most other providers publish at their `jwks_uri`.
    * **PEM** — a single PEM-encoded RSA public key.

    Onyx picks the format from the response. A response with `Content-Type: application/json`,
    or a body that starts with `{`, is read as JWKS. Any other body is read as PEM.

    <Tip>
      Most identity providers list the JWKS URL in their OIDC discovery document at
      `https://<YOUR_IDP>/.well-known/openid-configuration`, under the `jwks_uri` field.
    </Tip>
  </Step>

  <Step title="Configure Onyx">
    Set the variable in your `.env` or `values.yaml` file (Docker and Kubernetes, respectively).

    ```bash .env theme={null}
    JWT_PUBLIC_KEY_URL=https://<YOUR_IDP>/.well-known/jwks.json
    ```

    ```yaml values.yaml theme={null}
    configMap:
      JWT_PUBLIC_KEY_URL: https://<YOUR_IDP>/.well-known/jwks.json
    ```

    Restart the API server to apply the change.
  </Step>

  <Step title="Send a request">
    Put the token in the `Authorization` header of any Onyx API call. `GET /api/me` returns the user that Onyx resolved,
    so it is a good first check.

    ```bash theme={null}
    curl https://<YOUR_ONYX_DOMAIN>/api/me \
      -H "Authorization: Bearer <JWT>"
    ```
  </Step>
</Steps>

## Token requirements

| Requirement    | Value                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| Signature      | RS256                                                                                                 |
| Identity claim | The first valid email address in `email`, `preferred_username`, then `upn`                            |
| Expiry         | `exp` is enforced. Expired tokens are rejected                                                        |
| Audience       | `aud` and `iss` are checked when an expected value is configured (`v4.7.0+`), and unchecked otherwise |

The address in the identity claim is normalized and lowercased. It becomes the Onyx user's email.

<Warning>
  With no expected audience configured, any token that your configured key signs is accepted,
  even if it was minted for a different application. If the signing key is shared across several applications,
  set an expected audience so only tokens minted for Onyx authenticate.
</Warning>

## Audience and issuer enforcement

Starting in `v4.7.0`, Onyx can enforce the `aud` and `iss` claims. When an expected value is set,
a token whose claim does not match is rejected, and a token missing the claim is rejected too (the check fails closed).
Both the string and array forms of `aud` are accepted, and an array containing the expected audience matches.

Configure the values at **Admin Panel** → **Security & Hardening** → **External JWT Authentication**,
or with environment variables:

| Setting           | Environment variable    |
| ----------------- | ----------------------- |
| Public Key URL    | `JWT_PUBLIC_KEY_URL`    |
| Expected Audience | `JWT_EXPECTED_AUDIENCE` |
| Expected Issuer   | `JWT_EXPECTED_ISSUER`   |

A setting whose environment variable is set is **pinned**:
the environment value wins over anything saved in the admin panel, and the field displays as read-only text.
This keeps auth-gating configuration as reviewable config-as-code that cannot be changed from inside the application,
even by an admin account. With the variable unset, the value saved in the admin panel applies. On startup,
Onyx mirrors set environment values into the database,
so removing a variable later keeps its last pinned value in effect.

A Public Key URL saved through the admin panel must use `https` and is validated against the deployment's SSRF
Protection level, at save time and on every fetch, with redirects held to the same rules.
A URL pinned by the environment variable is trusted as operator configuration and skips these checks,
so internal endpoints stay usable when the operator configures them.
Changes made from the admin panel are recorded in the audit log with the acting user and the old and new values.

### Key selection and rotation

When the URL serves JWKS, Onyx selects the key by the token header `kid`, then by `x5t`.
If neither matches and the document holds exactly one key, Onyx uses that key.

Onyx caches the fetched key material. If verification fails, Onyx clears the cache, fetches the URL again,
and retries once. Routine key rotation therefore needs no restart.

## User handling

A request authenticated by JWT is treated like any other logged-in user.

* **Just-in-time provisioning.** If no Onyx user has that email, Onyx creates one. The account is
  marked verified and gets a random password it never uses.
* **Existing users.** If the email belongs to an existing user, that user is returned. Deactivated
  users are rejected. Accounts that are not web-login accounts are rejected.
* **Access policies still apply.** The email must satisfy the same invite allowlist and
  `VALID_EMAIL_DOMAINS` rules as every other login path.
* **Session expiry.** With `TRACK_EXTERNAL_IDP_EXPIRY=true`, Onyx stores the token's `exp` as the
  user's external IdP expiry.

A user provisioned this way gets no elevated permissions, with one exception:
the **first** user on an empty instance becomes an admin, whichever login path creates them.
Grant admin access to anyone else from the **Admin Panel → Users** page,
or add them to a group that grants the permissions they need.

<Info>
  Enterprise Edition adds two behaviors on this path. Emails in the default-admin list are made admins at creation.
  Provisioning a new user also consumes a license seat,
  so a login for an unknown user fails once the workspace reaches its seat limit.
  Community Edition applies no seat limit.
  Enterprise Edition can also manage access through [SCIM](/deployment/authentication/scim).
</Info>

## Precedence

A valid Onyx session cookie takes priority. Onyx reads the `Authorization` header only when the request has no session.

API keys and personal access tokens use the same header. Onyx tries the JWT path first,
and a value that is not a valid RS256 JWT falls through to the API key and personal access token paths.
Those credentials keep working unchanged when `JWT_PUBLIC_KEY_URL` is set.

## Support and stability

`JWT_PUBLIC_KEY_URL` is a documented and supported configuration option.
Onyx treats it like every other published setting on this page:

* The variable name, the `Authorization: Bearer` header, the RS256 requirement, the accepted key
  formats, and the identity claim order are part of the documented interface.
* Automated tests cover the behavior described above — existing-user login, just-in-time
  provisioning, rejection of tokens signed by an unknown key, rejection of expired tokens,
  and key rotation without a restart.
* If a future release changes or replaces this option, the change is called out in the release
  notes for that release, together with the mechanism that replaces it.

<Note>
  If you plan to build an integration on this option, [contact us](/deployment/miscellaneous/contact_us).
  We are happy to review your design and tell you about anything on the roadmap that touches it.
</Note>

## Troubleshooting

Onyx logs every verification failure on the API server. Check `api_server` logs for these messages:

| Log message                                | Cause                                                               |
| ------------------------------------------ | ------------------------------------------------------------------- |
| `JWT_PUBLIC_KEY_URL is not set`            | The variable is missing or empty                                    |
| `Failed to fetch JWT public key`           | Onyx cannot reach the URL. Check egress rules and TLS               |
| `JWT public key URL returned invalid JSON` | The response looks like JSON but does not parse                     |
| `no JWKS 'keys' field was found`           | The JSON response is not a JWKS document                            |
| `No matching JWK found for token header`   | The token `kid` is absent from the JWKS document                    |
| `Invalid JWT token`                        | Bad signature, expired token, or an algorithm other than RS256      |
| `no email claim found`                     | None of `email`, `preferred_username`, or `upn` holds a valid email |

A request that fails JWT verification is not rejected outright. It continues as an unauthenticated request,
and the endpoint returns `401` if it needs a user.


# Google OAuth
Source: https://docs.onyx.app/deployment/authentication/oauth

Google OAuth authentication setup

Configure Onyx to use Google OAuth for user authentication,
providing a seamless login experience through existing Google accounts.

Google providers are managed at **Admin Panel** → **Organization** → [SSO
Providers](/deployment/authentication/sso_providers). No environment variables or restarts are needed,
and you can configure multiple providers (enabling more than one at the same time requires the Business plan,
see [Plan Availability](/deployment/authentication/sso_providers#plan-availability)).

**Prerequisites:**

* [Google Cloud Console](https://console.cloud.google.com/) access
* Administrative permissions to configure OAuth applications

## Guide

<Steps>
  <Step title="Create Google Cloud Project">
    Navigate to the Google Cloud Console [Project Creation page](https://console.cloud.google.com/projectcreate)
    and fill in the required fields.

    <img alt="Google Cloud Console Project Creation Page" />
  </Step>

  <Step title="Enable Google People API">
    Navigate to **APIs & Services** and find [Google People
    API](https://console.cloud.google.com/apis/library/people.googleapis.com).

    Ensure your newly created project is selected in the top bar and click **Enable**.

    <img alt="Google Cloud Console People API Enable Page" />
  </Step>

  <Step title="Create Google Auth Platform">
    Open the left sidebar and navigate to **APIs & Services** → **OAuth Consent Screen**.

    Once on the **Overview** page, click **Get Started**.

    <img alt="Google Cloud Console OAuth Consent Screen Page" />
  </Step>

  <Step title="Configure OAuth Project & Consent Screen">
    Fill in the **App name** and **User support email** fields.

    Select your **Audience**. If you have a Google Workspace organization, select **Internal**. If not,
    select **External**.

    <Note>
      If you select **External**, you will need to add your users manually in the **Audience** tab under **Test users**.
    </Note>

    Fill in any other required fields and finalize the configuration.
  </Step>

  <Step title="Create OAuth Client">
    Navigate to **APIs & Services** → **OAuth Consent Screen** → **Clients** page.

    Click **"+ Create Client"** and select **Web Application**.

    <img alt="Google Cloud Console OAuth Client Creation Page" />
  </Step>

  <Step title="Configure OAuth Client">
    **Name:** `Onyx`

    Add your Onyx origin under **Authorized JavaScript origins**,
    and add an **Authorized redirect URI** using the name you will give the provider in Onyx (a lowercase slug, e.g.
    `google`):

    If hosting Onyx locally use:

    ```
    http://localhost:3000
    http://localhost:3000/api/auth/oidc/YOUR_PROVIDER_NAME/callback
    ```

    If hosting Onyx on a custom domain use:

    ```
    https://YOUR_ONYX_DOMAIN.com
    https://YOUR_ONYX_DOMAIN.com/api/auth/oidc/YOUR_PROVIDER_NAME/callback
    ```

    <img alt="Google Cloud Console OAuth Client Creation Page" />

    <Tip>
      Make sure the URIs you enter here match the URI you use to access Onyx!
    </Tip>
  </Step>

  <Step title="Save OAuth Credentials">
    Click **Create** → **Download JSON** to save the OAuth client credentials. Alternatively,
    save the **Client ID** and **Client Secret** to a password or secrets manager.
  </Step>

  <Step title="Add the Provider in Onyx">
    Navigate to **Admin Panel** → **Organization** → [SSO Providers](/deployment/authentication/sso_providers)
    and click **Add Provider**.

    Select the **Google** provider type, enter the **Name** you used in the redirect URI,
    and paste the **Client ID** and **Client Secret**.

    After creating the provider, its row shows the exact **Redirect URI**.
    Confirm it matches what you registered on the OAuth client, then sign in through the new option on the login page.
  </Step>
</Steps>

## Customizing requested scopes

By default, Onyx requests `openid`, `email`,
and `profile` from Google during login — the minimum needed to identify the user.
Overriding the list is primarily useful when the access token issued at login should be passed through to tool calls
that need additional Google API access.

Starting in `v4.5`, set **Scopes** on the provider entry (**Admin Panel** → **Organization** → **SSO Providers**)
to override the list per provider. A provider's **Scopes** take precedence. When left empty,
the deployment-wide environment variable applies, then the built-in defaults.

On `v4.4.x`, the only override is the deployment-wide `GOOGLE_OAUTH_SCOPE_OVERRIDE` environment variable,
a comma-separated list:

```bash .env theme={null}
GOOGLE_OAUTH_SCOPE_OVERRIDE=openid,email,profile,https://www.googleapis.com/auth/drive.readonly
```

<Warning>
  The override **replaces** the default scopes — make sure `openid`, `email`,
  and `profile` are still included if you want standard login to keep working.
</Warning>

<Note>
  Any scopes you add here must also be enabled on the OAuth client in Google Cloud Console (consent screen + client
  configuration). Onyx only changes what is sent in the authorize request;
  Google still rejects scopes that are not configured for the client.
</Note>

<Note>
  These scopes apply only to the **app login** and pass-through OAuth flows.
  The Google Drive and Gmail **connectors** use their own scopes and OAuth flow, which are not affected by this setting.
</Note>

## Enabling PKCE

PKCE is disabled by default.

Starting in `v4.5`,
turn on **Enable PKCE** on the provider entry (**Admin Panel** → **Organization** → **SSO Providers**).

On `v4.4.x`, the deployment-wide `OIDC_PKCE_ENABLED` environment variable enables it for all providers.
Google login shares the OIDC login route, so the OIDC-named variable applies here too:

```bash .env theme={null}
OIDC_PKCE_ENABLED=true
```

<Warning>
  `OIDC_PKCE_ENABLED=true` forces PKCE on for every provider, including providers whose **Enable PKCE** toggle is off.
  Unset it if you want the per-provider toggles to be the source of truth.
</Warning>

## Upgrading from v4.3 or Earlier

Versions before `v4.4.0` configured a single Google provider through environment variables,
using the redirect URI `https://YOUR_ONYX_DOMAIN.com/auth/oauth/callback` on the OAuth client.
On `v4.4.0` and later these variables no longer enable Google login, and they are planned for full removal in `v4.5`.
New installs must use the admin panel flow above.

<Note>
  When you upgrade an existing deployment,
  its environment-based configuration is imported into an SSO provider entry automatically,
  and existing logins keep working. The import runs once, when the upgrade first runs against your existing database,
  so keep the configuration in place through the upgrade.
  The migrated provider keeps using the redirect URI already registered in the Google Cloud Console,
  so nothing changes on the Google side. Once the migrated provider appears in the admin panel,
  sign-ins and token refresh use the provider entry's credentials, and `AUTH_TYPE`, `OAUTH_CLIENT_ID`,
  and `OAUTH_CLIENT_SECRET` can be removed.
  The variables only act as a fallback for login accounts that no provider entry matches,
  such as after deleting or renaming the migrated provider.
</Note>

For reference, a pre-`v4.4.0` configuration looks like:

```bash .env theme={null}
AUTH_TYPE=google_oauth
OAUTH_CLIENT_ID=YOUR_CLIENT_ID
OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET

# If you are deploying to a custom domain, you will need to set the `WEB_DOMAIN` environment variable.
WEB_DOMAIN=https://YOUR_ONYX_DOMAIN.com
```

```bash values.yaml theme={null}
auth:
  secrets:
    OAUTH_CLIENT_ID: <CLIENT_ID_FROM_GOOGLE>
    OAUTH_CLIENT_SECRET: <CLIENT_SECRET_FROM_GOOGLE>
configMap:
  AUTH_TYPE: google_oauth
```


# OIDC
Source: https://docs.onyx.app/deployment/authentication/oidc

OpenID Connect authentication setup

Configure Onyx with OpenID Connect (OIDC) authentication.
Available with common identity providers such as Okta and Microsoft Entra ID (Azure AD).

OIDC providers are managed at **Admin Panel** → **Organization** → [SSO
Providers](/deployment/authentication/sso_providers). No environment variables or restarts are needed,
and you can configure multiple providers (enabling more than one at the same time requires the Business plan,
see [Plan Availability](/deployment/authentication/sso_providers#plan-availability)).

This guide walks through the setup for Okta. Other identity providers follow a similar process.
Please contact us if you need help with a different identity provider.

## Guide

<Steps>
  <Step title="Create Okta Application">
    Navigate to the Okta **Admin Console** → **Applications** → **Create App Integration**.

    <img alt="Okta Create Integration Page" />
  </Step>

  <Step title="Configure Okta Application">
    Select **OIDC** and **Web Application**.

    Name your application `Onyx`.

    <Tip>
      If you are white-labeling Onyx, you can freely name your application.
    </Tip>

    Add a **Sign-in redirect URI** using the name you will give the provider in Onyx (a lowercase slug, e.g. `okta`):

    ```
    https://YOUR_ONYX_DOMAIN.com/api/auth/oidc/YOUR_PROVIDER_NAME/callback
    ```

    Determine whether all users or select groups may access Onyx or skip this step and assign users later.

    <img alt="Okta Configure OIDC Application Page" />
  </Step>

  <Step title="Save OIDC Credentials">
    Create the new Application and save the **Client ID** and **Client Secret**.

    Also note your **Okta Base URL** in the format of `https://<YOUR_ORG_NAME>.okta.com`.

    <img alt="Okta OIDC Credentials Page" />

    <Note>
      After saving your application,
      you can upload the Onyx logo or your white-labeled logo by clicking the gear icon next to the app title **Onyx**
    </Note>
  </Step>

  <Step title="Add the Provider in Onyx">
    Navigate to **Admin Panel** → **Organization** → [SSO Providers](/deployment/authentication/sso_providers)
    and click **Add Provider**.

    Select the **OIDC** provider type, enter the **Name** you used in the redirect URI, and paste the **Client ID**,
    **Client Secret**, and the OpenID configuration URL:

    ```
    https://<YOUR_OKTA_BASE_URL>/.well-known/openid-configuration
    ```

    After creating the provider, its row shows the exact **Redirect URI**.
    Confirm it matches what you registered in Okta, then sign in through the new option on the login page.
  </Step>
</Steps>

## Customizing requested scopes

By default, Onyx uses the standard OIDC base scopes when redirecting users to the identity provider.
Overriding the list is primarily useful when the access token issued at login should be passed through to tool calls
that need additional scopes from the identity provider.

Starting in `v4.5`, set **Scopes** on the provider entry (**Admin Panel** → **Organization** → **SSO Providers**)
to override the list per provider. A provider's **Scopes** take precedence. When left empty,
the deployment-wide environment variable applies, then the built-in defaults.

On `v4.4.x`, the only override is the deployment-wide `OIDC_SCOPE_OVERRIDE` environment variable,
a comma-separated list that applies to every OIDC provider:

```bash .env theme={null}
OIDC_SCOPE_OVERRIDE=openid,email,profile,groups
```

Onyx will always also request `offline_access` so refresh tokens are issued, even if it is not in the override list.

<Warning>
  The override **replaces** the default scopes — make sure `openid`, `email`,
  and `profile` are still included if you want standard login to keep working.
</Warning>

<Note>
  Any scopes you add here must also be enabled on the application in your identity provider.
  Onyx only changes what is sent in the authorize request;
  the IdP still rejects scopes that are not configured for the client.
</Note>

## Enabling PKCE

PKCE is disabled by default to preserve backwards compatibility with existing OIDC deployments.

Starting in `v4.5`,
turn on **Enable PKCE** on the provider entry (**Admin Panel** → **Organization** → **SSO Providers**).

On `v4.4.x`, the deployment-wide `OIDC_PKCE_ENABLED` environment variable enables it for all providers:

```bash .env theme={null}
OIDC_PKCE_ENABLED=true
```

<Warning>
  `OIDC_PKCE_ENABLED=true` forces PKCE on for every provider, including providers whose **Enable PKCE** toggle is off.
  Unset it if you want the per-provider toggles to be the source of truth.
</Warning>

## Upgrading from v4.3 or Earlier

Versions before `v4.4.0` configured a single OIDC provider through environment variables,
using the redirect URI `https://YOUR_ONYX_DOMAIN.com/auth/oidc/callback`.
On `v4.4.0` and later these variables no longer enable OIDC login, and they are planned for full removal in `v4.5`.
New installs must use the admin panel flow above.

<Note>
  When you upgrade an existing deployment,
  its environment-based configuration is imported into an SSO provider entry automatically,
  and existing logins keep working. The import runs once, when the upgrade first runs against your existing database,
  so keep the configuration in place through the upgrade.
  The migrated provider keeps using the redirect URI already registered with your IdP,
  so nothing changes on the IdP side. Once the migrated provider appears in the admin panel,
  sign-ins and token refresh use the provider entry's credentials, and `AUTH_TYPE`, `OAUTH_CLIENT_ID`,
  `OAUTH_CLIENT_SECRET`, and `OPENID_CONFIG_URL` can be removed.
  The variables only act as a fallback for login accounts that no provider entry matches,
  such as after deleting or renaming the migrated provider.
</Note>

For reference, a pre-`v4.4.0` configuration looks like:

```bash .env theme={null}
AUTH_TYPE=oidc
OAUTH_CLIENT_ID=<CLIENT_ID_FROM_OKTA>
OAUTH_CLIENT_SECRET=<CLIENT_SECRET_FROM_OKTA>
OPENID_CONFIG_URL=https://<YOUR_OKTA_BASE_URL>/.well-known/openid-configuration
```

```bash values.yaml theme={null}
auth:
   secrets:
      OAUTH_CLIENT_ID: <CLIENT_ID_FROM_OKTA>
      OAUTH_CLIENT_SECRET: <CLIENT_SECRET_FROM_OKTA>
configMap:
   AUTH_TYPE: oidc
   OPENID_CONFIG_URL: https://<YOUR_OKTA_BASE_URL>/.well-known/openid-configuration
```


# SAML
Source: https://docs.onyx.app/deployment/authentication/saml

SAML authentication setup

Configure Onyx with SAML authentication.

SAML providers are managed at **Admin Panel** → **Organization** → [SSO
Providers](/deployment/authentication/sso_providers). No configuration files or restarts are needed,
and you can configure multiple providers (enabling more than one at the same time requires the Business plan,
see [Plan Availability](/deployment/authentication/sso_providers#plan-availability)).
SAML works on the standard Onyx images.

This guide walks through the setup for Okta. Other identity providers follow a similar process.
Please contact us if you need help with a different identity provider.

## Guide

<Steps>
  <Step title="Create Okta Application">
    Navigate to the Okta **Admin Console** → **Applications** → **Create App Integration**.

    <img alt="Okta Create Integration Page" />
  </Step>

  <Step title="Configure Okta Application">
    Select **SAML 2.0**.

    **Name** your application `Onyx` and upload the Onyx logo.

    <Tip>
      If you are white-labeling Onyx, you can freely name your application and upload your own logo.
    </Tip>

    Add a **Single sign-on URL** (the ACS URL, shared by every SAML provider on the instance):

    ```
    https://YOUR_ONYX_DOMAIN.com/auth/saml/callback
    ```

    Add an **Audience URI (SP Entity ID)**. Any stable identifier works,
    as long as it matches the SP entity ID you enter in Onyx:

    ```
    https://YOUR_ONYX_DOMAIN.com/metadata
    ```

    Add an **Attribute Statement** where **Name** is `email` and **Value** is `user.email`.

    <img alt="Okta Configure SAML Application Page" />
  </Step>

  <Step title="Assign Users to Application">
    Create the application and navigate to the **Assignments** tab to assign users.
  </Step>

  <Step title="Collect the IdP Values">
    Onyx needs three values from Okta:

    <AccordionGroup>
      <Accordion title="IdP Entity ID">
        Go to the **Sign On** tab of your application in Okta, copy the **Metadata URL**,
        and paste it into your browser. You should see XML like:

        ```XML theme={null}
        <md:EntityDescriptor
            xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
            entityID="http://www.okta.com/exkngircrvOYQyNg35d7">
        ...
        </md:EntityDescriptor>
        ```

        Copy the `entityID` value.
      </Accordion>

      <Accordion title="IdP x509 Certificate">
        In the XML from the previous step, find the `ds:X509Certificate` element.

        ```XML theme={null}
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>
                        [Some certificate value here]
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        ```

        Copy the certificate value.
      </Accordion>

      <Accordion title="IdP SSO URL">
        Go to the **General** tab of your application in Okta and copy the **Embed Link**.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Add the Provider in Onyx">
    Navigate to **Admin Panel** → **Organization** → [SSO Providers](/deployment/authentication/sso_providers)
    and click **Add Provider**.

    Select the **SAML** provider type, give the provider a **Name** (a lowercase slug, e.g. `okta`),
    and paste the **IdP entity ID**, **IdP SSO URL**, **IdP x509 certificate**,
    and the **SP entity ID** from the Okta application.

    <Accordion title="Optional: SP certificate and private key">
      If your IdP requires signed requests,
      generate a self-signed certificate and enter both values in the provider form:

      ```bash theme={null}
      openssl genrsa -out sp-private-key.pem 2048
      openssl req -new -x509 -key sp-private-key.pem -out sp-cert.pem -days 730 -subj "/CN=<YOUR_DOMAIN e.g. saml.onyx.dev>"
      ```
    </Accordion>

    After creating the provider, its row shows the exact **ACS URL**.
    Confirm it matches the single sign-on URL you registered in Okta,
    then sign in through the new option on the login page.
  </Step>
</Steps>

## Upgrading from v4.3 or Earlier

Versions before `v4.4.0` configured a single SAML provider through a `settings.json` file placed in the SAML config
directory (`SAML_CONF_DIR`, default `/app/onyx/configs/saml_config`), with `AUTH_TYPE=saml` set.
That flow uses the same ACS URL as above. On `v4.4.0` and later this configuration no longer enables SAML login,
and `AUTH_TYPE` is planned for full removal in `v4.5`. New installs must use the admin panel flow above.

<Note>
  When you upgrade an existing deployment,
  its `settings.json` is imported as an SSO provider entry automatically when the upgraded api server starts,
  and existing logins keep working.
  Keep the settings file mounted and `AUTH_TYPE=saml` set through the upgrade (the import reads both).
  The migrated provider keeps using the ACS URL already registered with your IdP, so nothing changes on the IdP side.
  Remove both after the provider appears in the admin panel.
</Note>


# SCIM
Source: https://docs.onyx.app/deployment/authentication/scim

Automated user and group provisioning with SCIM 2.0

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

Configure Onyx with SCIM 2.0 to automatically provision and deprovision users and groups from your identity provider.

Onyx has been tested with **Okta** and **Microsoft Entra ID** (Azure AD).
Other SCIM 2.0 providers have not been validated yet. If you need support for a specific provider,
reach out on our [Slack](https://join.slack.com/t/onyx-dot-app/shared_invite/zt-2twesxdr6-5iQitKZQpgq~hYIZ~dv3KA)
or [Discord](https://discord.gg/onyx) channels and we can add it to the roadmap.

<Note>
  SCIM handles **provisioning** — syncing users and groups into Onyx.
  You still need a separate authentication method (e.g. [OIDC](/deployment/authentication/oidc)
  or [SAML](/deployment/authentication/saml)) for user sign-in.
</Note>

## What SCIM Does

* **User provisioning** — Automatically create Onyx accounts when users are assigned in your IdP
* **User deprovisioning** — Deactivate Onyx accounts when users are unassigned or suspended
* **Group sync** — Push group membership changes from your IdP to Onyx
* **Profile updates** — Keep user attributes (name, email) in sync

## Generate a SCIM Token

Before configuring your identity provider, generate a SCIM bearer token in Onyx.

<Steps>
  <Step title="Navigate to SCIM Settings">
    In your Onyx instance, go to the **Admin Panel** → **Permissions** → **SCIM**.
  </Step>

  <Step title="Generate Token">
    Click **Generate SCIM Token**. A new bearer token will be created for your IdP to authenticate with.

    <Warning>
      The token is displayed **only once**. Copy or download it immediately.
      Generating a new token will revoke the previous one.
    </Warning>
  </Step>
</Steps>

You will need these two values when configuring your identity provider:

| Field             | Value                              |
| ----------------- | ---------------------------------- |
| **SCIM Base URL** | `https://YOUR_ONYX_DOMAIN/scim/v2` |
| **Bearer Token**  | The token generated above          |

## Configure Your Identity Provider

Use the **SCIM Base URL** and **Bearer Token** from the previous step when configuring provisioning in your IdP.

<CardGroup>
  <div>
    <Card title="Okta" icon="https://mintcdn.com/danswer/AyVhIwSdfMMIcs1k/assets/icons/okta.svg?fit=max&auto=format&n=AyVhIwSdfMMIcs1k&q=85&s=05656cbda2d13a6446b45bdbb452c0e8" href="https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm">
      Follow Okta's guide to add SCIM provisioning to your application
    </Card>
  </div>

  <Card title="Microsoft Entra ID" icon="microsoft" href="https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#getting-started">
    Follow Microsoft's guide to configure automatic provisioning
  </Card>
</CardGroup>

When prompted for connection details, use:

| IdP Field                          | Value                              |
| ---------------------------------- | ---------------------------------- |
| **SCIM Base URL** / **Tenant URL** | `https://YOUR_ONYX_DOMAIN/scim/v2` |
| **Authentication**                 | Bearer token (HTTP Header)         |

## Verifying the Connection

Once provisioning is configured,
the **SCIM** page in the Onyx Admin Panel will show a **Connected** status once the IdP has made its first request.
You can also check the **Users and Groups** page to confirm that provisioned users and groups appear correctly.

## Supported Attributes

The SCIM discovery endpoints are **unauthenticated** — no token required.
You can query them directly to see exactly what Onyx supports without guessing.

```bash theme={null}
curl -s https://YOUR_ONYX_DOMAIN/scim/v2/Schemas -H "Accept: application/scim+json" | jq .
curl -s https://YOUR_ONYX_DOMAIN/scim/v2/ServiceProviderConfig -H "Accept: application/scim+json" | jq .
curl -s https://YOUR_ONYX_DOMAIN/scim/v2/ResourceTypes -H "Accept: application/scim+json" | jq .
```

The tables below reflect the current responses.

### User Attributes (`/scim/v2/Schemas`)

| Attribute          | Type    | Required | Notes                                                  |
| ------------------ | ------- | -------- | ------------------------------------------------------ |
| `userName`         | string  | Yes      | Unique identifier — typically the user's email address |
| `name.givenName`   | string  | No       | First name                                             |
| `name.familyName`  | string  | No       | Last name                                              |
| `name.formatted`   | string  | No       | Full name including middle names and titles            |
| `emails[].value`   | string  | No       | Email address                                          |
| `emails[].type`    | string  | No       | Label, e.g. `work`                                     |
| `emails[].primary` | boolean | No       | Whether this is the primary email                      |
| `active`           | boolean | No       | Whether the account is active                          |
| `externalId`       | string  | No       | Identifier from the IdP (case-sensitive)               |

**Enterprise User extension** (`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`):

| Attribute       | Type   | Required | Notes             |
| --------------- | ------ | -------- | ----------------- |
| `department`    | string | No       | Department        |
| `manager.value` | string | No       | Manager's user ID |

### Group Attributes (`/scim/v2/Schemas`)

| Attribute           | Type   | Required | Notes                                    |
| ------------------- | ------ | -------- | ---------------------------------------- |
| `displayName`       | string | Yes      | Human-readable group name                |
| `members[].value`   | string | No       | User ID of the group member              |
| `members[].display` | string | No       | Display name of the member (read-only)   |
| `externalId`        | string | No       | Identifier from the IdP (case-sensitive) |

### Supported Operations (`/scim/v2/ServiceProviderConfig`)

| Feature         | Supported             |
| --------------- | --------------------- |
| PATCH           | Yes                   |
| Bulk operations | No                    |
| Filtering       | Yes (max 100 results) |
| Change password | No                    |
| Sorting         | No                    |
| ETags           | No                    |
| Authentication  | Bearer token          |

### Resource Types (`/scim/v2/ResourceTypes`)

| Resource | Endpoint          | Schema                                                                         |
| -------- | ----------------- | ------------------------------------------------------------------------------ |
| User     | `/scim/v2/Users`  | `urn:ietf:params:scim:schemas:core:2.0:User` + Enterprise extension (optional) |
| Group    | `/scim/v2/Groups` | `urn:ietf:params:scim:schemas:core:2.0:Group`                                  |


# SSO Providers
Source: https://docs.onyx.app/deployment/authentication/sso_providers

Manage multiple SSO providers from the admin panel

Onyx supports configuring SSO providers directly from the admin panel. Google, OIDC,
and SAML providers are stored as rows you can add, edit,
and enable without touching environment variables or restarting Onyx. Users pick their provider on the login page,
so one Onyx instance can serve teams on different identity providers.

<Note>
  Available starting in `v4.4.0`. From this version on, the admin panel is the only way to set up SSO.
  The legacy environment variables (`AUTH_TYPE=google_oauth`, `AUTH_TYPE=oidc`,
  or `AUTH_TYPE=saml` and their companion variables) no longer enable SSO on a new install.
  Onyx logs a warning while `AUTH_TYPE` is still set, and the variables are planned for full removal in `v4.5`.
  On a fresh install, create the first user with email and password (the first user becomes an admin),
  then add your provider from the admin panel.
</Note>

<Note>
  If you are upgrading from `v4.3` or earlier with environment-based SSO,
  the upgrade imports your configuration into an SSO provider entry automatically, and existing logins keep working.
  The import runs once, when the upgrade first runs against your existing database,
  so keep the legacy configuration in place through the upgrade.
  Migrated providers keep using the redirect URIs and ACS URLs already registered with your identity provider,
  so nothing changes on the IdP side. Once the migrated provider appears in the admin panel,
  sign-ins and token refresh use the provider entry's credentials, and the legacy variables (`AUTH_TYPE`,
  the OAuth credential variables, and for SAML the settings file) can be removed.
  The variables only act as a fallback for login accounts that no provider entry matches,
  such as after deleting or renaming the migrated provider.
</Note>

## Managing Providers

Navigate to **Admin Panel** → **Organization** → **SSO Providers**.

<img alt="SSO Providers admin page" />

<Steps>
  <Step title="Add a Provider">
    Click **Add Provider** and pick the provider type: **Google**, **OIDC**, or **SAML**.

    Give the provider a **Name** (a lowercase slug used in the login URL)
    and a **Display Name** (the label users see on the sign-in button).

    <img alt="Add SSO Provider modal" />
  </Step>

  <Step title="Fill in the Provider Configuration">
    Each provider type asks for its own credentials:

    * **Google**: Client ID and Client Secret from your Google Cloud Console.
    * **OIDC**: Client ID, Client Secret, and the OpenID configuration URL
      (the `.well-known/openid-configuration` endpoint).
    * **SAML**: IdP entity ID, IdP SSO URL, the IdP x509 certificate, and
      the SP entity ID. The SP certificate, private key, and email attribute are optional depending on your IdP.

    Optionally restrict the provider to specific **email domains**.
    Users outside those domains cannot sign in through it. (On Onyx Cloud this list is required.
    See [Onyx Cloud](#onyx-cloud) below.)

    OIDC entries also expose a **Require Verified Email Claim** toggle for IdPs that send the optional `email_verified`
    claim. Starting in `v4.5`,
    Google and OIDC entries additionally offer **Enable PKCE** and a per-provider **Scopes** override,
    taking precedence over the deployment-wide environment variables.
    See [Customizing requested scopes](/deployment/authentication/oidc#customizing-requested-scopes) for the details.
  </Step>

  <Step title="Register the Callback with your Identity Provider">
    After saving, the provider row shows its **Redirect URI** (OIDC and Google) or **ACS URL** (SAML).
    Copy it into your identity provider's console as the allowed callback for the application.
  </Step>

  <Step title="Verify the Sign-In Option">
    New providers are enabled on creation and appear as sign-in options on the login page.
    Use the toggle on the provider row to disable or re-enable it later.
  </Step>
</Steps>

## Onyx Cloud

Onyx Cloud is multi-tenant: many workspaces share one login page,
so provider configuration and sign-in work a little differently than self-hosted.

* The provider type picker offers **Google** and **OIDC** only. SAML is not available on Onyx Cloud.
* **Email Domains** are required, not optional. Without them the provider would admit every account your identity
  provider authenticates, and each one consumes a seat.
* The login page shows a single **Sign in with SSO** button. A visitor enters their email first, and Onyx resolves
  which workspace they belong to (or, for a first-time employee, which workspace their domain belongs to)
  and shows that workspace's sign-in options next.

### Domain Verification

Because Onyx Cloud serves many companies from one instance,
a domain only routes sign-ins once your workspace proves it controls that domain:
listing a domain on a provider claims it,
but a first-time employee on that domain cannot sign in and be provisioned automatically until the claim is verified.
Users already provisioned in the workspace can always sign in through the provider regardless of verification status.

<Steps>
  <Step title="Save the Provider">
    Add or update the provider with the domain listed under **Email Domains**, then save.
  </Step>

  <Step title="Publish the DNS Record">
    Reopen the provider and find the domain under **Domain Verification**.
    Copy the shown **Name** and **Value** into a new **TXT** record at your DNS provider.
  </Step>

  <Step title="Verify the Domain">
    Click **Verify Domain**. Onyx resolves the record and, on a match, marks the domain verified.
    DNS changes can take up to an hour to propagate, so if verification fails right away, wait and try again.
  </Step>
</Steps>

Onyx re-checks each verified domain's TXT record on an ongoing schedule (about every six hours).
If the record is removed or changed, the domain stops routing new sign-ins.
A temporary DNS lookup failure does not drop verification.

<Note>
  Domain verification does not apply to Google. List your email domains as usual,
  but a first-time employee on a Google Workspace domain can sign in and be provisioned without a DNS TXT record,
  since their Google sign-in already proves they control an address on that domain.
</Note>

## Turning Off Password Login

<Note>
  Available in `v4.5` and in `v4.4` patch releases after `v4.4.5`.
</Note>

Once SSO works, you can close password login and sign-up entirely so your identity provider is the only way in.
Go to **Admin Panel** → **Organization** → **Security & Hardening** and turn on **Disable Password Login & Signup**.

* The save is refused unless at least one SSO provider is enabled, so you
  cannot lock yourself out.
* With the switch on, the login page shows only the SSO sign-in options,
  the sign-up page redirects to login, and password sign-in is refused by the backend regardless of how it is called.
* Disabling the last enabled SSO provider is refused while the switch is on.
* Self-hosted (single-tenant) deployments only.

## Plan Availability

Configuring a single SSO provider is available on every plan.
Enabling more than one provider at the same time requires the **Business** plan or above.

## Notes

* Secrets are write-only. After saving, credentials are shown masked and are
  never returned in full by the API.
* Provider **type** and **name** are fixed after creation. To change them,
  add a new provider and disable the old one.
* Providers are disabled rather than deleted, so accounts that signed in
  through a provider survive a disable and re-enable.
* Google and OIDC sign-ins do not attach to an existing account with the same email.
  The sign-in fails with an error instead of merging the accounts. To move a user to a Google or OIDC provider,
  have an admin deactivate and then delete the account so the user can sign up fresh through it.
  SAML sign-ins match users by email, so an existing account can sign in through a new SAML provider directly.
* If open sign-up is restricted (the **Restrict Open Sign-Up** setting on
  **Admin Panel** → **Permissions** → **Users**), SSO sign-ups are gated too.
  New users who have not been invited are rejected at sign-in until an admin invites their email address.


# EC2
Source: https://docs.onyx.app/deployment/cloud/aws/ec2

Deploy Onyx on AWS EC2

Using AWS EC2 is the recommended way of deploying Onyx.
It is simple to set up and should meet the performance needs of 90% of organizations looking to use Onyx!

## Guide

<Steps>
  <Step title="Create an EC2 instance">
    Create an EC2 instance with the appropriate resources. For this guide,
    we will use the recommended `m7g.xlarge` instance.

    <Note>
      Read our [Resourcing guide](/deployment/getting_started/resourcing) for more details.
    </Note>

    * Give your instance a descriptive name like `onyx-prod`
    * Select the `Amazon Linux 2023` AMI
    * Select the `64-bit (Arm)` architecture
    * Select the `m7g.xlarge` instance type
    * Select `Allow HTTPS traffic from the internet` in the *Network settings* section
    * Configure storage following the Resourcing Guide

    <img alt="EC2 Instance Creation" />

    <img alt="EC2 Security Group Configuration" />
  </Step>

  <Step title="Create the instance">
    Click **Launch instance** and then view your instance details.

    <Tip>
      Save the **Public IPv4 address** of the instance!
    </Tip>

    <img alt="EC2 Public IPv4 Address" />
  </Step>

  <Step title="Point domain to the instance">
    <Note>
      If you don't have a domain, buy one from a DNS provider like [GoDaddy](https://www.godaddy.com/)
      or just skip HTTPS for now.
    </Note>

    To point our domain to the new instance, we need to add an `A` and `CNAME` record to our DNS provider.

    The `A` record should be the subdomain that you would like to use for the Onyx instance like `prod`.

    The `CNAME` record should be the same name with the `www.` in front resulting in `www.prod` pointing to the full
    domain like `prod.onyx.app`.

    <img alt="DNS A Record Configuration" />

    <img alt="DNS CNAME Record Configuration" />
  </Step>

  <Step title="Install Onyx requirements">
    Onyx requires `git`, `docker`, and `docker compose`.

    To install these on Amazon Linux 2023, run the following:

    ```bash theme={null}
    sudo yum update -y

    sudo yum install docker -y
    sudo service docker start

    sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
    sudo chmod +x /usr/local/bin/docker-compose

    sudo yum install git
    ```
  </Step>

  <Step title="Install and Configure Onyx">
    To install Onyx, we'll need to clone the repo and set the necessary environment variables.

    ```bash theme={null}
    git clone --depth 1 https://github.com/onyx-dot-app/onyx.git

    cd onyx/deployment/docker_compose
    cp env.prod.template .env
    cp env.nginx.template .env.nginx
    ```

    Fill out the `.env` and `.env.nginx` files.

    ```bash .env expandable theme={null}
    WEB_DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"

    # If your email is something like "chris@onyx.app", then this should be "onyx.app"
    # This prevents people outside your company from creating an account
    VALID_EMAIL_DOMAINS=<YOUR_COMPANIES_EMAIL_DOMAIN>
    ```

    Email/password login works out of the box, and SSO (Google / OIDC / SAML) is configured later from the admin panel.
    See our [auth guides](/deployment/authentication/basic) for details.

    ```bash .env.nginx theme={null}
    DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"
    ```
  </Step>

  <Step title="Launch Onyx">
    Running the `init-letsencrypt.sh` script will get us a SSL certificate from letsencrypt and launch the Onyx stack.

    ```bash theme={null}
    ./init-letsencrypt.sh
    ```

    <Warning>
      You will hit an error if you fail the letsencrypt workflow more than 5 times.
      You will need to wait 72 hours or request a new domain.
    </Warning>

    If you are skipping the HTTPS setup, start Onyx manually:

    ```bash theme={null}
    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
    ```

    <Note>
      Give Onyx a few minutes to start up.

      You can monitor the progress with `docker logs onyx-stack-api_server-1 -f`.
    </Note>

    You can access Onyx from the instance Public IPv4 or from the domain you set up earlier!
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# EKS
Source: https://docs.onyx.app/deployment/cloud/aws/eks

Deploy Onyx on AWS EKS

<Warning>
  EKS has recently updated their cluster and node group creation process. The contents of this guide are still relevant,
  but the flow has changed slightly.

  Updates to this guide are coming soon!
</Warning>

## Guide

<Steps>
  <Step title="Install requirements">
    EKS requires the AWS CLI and kubectl CLI.

    * Download and install the [AWS CLI](https://aws.amazon.com/cli/)
    * Download and install [kubectl CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/)
  </Step>

  <Step title="Create the cluster">
    For this guide, we will use standard settings with the EBS CSI driver.

    * Navigate to Elastic Kubernetes Service (EKS) and create a new cluster
    * For **Cluster service role**, create a new IAM role with a descriptive name like `onyx-eks-cluster-role`

    <Note>
      If you do not see the newly created role in the dropdown, click the refresh button in the UI.
    </Note>

    * For **Kubernetes version**, select a version with standard support
    * Choose **Standard** upgrade policy
    * Add the **Amazon EBS CSI Driver** add-on for Onyx's `Persistent Volume Claims`
    * Keep the other default add-ons enabled
    * Review and click **Create**

    The cluster may take several minutes to become ready

    <img alt="EKS Cluster Creation" />
  </Step>

  <Step title="Add nodes">
    Once the cluster is active, add worker nodes where Onyx services will run.

    * On the **Cluster** page, select the **Compute** tab and click **Add node group**
    * Provide a **Name** for the group (e.g., `onyx-node-group`)
    * For **Node IAM role**, either select an existing role used by your organization or create
      a new one.

    <Note>
      Ensure the role has the `AmazonEBSCSIDriverPolicy` attached so that PVCs can be fulfilled. If creating a role,
      add this policy in addition to the default policies.
    </Note>

    * Replace the **Instance types** with `c5.2xlarge` machines (or `c5.4xlarge` if you plan to scale beyond 100k documents)
    * Set **Volume size** in the 200GB - 800GB range depending on your document count

    <Tip>
      See the [Resourcing Guide](/deployment/getting_started/resourcing) for more details on storage requirements.
    </Tip>

    * For most setups, set the **Desired size** and **Minimum size** to 1. You can increase
      these later to scale up.
    * **Maximum unavailable** can remain at the default
    * Keep the default networking configuration and click **Create**

    It may take up to 15 minutes for the compute nodes to come online.
  </Step>

  <Step title="Create and connect a user">
    We will need an IAM user with CLI access to manage AWS and the cluster.

    * Navigate to the [IAM Dashboard](https://console.aws.amazon.com/iam/), select **Users** in the left sidebar, and click **Create user**

    * Give the user a descriptive name (e.g., `onyx-eks-user`)

    * Under permissions, click **Attach policies directly** and attach:

    * `AmazonEKSClusterPolicy`

    * `AmazonEKSServicePolicy`

    * Click **Create user**

    * On the user's page, click **Create access key** and follow the prompts.

    * Select the **Command Line Interface (CLI)** option during creation.

    <Tip>
      Save the **Access key** and **Secret access key** for later!
    </Tip>

    * Navigate back to the EKS cluster and select **Access** and then **Create access entry**
    * In **IAM principal**, select the IAM ARN we just created, then click **Next**
    * For Access policies, set **Policy name** to `AmazonEKSClusterAdminPolicy`, then click **Next** and **Create**
  </Step>

  <Step title="Fetch kubeconfig">
    Log in to the AWS CLI and provide the access key and secret key from the IAM user we just created:

    ```bash theme={null}
    aws configure
    ```

    Configure your kubeconfig to connect to the cluster by filling in the `region-code` and `cluster-name`:

    ```bash theme={null}
    aws eks update-kubeconfig --region region-code --name cluster-name
    ```

    <Info>
      Reference [AWS EKS kubeconfig docs](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html).
    </Info>
  </Step>

  <Step title="Install Onyx services">
    The Onyx Helm chart packages all the required services (API, web, PostgreSQL, Vespa, etc.) into a single deployment.
    By default, persistent volumes will be created for stateful services.

    First, ensure the `gp2` storage class is set as the default storage class (required for PVCs):

    ```bash theme={null}
    kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
    ```

    Add the Onyx Helm repository:

    ```bash theme={null}
    helm repo add onyx https://onyx-dot-app.github.io/onyx/
    helm repo update
    helm search repo onyx
    ```

    Create a dedicated namespace and install Onyx:

    ```bash theme={null}
    kubectl create namespace onyx
    helm install onyx onyx/onyx -n onyx
    ```

    This will pull the latest Onyx chart and deploy all dependencies.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    helm list -n onyx
    kubectl get pods -n onyx
    ```

    Wait until all pods are in a `Running` state before accessing Onyx.

    To check the API server logs (often the last to become ready):

    ```bash theme={null}
    kubectl -n onyx get pods | grep api-server | awk '{print $1}' | xargs -I {} kubectl -n onyx logs {} -f
    ```
  </Step>

  <Step title="Access Onyx">
    For local testing, port-forward:

    ```bash theme={null}
    kubectl -n onyx port-forward service/onyx-nginx 8080:80
    ```

    Then open [http://localhost:8080](http://localhost:8080).
  </Step>
</Steps>

## Upgrading

To upgrade Onyx services, first update the Helm repository:

```bash theme={null}
helm repo update
helm upgrade onyx onyx/onyx -n onyx
```

To upgrade to a specific version, use:

```bash theme={null}
helm upgrade onyx onyx/onyx -n onyx --version <VERSION>
```

## Uninstalling

To remove the Onyx services:

```bash theme={null}
helm uninstall onyx -n onyx
```

Vespa, Postgres, and MinIO leave behind PVCs. To delete them:

```bash theme={null}
kubectl -n onyx get pvc
kubectl -n onyx delete pvc vespa-storage-da-vespa-0
kubectl -n onyx delete pvc onyx-minio
kubectl -n onyx delete pvc data-onyx-postgresql-0
```

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# RDS
Source: https://docs.onyx.app/deployment/cloud/aws/rds

Setup AWS RDS for Onyx

Using AWS RDS provides a managed PostgreSQL database for Onyx.
This guide covers both basic and IAM authentication for enhanced security.

## Guide

<Steps>
  <Step title="Create an RDS PostgreSQL instance">
    Navigate to the Amazon RDS console and create a new PostgreSQL database.

    * Click **Create database**
    * Select **PostgreSQL** as the engine type
    * Choose **Standard create** for the creation method
    * Select your preferred **PostgreSQL version**
    * Choose **Production** or **Dev/Test** template as needed
  </Step>

  <Step title="Configure database settings">
    Set up your database identifier, credentials, and instance configuration.

    **Settings:**

    * Set a descriptive **DB instance identifier** like `onyx-prod-db`
    * Set **Master username** (e.g., `postgres`)
    * Set a strong **Master password** and confirm it

    **Instance configuration:**

    * Choose an appropriate **Instance class** (e.g., `db.t3.micro` for testing, `db.t3.medium` for production)
    * Configure **Storage** size and enable autoscaling if needed

    <Tip>
      Save your database credentials securely - you'll need them to configure Onyx.
    </Tip>
  </Step>

  <Step title="Configure connectivity and security">
    Set up network access and security groups for your database.

    * Select your **VPC** and **Subnet group**
    * Configure **VPC security group** to allow access from your Onyx instance
    * Set **Public access** to "No" for production (recommended)
    * Choose your preferred **Availability Zone**

    Click **Create database** to launch your RDS instance.
  </Step>

  <Step title="Configure Onyx environment variables">
    Once your RDS instance is running, configure Onyx to connect to it.

    Get your database details from the RDS console:

    * **Endpoint**: Found in the RDS instance details
    * **Port**: Typically `5432`
    * **Database name**: Your database name or `postgres` if using default

    **For Docker deployments**, add these variables to your `.env` file:

    ```bash theme={null}
    USE_IAM_AUTH=false
    POSTGRES_HOST=<your-rds-endpoint>
    POSTGRES_PORT=5432
    POSTGRES_DB=<your-database-name>
    POSTGRES_USER=<your-master-username>
    POSTGRES_PASSWORD=<your-master-password>
    ```

    **For EKS deployments**, add these to your `values.yaml` file:

    ```yaml theme={null}
    auth:
      secrets:
        POSTGRES_PASSWORD: "<your-master-password>"
    configMap:
      USE_IAM_AUTH: "false"
      POSTGRES_HOST: "<your-rds-endpoint>"
      POSTGRES_PORT: "5432"
      POSTGRES_DB: "<your-database-name>"
      POSTGRES_USER: "<your-master-username>"
    ```

    Onyx will now connect to your RDS PostgreSQL instance using these credentials.
  </Step>
</Steps>

## Optional: Enable IAM Authentication

For enhanced security, you can enable IAM database authentication instead of using static passwords.
This allows Onyx to connect using short-lived IAM credentials.

<Steps>
  <Step title="Enable IAM authentication on RDS">
    Navigate to your RDS instance in the AWS console and enable IAM authentication.

    * Go to your RDS PostgreSQL instance
    * Click **Modify**
    * Under **Database authentication**, enable **IAM database authentication**
    * Click **Continue**, then **Apply immediately**
  </Step>

  <Step title="Create IAM database user">
    Connect to your database and create a user for IAM authentication.

    Using your master credentials, run these SQL commands:

    ```sql theme={null}
    CREATE ROLE onyxuser LOGIN;
    GRANT rds_iam TO onyxuser;
    ALTER ROLE onyxuser WITH NOINHERIT;
    GRANT CREATE ON DATABASE <your-db-name> TO onyxuser;
    GRANT USAGE ON SCHEMA public TO onyxuser;
    GRANT CREATE ON SCHEMA public TO onyxuser;
    ```
  </Step>

  <Step title="Configure IAM policy">
    Create an IAM policy to allow database connections.

    Get your `DbiResourceId` or `DbClusterResourceId`:

    ```bash theme={null}
    aws rds describe-db-instances \
      --db-instance-identifier <your-db-instance-name> \
      --region <your-region>
    ```

    Create this IAM policy, fill in the `region`, `account-id`, `resource-id`, and attach it to your EC2 instance role:

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "rds-db:connect",
          "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<resource-id>/onyxuser"
        }
      ]
    }
    ```
  </Step>

  <Step title="Download SSL certificate">
    Download the RDS CA certificate bundle for secure connections.

    ```bash theme={null}
    wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem
    ```

    <Note>
      The SSL certificate is required for IAM authentication to work properly.
    </Note>
  </Step>

  <Step title="Configure Onyx for IAM authentication">
    Update your environment variables to use IAM authentication.

    **For Docker deployments**, add these variables to your `.env` file:

    ```bash theme={null}
    USE_IAM_AUTH=true
    AWS_REGION=<your-region>
    POSTGRES_HOST=<your-rds-endpoint>
    POSTGRES_PORT=5432
    POSTGRES_DB=<your-database-name>
    POSTGRES_USER=onyxuser
    ```

    Mount the SSL certificate in your `docker-compose.yml`:

    ```yaml docker-compose-prod.yml theme={null}
    services:
      api_server:
        volumes:
          - ./rds-combined-ca-bundle.pem:/app/bundle.pem:ro
    ```

    **For Kubernetes deployments**, add these to your `values.yaml` file:

    ```yaml theme={null}
    configMap:
      USE_IAM_AUTH: "true"
      AWS_REGION: "<your-region>"
      POSTGRES_HOST: "<your-rds-endpoint>"
      POSTGRES_PORT: "5432"
      POSTGRES_DB: "<your-database-name>"
      POSTGRES_USER: "onyxuser"
    ```

    Create a secret for the SSL certificate and mount it:

    ```bash theme={null}
    kubectl create secret generic bundle-pem-secret --from-file=rds-combined-ca-bundle.pem
    ```

    Next, we'll mount the certificate in all of our containers in the `values.yaml` file.

    **Go through each container and replace the empty `volumes` and `volumeMounts` with the following:**

    ```yaml theme={null}
    volumes:
    - name: rds-ca
        secret:
          secretName: bundle-pem-secret

    volumeMounts:
      - name: rds-ca
        mountPath: "/app/bundle.pem"
        subPath: bundle.pem
        readOnly: true
    ```
  </Step>

  <Step title="Restart Onyx">
    Restart your Onyx instance to apply the changes.

    ```bash Docker theme={null}
    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
    ```

    ```bash kubectl theme={null}
    kubectl rollout restart deployment
    ```
  </Step>
</Steps>

For more details,
see the [AWS RDS IAM Authentication
documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html).


# Azure
Source: https://docs.onyx.app/deployment/cloud/azure

Deploy Onyx on Azure Virtual Machines

<Steps>
  <Step title="Create a VM instance">
    Create a VM instance with the appropriate resources. For this guide,
    we will use the recommended `Standard_D4s_v3` instance.

    <Note>
      Read our [Resourcing guide](/deployment/getting_started/resourcing) for more details.
    </Note>

    * Give your instance a descriptive name like `onyx-prod`
    * Select the `Ubuntu Server 20.04 LTS` image
    * Select the `Standard_D4s_v3` size
    * Select `Allow selected ports` and check `HTTPS (443)` in the *Inbound port rules* section
    * Configure storage following the Resourcing Guide

    <img alt="Create VM Instance" />

    <img alt="Instance Settings" />

    <img alt="Network Settings" />
  </Step>

  <Step title="Create the instance">
    Click **Create** and then view your instance details.

    <Tip>
      Save the **Public IP address** of the instance!
    </Tip>

    <img alt="Azure Public IP Address" />
  </Step>

  <Step title="Point domain to the instance">
    <Note>
      If you don't have a domain, buy one from a DNS provider like [GoDaddy](https://www.godaddy.com/)
      or just skip HTTPS for now.
    </Note>

    To point our domain to the new instance, we need to add an `A` and `CNAME` record to our DNS provider.

    The `A` record should be the subdomain that you would like to use for the Onyx instance like `prod`.

    The `CNAME` record should be the same name with the `www.` in front resulting in `www.prod` pointing to the full
    domain like `prod.onyx.app`.

    <img alt="DNS A Record Configuration" />

    <img alt="DNS CNAME Record Configuration" />
  </Step>

  <Step title="Install Onyx requirements">
    Onyx requires `git`, `docker`, and `docker compose`.

    To install these on Ubuntu Server 20.04 LTS, run the following:

    ```bash theme={null}
    sudo apt-get update
    sudo apt-get install -y ca-certificates curl

    sudo install -m 0755 -d /etc/apt/keyrings
    sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
    sudo chmod a+r /etc/apt/keyrings/docker.asc

    echo \
      "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
      $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
      sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

    sudo apt-get update
    sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin git
    ```
  </Step>

  <Step title="Install and Configure Onyx">
    To install Onyx, we'll need to clone the repo and set the necessary environment variables.

    ```bash theme={null}
    git clone --depth 1 https://github.com/onyx-dot-app/onyx.git

    cd onyx/deployment/docker_compose
    cp env.prod.template .env
    cp env.nginx.template .env.nginx
    ```

    Fill out the `.env` and `.env.nginx` files.

    ```bash .env expandable theme={null}
    WEB_DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"

    # If your email is something like "chris@onyx.app", then this should be "onyx.app"
    # This prevents people outside your company from creating an account
    VALID_EMAIL_DOMAINS=<YOUR_COMPANIES_EMAIL_DOMAIN>
    ```

    Email/password login works out of the box, and SSO (Google / OIDC / SAML) is configured later from the admin panel.
    See our [auth guides](/deployment/authentication/basic) for details.

    ```bash .env.nginx theme={null}
    DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"
    ```
  </Step>

  <Step title="Launch Onyx">
    Running the `init-letsencrypt.sh` script will get us a SSL certificate from letsencrypt and launch the Onyx stack.

    ```bash theme={null}
    ./init-letsencrypt.sh
    ```

    <Warning>
      You will hit an error if you fail the letsencrypt workflow more than 5 times.
      You will need to wait 72 hours or request a new domain.
    </Warning>

    If you are skipping the HTTPS setup, start Onyx manually:

    ```bash theme={null}
    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
    ```

    <Note>
      Give Onyx a few minutes to start up.

      You can monitor the progress with `docker logs onyx-stack-api_server-1 -f`.
    </Note>

    You can access Onyx from the instance Public IPv4 or from the domain you set up earlier!
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# Digital Ocean
Source: https://docs.onyx.app/deployment/cloud/digital_ocean

Deploy Onyx on Digital Ocean Droplets

<Steps>
  <Step title="Create a Droplet">
    Create a Droplet with the appropriate resources. For this guide,
    we will use a recommended configuration with Docker pre-installed.

    <Note>
      Read our [Resourcing guide](/deployment/getting_started/resourcing) for more details.
    </Note>

    * Give your Droplet a descriptive name like `onyx-prod`
    * Select a region close to your users
    * Select the `Docker` image from the *Marketplace* tab
    * Choose a Droplet size with at least 4 vCPUs and 16GB RAM
    * Configure storage following the Resourcing Guide
    * Add your SSH key for secure access
  </Step>

  <Step title="Create the Droplet">
    Click **Create Droplet** and then view your Droplet details.

    <Tip>
      Save the **Public IP address** of the Droplet!
    </Tip>

    <img alt="Digital Ocean Public IP Address" />
  </Step>

  <Step title="Point domain to the instance">
    <Note>
      If you don't have a domain, buy one from a DNS provider like [GoDaddy](https://www.godaddy.com/)
      or just skip HTTPS for now.
    </Note>

    To point our domain to the new instance, we need to add an `A` and `CNAME` record to our DNS provider.

    The `A` record should be the subdomain that you would like to use for the Onyx instance like `prod`.

    The `CNAME` record should be the same name with the `www.` in front resulting in `www.prod` pointing to the full
    domain like `prod.onyx.app`.

    <img alt="DNS A Record Configuration" />

    <img alt="DNS CNAME Record Configuration" />
  </Step>

  <Step title="Install Onyx requirements">
    Since we selected the Docker Marketplace image, Docker and Docker Compose are already installed.

    We just need to install `git`:

    ```bash theme={null}
    sudo apt update
    sudo apt install -y git
    ```
  </Step>

  <Step title="Install and Configure Onyx">
    To install Onyx, we'll need to clone the repo and set the necessary environment variables.

    ```bash theme={null}
    git clone --depth 1 https://github.com/onyx-dot-app/onyx.git

    cd onyx/deployment/docker_compose
    cp env.prod.template .env
    cp env.nginx.template .env.nginx
    ```

    Fill out the `.env` and `.env.nginx` files.

    ```bash .env expandable theme={null}
    WEB_DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"

    # If your email is something like "chris@onyx.app", then this should be "onyx.app"
    # This prevents people outside your company from creating an account
    VALID_EMAIL_DOMAINS=<YOUR_COMPANIES_EMAIL_DOMAIN>
    ```

    Email/password login works out of the box, and SSO (Google / OIDC / SAML) is configured later from the admin panel.
    See our [auth guides](/deployment/authentication/basic) for details.

    ```bash .env.nginx theme={null}
    DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"
    ```
  </Step>

  <Step title="Launch Onyx">
    Running the `init-letsencrypt.sh` script will get us a SSL certificate from letsencrypt and launch the Onyx stack.

    ```bash theme={null}
    ./init-letsencrypt.sh
    ```

    <Warning>
      You will hit an error if you fail the letsencrypt workflow more than 5 times.
      You will need to wait 72 hours or request a new domain.
    </Warning>

    If you are skipping the HTTPS setup, start Onyx manually:

    ```bash theme={null}
    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
    ```

    <Note>
      Give Onyx a few minutes to start up.

      You can monitor the progress with `docker logs onyx-stack-api_server-1 -f`.
    </Note>

    You can access Onyx from the instance Public IPv4 or from the domain you set up earlier!
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# GCP
Source: https://docs.onyx.app/deployment/cloud/gcp

Deploy Onyx on GCP Compute Engine

**Make sure your Google Cloud Platform account has the necessary permissions to create a VM instance.**

<Steps>
  <Step title="Create a VM instance">
    Create a VM instance with the appropriate resources. For this guide,
    we will use the recommended `e2-standard-4` instance.

    <Note>
      Read our [Resourcing guide](/deployment/getting_started/resourcing) for more details.
    </Note>

    * Give your instance a descriptive name like `onyx-prod`
    * Select the `Debian GNU/Linux 12` boot disk
    * Select the `e2-standard-4` machine type
    * Select `Allow HTTPS traffic` in the **Firewall** section
    * Configure storage following the Resourcing Guide

    <img alt="Create VM Instance" />

    <img alt="Instance Settings" />

    <img alt="Firewall Settings" />
  </Step>

  <Step title="Create the instance">
    Click **Create** and then view your instance details.

    <Tip>
      Save the **External IP** of the instance!
    </Tip>
  </Step>

  <Step title="Point domain to the instance">
    <Note>
      If you don't have a domain, buy one from a DNS provider like [GoDaddy](https://www.godaddy.com/)
      or just skip HTTPS for now.
    </Note>

    To point our domain to the new instance, we need to add an `A` and `CNAME` record to our DNS provider.

    The `A` record should be the subdomain that you would like to use for the Onyx instance like `prod`.

    The `CNAME` record should be the same name with the `www.` in front resulting in `www.prod` pointing to the full
    domain like `prod.onyx.app`.

    <img alt="DNS A Record Configuration" />

    <img alt="DNS CNAME Record Configuration" />
  </Step>

  <Step title="Install Onyx requirements">
    Onyx requires `git`, `docker`, and `docker compose`.

    To install these on Debian GNU/Linux 12, run the following:

    ```bash theme={null}
    sudo apt update
    sudo apt install -y ca-certificates curl gnupg

    sudo install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
    sudo chmod a+r /etc/apt/keyrings/docker.gpg
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

    sudo apt update
    sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    ```

    If using CentOS, Red Hat Linux, or similar, run the following:

    ```bash theme={null}
    sudo yum update -y

    sudo yum install docker -y
    sudo service docker start

    sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
    sudo chmod +x /usr/local/bin/docker-compose

    sudo yum install git
    ```
  </Step>

  <Step title="Install and Configure Onyx">
    To install Onyx, we'll need to clone the repo and set the necessary environment variables.

    ```bash theme={null}
    git clone --depth 1 https://github.com/onyx-dot-app/onyx.git

    cd onyx/deployment/docker_compose
    cp env.prod.template .env
    cp env.nginx.template .env.nginx
    ```

    Fill out the `.env` and `.env.nginx` files.

    ```bash .env expandable theme={null}
    WEB_DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"

    # If your email is something like "chris@onyx.app", then this should be "onyx.app"
    # This prevents people outside your company from creating an account
    VALID_EMAIL_DOMAINS=<YOUR_COMPANIES_EMAIL_DOMAIN>
    ```

    Email/password login works out of the box, and SSO (Google / OIDC / SAML) is configured later from the admin panel.
    See our [auth guides](/deployment/authentication/basic) for details.

    ```bash .env.nginx theme={null}
    DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"
    ```
  </Step>

  <Step title="Launch Onyx">
    Running the `init-letsencrypt.sh` script will get us a SSL certificate from letsencrypt and launch the Onyx stack.

    ```bash theme={null}
    ./init-letsencrypt.sh
    ```

    <Warning>
      You will hit an error if you fail the letsencrypt workflow more than 5 times.
      You will need to wait 72 hours or request a new domain.
    </Warning>

    If you are skipping the HTTPS setup, start Onyx manually:

    ```bash theme={null}
    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
    ```

    <Note>
      Give Onyx a few minutes to start up.

      You can monitor the progress with `docker logs onyx-stack-api_server-1 -f`.
    </Note>

    You can access Onyx from the instance Public IPv4 or from the domain you set up earlier!
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# Chrome Extension
Source: https://docs.onyx.app/deployment/configuration/chrome_extension

Use Onyx in Chrome from any page

The Onyx Chrome Extension allows users to access Onyx from anywhere in their browser.

Features include:

* An Onyx browser home page
* An Onyx sidebar in your browser
* Contextual search on selected text
* Deep Research capabilities

<Info>
  Coming soon: Full page context chat and indexing visited pages into your Onyx knowledge base!
</Info>

<img alt="Onyx Chrome Extension Home Page" />

## Installation Options

**Onyx Cloud users**: Install directly from the Chrome Web Store

**Self-hosted users**: Your administrator will provide installation instructions

## Manual Installation (Self-Hosted)

<Steps>
  <Step title="Get the extension files">
    Clone the [Onyx Chrome Extension](https://github.com/onyx-dot-app/onyx-chrome-extension) repo from GitHub.
  </Step>

  <Step title="Enable Developer Mode">
    * Visit `chrome://extensions/` in your Chrome browser
    * In the upper right corner, click **Developer mode** to enable it

    <img alt="Chrome Extension Developer Mode" />
  </Step>

  <Step title="Load the extension">
    * Click **Load unpacked**
    * Select the folder containing the Onyx Chrome Extension files
    * Click **Load**

    The extension is now installed and ready to configure.
  </Step>

  <Step title="Configure connection settings">
    * Click the three dots (...) next to the extension
    * Select **Options**
    * Set the **Root Domain** to your self-hosted Onyx instance's URL

    <img alt="Extension Settings Menu" />

    <img alt="Root Domain Configuration" />
  </Step>
</Steps>

<Note>
  The extension will now connect to your self-hosted Onyx instance and can be used from any page in Chrome.
</Note>

## Enterprise Deployment

For organizations deploying the extension at scale, use Google Admin Console for centralized management.

<Steps>
  <Step title="Access Chrome Management">
    * Log in to your Google Admin console
    * Navigate to **Devices → Chrome → Apps and extensions**
  </Step>

  <Step title="Add the extension">
    * Obtain the Chrome extension ID from an Onyx team member - Click the yellow
      plus icon to add the extension - Enter the Chrome extension ID and click **Add**
  </Step>

  <Step title="Configure deployment">
    Configure deployment options such as:

    * Force installation for specific organizational units
    * User access controls
    * Update policies and version management
    * Installation policies (allowed, forced, or blocked)
  </Step>

  <Step title="Save configuration">
    <Warning>
      Remember to save your changes after configuring the extension settings.
    </Warning>
  </Step>
</Steps>

### Self-Hosting the Extension

For private distribution without the Chrome Web Store:

<Steps>
  <Step title="Package the extension">
    Use Chrome's developer tools to create a CRX file
  </Step>

  <Step title="Host the files">
    Place the CRX and update manifest on your server
  </Step>

  <Step title="Configure clients">
    Use Admin console or Group Policy to point to your hosted files
  </Step>
</Steps>

## Extension Management

### Update Policies

* **Enterprise deployments**: Chrome handles automatic updates every 5 hours
* **Version pinning**: Available for force-installed extensions, but avoid extended use due to
  security updates
* **Self-hosted updates**: Increment version in manifest.json and replace hosted files


# Configure Onyx
Source: https://docs.onyx.app/deployment/configuration/configuration

How to configure Onyx using environment variables and deployment files

<Warning>
  This page is for configuring your **deployment**.

  To find out more about configuring the Onyx app, checkout our [Admin docs](/admins/overview)!
</Warning>

## Configuring Onyx Deployments

Onyx offers a wide range of deployment-level configuration options.
These are controlled via environment variables or through your deployment files.

## Onyx Lite

Onyx Lite is a minimal deployment of Onyx designed for teams that only need the core LLM chat experience without
connectors or RAG search. It is ideal for resource-constrained environments, quick evaluations,
or use cases where you want to bring your own LLM and tools without ingesting external data sources.

### What's Included

Onyx Lite retains the following capabilities:

* LLM chat conversations
* Tools (including code interpreter in Docker deployments)
* User file uploads
* Projects
* Agent knowledge
* Assistants (without RAG retrieval)

### What's Removed

To reduce resource requirements, Onyx Lite disables:

* **Vespa** (vector database): no document indexing or RAG search
* **Redis**: PostgreSQL handles caching and session management instead
* **Model servers**: no local embedding models (LLM inference is handled by your configured provider)
* **Celery background workers**: the API server handles background work directly
* **MinIO / S3 file storage**: PostgreSQL handles file storage instead
* **Connectors**: all data source connectors are disabled

### How It Works

Onyx Lite is not a separate application.
It uses the same Onyx images with a different configuration that consolidates all storage onto PostgreSQL and disables
the vector database. The key environment variables that drive this are:

| Variable             | Lite Value | Full Onyx Default | Purpose                                              |
| -------------------- | ---------- | ----------------- | ---------------------------------------------------- |
| `DISABLE_VECTOR_DB`  | `true`     | `false`           | Disables Vespa, connectors, and RAG search           |
| `CACHE_BACKEND`      | `postgres` | `redis`           | Uses PostgreSQL for caching instead of Redis         |
| `AUTH_BACKEND`       | `postgres` | `redis`           | Uses PostgreSQL for sessions instead of Redis        |
| `FILE_STORE_BACKEND` | `postgres` | `s3`              | Uses PostgreSQL for file storage instead of S3/MinIO |

<Note>
  Onyx Lite cannot be used with the Craft feature (`ENABLE_CRAFT`).
</Note>

<AccordionGroup>
  <Accordion title="Configuring Docker Deployments">
    If you don't have a `.env` file:

    ```bash theme={null}
    cd onyx/deployment/docker_compose
    cp env.prod.template .env

    # If applicable
    cp env.nginx.template .env.nginx
    ```

    The template files have a subset of common environment variables provided for you.
    You can add more environment variables (listed below) to these `.env` files.

    Some configuration options must be set in your Docker Compose file.

    <Note>
      The Docker Compose file you use to launch Onyx is the one you will need to modify.
      Likely either `docker-compose.dev.yml` or `docker-compose.prod.yml`.
    </Note>

    ### Deploying Onyx Lite with Docker Compose

    Onyx Lite is deployed using a Docker Compose override file that layers on top of your base Compose file.
    The override moves non-essential services (Vespa, Redis, model servers, background workers)
    into Docker Compose [profiles](https://docs.docker.com/compose/how-tos/profiles/) so they do not start by default.

    **Quick start:**

    ```bash theme={null}
    cd onyx/deployment/docker_compose
    docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml up -d
    ```

    With development ports exposed:

    ```bash theme={null}
    docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml \
                   -f docker-compose.dev.yml up -d --wait
    ```

    Services started in Lite mode:

    | Service                                   | Description                                    |                                                   |
    | ----------------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
    | api\_server                               | Onyx API server (also handles background work) |                                                   |
    | web\_server                               | Next.js frontend                               |                                                   |
    | relational\_db                            | PostgreSQL database                            |                                                   |
    | nginx                                     | Reverse proxy                                  |                                                   |
    | Services not started (moved to profiles): |                                                |                                                   |
    | Service                                   | Profile                                        | Bring back with                                   |
    | --------------------------                | ----------------                               | -----------------------------------------         |
    | background (Celery)                       | background                                     | --profile background (also needs --profile redis) |
    | cache (Redis)                             | redis                                          | --profile redis                                   |
    | index (Vespa)                             | vectordb                                       | --profile vectordb                                |
    | indexing\_model\_server                   | vectordb                                       | --profile vectordb                                |
    | inference\_model\_server                  | inference                                      | --profile inference                               |

    <Tip>
      You can selectively bring services back by adding `--profile <name>` flags. For example, to run Lite with Redis:

      ```bash theme={null}
      docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml \
                  --profile redis up -d
      ```
    </Tip>

    <Note>
      The .env file setup is the same as a standard Docker deployment.
      Lite-specific environment variables (DISABLE\_VECTOR\_DB, CACHE\_BACKEND, AUTH\_BACKEND, FILE\_STORE\_BACKEND)
      are set automatically by the override file, so you do not need to add them to your .env.
    </Note>
  </Accordion>

  <Accordion title="Configuring Kubernetes Deployments">
    Kubernetes deployments are configured using Helm charts.
    We have provided a `values.yaml` file where you can set all environment variables.

    ```bash theme={null}
    cd onyx/deployment/helm/charts/onyx
    vim values.yaml
    ```

    Add environment variables and secrets to the `configMap` and `auth.secrets` sections.
    A subset of common configuration options are provided for you. You can add more environment variables (listed below)
    to these sections.

    ### Deploying Onyx Lite with Helm

    Onyx Lite is deployed by providing the values-lite.yaml file when installing the Helm chart.
    This values file disables the vector database, Redis, and all Celery workers, leaving only the API server,
    web server, and PostgreSQL. Quick start:

    ```
    helm install onyx ./deployment/helm/charts/onyx \
      -f ./deployment/helm/charts/onyx/values-lite.yaml
    ```

    To merge with your own overrides (custom domain, auth, LLM config, etc.):

    ```
      helm install onyx ./deployment/helm/charts/onyx \
    -f ./deployment/helm/charts/onyx/values-lite.yaml \
    -f my-overrides.yaml
    ```

    <Tip>
      You can always upgrade from Lite to a full deployment later by re-installing with the default values.yaml (without
      values-lite.yaml). This will bring up Opensearch, Redis, and all background workers.
    </Tip>
  </Accordion>
</AccordionGroup>

<Tip>
  Many configuration options are available in the Admin Panel! This page only covers deployment-level configuration.
</Tip>

## Commonly Configured Options

### Authentication

<CardGroup>
  <Card title="Basic Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up email and password authentication.
  </Card>

  <Card title="Google OAuth" icon="google" href="/deployment/authentication/oauth">
    Authenticate with Google accounts.
  </Card>

  <Card title="OIDC" icon="shield-check" href="/deployment/authentication/oidc">
    Single-sign on with OpenID Connect (OIDC)
  </Card>

  <Card title="SAML" icon="shield-check" href="/deployment/authentication/saml">
    Single-sign on with Security Assertion Markup Language (SAML)
  </Card>
</CardGroup>

### Custom Domain

To host Onyx on a custom domain,
set the `WEB_DOMAIN` environment variable and update your DNS records to point to your public Onyx deployment IP.

For additional instructions, read the [EC2 Deployment Guide](/deployment/cloud/aws/ec2)!

### SSL

If using Docker,
the `init-letsencrypt.sh` script in `onyx/deployment/docker_compose` will automatically generate a Let's Encrypt
certificate and launch Onyx with SSL enabled.

### Web Search

To enable the Web Search Tool, set the `EXA_API_KEY` environment variable.

<Note>
  Web Search in Onyx is continually developing and these instructions will be updated as we make improvements.
</Note>

### Logging

When self-hosting Onyx, you can configure the level of detail in the logs. This is helpful when troubleshooting issues.

If using Docker, set `LOG_LEVEL` to `debug` in each container of your Docker Compose file.

If using Kubernetes, set `LOG_LEVEL` to `debug` in your `values.yaml` file.

### Observability

You can connect your observability tools to Onyx. We support the following providers:

**Braintrust (recommended)**

Braintrust is what we use internally for the cloud version of Onyx. Set the following environment variables:

```bash theme={null}
BRAINTRUST_PROJECT="Your project name"
BRAINTRUST_API_KEY="sk-..."
```

**Langfuse**

```bash theme={null}
LANGFUSE_SECRET_KEY="sk-..."
LANGFUSE_PUBLIC_KEY="pk-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com" # Or "https://us.cloud.langfuse.com"
```

### Craft

Craft is enabled with `ENABLE_CRAFT=true` and requires a supported sandbox backend.
Use `SANDBOX_BACKEND=docker` for Docker Compose deployments and `SANDBOX_BACKEND=kubernetes` for Helm deployments.

Read [Deploying Craft](/deployment/local/craft) before enabling Craft in self-hosted deployments.

## Onyx Environment Variables

<Info>
  This is not an exhaustive list of all Onyx environment variables.
</Info>

<AccordionGroup>
  <Accordion title="App Configuration">
    `SKIP_WARM_UP`: Skip application warm-up process for hot-reloading the `API server`.
    Only set this for development purposes.

    `WEB_DOMAIN`: Set this if you are deploying Onyx on a custom domain.

    `DISABLE_GENERATIVE_AI`: Disable generative AI features.

    `DISABLE_USER_KNOWLEDGE`: Controls whether users can use the My Documents feature with assistants.

    `ONYX_QUERY_HISTORY_TYPE`: Controls query history reports (show user emails, anonymous, no queries)
  </Accordion>

  <Accordion title="Craft Configuration">
    `ENABLE_CRAFT`: Enables Craft APIs and UI. Defaults to `false`.

    `SANDBOX_BACKEND`: Craft sandbox backend. Valid values are `docker` and `kubernetes`. Defaults to `kubernetes`.

    `SANDBOX_API_SERVER_URL`: Onyx base URL reachable from inside Craft sandboxes. Required for Craft deployments.

    `SANDBOX_IDLE_TIMEOUT_SECONDS`: Idle timeout before sandbox sleep or cleanup. Defaults to `3600`.

    `SANDBOX_MAX_CONCURRENT_PER_ORG`: Maximum concurrent Craft sandboxes per organization. Defaults to `10`.

    `SANDBOX_TURN_TIMEOUT_SECONDS`: Wall-clock budget for one Craft turn. Defaults to `900`.

    `BUILD_MAX_UPLOAD_FILE_SIZE_MB`: Maximum Craft session attachment size. Defaults to `50`.

    `BUILD_MAX_UPLOAD_FILES_PER_SESSION`: Maximum number of files attached to one Craft session. Defaults to `20`.

    `BUILD_MAX_TOTAL_UPLOAD_SIZE_MB`: Maximum total attachment size for one Craft session. Defaults to `200`.

    `USER_LIBRARY_MAX_FILE_SIZE_MB`: Maximum User Library file size. Defaults to `500`.

    `USER_LIBRARY_MAX_FILES_PER_UPLOAD`: Maximum files in one User Library upload. Defaults to `100`.

    `USER_LIBRARY_MAX_TOTAL_SIZE_GB`: Maximum User Library storage per user. Defaults to `10`.

    Docker backend variables:

    * `SANDBOX_DOCKER_MEMORY_LIMIT`: Per-sandbox Docker memory limit. Defaults to `2g`.
    * `SANDBOX_DOCKER_CPU_LIMIT`: Per-sandbox Docker CPU limit. Defaults to `1.0`.

    Docker Compose Craft uses the `onyx_craft_sandbox` bridge network created by the installer and referenced by the
    Craft compose overlay.
  </Accordion>

  <Accordion title="Authentication & Security">
    `AUTH_TYPE`: Legacy (pre-`v4.4.0`). Authentication is always enabled and SSO is configured in the admin panel,
    so the variable is inert. Planned for full removal in `v4.5`.

    `PASSWORD_MIN_LENGTH`: For basic auth. The minimum password length requirement

    `PASSWORD_MAX_LENGTH`: For basic auth. The maximum password length requirement

    `PASSWORD_REQUIRE_UPPERCASE`: For basic auth. Require uppercase letters in passwords

    `PASSWORD_REQUIRE_LOWERCASE`: For basic auth. Require lowercase letters in passwords

    `PASSWORD_REQUIRE_DIGIT`: For basic auth. Require digits in passwords

    `PASSWORD_REQUIRE_SPECIAL_CHAR`: For basic auth. Require special characters in passwords

    `ENCRYPTION_KEY_SECRET`: Enterprise Edition only. Key for encrypting connector credentials, API keys, etc.

    `MASK_CREDENTIAL_PREFIX`: Mask connector credentials in the admin UI.
    Turn off if admins should see the credentials in the admin panel.

    `SESSION_EXPIRE_TIME_SECONDS`: Session expiration time in seconds.

    `AUTH_COOKIE_EXPIRE_TIME_SECONDS`: JWT token validity duration in seconds.

    `VALID_EMAIL_DOMAINS`: Comma-separated list of allowed email domains.

    `REQUIRE_EMAIL_VERIFICATION`: Require email verification for registration

    `TRACK_EXTERNAL_IDP_EXPIRY`: Honor the `expires_at` field returned by the external identity provider.
    Disabled be default because many auth providers have very short expiry times.

    `JWT_PUBLIC_KEY_URL`: JWKS or PEM endpoint for verifying API bearer JWTs.
    See [JWT Header Auth](/deployment/authentication/jwt).

    `JWT_EXPECTED_AUDIENCE`: Reject bearer JWTs whose `aud` claim does not match. Empty disables the check.

    `JWT_EXPECTED_ISSUER`: Reject bearer JWTs whose `iss` claim does not match. Empty disables the check.
  </Accordion>

  <Accordion title="OAuth & OIDC Configuration">
    `OAUTH_CLIENT_ID`: For both Google OAuth and OIDC.

    `OAUTH_CLIENT_SECRET`: For both Google OAuth and OIDC.

    `OPENID_CONFIG_URL`: For OIDC.

    `GOOGLE_OAUTH_SCOPE_OVERRIDE`: For Google login.
    Comma-separated list of scopes to request from Google instead of the defaults (`openid,email,profile`).
    Useful when the access token from login needs to be passed through to tool calls that require additional Google API
    scopes (i.e. when using Pass-Through OAuth for an MCP server).
    Any scopes added here must also be enabled on the OAuth client in Google Cloud Console.

    `OIDC_SCOPE_OVERRIDE`: For OIDC login.
    Comma-separated list of scopes to request from the OIDC provider instead of the defaults.
    Same use case as `GOOGLE_OAUTH_SCOPE_OVERRIDE`.

    `OIDC_PKCE_ENABLED`: For OIDC login. Set to `true` to enable PKCE in the OIDC login flow.
    Disabled by default for backwards compatibility.
  </Accordion>

  <Accordion title="JWT Header Auth">
    `JWT_PUBLIC_KEY_URL`: URL that serves the public key material (JWKS or PEM) for an external token issuer. When set,
    Onyx accepts an RS256 JWT in the `Authorization: Bearer` header and resolves the user from the token's email claim.
    See [JWT Header Auth](/deployment/authentication/jwt) for the full behavior.
  </Accordion>

  <Accordion title="Email Configuration">
    <Info>
      Set the following for basic auth email verification and invites.
    </Info>

    `SMTP_SERVER`: SMTP server hostname

    `SMTP_PORT`: SMTP server port

    `SMTP_USER`: SMTP username

    `SMTP_PASS`: SMTP password

    `EMAIL_FROM`: From email address

    `SENDGRID_API_KEY`: Alternative to SMTP for email delivery.

    `ENABLE_EMAIL_INVITES`: Enable email invitations
  </Accordion>

  <Accordion title="Slack Configuration">
    `OAUTH_SLACK_CLIENT_ID`: Slack OAuth client ID for Slack bot.

    `OAUTH_SLACK_CLIENT_SECRET`: Slack OAuth client secret for Slack bot.
  </Accordion>

  <Accordion title="Postgres Configuration">
    `POSTGRES_USER`: PostgreSQL username

    `POSTGRES_PASSWORD`: PostgreSQL password

    `POSTGRES_HOST`: PostgreSQL host

    `POSTGRES_PORT`: PostgreSQL port

    `POSTGRES_DB`: PostgreSQL database name

    `POSTGRES_API_SERVER_POOL_SIZE`: API server connection pool size

    `POSTGRES_API_SERVER_POOL_OVERFLOW`: API server pool overflow

    `POSTGRES_API_SERVER_READ_ONLY_POOL_SIZE`: Read-only pool size

    `POSTGRES_API_SERVER_READ_ONLY_POOL_OVERFLOW`: Read-only pool overflow

    `POSTGRES_USE_NULL_POOL`: Use null connection pool

    `POSTGRES_POOL_PRE_PING`: Enable connection pre-ping

    `POSTGRES_POOL_RECYCLE`: Pool recycle timeout in seconds

    `USE_IAM_AUTH`: Use IAM authentication for database

    `DB_READONLY_USER`: Read-only database user

    `DB_READONLY_PASSWORD`: Read-only database password
  </Accordion>

  <Accordion title="Redis Configuration">
    `REDIS_SSL`: Enable SSL for Redis connections

    `REDIS_HOST`: Redis host

    `REDIS_PORT`: Redis port

    `REDIS_PASSWORD`: Redis password

    `REDIS_REPLICA_HOST`: Redis replica host

    `REDIS_DB_NUMBER`: Redis database number

    `REDIS_DB_NUMBER_CELERY_RESULT_BACKEND`: Celery result backend database number

    `REDIS_DB_NUMBER_CELERY`: Celery broker database number

    `REDIS_HEALTH_CHECK_INTERVAL`: Health check interval

    `REDIS_POOL_MAX_CONNECTIONS`: Maximum pool connections

    `REDIS_SSL_CERT_REQS`: SSL certificate requirements

    `REDIS_SSL_CA_CERTS`: SSL CA certificates
  </Accordion>

  <Accordion title="Vespa Configuration">
    `VESPA_HOST`: Vespa host

    `VESPA_CONFIG_SERVER_HOST`: Vespa config server host

    `VESPA_PORT`: Vespa port

    `VESPA_TENANT_PORT`: Vespa tenant port

    `NUM_RETRIES_ON_STARTUP`: Startup connection attempts

    `VESPA_CLOUD_URL`: Vespa Cloud URL

    `VESPA_CLOUD_CERT_PATH`: Vespa Cloud certificate path

    `VESPA_CLOUD_KEY_PATH`: Vespa Cloud key path

    `MANAGED_VESPA`: Use managed Vespa (Vespa Cloud)

    `VESPA_REQUEST_TIMEOUT`: Request timeout in seconds

    `VESPA_LANGUAGE_OVERRIDE`: Force Vespa language (en, de, etc.)
  </Accordion>

  <Accordion title="Celery Configuration">
    `CELERY_RESULT_EXPIRES`: Result expiration time in seconds

    `CELERY_BROKER_POOL_LIMIT`: Broker connection pool limit

    `CELERY_WORKER_LIGHT_CONCURRENCY`: Light worker concurrency

    `CELERY_WORKER_LIGHT_PREFETCH_MULTIPLIER`: Light worker prefetch multiplier

    `CELERY_WORKER_DOCPROCESSING_CONCURRENCY`: Document processing worker concurrency

    `CELERY_WORKER_DOCFETCHING_CONCURRENCY`: Document fetching worker concurrency

    `CELERY_WORKER_KG_PROCESSING_CONCURRENCY`: Knowledge graph processing worker concurrency
  </Accordion>

  <Accordion title="Rate Limiting">
    <Info>
      These rate limits apply to auth endpoints
    </Info>

    `RATE_LIMIT_WINDOW_SECONDS`: Rate limiting window in seconds

    `RATE_LIMIT_MAX_REQUESTS`: Maximum requests per window

    `REQUEST_TIMEOUT_SECONDS`: Default request timeout
  </Accordion>

  <Accordion title="Indexing Configuration">
    `INDEX_BATCH_SIZE`: Batch size during indexing

    `DISABLE_INDEX_UPDATE_ON_SWAP`: Disable primary index updates during embedding model swaps

    `ENABLE_MULTIPASS_INDEXING`: Enable multipass indexing for better accuracy

    `ENABLE_CONTEXTUAL_RAG`: Enable contextual retrieval

    `SKIP_METADATA_IN_CHUNK`: Skip metadata in chunks

    `INDEXING_SIZE_WARNING_THRESHOLD`: Size warning threshold in bytes

    `INDEXING_EMBEDDING_MODEL_NUM_THREADS`: Embedding model threads

    `CONTINUE_ON_CONNECTOR_FAILURE`: Continue indexing on connector failures

    `MAX_DOCUMENT_CHARS`: Maximum document characters

    `MAX_FILE_SIZE_BYTES`: Maximum file size in bytes

    `USE_DOCUMENT_SUMMARY`: Use document summary for contextual RAG

    `USE_CHUNK_SUMMARY`: Use chunk summary for contextual RAG
  </Accordion>

  <Accordion title="Connector Configuration">
    <Note>
      Most of the settings below can be configured in the admin UI.
    </Note>

    **General Connector Settings**

    `ENABLED_CONNECTOR_TYPES`: Comma-separated list of enabled connector types

    `LEAVE_CONNECTOR_ACTIVE_ON_INITIALIZATION_FAILURE`: Keep connector active on init failure

    **Web Connector**

    `WEB_CONNECTOR_VALIDATE_URLS`: Validate URLs in web connector

    `HTML_BASED_CONNECTOR_TRANSFORM_LINKS_STRATEGY`: Link transformation strategy

    `PARSE_WITH_TRAFILATURA`: Use Trafilatura for HTML parsing

    **Confluence Connector**

    `OAUTH_CONFLUENCE_CLOUD_CLIENT_ID`: Confluence Cloud OAuth client ID

    `OAUTH_CONFLUENCE_CLOUD_CLIENT_SECRET`: Confluence Cloud OAuth client secret

    `CONFLUENCE_CONNECTOR_LABELS_TO_SKIP`: Labels to skip during indexing

    `CONFLUENCE_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD`: Attachment size threshold

    `CONFLUENCE_CONNECTOR_ATTACHMENT_CHAR_COUNT_THRESHOLD`: Attachment character threshold

    `CONFLUENCE_CONNECTOR_USER_PROFILES_OVERRIDE`: User profiles override JSON

    `CONFLUENCE_TIMEZONE_OFFSET`: Timezone offset for CQL queries

    **Google Drive Connector**

    `OAUTH_GOOGLE_DRIVE_CLIENT_ID`: Google Drive OAuth client ID

    `OAUTH_GOOGLE_DRIVE_CLIENT_SECRET`: Google Drive OAuth client secret

    `MAX_DRIVE_WORKERS`: Maximum Google Drive workers

    `GOOGLE_DRIVE_CONNECTOR_SIZE_THRESHOLD`: File size threshold for Google Drive

    **SharePoint Connector**

    `SHAREPOINT_CONNECTOR_SIZE_THRESHOLD`: File size threshold for SharePoint

    **Jira Connector**

    `JIRA_CONNECTOR_LABELS_TO_SKIP`: Labels to skip during indexing

    `JIRA_CONNECTOR_MAX_TICKET_SIZE`: Maximum ticket size in bytes

    **GitHub Connector**

    `GITHUB_CONNECTOR_BASE_URL`: GitHub base URL (for enterprise)

    **GitLab Connector**

    `GITLAB_CONNECTOR_INCLUDE_CODE_FILES`: Include code files in indexing

    **Gong Connector**

    `GONG_CONNECTOR_START_TIME`: Start time for Gong connector

    **Notion Connector**

    `NOTION_CONNECTOR_DISABLE_RECURSIVE_PAGE_LOOKUP`: Disable recursive page lookup

    **Zendesk Connector**

    `ZENDESK_CONNECTOR_SKIP_ARTICLE_LABELS`: Article labels to skip

    **Egnyte Integration**

    `EGNYTE_CLIENT_ID`: Egnyte OAuth client ID

    `EGNYTE_CLIENT_SECRET`: Egnyte OAuth client secret

    **Linear Integration**

    `LINEAR_CLIENT_ID`: Linear OAuth client ID

    `LINEAR_CLIENT_SECRET`: Linear OAuth client secret
  </Accordion>

  <Accordion title="Pruning Configuration">
    `ALLOW_SIMULTANEOUS_PRUNING`: Allow simultaneous pruning operations

    `MAX_PRUNING_DOCUMENT_RETRIEVAL_PER_MINUTE`: Maximum document retrieval rate during pruning
  </Accordion>

  <Accordion title="Tool Configuration">
    `OKTA_PROFILE_TOOL_ENABLED`: Enable Okta profile tool

    `OKTA_API_TOKEN`: Okta API token for SSWS auth
  </Accordion>

  <Accordion title="Logging Configuration">
    `LOG_ONYX_MODEL_INTERACTIONS`: Log Onyx model interactions

    `LOG_VESPA_TIMING_INFORMATION`: Log Vespa query performance

    `LOG_ENDPOINT_LATENCY`: Log endpoint latency

    `LOG_POSTGRES_LATENCY`: Log PostgreSQL latency

    `LOG_POSTGRES_CONN_COUNTS`: Log PostgreSQL connection counts
  </Accordion>

  <Accordion title="Image Processing Configuration">
    `IMAGE_MODEL_NAME`: Image model name

    `AZURE_IMAGE_API_VERSION`: Azure OpenAI image API version

    `AZURE_IMAGE_API_KEY`: Azure OpenAI key used for image generation

    `AZURE_IMAGE_API_BASE`: Azure OpenAI endpoint base URL for image generation

    `AZURE_IMAGE_DEPLOYMENT_NAME`: Azure OpenAI image deployment namespace

    `AZURE_DALLE_API_VERSION`: Legacy alias for `AZURE_IMAGE_API_VERSION` (kept for backwards compatibility)

    `AZURE_DALLE_API_KEY`: Legacy alias for `AZURE_IMAGE_API_KEY` (kept for backwards compatibility)

    `AZURE_DALLE_API_BASE`: Legacy alias for `AZURE_IMAGE_API_BASE` (kept for backwards compatibility)

    `AZURE_DALLE_DEPLOYMENT_NAME`: Legacy alias for `AZURE_IMAGE_DEPLOYMENT_NAME` (kept for backwards compatibility)

    `IMAGE_SUMMARIZATION_SYSTEM_PROMPT`: System prompt for image summarization

    `IMAGE_SUMMARIZATION_USER_PROMPT`: User prompt for image summarization
  </Accordion>

  <Accordion title="File Storage Configuration">
    `S3_FILE_STORE_BUCKET_NAME`: S3 bucket name for file storage

    `S3_FILE_STORE_PREFIX`: S3 prefix for file storage

    `S3_ENDPOINT_URL`: S3 endpoint URL (for MinIO and other S3-compatible storage)

    `S3_VERIFY_SSL`: Verify SSL for S3 connections

    `S3_AWS_ACCESS_KEY_ID`: AWS access key ID for S3

    `S3_AWS_SECRET_ACCESS_KEY`: AWS secret access key for S3
  </Accordion>

  <Accordion title="Telemetry & Analytics">
    `DISABLE_TELEMETRY`: Disable anonymous usage telemetry

    `CUSTOM_ANSWER_VALIDITY_CONDITIONS`: Custom answer validity conditions
  </Accordion>

  <Accordion title="API Configuration">
    `API_PREFIX`: Used to prepend a base path for all API routes.
    Set this to `/api` if you are running Onyx behind a reverse proxy that doesn't support stripping the `/api` prefix
    from requests to the `API server`.

    `API_KEY_HASH_ROUNDS`: Hash rounds for API keys

    `LLM_MODEL_UPDATE_API_URL`: LLM model update API endpoint

    `LITELLM_CUSTOM_ERROR_MESSAGE_MAPPINGS`: Custom error message mappings (JSON)

    `GEN_AI_MODEL_FALLBACK_MAX_TOKENS`: Maximum token limit for generative AI model fallback
  </Accordion>

  <Accordion title="Enterprise Configuration">
    <Tip>
      [Contact us](/deployment/miscellaneous/contact_us) to enable Enterprise Edition features!
    </Tip>

    `DATA_PLANE_SECRET`: Secret for secure control/data plane communication

    `EXPECTED_API_KEY`: Additional security check for control plane API

    `CONTROL_PLANE_API_BASE_URL`: Control plane API base URL
  </Accordion>

  <Accordion title="Development & Testing">
    `DEV_MODE`: Enable development mode

    `INTEGRATION_TESTS_MODE`: Enable integration tests mode

    `MOCK_LLM_RESPONSE`: Boolean to create mock LLM responses for testing
  </Accordion>

  <Accordion title="Deployment Configuration">
    `POD_NAME`: Kubernetes pod name

    `POD_NAMESPACE`: Kubernetes pod namespace

    `AWS_REGION_NAME`: AWS region name

    `TARGET_AVAILABLE_TENANTS`: Number of pre-provisioned tenants to maintain

    `SYSTEM_RECURSION_LIMIT`: System recursion limit
  </Accordion>
</AccordionGroup>

## Enterprise Edition Environment Variables

Enterprise Edition adds additional environment variables to Onyx.

<AccordionGroup>
  <Accordion title="ENV_SEED_CONFIGURATION">
    Setting this variable allows you to start your Onyx instance with pre-configured options that persist across
    restarts.

    `ENV_SEED_CONFIGURATION` accepts a JSON string with the following options:

    * `llms`: List of LLM configurations (name, provider, api\_key, api\_base, api\_version, custom\_config, default\_model\_name, fast\_default\_model\_name)
    * `admin_user_emails`: List of email addresses for automatic admin role assignment
    * `seeded_name`: Pre-set name for your Onyx instance
    * `seeded_logo_path`: Path to your logo within the assets folder
  </Accordion>

  <Accordion title="API_KEY_HASH_ROUNDS">
    This variable allows you to configure the number of rounds used in the SHA-256 Crypt hashing algorithm for API keys.

    * Default value: `535000`
    * Allowed range: `1000` to `999999999`

    <Info>
      Increasing this value enhances security but may impact performance.
      The default value provides a good balance for most use cases.
    </Info>
  </Accordion>
</AccordionGroup>


# Onyx MCP Server
Source: https://docs.onyx.app/deployment/configuration/mcp_server

Connect LLMs like Claude, Cursor, and other AI tools to your Onyx knowledge base via the Model Context Protocol

## Overview

The Onyx MCP Server lets any MCP-compatible LLM client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.)
access your Onyx knowledge base, web search,
and URL fetching capabilities through the [Model Context Protocol](https://modelcontextprotocol.io/).

## Prerequisites

Before connecting, you'll need:

* **A running Onyx instance** (either self-hosted or Onyx Cloud)
* **Authentication** — see [Personal Access Tokens](/developers/overview#personal-access-tokens)
  or [API Keys](/admins/user_management/api_keys)
* **An MCP-compatible client** (Claude Desktop, Claude Code, Cursor, etc.)

<Card title="Self-Hosted MCP Server Configuration" icon="server" href="#self-hosted-configuration">
  Jump to environment variables, networking, and deployment settings for self-hosted MCP server
</Card>

## Quick Start

### Claude Code (CLI)

```bash theme={null}
claude mcp add --transport http onyx https://cloud.onyx.app/mcp \
  --header "Authorization: Bearer YOUR_ONYX_TOKEN_HERE"
```

Or add it to your project's `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "onyx": {
      "type": "http",
      "url": "https://cloud.onyx.app/mcp",
      "headers": {
        "Authorization": "Bearer ${ONYX_TOKEN}"
      }
    }
  }
}
```

Then set the environment variable before running Claude Code:

```bash theme={null}
export ONYX_TOKEN="your-token-here"
claude
```

### Claude Desktop

Add the following to your Claude Desktop config file:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "onyx": {
      "url": "https://cloud.onyx.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ONYX_TOKEN_HERE"
      }
    }
  }
}
```

<Tip>
  Replace `https://cloud.onyx.app/mcp` with `http://YOUR_ONYX_DOMAIN:8090/` if you're self-hosting.
</Tip>

### Cursor / Windsurf / Other MCP Clients

Most MCP clients support HTTP transport with custom headers. The connection details are:

| Setting         | Value                                                        |
| --------------- | ------------------------------------------------------------ |
| **URL**         | `https://cloud.onyx.app/mcp` (or `http://YOUR_DOMAIN:8090/`) |
| **Transport**   | HTTP (Streamable HTTP)                                       |
| **Auth Header** | `Authorization: Bearer YOUR_TOKEN`                           |

Refer to your client's MCP documentation for exact configuration steps.

## Available Tools

The MCP server exposes three tools that LLM clients can invoke:

<AccordionGroup>
  <Accordion title="search_indexed_documents" icon="magnifying-glass">
    Search your private knowledge base indexed in Onyx. Returns ranked document chunks with content, relevance scores,
    and metadata.

    **Parameters:**

    | Parameter      | Type      | Required | Default     | Description                                                        |
    | -------------- | --------- | -------- | ----------- | ------------------------------------------------------------------ |
    | `query`        | string    | Yes      | —           | Natural language search query                                      |
    | `source_types` | string\[] | No       | All sources | Filter by connector type (e.g. `["confluence", "github", "jira"]`) |
    | `time_cutoff`  | string    | No       | No cutoff   | ISO 8601 datetime — only return docs updated after this time       |
    | `limit`        | integer   | No       | `10`        | Maximum number of results to return                                |

    **Example call:**

    ```json theme={null}
    {
      "query": "What is the latest status of PROJ-1234?",
      "source_types": ["jira", "google_drive"],
      "time_cutoff": "2025-01-01T00:00:00Z",
      "limit": 5
    }
    ```

    **Response fields:**

    | Field                             | Description                                                |
    | --------------------------------- | ---------------------------------------------------------- |
    | `documents`                       | Array of result objects                                    |
    | `documents[].semantic_identifier` | Human-readable document name                               |
    | `documents[].content`             | Relevant text snippet                                      |
    | `documents[].source_type`         | Connector source (e.g. `"confluence"`)                     |
    | `documents[].link`                | URL to the original document                               |
    | `documents[].score`               | Relevance score                                            |
    | `total_results`                   | Number of results returned                                 |
    | `query`                           | The original query                                         |
    | `executed_queries`                | List of queries actually executed (may include expansions) |

    <Tip>
      To discover which source types are available, use the `indexed_sources` resource (see below).
    </Tip>
  </Accordion>

  <Accordion title="search_web" icon="globe">
    Search the public internet for general knowledge and current events.

    **Parameters:**

    | Parameter | Type    | Required | Default | Description               |
    | --------- | ------- | -------- | ------- | ------------------------- |
    | `query`   | string  | Yes      | —       | Search query              |
    | `limit`   | integer | No       | `5`     | Maximum number of results |

    **Example call:**

    ```json theme={null}
    {
      "query": "React 19 migration guide",
      "limit": 5
    }
    ```

    **Response fields:**

    | Field               | Description                 |
    | ------------------- | --------------------------- |
    | `results`           | Array of web search results |
    | `results[].title`   | Page title                  |
    | `results[].url`     | Page URL                    |
    | `results[].snippet` | Short text excerpt          |
    | `query`             | The original query          |

    <Note>
      `search_web` returns snippets, not full page content. Use `open_urls` to fetch the complete text of any result.
    </Note>
  </Accordion>

  <Accordion title="open_urls" icon="link">
    Retrieve the complete text content from one or more web URLs.

    **Parameters:**

    | Parameter | Type      | Required | Description           |
    | --------- | --------- | -------- | --------------------- |
    | `urls`    | string\[] | Yes      | List of URLs to fetch |

    **Example call:**

    ```json theme={null}
    {
      "urls": [
        "https://react.dev/blog/2024/12/05/react-19",
        "https://react.dev/learn/react-compiler"
      ]
    }
    ```

    **Response fields:**

    | Field               | Description                 |
    | ------------------- | --------------------------- |
    | `results`           | Array of fetched pages      |
    | `results[].title`   | Page title                  |
    | `results[].url`     | The fetched URL             |
    | `results[].content` | Full extracted text content |
  </Accordion>
</AccordionGroup>

## Available Resources

<AccordionGroup>
  <Accordion title="indexed_sources" icon="database">
    **URI:** `resource://indexed_sources`

    Lists all document connector types currently indexed in your Onyx instance (e.g. `"confluence"`, `"github"`,
    `"google_drive"`, `"slack"`).

    Use this to discover valid values for the `source_types` filter in `search_indexed_documents`.

    **Example response:**

    ```json theme={null}
    {
      "indexed_sources": ["confluence", "github", "google_drive", "jira", "slack"]
    }
    ```
  </Accordion>
</AccordionGroup>

## Self-Hosted Configuration

To self-host the MCP server, you will need to enable the deployment via environment variables.

Docker:

```bash .env theme={null}
MCP_SERVER_ENABLED=true
```

Kubernetes:

```yaml values.yaml theme={null}
configMap:
  MCP_SERVER_ENABLED: "true"
```

### Health Check

Verify the MCP server is running:

```bash theme={null}
curl http://localhost:8090/health # or http://YOUR_DOMAIN:8090/health
```

Expected response:

```json theme={null}
{
  "status": "healthy",
  "service": "mcp_server"
}
```

### Environment Variables

<Info>
  Most users should not need to configure these environment variables.
</Info>

| Variable                                    | Default     | Description                                                                                    |
| ------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `MCP_SERVER_ENABLED`                        | `false`     | Set to `"true"` to enable the MCP server                                                       |
| `MCP_SERVER_HOST`                           | `0.0.0.0`   | Host to bind the MCP server                                                                    |
| `MCP_SERVER_PORT`                           | `8090`      | Port for the MCP server                                                                        |
| `MCP_SERVER_CORS_ORIGINS`                   | (empty)     | Comma-separated list of allowed CORS origins                                                   |
| `API_SERVER_PROTOCOL`                       | `http`      | Protocol for internal API server connection                                                    |
| `API_SERVER_HOST`                           | `127.0.0.1` | Hostname for internal API server connection                                                    |
| `API_SERVER_URL_OVERRIDE_FOR_HTTP_REQUESTS` | (unset)     | Full URL override for API server. Use this when self-hosting the MCP server against Onyx Cloud |

## Debugging & Testing

### MCP Inspector

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive debugging tool for MCP servers:

```bash theme={null}
npx @modelcontextprotocol/inspector
```

**Setup in Inspector:**

* Ignore the OAuth configuration menus
* Open the **Authentication** tab
* Select **Bearer Token** authentication
* Paste your Onyx PAT or API key
* Click **Connect**

Once connected, you can browse tools, test calls with different parameters, and inspect request/response payloads.

## Next Steps

<CardGroup>
  <Card title="Personal Access Tokens" icon="key" href="/developers/overview#personal-access-tokens">
    Create a token to authenticate with the MCP server
  </Card>

  <Card title="API Keys" icon="shield-check" href="/admins/user_management/api_keys">
    Create shared API keys for team-wide MCP access
  </Card>

  <Card title="Connectors" icon="plug" href="/admins/connectors/overview">
    Add data sources to make your knowledge searchable via MCP
  </Card>

  <Card title="MCP Actions" icon="diagram-project" href="/admins/actions/mcp">
    Connect Onyx to external MCP servers as a client
  </Card>
</CardGroup>


# Website Widget
Source: https://docs.onyx.app/deployment/configuration/website_widget

Deploy the Onyx chat widget on your website

The Onyx Website Widget allows you to embed AI-powered chat directly on any website.

Features include:

* Lightweight \~100-150kb gzipped bundle
* Fully customizable colors and branding
* Responsive design (desktop popup, mobile fullscreen)
* Real-time streaming responses via SSE
* Session persistence across page reloads

## Deployment Options

### Cloud Deployment (Recommended)

For Onyx Cloud users, the widget is served from Onyx's CDN. Simply add the following to your website:

```html theme={null}
<!-- Load the widget -->
<script type="module" src="https://cdn.onyx.app/widget/1.1/dist/onyx-widget.js"></script>

<!-- Configure and display -->
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="your_api_key_here"
  mode="launcher"
>
</onyx-chat-widget>
```

### Self-Hosted Deployment

For self-hosted Onyx instances, you'll need to build and host the widget yourself.

<Steps>
  <Step title="Clone the repository">
    Clone the [Onyx repository](https://github.com/onyx-dot-app/onyx) from GitHub.
  </Step>

  <Step title="Navigate to widget directory">
    ```bash theme={null}
    cd widget/
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Obtain a widget API key">
    Navigate to your Onyx admin panel and create a new API key specifically for the widget.

    <img alt="Creating a widget API key in the Onyx admin panel" />

    <Warning>
      Create a **limited-scope API key** with only chat permissions.
      Never use admin or full-access keys since the API key will be visible in client-side code.
    </Warning>
  </Step>

  <Step title="Configure environment (optional)">
    For builds with baked-in configuration, create a `.env` file:

    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env` and set your backend URL and API key:

    ```
    VITE_WIDGET_BACKEND_URL=https://your-backend.com
    VITE_WIDGET_API_KEY=your_api_key
    ```
  </Step>

  <Step title="Build the widget">
    For **cloud-style deployment** (config via HTML attributes):

    ```bash theme={null}
    npm run build:cloud
    ```

    For **self-hosted deployment** (config baked into bundle):

    ```bash theme={null}
    npm run build:self-hosted
    ```
  </Step>

  <Step title="Deploy the bundle">
    Upload `dist/onyx-widget.js` to your CDN or web server.
  </Step>
</Steps>

### Customer Embed Code

After deployment, provide customers with the embed code:

**Cloud-style (attributes required):**

```html theme={null}
<script type="module" src="https://your-cdn.com/onyx-widget.js"></script>
<onyx-chat-widget
  backend-url="https://your-backend.com"
  api-key="customer_api_key"
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</onyx-chat-widget>
```

**Self-hosted (config baked in):**

```html theme={null}
<script type="module" src="https://your-cdn.com/onyx-widget.js"></script>
<onyx-chat-widget
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</onyx-chat-widget>
```

## Configuration Reference

### Required Attributes

| Attribute     | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `backend-url` | string | Your Onyx backend API URL  |
| `api-key`     | string | API key for authentication |

#### `backend-url`

The URL of your Onyx backend API. This is where the widget sends chat requests.

* **Onyx Cloud**: Use `https://cloud.onyx.app` or your tenant-specific URL
* **Self-hosted**: Use your Onyx instance URL (e.g., `https://onyx.yourcompany.com`)

```html theme={null}
<!-- Onyx Cloud -->
<onyx-chat-widget backend-url="https://cloud.onyx.app/api" ...></onyx-chat-widget>

<!-- Self-hosted -->
<onyx-chat-widget backend-url="https://onyx.yourcompany.com" ...></onyx-chat-widget>
```

#### `api-key`

A valid Onyx API key for authenticating widget requests. **This key is visible in client-side code**,
so always use a limited-scope key.

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123xyz789"
  ...
></onyx-chat-widget>
```

<Note>
  For self-hosted builds with baked-in config,
  `backend-url` and `api-key` can be set via environment variables during build instead of HTML attributes.
</Note>

### Optional Attributes

| Attribute           | Type    | Default       | Description                                      |
| ------------------- | ------- | ------------- | ------------------------------------------------ |
| `agent-id`          | number  | `undefined`   | Specific agent/persona to use                    |
| `agent-name`        | string  | `"Assistant"` | Display name in header                           |
| `logo`              | string  | Onyx logo     | URL to custom logo image                         |
| `primary-color`     | string  | `#1c1c1c`     | Primary brand color (buttons, accents)           |
| `background-color`  | string  | `#e9e9e9`     | Widget background color                          |
| `text-color`        | string  | `#000000bf`   | Text color (75% opacity black)                   |
| `mode`              | string  | `"launcher"`  | Display mode: `"launcher"` or `"inline"`         |
| `include-citations` | boolean | `false`       | Show citation badges linking to source documents |

#### `include-citations`

When enabled, assistant messages display clickable citation badges below the response text.
Each badge shows a sequential number and the source document title, linking directly to the original document.

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123"
  include-citations="true"
>
</onyx-chat-widget>
```

<Warning>
  **Be mindful of document access when enabling citations.** The widget will cite any documents accessible to the
  configured agent or API key. If the agent has access to private or internal documents,
  citation links may point to resources that end users do not have permission to view.

  To avoid exposing private document links, either scope the agent's document access to only public-facing sources,
  or disable citations for public-facing widget deployments.
</Warning>

## API Key Security

<Warning>
  The widget's API key is exposed in client-side code. Always create a dedicated API key with:

  * **Limited permissions** - Only chat access, no admin features
  * **Rate limiting** - Prevent abuse from malicious actors
  * **Monitoring** - Track usage and detect anomalies
</Warning>

<Steps>
  <Step title="Create a widget-specific API key">
    In your Onyx admin panel, create a new API key with minimal permissions.
  </Step>

  <Step title="Enable rate limiting">
    Configure rate limits appropriate for your expected usage.
  </Step>

  <Step title="Monitor usage">
    Regularly review API key usage for unusual patterns.
  </Step>
</Steps>

## Browser Support

* Chrome/Edge 90+ (Chromium)
* Firefox 90+
* Safari 15+
* Mobile Safari (iOS 15+)
* Mobile Chrome (Android)

<Info>
  **Need help with setup?** Contact your Onyx administrator for API key configuration or deployment assistance.
</Info>


# Quickstart
Source: https://docs.onyx.app/deployment/getting_started/quickstart

Recommended way to deploy Onyx in minutes

## Onyx CLI

The recommended way to install Onyx is the guided installer built into the [Onyx CLI](/overview/onyx_anywhere/cli):

```bash theme={null}
uv tool install onyx-cli && onyx-cli deploy install
```

The installer will:

* Check your system resources and requirements (installing Docker on Linux if needed)
* Let you choose between **Lite** and **Standard** deployment modes
* Prompt for the version of Onyx to deploy
* Set up the deployment configuration in `~/.config/onyx`
* Pull the Onyx containers, start them, and wait until every service is healthy

After installation, the same command group manages the deployment: `onyx-cli deploy upgrade`, `status`, `logs`, `stop`,
and `uninstall`.

<Card title="Deploy with the Onyx CLI" icon="terminal" href="/deployment/local/onyx_cli">
  Full documentation for `onyx-cli deploy` and its lifecycle commands.
</Card>

## Installation Scripts

The installation scripts are thin wrappers around the CLI:
they install `onyx-cli` if needed and run `onyx-cli deploy install`, producing the same deployment as the command above.
Use them when you want a single copy-paste one-liner:

<Tabs>
  <Tab title="Linux / macOS">
    ```bash theme={null}
    curl -fsSL https://onyx.app/install_onyx.sh | bash
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://onyx.app/install_onyx.ps1 | iex
    ```
  </Tab>
</Tabs>

Or download the script and run it manually:

<CardGroup>
  <Card title="Linux / macOS (Bash)" icon="terminal" href="https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.sh">
    Download **install.sh** and run it with `bash install.sh`.
  </Card>

  <Card title="Windows (PowerShell)" icon="windows" href="https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.ps1">
    Download **install.ps1** and run it with `.\install.ps1` in PowerShell.
  </Card>
</CardGroup>

<Info>
  Older versions of the scripts were standalone and installed into a directory called **onyx\_data**.
  The Onyx CLI detects those deployments and manages them in place — see [migrating an existing
  deployment](/deployment/local/onyx_cli#migrating-an-existing-deployment).
</Info>

## Next Steps

<CardGroup>
  <Card title="Set Up the Desktop App" icon="desktop" href="/deployment/local/desktop_app">
    Install the Onyx desktop application for a native experience on Windows, macOS, and Linux.
  </Card>

  <Card title="Deploy Onyx on AWS EC2" icon="aws" href="/deployment/cloud/aws/ec2">
    Follow our guide to deploy Onyx on an AWS EC2 instance.
  </Card>
</CardGroup>


# Resourcing
Source: https://docs.onyx.app/deployment/getting_started/resourcing

Resource requirements for deploying Onyx

## Resourcing Overview

### Onyx Lite

| Resource | Minimum | Preferred |
| -------- | ------- | --------- |
| CPU      | 2 vCPU  | 4 vCPU    |
| RAM      | 2 GB    | 4 GB      |
| Disk     | 10 GB   | 50 GB     |

<Info>
  Onyx Lite uses under 1GB of memory at baseline.
  Disk and memory usage scale with the number of files users upload to the system,
  since PostgreSQL handles file storage in Lite mode.
</Info>

### Onyx Standard

| Resource | Minimum                     | Preferred                             |
| -------- | --------------------------- | ------------------------------------- |
| CPU      | 4 vCPU                      | 8+ vCPU                               |
| RAM      | 10 GB                       | 16+ GB                                |
| Disk     | 32 GB + \~2.5x indexed data | 500 GB for organizations \<5000 users |

<Warning>
  OpenSearch enforces a read-only block on indices when disk usage hits the flood stage watermark (default 95%),
  which effectively blocks all writes. Monitor disk usage and plan capacity accordingly.
</Warning>

## Local Deployment (Docker)

You can control the resources available to Docker in the **Resources** section of the Docker Desktop settings menu.

<Info>
  Often old, unused Docker images take up sizeable disk space. To clean up dangling images, run `docker image prune`.
</Info>

## Cloud Providers (AWS, GCP, etc.)

For small to mid scale deployments, we recommend deploying Onyx to a single instance in your cloud provider of choice.

When evaluating your instance, follow the Preferred resources in the table above.

### Onyx Lite

| Provider | Recommended Instance Type |
| -------- | ------------------------- |
| AWS      | `t3.medium`               |
| GCP      | `e2-medium`               |
| Azure    | `B2s`                     |

### Onyx Standard

| Provider     | Recommended Instance Type                       |
| ------------ | ----------------------------------------------- |
| AWS          | `m7g.xlarge`                                    |
| GCP          | `e2-standard-4` or `e2-standard-8`              |
| Azure        | `D4s_v3`                                        |
| DigitalOcean | Meet the preferred resources in the table above |

## Container-Specific Resourcing (Standard)

For more efficient scaling, you can dedicate resources to each Onyx container using Kubernetes or AWS EKS.

See the [Onyx Helm chart](https://github.com/onyx-dot-app/onyx/blob/main/deployment/helm/charts/onyx/values.yaml)
`values.yaml` for our default requests and limits.

| Component                | CPU        | Memory |
| ------------------------ | ---------- | ------ |
| `api_server`             | 1          | 2 Gi   |
| `background`             | 2          | 8 Gi   |
| `indexing_model_server`  | 2          | 4 Gi   |
| `inference_model_server` | 2          | 4 Gi   |
| `postgres`               | 2          | 2 Gi   |
| `opensearch`             | 2          | 4 Gi   |
| `nginx`                  | 250m (1/4) | 128 Mi |

<Info>
  If you are using cloud-based embedding models (e.g. OpenAI, Cohere, etc.) instead of locally hosted ones,
  the `indexing_model_server` and `inference_model_server` will use significantly less memory.
</Info>

All together, this comes out to a total available node size of at least \~12 CPU and \~24GB of Memory.

## Container-Specific Resourcing (Lite)

Onyx Lite runs only four services. All storage is consolidated onto PostgreSQL.

| Component    | CPU        | Memory |
| ------------ | ---------- | ------ |
| `api_server` | 1          | 1 Gi   |
| `web_server` | 250m (1/4) | 512 Mi |
| `postgres`   | 1          | 1 Gi   |
| `nginx`      | 250m (1/4) | 128 Mi |

<Info>
  Memory usage in Lite mode scales with the number of user-uploaded files, since PostgreSQL handles file storage,
  caching, and session management.
</Info>

## How Resource Requirements Scale

The main driver of resource requirements for Standard mode is the number of indexed documents.
This primarily affects the search index (OpenSearch),
which is responsible for storing documents and handling search requests.

### OpenSearch Memory

OpenSearch memory is split roughly 50/50 between the JVM heap and the OS file system cache.
Both halves are critical — the heap handles indexing and search operations while the file system cache keeps frequently
accessed index segments in memory for fast reads.

Key rules for JVM heap sizing:

* Set `Xms` and `Xmx` to **50% of available RAM** (the other 50% goes to OS/file cache)
* **Never exceed 32 GB heap** — beyond this, Java disables compressed ordinary object pointers, causing
  significant performance degradation

### Storage Overhead

OpenSearch adds overhead on top of the raw source data. The formula for on-disk storage is:

```
Storage = Source data × (1 + replicas) × 1.45
```

The 1.45 multiplier accounts for indexing overhead (\~10%), Linux reserved space (\~5%),
and OpenSearch internal overhead (\~20%), plus a safety margin.

<Note>
  Onyx defaults to 0 replicas for single-node deployments, so storage is approximately **1.45× the source data size**.
</Note>

### Scaling Guidelines

OpenSearch resource requirements scale linearly with the volume of indexed data.
The exact ratio depends on deployment size — large distributed clusters are more efficient per GB than single-node
deployments due to fixed per-node overhead (cluster management, garbage collection, segment merging).

Industry guidelines for large clusters suggest a memory-to-data ratio of around 1:16 for search-heavy workloads.
However, for the **single-node deployments typical of self-hosted Onyx**,
the fixed overhead per node is a much larger fraction of total resources.

Based on our experience, we recommend the following for single-node or small-cluster deployments:

| Scale            | Memory per 1 GB of source docs | CPU per 1 GB of source docs |
| ---------------- | ------------------------------ | --------------------------- |
| Small (\< 5 GB)  | \~2 GB                         | \~0.25 CPU                  |
| Medium (5–50 GB) | \~1.5 GB                       | \~0.25 CPU                  |
| Large (50+ GB)   | \~1 GB                         | \~0.2 CPU                   |

The per-GB cost decreases at larger scale because the fixed baseline overhead is amortized. At very large scale,
consider a dedicated OpenSearch cluster or a managed service.

Other factors that may affect resource requirements include:

* The embedding model and vector dimensions
* Whether you have quantization and dimensional reduction enabled
* Query throughput and concurrency

### Resourcing Example

For a deployment with 10GB of text content, your `opensearch` component will need:

* Memory: 4 (base) + 10 × 1.5 = 19 GB
* CPU: 2 (base) + 10 × 0.25 = 4.5 cores

If deploying in a single instance, this would be *in addition to* the base requirements. Overall, that would take us to

> \= 9 CPU and >= 35GB of memory.

Given these requirements, a `m7g.2xlarge` or `c5.4xlarge` EC2 instance would be appropriate.

If deploying with Kubernetes or AWS EKS, this would give a per-component resource allocation of:

| Component                | CPU | Memory |
| ------------------------ | --- | ------ |
| `api_server`             | 1   | 2 Gi   |
| `background`             | 2   | 8 Gi   |
| `indexing_model_server`  | 2   | 4 Gi   |
| `inference_model_server` | 2   | 4 Gi   |
| `postgres`               | 2   | 4 Gi   |
| `opensearch`             | 5   | 19 Gi  |

Total available node size: \~14 CPU and \~41GB of Memory.

## Next Steps

<CardGroup>
  <Card title="Guide: Deploy Onyx Locally" icon="microchip" href="/deployment/local/docker">
    Deploy Onyx locally with Docker.
  </Card>

  <Card title="Guide: Deploy on AWS" icon="microchip" href="/deployment/cloud/aws/ec2">
    Deploy Onyx on an EC2 instance.
  </Card>
</CardGroup>


# Deploying Craft
Source: https://docs.onyx.app/deployment/local/craft

Choose and prepare a sandbox runtime for self-hosted Craft

Craft runs generated code in isolated sandboxes and sends sandbox network traffic through an egress proxy.
Self-hosted deployments can run these sandboxes in Kubernetes or Docker.

<CardGroup>
  <Card title="Kubernetes" icon="dharmachakra" href="/deployment/local/craft_kubernetes">
    Deploy sandbox pods, the proxy, RBAC, and workers with the Onyx Helm chart.
  </Card>

  <Card title="Docker Compose" icon="docker" href="/deployment/local/craft_docker_compose">
    Run sandbox containers and the proxy on a trusted single Docker host.
  </Card>
</CardGroup>

<Tip>
  Use Kubernetes if more than a few people will use Craft, especially when they may work concurrently.
  Each active user needs a sandbox, so Docker Compose is best suited to small, single-host deployments.
</Tip>

|                 | Kubernetes                            | Docker Compose                            |
| --------------- | ------------------------------------- | ----------------------------------------- |
| Sandbox runtime | One pod per active user               | One container per active user             |
| Recommended for | Production and multi-node deployments | Single-host self-hosted deployments       |
| Provisioning    | Onyx Helm chart                       | `onyx-cli deploy install --include-craft` |
| Host access     | Kubernetes API through scoped RBAC    | Docker socket access on the host          |

## Requirements

Both deployment paths require:

* A full Onyx deployment with the vector database and background workers. Craft does not run on Onyx Lite.
* A supported Onyx release and matching application and sandbox image versions.
* An Onyx URL that the sandbox runtime can reach, configured as `SANDBOX_API_SERVER_URL`.
* Capacity for a sandbox per active Craft user.
* An Anthropic, OpenAI, or OpenRouter provider configured after deployment.

<Warning>
  Sandboxes execute model-generated code. Review [Craft Architecture](/security/architecture/craft)
  before enabling Craft, especially the sandbox, network, credential, and sharing boundaries.
</Warning>

## After the runtime is ready

<Steps>
  <Step title="Configure a model">
    In **Admin Panel → Language Models**, add an Anthropic, OpenAI,
    or OpenRouter provider and make at least one model available to your Craft users.
  </Step>

  <Step title="Configure workspace access">
    Open **Admin Panel → Craft → Access**. Keep the workspace default off for a limited rollout,
    or enable Craft for everyone.
  </Step>

  <Step title="Run a complete test">
    As an enabled user, start a Craft session, send a prompt that creates a file, and open or download the result.
  </Step>

  <Step title="Add Apps and Skills">
    Configure external services under **Admin Panel → Craft → Apps** and reusable workflows under **Craft → Skills**.
  </Step>
</Steps>

<CardGroup>
  <Card title="Managing Craft" icon="sliders" href="/admins/managing_features/craft">
    Configure access, models, Apps, and workspace instructions.
  </Card>

  <Card title="Craft Architecture" icon="diagram-project" href="/security/architecture/craft">
    Understand sandbox isolation, egress, credentials, and approvals.
  </Card>
</CardGroup>


# Docker Compose
Source: https://docs.onyx.app/deployment/local/craft_docker_compose

Deploy Craft sandboxes on a trusted Docker host

Docker Compose runs one sandbox container per active Craft user. Use this path for a small,
single-host Onyx deployment that you trust and control.

<Tip>
  If more than a few people will use Craft, especially concurrently,
  deploy Craft on [Kubernetes](/deployment/local/craft_kubernetes) instead.
</Tip>

<Warning>
  Craft gives the API server and background container read-write access to the Docker socket.
  This read-write access is effectively root access to the host. The sandbox proxy receives read-only socket access.
</Warning>

## Requirements

* A full Docker Compose deployment of Onyx 4.0.6 or later
* Docker Engine with Compose
* A host with capacity for the Onyx stack and active sandbox containers
* An Onyx URL reachable through the sandbox proxy

Craft does not run with the Onyx Lite Compose overlay.

## New deployment

Run the [Onyx CLI](/deployment/local/onyx_cli) installer with the Craft overlay:

```bash theme={null}
onyx-cli deploy install --include-craft
```

The installer downloads `docker-compose.craft.yml`, enables Craft, selects the Docker sandbox backend,
creates the sandbox bridge network and proxy CA volume, and starts the deployment.

<Note>
  The examples below use the CLI's default deployment directory.
  For a deployment created by an older version of the `install.sh` script,
  replace `~/.config/onyx` with your `onyx_data` directory (e.g. `onyx_data/deployment/.env`).
</Note>

Open `~/.config/onyx/deployment/.env` and set the Onyx URL:

```dotenv theme={null}
ONYX_SERVER_URL=https://onyx.example.com
```

Then recreate the affected services with both Compose files:

```bash theme={null}
cd ~/.config/onyx/deployment
docker compose \
  -f docker-compose.yml \
  -f docker-compose.craft.yml \
  up -d --force-recreate
```

## Existing deployment

Set `ONYX_SERVER_URL` in the existing deployment's `.env`, then rerun the installer:

```bash theme={null}
onyx-cli deploy install --include-craft
```

The installer adds the Craft overlay and updates the existing `.env` with:

```dotenv theme={null}
ENABLE_CRAFT=true
SANDBOX_BACKEND=docker
```

Setting `ENABLE_CRAFT=true` without the overlay is not sufficient. The overlay mounts the Docker socket,
starts the sandbox proxy, and attaches the API server and background worker to the sandbox network.

## Set the Onyx URL

For production, use the public HTTPS URL users use to reach Onyx:

```dotenv theme={null}
ONYX_SERVER_URL=https://onyx.example.com
```

For local Docker Desktop on macOS or Windows, use the host port selected by the installer:

```dotenv theme={null}
ONYX_SERVER_URL=http://host.docker.internal:3000
```

On Linux, use a hostname or host address reachable from Docker containers.
Compose service names such as `api_server` and `nginx` do not resolve from the isolated sandbox bridge.

## Plan host capacity

Docker sandboxes default to one CPU and 2 GB of memory each:

```dotenv theme={null}
SANDBOX_DOCKER_CPU_LIMIT=1.0
SANDBOX_DOCKER_MEMORY_LIMIT=2g
```

Budget for the base Onyx services plus the number of users who may run Craft concurrently.
An idle sandbox is snapshotted and stopped after 3,600 seconds by default;
change this with `SANDBOX_IDLE_TIMEOUT_SECONDS` when faster cleanup or longer-lived sandboxes are required.

The sandbox image follows `IMAGE_TAG`. Keep the Onyx backend and sandbox on the same release.
Normal deployments should not set `SANDBOX_CONTAINER_IMAGE` separately.

## Build Craft from source

`docker compose up --build` builds the Onyx services declared in the Compose files.
It does not build the Craft sandbox image because sandboxes are created dynamically by the API server rather than
running as a Compose service.

From the root of an Onyx source checkout, build the sandbox image separately with a local, non-mutable tag:

```bash theme={null}
docker build \
  -t onyxdotapp/sandbox:local-source \
  -f backend/onyx/server/features/build/sandbox/image/Dockerfile \
  backend/onyx/server/features/build/sandbox/image
```

Set the image in the `.env` used by your source checkout:

```dotenv theme={null}
SANDBOX_CONTAINER_IMAGE=onyxdotapp/sandbox:local-source
```

Then build and recreate the Onyx services with the Craft overlay:

```bash theme={null}
cd deployment/docker_compose
docker compose \
  -f docker-compose.yml \
  -f docker-compose.craft.yml \
  up -d --build --force-recreate
```

<Warning>
  Do not use `latest`, `edge`, or `beta` for a locally built sandbox image.
  The API server treats these tags as mutable and attempts to refresh them from the registry before provisioning.
  Use a tag such as `local-source`.
</Warning>

Setting `IMAGE_TAG` does not build the corresponding `onyxdotapp/sandbox:${IMAGE_TAG}` image.
Either build that sandbox tag separately or set `SANDBOX_CONTAINER_IMAGE` explicitly.
Recreate `api_server` and `background` after changing the setting.
Existing `sandbox-*` containers continue using the image with which they were created and must be terminated and
provisioned again to use the new image.

If you instead launch from a staged directory such as `onyx_data/deployment`,
copy the setting into that directory's `.env`.
Staged deployment directories do not contain the source checkout expected by the Compose build contexts,
so use already-built or published images with `--no-build`.

## Verify the deployment

Confirm the core services and proxy are running:

```bash theme={null}
cd ~/.config/onyx/deployment
docker compose \
  -f docker-compose.yml \
  -f docker-compose.craft.yml \
  ps api_server background sandbox-proxy
```

After configuring a model and user access, send a prompt in Craft. A sandbox container should appear:

```bash theme={null}
docker ps --filter label=onyx.app/component=craft-sandbox
```

The `background` service includes the worker used for Scheduled Task runs; no separate Compose service is required.

## Network and host security

Sandbox containers join only the external `onyx_craft_sandbox` bridge. They cannot resolve PostgreSQL, Redis,
object storage, or the API server by Compose service name.
Their outbound HTTP and HTTPS traffic passes through `sandbox-proxy`,
which enforces App policies and injects credentials after a request is approved.

<Warning>
  On cloud VMs, block sandbox access to the instance metadata service at the host or platform level. On EC2,
  require IMDSv2 with `HttpTokens=required` and apply a host firewall rule that blocks Docker bridge traffic to
  `169.254.169.254`.
</Warning>

See [Craft Architecture](/security/architecture/craft) for the complete trust and network model.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Craft does not appear after changing the environment">
    Confirm `ENABLE_CRAFT=true` and `SANDBOX_BACKEND=docker`, then recreate the API server and web application.
    Include both `docker-compose.yml` and `docker-compose.craft.yml` in the Compose command.
  </Accordion>

  <Accordion title="Sandbox provisioning reports that ONYX_SERVER_URL is missing">
    Set the value in the deployment directory's `.env` and recreate the API server, background worker,
    and sandbox proxy with the Craft overlay.
  </Accordion>

  <Accordion title="The configured Onyx URL uses a Compose hostname">
    Replace `api_server`, `nginx`,
    or another Compose-only hostname with the public Onyx URL or a host address reachable from Docker containers.
  </Accordion>

  <Accordion title="The sandbox proxy is unhealthy">
    Run `docker compose -f docker-compose.yml -f docker-compose.craft.yml logs sandbox-proxy`. Check `ONYX_SERVER_URL`,
    PostgreSQL and Redis availability, the `sandbox_proxy_ca` volume, and access to the Docker socket.
  </Accordion>

  <Accordion title="The sandbox network or CA volume is missing">
    Rerun `onyx-cli deploy install --include-craft`. If automatic creation fails,
    create the resources and restart the deployment:

    ```bash theme={null}
    docker network create onyx_craft_sandbox
    docker volume create sandbox_proxy_ca
    ```
  </Accordion>

  <Accordion title="A sandbox exits or is killed during larger jobs">
    Inspect the sandbox container logs and host memory pressure.
    Increase `SANDBOX_DOCKER_MEMORY_LIMIT` or `SANDBOX_DOCKER_CPU_LIMIT` only when the host has enough capacity for
    every concurrent sandbox.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Craft deployment overview" icon="hammer" href="/deployment/local/craft">
    Compare the Docker Compose and Kubernetes paths.
  </Card>

  <Card title="Managing Craft" icon="sliders" href="/admins/managing_features/craft">
    Configure models and user access after deployment.
  </Card>
</CardGroup>


# Kubernetes
Source: https://docs.onyx.app/deployment/local/craft_kubernetes

Deploy Craft sandboxes with the Onyx Helm chart

Use the Onyx Helm chart to deploy Craft with Kubernetes sandboxes. The chart creates the sandbox namespace, PodTemplate,
RBAC, egress proxy, NetworkPolicies, and Scheduled Task worker used by Craft.

## Requirements

* Kubernetes 1.33 or later
* A full Onyx Helm deployment with the vector database enabled
* Nodes with enough CPU, memory, and ephemeral storage for active sandboxes
* A URL that sandbox pods can use to reach the Onyx API

The chart fails the install or upgrade when Craft is enabled on an older Kubernetes version,
when the sandbox backend is not `kubernetes`, when `SANDBOX_API_SERVER_URL` is empty,
or when sandbox push authentication is not configured.

## Prepare sandbox nodes

By default, sandbox pods select nodes with this label:

```text theme={null}
onyx.app/workload=sandbox
```

Label each node that can run sandboxes:

```bash theme={null}
kubectl label node <node-name> onyx.app/workload=sandbox
```

The default sandbox toleration also supports nodes dedicated with this taint:

```bash theme={null}
kubectl taint node <node-name> workload=sandbox:NoSchedule
```

The taint is optional.
The node label is required unless you replace `sandboxPod.nodeSelector` with a selector that matches your cluster.

## Create the sandbox push Secret

Craft uses an Ed25519 key to authenticate file and history pushes into sandbox pods.
Generate a key and store it in the Onyx namespace:

```bash theme={null}
SANDBOX_PUSH_PRIVATE_KEY="$(python3 -c 'import base64; from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey; from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption, PrivateFormat; key = Ed25519PrivateKey.generate(); print(base64.b64encode(key.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())).decode())')"

kubectl create namespace onyx --dry-run=client -o yaml | kubectl apply -f -
kubectl -n onyx create secret generic onyx-sandbox-push-secret \
  --from-literal=private_key="$SANDBOX_PUSH_PRIVATE_KEY"
unset SANDBOX_PUSH_PRIVATE_KEY
```

Keep this Secret stable across upgrades.
Replacing the key while sandboxes are running interrupts authenticated pushes until the affected components and
sandboxes are recreated.

## Configure Helm

Add the following settings to the values file used by your existing Onyx deployment.
If `configMap` or `auth` is already present,
merge these entries under the existing keys rather than adding a second block.

```yaml values.yaml theme={null}
configMap:
  ENABLE_CRAFT: "true"
  SANDBOX_BACKEND: "kubernetes"
  SANDBOX_API_SERVER_URL: "https://onyx.example.com"

auth:
  sandboxPushSecret:
    enabled: true
    existingSecret: "onyx-sandbox-push-secret"
```

`SANDBOX_API_SERVER_URL` can be the public Onyx URL or a cluster-internal URL.
Use a scheme and hostname that resolve from the sandbox proxy and route to the Onyx API.

Install or upgrade Onyx with your complete deployment values:

```bash theme={null}
helm upgrade --install onyx onyx/onyx \
  --namespace onyx \
  --create-namespace \
  --values onyx-values.yaml
```

Replace `onyx-values.yaml` with the path to the values file used by your deployment.

Alternatively, save only the Craft settings in a separate `craft-values.yaml` overlay.
Pass your existing deployment values first and the Craft overlay second so Helm combines them:

```bash theme={null}
helm upgrade --install onyx onyx/onyx \
  --namespace onyx \
  --create-namespace \
  --values onyx-values.yaml \
  --values craft-values.yaml
```

## Plan sandbox capacity

Each active user receives a sandbox pod. The main sandbox container has these defaults:

| Resource          | Request | Limit   |
| ----------------- | ------- | ------- |
| CPU               | `1000m` | `2000m` |
| Memory            | `2Gi`   | `10Gi`  |
| Ephemeral storage | `5Gi`   | `20Gi`  |

The pod also includes initialization and sidecar containers for network setup, file transfer, snapshots, and restore.
To change the main container resources, merge these `configMap` entries into your deployment values or Craft overlay:

```yaml theme={null}
configMap:
  SANDBOX_POD_CPU_REQUEST: "1000m"
  SANDBOX_POD_CPU_LIMIT: "2000m"
  SANDBOX_POD_MEMORY_REQUEST: "2Gi"
  SANDBOX_POD_MEMORY_LIMIT: "10Gi"
  SANDBOX_POD_EPHEMERAL_STORAGE_REQUEST: "5Gi"
  SANDBOX_POD_EPHEMERAL_STORAGE_LIMIT: "20Gi"
```

Use `sandboxPod.nodeSelector`, `sandboxPod.tolerations`, and `sandboxPod.affinity` to control placement.
The proxy and Scheduled Task worker have separate resource settings under `sandboxProxy.resources` and
`celery_worker_scheduled_tasks.resources`.

## Verify the deployment

Confirm the proxy, sandbox template, and Scheduled Task worker exist:

```bash theme={null}
kubectl -n onyx get deployment -l app.kubernetes.io/component=sandbox-proxy
kubectl -n onyx-sandboxes get podtemplate sandbox-pod
kubectl -n onyx get deployment -l app=celery-worker-scheduled-tasks
```

After configuring a model and user access, send a prompt in Craft. A sandbox pod should appear:

```bash theme={null}
kubectl -n onyx-sandboxes get pods -l app.kubernetes.io/component=sandbox
```

## Network configuration

Sandbox pods can send traffic only to DNS and the sandbox proxy. The proxy handles external requests, App policies,
and credential injection.

Most clusters work with the chart defaults. Two cluster layouts require additional values:

| Cluster layout                                | Configuration                                  |
| --------------------------------------------- | ---------------------------------------------- |
| NodeLocal DNS or another non-pod DNS listener | Add its CIDR to `craft.dnsExtraCIDRs`.         |
| An external or unlabeled sandbox proxy        | Add the proxy CIDR to `craft.proxyExtraCIDRs`. |
| Dual-stack networking                         | Set `sandboxProxy.egressAllowIPv6: true`.      |

<Warning>
  Keep the sandbox egress NetworkPolicies enabled. They restrict sandbox pods to the proxy and DNS,
  and block link-local cloud metadata access from the proxy path.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Helm rejects the Craft configuration">
    Read the render error first. Confirm Kubernetes 1.33 or later, `SANDBOX_BACKEND: "kubernetes"`,
    a non-empty `SANDBOX_API_SERVER_URL`, and `auth.sandboxPushSecret.enabled: true` with a populated Secret.
  </Accordion>

  <Accordion title="Sandbox pods remain Pending">
    Run `kubectl -n onyx-sandboxes describe pod <pod-name>`.
    Confirm at least one node matches `sandboxPod.nodeSelector`, accepts the configured taints and tolerations,
    and has enough CPU, memory, and ephemeral storage.
  </Accordion>

  <Accordion title="A sandbox fails during initialization">
    Inspect the `sandbox-init` container logs and the proxy pods.
    DNS must resolve the proxy before the sandbox firewall is installed.
    Clusters using NodeLocal DNS usually need its listener CIDR under `craft.dnsExtraCIDRs`.
  </Accordion>

  <Accordion title="Craft cannot reach the Onyx API">
    Verify `SANDBOX_API_SERVER_URL`, DNS, TLS trust, and routing from the proxy.
    Do not point it at a Service name from another cluster or an address the proxy cannot resolve.
  </Accordion>

  <Accordion title="The sandbox proxy is not Ready">
    Run `kubectl -n onyx logs -l app.kubernetes.io/component=sandbox-proxy --tail=200` and check its access to
    PostgreSQL, Redis, the Onyx API, and external destinations. On dual-stack clusters,
    enable `sandboxProxy.egressAllowIPv6`.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Craft deployment overview" icon="hammer" href="/deployment/local/craft">
    Compare the Kubernetes and Docker Compose paths.
  </Card>

  <Card title="Managing Craft" icon="sliders" href="/admins/managing_features/craft">
    Configure models and user access after deployment.
  </Card>
</CardGroup>


# Desktop App
Source: https://docs.onyx.app/deployment/local/desktop_app

Install and configure the Onyx desktop application

The Onyx Desktop App provides users with a native application experience for accessing Onyx on Windows, macOS,
and Linux.

Features include:

* Quick-launch from system tray or dock
* Desktop notifications

<img alt="Onyx Desktop App" />

<Info>
  The desktop app is used for connecting to an Onyx server backend. Users will need access to the Onyx instance URL.
  It cannot connect directly to a local inference backend.
</Info>

## Download

Download the latest Onyx Desktop App for your platform:

<CardGroup>
  <Card title="Windows" icon="windows" href="https://github.com/onyx-dot-app/onyx/releases/latest/download/Onyx_x64.exe">
    Download for Windows (.exe)
  </Card>

  <Card title="macOS" icon="apple" href="https://github.com/onyx-dot-app/onyx/releases/latest/download/Onyx_universal.dmg">
    Download for macOS (.dmg)
  </Card>

  <Card title="Linux" icon="linux" href="https://github.com/onyx-dot-app/onyx/releases/latest/download/Onyx_amd64.deb">
    Download for Linux (.deb)
  </Card>
</CardGroup>

<Tip>
  Additional architectures and formats (.msi, .rpm, .app.tar.gz)
  are available on the [GitHub Releases page](https://github.com/onyx-dot-app/onyx/releases/latest).
</Tip>

## First Launch

**Self-hosted users**: On first launch,
the app opens a **Settings** screen to configure the connection to your Onyx instance:

* **Server URL**: Your Onyx instance URL (e.g., `https://onyx.yourcompany.com`)
* **Authentication**: Sign in with your configured authentication method

The Server URL can be changed at any time from the **Settings** screen (`⌘ ,` on macOS, `Ctrl ,` on Windows and Linux).

## Enterprise Deployment

For organizations rolling out the desktop app at scale, you can pre-configure the Server URL (and other options)
so users skip the first-launch **Settings** prompt entirely.
Place a `config.json` file on each machine before the user first opens the app. On launch,
Onyx reads the file and connects to your instance directly; users only need to sign in.

### Configuration File Location

The app reads its settings from a `config.json` file at the following location:

<Tabs>
  <Tab title="Windows">
    ```
    %APPDATA%\onyx\onyx-desktop\config\config.json
    ```
  </Tab>

  <Tab title="macOS">
    ```
    ~/Library/Application Support/app.onyx.onyx-desktop/config.json
    ```
  </Tab>

  <Tab title="Linux">
    ```
    ~/.config/onyx-desktop/config.json
    # or, if $XDG_CONFIG_HOME is set:
    $XDG_CONFIG_HOME/onyx-desktop/config.json
    ```
  </Tab>
</Tabs>

Example `config.json`:

```json theme={null}
{
  "server_url": "https://onyx.yourcompany.com",
  "window_title": "Onyx"
}
```

## Configuration Options

| Option                    | Values                                            | Platforms             | Description                                                                                                                                                                                      |
| ------------------------- | ------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `server_url`              | string<br />(default: `"https://cloud.onyx.app"`) | Windows, macOS, Linux | The Onyx instance the app connects to. Required for the app to skip the first-launch **Settings** prompt. A trailing slash is ignored.                                                           |
| `window_title`            | string<br />(default: `"Onyx"`)                   | Windows, macOS, Linux | Custom title shown in the application window.                                                                                                                                                    |
| `show_menu_bar`           | boolean<br />(default: `true`)                    | Windows, Linux        | Whether the application menu bar is shown. Normally toggled from **Window → Show Menu Bar** rather than pre-configured. Ignored on macOS, where the menu bar is managed by the operating system. |
| `hide_window_decorations` | boolean<br />(default: `false`)                   | Linux                 | Hides the window's title bar and borders. Normally toggled from **Window → Hide Window Decorations**.                                                                                            |

<Warning>
  `config.json` must be valid JSON with values of the correct type.
  A single invalid entry causes the app to discard the **entire** file and fall back to the default settings.
</Warning>


# Docker
Source: https://docs.onyx.app/deployment/local/docker

Deploy Onyx with Docker Compose

<Tip>
  Check out the [Resourcing Guide](/deployment/getting_started/resourcing) before getting started with Docker.
</Tip>

<Note>
  This guide covers managing the compose files manually. For a guided install with managed upgrades,
  use the [Onyx CLI](/deployment/local/onyx_cli)
  instead — it can also [adopt an existing manual setup](/deployment/local/onyx_cli#from-a-manual-docker-compose-setup)
  later.
</Note>

## Guide

**Note:** On Windows, the commands will be slightly different but all the steps are the same.

<Steps>
  <Step title="Install Requirements">
    * [Git](https://git-scm.com/downloads)
    * [Docker (with compose)](https://docs.docker.com/get-docker/)
  </Step>

  <Step title="Clone the Onyx repo">
    ```bash theme={null}
    git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
    ```
  </Step>

  <Step title="Navigate to the compose files">
    ```bash theme={null}
    cd onyx/deployment/docker_compose
    ```
  </Step>

  <Step title="Launch Onyx">
    To pull images from Docker Hub and start Onyx:

    ```bash theme={null}
    docker compose up -d
    ```

    Alternatively, to build images from source:

    ```bash theme={null}
    docker compose up -d --build --force-recreate
    ```

    <Warning>
      If you've previously launched Onyx with the old `onyx-stack` service name,
      you'll need to add `-p onyx-stack` to your launch command.

      For example: `docker compose up -p onyx-stack -d`.
    </Warning>
  </Step>
</Steps>

After the containers come up,
the system needs to go through an initialization process after which you can access Onyx at
[localhost:3000](localhost:3000).

## Enabling Onyx Craft

Craft adds isolated sandbox containers and an egress proxy to the Docker Compose deployment.
Use the dedicated guide for both new and existing installations.

<Card title="Deploy Craft on Docker Compose" icon="docker" href="/deployment/local/craft_docker_compose">
  Install the Craft overlay, configure the sandbox API URL, plan host capacity, and verify the runtime.
</Card>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# Kubernetes
Source: https://docs.onyx.app/deployment/local/kubernetes

Deploy Onyx with Helm

<Tip>
  Check out our [Resourcing Guide](/deployment/getting_started/resourcing) before getting started.
</Tip>

## Guide

The Onyx Helm chart packages all the required services (API, web, PostgreSQL, Vespa, etc.) into a single deployment.
By default, persistent volumes will be created for stateful services (e.g. PostgreSQL, Vespa).

<Steps>
  <Step title="Add the Onyx Helm repository">
    ```bash theme={null}
    helm repo add onyx https://onyx-dot-app.github.io/onyx/
    helm repo update
    helm search repo onyx
    ```
  </Step>

  <Step title="Install Onyx">
    Install into its own namespace (recommended):

    ```bash theme={null}
    kubectl create namespace onyx
    helm install onyx onyx/onyx -n onyx
    ```

    This will pull the latest Onyx chart and deploy all dependencies.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    helm list -n onyx
    kubectl get pods -n onyx
    ```

    Wait until all pods are in a `Running` state before accessing Onyx.
  </Step>

  <Step title="Access Onyx">
    By default, the chart exposes Onyx via a Kubernetes Service. For local testing, you can port-forward:

    ```bash theme={null}
    kubectl -n onyx port-forward service/onyx-nginx 8080:80
    ```

    Then open [http://localhost:8080](http://localhost:8080).
  </Step>

  <Step title="Configure Onyx">
    Configure your deployment by modifying the `values.yaml` file in the `onyx/deployment/helm/charts/onyx` directory.

    You'll need to restart Onyx after changing any `values.yaml` variables.

    ```bash theme={null}
    helm upgrade onyx onyx/onyx -n onyx -f deployment/helm/charts/onyx/values.yaml
    ```
  </Step>
</Steps>

See the [Helm chart README](https://github.com/onyx-dot-app/onyx/tree/main/deployment/helm)
for advanced options such as running as non-root and testing with Kind.

## Enabling Onyx Craft

Craft adds per-user sandbox pods, scoped RBAC, NetworkPolicies, an egress proxy,
and a Scheduled Task worker to the Helm deployment.

<Card title="Deploy Craft on Kubernetes" icon="dharmachakra" href="/deployment/local/craft_kubernetes">
  Prepare sandbox nodes and authentication, configure Helm, plan capacity, and verify the runtime.
</Card>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# Onyx CLI
Source: https://docs.onyx.app/deployment/local/onyx_cli

Install and manage a Docker Compose deployment with onyx-cli deploy

The [Onyx CLI](/overview/onyx_anywhere/cli)
includes a `deploy` command group that installs and manages a self-hosted Docker Compose deployment:
a guided installer plus lifecycle commands for upgrading, inspecting, stopping, and removing the deployment.

It is the recommended way to set up and manage a self-hosted deployment on Linux, macOS, and Windows.
The `install.sh` / `install.ps1` [installation scripts](/deployment/getting_started/quickstart)
are thin wrappers that install the CLI and run `onyx-cli deploy install`, so both paths produce the same deployment.
Deployments created by older versions of the scripts are detected and [managed in
place](#migrating-an-existing-deployment).

Compared to managing the [Docker Compose files](/deployment/local/docker) by hand, the CLI:

* **Keeps the compose files in sync automatically**: `deploy upgrade` refreshes the compose files, overlays,
  and nginx config to match the target version, so you never diff them against the repo yourself.
* **Protects your customizations**: hand-edited files are detected via a checksum manifest and backed up before
  they are ever overwritten, and your `.env` settings survive every upgrade.
* **Steers debugging**: `deploy status` flags version drift and explains *why* a service is down
  (restarts, exit code, OOM, last failing health probe),
  and `deploy logs` finds the right compose files and overlays for you.
* **Handles the environment**: it checks RAM, disk, and ports, installs Docker on Linux,
  and generates secrets, instead of leaving prerequisites to a README.
* **Has a convenient, discoverable interface**: guided prompts with sensible defaults, `--help` on every command,
  and clear error messages, with `--no-prompt` and `--json` for automation.

| Command                     | Description                                                   |
| --------------------------- | ------------------------------------------------------------- |
| `onyx-cli deploy install`   | Install a new deployment, or restart / update an existing one |
| `onyx-cli deploy upgrade`   | Upgrade an existing deployment to a newer version             |
| `onyx-cli deploy status`    | Show versions, containers, and health                         |
| `onyx-cli deploy stop`      | Stop the containers without removing any data                 |
| `onyx-cli deploy logs`      | Show service logs                                             |
| `onyx-cli deploy uninstall` | Permanently delete the deployment and all its data            |

## Prerequisites

Install the CLI from PyPI:

```shell theme={null}
uv tool install onyx-cli
```

Or with pip:

```shell theme={null}
pip install onyx-cli
```

See the [CLI overview](/overview/onyx_anywhere/cli) for other installation methods.
No `onyx-cli configure` step is needed — the `deploy` commands work directly against your local Docker,
not an Onyx server.

<Tip>
  Check out the [Resourcing Guide](/deployment/getting_started/resourcing) before getting started.
</Tip>

## Install

```shell theme={null}
onyx-cli deploy install
```

The interactive installer asks two questions — the deployment mode (**Lite** or **Standard**) and the version to deploy,
prefilled with the latest release — while environment checks run in the background. It then:

* Checks system resources (RAM, disk) and scans for a free host port
* Installs Docker Engine and the compose plugin on Linux after confirmation;
  starts Docker Desktop and waits for it on macOS; detects Docker and provides instructions on Windows
* Creates a `.env` file from the template with randomly generated secrets
* Pulls the Onyx images and starts the containers, waiting until every service reports healthy

Re-running `deploy install` on an existing deployment asks a single question:
**Restart** it as-is or **Upgrade** it to a newer version.

### Flags

| Flag              | Description                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--lite`          | Deploy Onyx Lite (no OpenSearch, Redis, or model servers)                                                                                     |
| `--include-craft` | Enable [Onyx Craft](/deployment/local/craft_docker_compose) — Craft is opt-in via this flag only and is not offered by the interactive prompt |
| `--tag <version>` | Image tag to deploy (default: the latest Onyx release)                                                                                        |
| `--dir <path>`    | Deployment directory (default: `~/.config/onyx`, or an existing `./onyx_data`)                                                                |
| `--no-prompt`     | Run non-interactively with defaults applied to every prompt (for CI/automation)                                                               |
| `--local`         | Use existing config files on disk instead of downloading                                                                                      |
| `--offline`       | Deploy from images already on the host without any network access (implies `--local`)                                                         |
| `--no-wait`       | Return as soon as containers are started instead of waiting for health                                                                        |
| `--dry-run`       | Show what would be done without making changes                                                                                                |
| `--force`         | Overwrite hand-edited managed files (a backup is kept) and recreate running services                                                          |
| `--verbose`       | Show detailed output for debugging                                                                                                            |

For example, a fully non-interactive install pinned to a specific version:

```shell theme={null}
onyx-cli deploy install --tag v4.4.6 --no-prompt
```

### Deployment directory

New installs live in `~/.config/onyx` (XDG-aware).
Deployments created by older versions of the `install.sh` script in `./onyx_data` are detected automatically and managed
**in place** — no migration needed.
Pass `--dir` or set the `ONYX_DEPLOYMENT_DIR` environment variable to target a specific location.

The directory holds the compose files, `.env`, and an `install-state.json` manifest recording the deployment mode,
version, and a checksum of each managed file. No application data lives there — chats, users,
and documents are stored in named Docker volumes.

### Offline install

`--offline` deploys entirely from what is already on the host — no release lookup, no config download,
and no image pull. The images must be loaded in advance,
and Docker must already be installed (the installer cannot install it without a network). It implies `--local`:
config files already on disk are used as-is, and any that are missing are written from copies bundled with the CLI.
Staging the deployment directory from a connected install (below)
is still recommended — the bundled copies match the CLI's own version, not necessarily the Onyx version being deployed.

On a machine with internet access,
install the latest release with the same mode flags (or pin a specific version with `--tag`),
then export the images the deployment resolved to:

```bash theme={null}
onyx-cli deploy install
cd ~/.config/onyx/deployment
docker save -o onyx-images.tar $(docker compose config --images)
```

Copy `onyx-images.tar` and the `~/.config/onyx` directory to the offline host, then:

```bash theme={null}
docker load -i onyx-images.tar
onyx-cli deploy install --offline
```

Without `--tag`,
an offline install offers the newest released version whose images are already on the host — the one just loaded.
Before starting anything,
the installer verifies every image the deployment needs and names each one that is missing — load those with `docker
load` and re-run.

<Note>
  `deploy upgrade --offline` works the same way for moving an air-gapped deployment to a newer staged version.
</Note>

## Upgrade

```shell theme={null}
onyx-cli deploy upgrade
```

Upgrades an existing deployment to the latest release, or to a specific version with `--tag`:

```shell theme={null}
onyx-cli deploy upgrade --tag v4.4.6
```

The upgrade is designed to preserve your customizations:

* Only the `IMAGE_TAG` line in `.env` is rewritten (plus `SANDBOX_BACKEND` when Craft is enabled) —
  every other setting, including your edits, is kept.
* Managed files (compose files, overlays, nginx config) are refreshed to match the target version.
  Files you hand-edited are detected via the manifest, backed up,
  and only overwritten after you confirm (or with `--force`).
* Downgrades to an older version warn and require confirmation or `--force`.

The running services keep serving while the new images download and are then recreated on the new version.
`upgrade` accepts the same `--dir`, `--no-prompt`, `--local`, `--offline`, `--no-wait`, `--dry-run`,
and `--verbose` flags as `install`.

## Status

```shell theme={null}
onyx-cli deploy status
```

Shows the installed version as recorded by the CLI, by `.env`,
and by the running containers (drift between them is flagged), plus per-container status and health, the published port,
and — for a service that is down — why (restarts, exit code, OOM, last failing health probe).

`status` is read-only and works as a health probe: use `--json` for machine-readable output, and check the exit code.

| Exit code | Meaning                      |
| --------- | ---------------------------- |
| `0`       | Everything is up and healthy |
| `1`       | Stopped or degraded          |
| `9`       | No installation found        |

## Logs

```shell theme={null}
onyx-cli deploy logs api_server
```

Shows service logs without needing to locate the deployment directory or remember which compose overlays it uses.
Name one or more services to narrow the output, or pass none for all services.

| Flag             | Description                                                                  |
| ---------------- | ---------------------------------------------------------------------------- |
| `-f`, `--follow` | Keep printing new log lines                                                  |
| `--tail <n>`     | Lines to show from the end of each log (default `200`, `all` for everything) |
| `--since <time>` | Only logs since this point (e.g. `10m`, `2h`, or a timestamp)                |

## Stop

```shell theme={null}
onyx-cli deploy stop
```

Stops the containers without removing them or any data. Start the deployment again with `onyx-cli deploy install`.

## Uninstall

```shell theme={null}
onyx-cli deploy uninstall
```

Removes the Onyx containers, volumes, and the deployment directory.

<Warning>
  This permanently deletes all user data and documents. Interactive runs must type `DELETE` to confirm;
  non-interactive runs require `--force`.
</Warning>

## Migrating an existing deployment

### From an older install.sh deployment

Today's `install.sh` runs the CLI, but older versions were standalone and installed into an `onyx_data` directory.
Those deployments are managed in place — run the CLI from the directory containing `onyx_data` (or point `--dir` at it)
and it takes over, no migration required. The old script's mode flags map to dedicated commands:

| install.sh                   | Onyx CLI                    |
| ---------------------------- | --------------------------- |
| `./install.sh`               | `onyx-cli deploy install`   |
| Re-run and type `update`     | `onyx-cli deploy upgrade`   |
| `./install.sh --shutdown`    | `onyx-cli deploy stop`      |
| `./install.sh --delete-data` | `onyx-cli deploy uninstall` |

### Moving to \~/.config/onyx

A legacy `onyx_data` install can also be relocated to the recommended `~/.config/onyx` location.
Only configuration moves: chats, users,
and documents live in named Docker volumes keyed by the compose project name (`onyx`), which stays the same,
so the relocated deployment adopts them automatically.
The one file that must be carried over is `.env` — it holds the secrets the database and object-store volumes were
initialized with.

```bash theme={null}
# From the directory containing onyx_data
onyx-cli deploy stop
mkdir -p ~/.config/onyx/deployment
cp onyx_data/deployment/.env ~/.config/onyx/deployment/
onyx-cli deploy install --dir ~/.config/onyx
```

Choose **Restart** to come back up on the version already pinned in `.env`, or **Upgrade** to move to a newer one.
The compose files are downloaded fresh, so re-apply any hand edits you made to them.
Once `onyx-cli deploy status` reports healthy, delete the old directory — it only holds configuration:

```bash theme={null}
rm -rf onyx_data
```

<Note>
  Deleting the old directory matters: when `onyx_data` exists in the working directory,
  the CLI prefers it over `~/.config/onyx`. Once it is gone,
  plain `onyx-cli deploy` commands find the new location without `--dir`.
</Note>

### From a manual docker compose setup

A deployment you started by hand from the repo's `deployment/docker_compose` directory can be adopted the same way,
as long as it uses the default compose project name (`onyx`, pinned in `docker-compose.yml`):

```bash theme={null}
# From the directory with your docker-compose.yml
docker compose down   # keeps the data volumes — do NOT pass -v
mkdir -p ~/.config/onyx/deployment
cp .env ~/.config/onyx/deployment/
onyx-cli deploy install
```

The installer detects the copied `.env` as an existing deployment, downloads the managed compose files,
and brings the stack back up on the existing volumes.

<Warning>
  Deployments launched under a different project name — the old `onyx-stack` name,
  or any custom `-p` value — store their volumes under that prefix and are **not** adopted automatically.
  Keep managing those with `docker compose` directly, or migrate the volume data manually before switching.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# OpenSearch
Source: https://docs.onyx.app/deployment/local/opensearch

Configuring Onyx with OpenSearch

## Overview

OpenSearch is the document index Onyx uses for retrieval.

In Onyx’s **Helm** chart, we maintain a section which defines the desired setup for an instance of OpenSearch,
and another section which defines auth for that instance. If these are enabled (the default as of `v3`),
when you start your Onyx instance using Helm,
Helm will also start the OpenSearch instance (containing one or more containers)
and seed the appropriate auth values throughout the application.
By default the OpenSearch instance will have only one container.

Additionally, the Onyx application itself needs to know that OpenSearch is enabled,
and how to connect to the OpenSearch instance. In the configmap template that the Onyx Helm chart tracks,
if the OpenSearch section mentioned above is enabled (the default as of `v3`),
the environment variables for the OpenSearch host, port, and whether it is enabled at all,
will be set throughout the application.

In Onyx's **docker-compose** file, the `opensearch` service defines both the desired setup and auth.
Rather than a configmap as in Helm, the application just reads environment variables that you can set in a `.env` file.

## Auth

Unless explicitly disabled,
OpenSearch requires setting initial credentials for the cluster which are used to authenticate all requests.
The password must meet certain complexity requirements: minimum 8 chars, at least one uppercase, lowercase, digit,
and special character.

If using Onyx's **docker-compose**,
there is no action necessarily required as the compose file supplies a default initial password which matches the
default value Onyx falls back to in the absence of the relevant env var `OPENSEARCH_ADMIN_PASSWORD`.

If you wish to set this password to some other value, set an env var `OPENSEARCH_ADMIN_PASSWORD` to your desired string,
ensure `docker` references this env var when running `docker-compose`,
and also ensure this env var is in a `.env` file Onyx references as well.

If using **Helm**,
there is no default password and some password must be specified in the `values.yaml` file specified in your Helm
command as shown:

```yaml values.yaml theme={null}
# Other overrides you may have.

configMap:
  # Other overrides you may have.

  OPENSEARCH_ADMIN_PASSWORD: <your chosen password>

auth:
  # Other overrides you may have.

  opensearch:
   values:
     opensearch_admin_password: <your chosen password>
```

## If using your own provisioned managed OpenSearch

[If you provisioned a managed instance](/deployment/local/terraform#opensearch-optional),
you do not need Helm to start an OpenSearch container/cluster for you.
You can disable this in your Helm values `yaml` file.

```yaml values.yaml theme={null}
# Other overrides you may have.

opensearch:
  enabled: false

auth:
  # Other overrides you may have.

  opensearch:
    enabled: false
```

You also need to specify what the intended environment variables should be, based on the OpenSearch cluster.
These variables will be propagated throughout the Onyx application.

```yaml values.yaml theme={null}
# Other overrides you may have.

configMap:
  # Other overrides you may have.

  OPENSEARCH_ADMIN_USERNAME: "<the username you set when creating the OpenSearch cluster>"
  OPENSEARCH_ADMIN_PASSWORD: "<the password you set when creating the OpenSearch cluster>"
  OPENSEARCH_HOST: "<the host name of the OpenSearch cluster, as reported on the AWS console; do not include https://>"
  OPENSEARCH_REST_API_PORT: "443"
  USING_AWS_MANAGED_OPENSEARCH: "true"
```


# Terraform
Source: https://docs.onyx.app/deployment/local/terraform

Provision Onyx infrastructure on AWS with Terraform

<Tip>
  Check out the [Resourcing Guide](/deployment/getting_started/resourcing) before getting started.
</Tip>

Onyx ships a set of [Terraform modules](https://github.com/onyx-dot-app/onyx/tree/main/deployment/terraform/modules/aws)
that provision the AWS infrastructure Onyx needs: VPC, EKS, RDS for PostgreSQL, ElastiCache for Redis, S3,
and (optionally) OpenSearch and WAF. Once the infra is up,
you install the Onyx workloads with the [Helm chart](/deployment/local/kubernetes).

<Info>
  These modules are intended as a **reference implementation**.
  They reflect how we deploy Onyx and encode sensible defaults,
  but every environment is different — you should treat them as a starting point to fork and adapt to your account,
  networking, and compliance requirements rather than a black box to consume as-is.
</Info>

## What gets provisioned

The composed `onyx` module wires together the building blocks below.
You can also use them individually if you need more granular control.

| Module       | Resource                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `vpc`        | VPC, public/private subnets across AZs, NAT, and an S3 gateway endpoint                         |
| `eks`        | EKS cluster, managed node groups (main + dedicated Vespa), addons, IRSA                         |
| `postgres`   | RDS for PostgreSQL with backups and CloudWatch alarms                                           |
| `redis`      | ElastiCache for Redis replication group with TLS in transit                                     |
| `s3`         | S3 bucket for the Onyx file store, locked to the VPC's S3 endpoint                              |
| `opensearch` | (Optional) Amazon OpenSearch domain inside the VPC                                              |
| `waf`        | (Optional, recommended) AWS WAFv2 web ACL with managed rule sets, rate limits, and geo controls |
| `onyx`       | Top-level composition that wires the modules above together                                     |

## Prerequisites

<Steps>
  <Step title="Install tooling">
    * [Terraform](https://developer.hashicorp.com/terraform/install) `>= 1.12.0`
    * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) configured with credentials that can create VPCs, EKS clusters, RDS, ElastiCache, S3 buckets, IAM roles, and (optionally) WAF and OpenSearch
    * [`kubectl`](https://kubernetes.io/docs/tasks/tools/) and [`helm`](https://helm.sh/docs/intro/install/) for the post-apply Helm install
  </Step>

  <Step title="Clone the Onyx repo">
    ```bash theme={null}
    git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
    cd onyx/deployment/terraform
    ```

    The modules live under `modules/aws/`. You will create a small root module that calls them.
  </Step>

  <Step title="Pick an AWS region and a name">
    The `name` variable is used as a prefix for everything the modules create (VPC, cluster, RDS, S3 bucket, etc.)
    and is combined with the current Terraform workspace, so the same code can produce isolated `dev`, `staging`,
    and `prod` environments.
  </Step>
</Steps>

## Quickstart

The snippet below is a minimal root module that provisions a complete Onyx stack on AWS using the composed `onyx`
module.

```hcl main.tf theme={null}
locals {
  region = "us-west-2"
}

terraform {
  required_version = ">= 1.12.0"

  required_providers {
    aws        = { source = "hashicorp/aws",        version = "~> 5.100" }
    helm       = { source = "hashicorp/helm",       version = "~> 2.16"  }
    kubernetes = { source = "hashicorp/kubernetes", version = "~> 2.37"  }
  }
}

provider "aws" {
  region = local.region
}

module "onyx" {
  # Adjust the source path to wherever you have the modules checked out.
  source = "./modules/aws/onyx"

  region            = local.region
  name              = "onyx"
  postgres_username = "onyx"
  postgres_password = var.postgres_password # pass via TF_VAR_postgres_password
}

# Wait for the EKS control plane before configuring the k8s/helm providers.
resource "null_resource" "wait_for_cluster" {
  provisioner "local-exec" {
    command = "aws eks wait cluster-active --name ${module.onyx.cluster_name} --region ${local.region}"
  }
}

data "aws_eks_cluster" "eks" {
  name       = module.onyx.cluster_name
  depends_on = [null_resource.wait_for_cluster]
}

data "aws_eks_cluster_auth" "eks" {
  name       = module.onyx.cluster_name
  depends_on = [null_resource.wait_for_cluster]
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.eks.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.eks.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.eks.token
}

provider "helm" {
  kubernetes {
    host                   = data.aws_eks_cluster.eks.endpoint
    cluster_ca_certificate = base64decode(data.aws_eks_cluster.eks.certificate_authority[0].data)
    token                  = data.aws_eks_cluster_auth.eks.token
  }
}

output "cluster_name" {
  value = module.onyx.cluster_name
}

output "postgres_endpoint" {
  value = module.onyx.postgres_endpoint
}

output "redis_connection_url" {
  value     = module.onyx.redis_connection_url
  sensitive = true
}
```

Apply it:

```bash theme={null}
export TF_VAR_postgres_password='change-me'

terraform init
terraform plan
terraform apply
```

The full apply takes \~20 minutes — most of the time is spent waiting on EKS, RDS, and ElastiCache.

## Common configuration

The composed `onyx` module exposes the inputs you'll most often want to tune.

### Core

<ParamField type="string">
  Prefix for every resource created by the module. Combined with the active Terraform workspace,
  so the same code base can manage multiple environments.
</ParamField>

<ParamField type="string">
  AWS region for all resources.
</ParamField>

<ParamField type="string">
  Master username for the RDS Postgres instance.
</ParamField>

<ParamField type="string">
  Master password for the RDS Postgres instance.
  Marked sensitive — pass via `TF_VAR_postgres_password` or your secrets manager rather than hard-coding.
</ParamField>

<ParamField type="map(string)">
  Base tags applied to every AWS resource created by the modules.
</ParamField>

### Networking

<ParamField type="bool">
  When `true`, the module creates a new VPC sized for EKS.
  Set to `false` to reuse an existing VPC — see [Using an existing VPC](#using-an-existing-vpc).
</ParamField>

<ParamField type="bool">
  Whether the EKS API endpoint is reachable from the public internet.
  Combine with `cluster_endpoint_public_access_cidrs` to lock it down to specific IPs.
</ParamField>

<ParamField type="bool">
  Enable the private EKS API endpoint. Recommended for production. You can enable both public and private together,
  or only private.
</ParamField>

<ParamField type="list(string)">
  CIDR blocks allowed to reach the public EKS API endpoint when it is enabled.
</ParamField>

### Database & cache

<ParamField type="bool">
  Enables RDS IAM authentication and wires an IRSA role into the EKS module so Onyx workloads can connect to Postgres
  without a static password. Requires `rds_db_connect_arn` to be set.
</ParamField>

<ParamField type="number">
  Days to retain automated RDS backups. Set to `0` to disable.
</ParamField>

<ParamField type="string">
  Optional auth token for Redis. Marked sensitive.
</ParamField>

### OpenSearch (optional)

Managed OpenSearch is **off by default**.
Enable it if you want a managed document index backend instead of the in-cluster Vespa node group.

If provisioning a managed document index,
you should disable starting an OpenSearch container in your relevant docker-compose/Helm as Onyx will not use this
container. You should also set the relevant environment variables.
See how to [configure Onyx with OpenSearch](/deployment/local/opensearch).

<ParamField type="bool">
  Provision an Amazon OpenSearch domain inside the VPC.
</ParamField>

<ParamField type="string" />

<ParamField type="number" />

<ParamField type="string" />

<ParamField type="string" />

### WAF

The `waf` module is optional but **strongly recommended** for any internet-facing deployment.
It provisions an AWS WAFv2 web ACL with the common managed rule sets, rate limits,
and optional geo blocking that you can attach to the load balancer fronting Onyx.
Tune the inputs below to fit your traffic profile.

<ParamField type="list(string)">
  Optional IP allowlist. Leave empty to allow all source IPs subject to the managed rule sets and rate limits.
</ParamField>

<ParamField type="number" />

<ParamField type="number" />

<ParamField type="list(string)">
  Country codes to block. Leave empty to disable geo restrictions.
</ParamField>

For the full list of inputs,
see
[`modules/aws/onyx/variables.tf`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/terraform/modules/aws/onyx/variables.tf).

## Using an existing VPC

If you already have a VPC you want to deploy into, set `create_vpc = false` and pass in the VPC details,
including the ID of an existing S3 gateway VPC endpoint that the bucket policy will reference.

```hcl theme={null}
module "onyx" {
  source = "./modules/aws/onyx"

  region            = "us-west-2"
  name              = "onyx"
  postgres_username = "onyx"
  postgres_password = var.postgres_password

  create_vpc         = false
  vpc_id             = "vpc-0123456789abcdef0"
  vpc_cidr_block     = "10.0.0.0/16"
  private_subnets    = ["subnet-aaa", "subnet-bbb", "subnet-ccc"]
  public_subnets     = ["subnet-ddd", "subnet-eee", "subnet-fff"]
  s3_vpc_endpoint_id = "vpce-0123456789abcdef0"
}
```

<Warning>
  The S3 bucket policy locks bucket access to the provided `s3_vpc_endpoint_id`.
  Make sure your worker nodes route S3 traffic through that endpoint,
  otherwise S3 calls from the cluster will be denied.
</Warning>

## Production hardening

For production environments we recommend the following deltas from the quickstart:

```hcl theme={null}
module "onyx" {
  source = "./modules/aws/onyx"

  region            = "us-west-2"
  name              = "onyx"
  postgres_username = "onyx"
  postgres_password = var.postgres_password

  # Restrict the EKS control plane
  private_cluster_enabled              = true
  public_cluster_enabled               = true
  cluster_endpoint_public_access_cidrs = ["203.0.113.0/24"] # your office/VPN

  # Use IAM auth instead of a static Postgres password in cluster secrets
  enable_iam_auth    = true
  rds_db_connect_arn = "arn:aws:rds-db:us-west-2:123456789012:dbuser:*/onyx"

  # Tighten WAF
  waf_rate_limit_requests_per_5_minutes     = 1000
  waf_api_rate_limit_requests_per_5_minutes = 500
  waf_geo_restriction_countries             = ["RU", "KP"]

  # Backups
  postgres_backup_retention_period = 30

  # Optional: managed search backend
  enable_opensearch               = true
  opensearch_master_user_name     = "onyx-admin"
  opensearch_master_user_password = var.opensearch_password
}
```

## Outputs

Once `terraform apply` finishes, the `onyx` module exposes the values you'll need to configure the Helm chart.

| Output                          | Description                                                 |
| ------------------------------- | ----------------------------------------------------------- |
| `cluster_name`                  | EKS cluster name — pass to `aws eks update-kubeconfig`      |
| `postgres_endpoint`             | RDS hostname                                                |
| `postgres_port`                 | RDS port                                                    |
| `postgres_db_name`              | Database name (defaults to `postgres`)                      |
| `postgres_username`             | Master username (sensitive)                                 |
| `redis_connection_url`          | Redis primary endpoint (sensitive)                          |
| `opensearch_endpoint`           | OpenSearch domain endpoint, when `enable_opensearch = true` |
| `opensearch_dashboard_endpoint` | OpenSearch Dashboards endpoint, when enabled                |

Read them with `terraform output`:

```bash theme={null}
terraform output cluster_name
terraform output -raw postgres_endpoint
terraform output -raw redis_connection_url
```

## Install Onyx with Helm

Terraform only stands up the infrastructure — Onyx itself is installed via the [Helm
chart](/deployment/local/kubernetes).

<Steps>
  <Step title="Update kubeconfig">
    ```bash theme={null}
    aws eks update-kubeconfig \
      --name $(terraform output -raw cluster_name) \
      --region us-west-2
    ```
  </Step>

  <Step title="Create the namespace">
    ```bash theme={null}
    kubectl create namespace onyx
    ```
  </Step>

  <Step title="Install the chart">
    The EKS module creates an IRSA-backed `ServiceAccount` named `onyx-workload-access` in the `onyx` namespace,
    which has access to the S3 bucket the module created.
    Point the chart at it and disable the in-cluster MinIO so file storage uses the real S3 bucket.

    ```bash theme={null}
    helm repo add onyx https://onyx-dot-app.github.io/onyx/
    helm repo update

    helm upgrade --install onyx onyx/onyx \
      --namespace onyx \
      --set minio.enabled=false \
      --set serviceAccount.create=false \
      --set serviceAccount.name=onyx-workload-access
    ```

    You'll also want to wire the chart's database, Redis, and (optionally)
    OpenSearch settings to the Terraform outputs via your own `values.yaml`.
    See the [Kubernetes deployment guide](/deployment/local/kubernetes) for the full set of values.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    kubectl get pods -n onyx
    ```

    Wait until all pods report `Running` before accessing Onyx.
  </Step>
</Steps>

## Workspaces and multiple environments

Every resource the `onyx` module creates is named with the active Terraform workspace,
so the same root module can manage isolated environments without collisions:

```bash theme={null}
terraform workspace new dev
terraform workspace new staging
terraform workspace new prod

terraform workspace select prod
terraform apply
```

A `name = "onyx"` module call in workspace `prod` will produce `onyx-prod`-prefixed resources,
while the same call in `dev` produces `onyx-dev` resources.

## Notes & gotchas

* **Sensitive outputs.** `postgres_username`, `redis_connection_url`, and the
  EKS CA data are marked sensitive.
  Hand them off to your secrets manager or Helm values file rather than echoing them to logs.
* **State storage.** The quickstart uses local state for brevity. For shared
  or production use, configure an [S3 backend](https://developer.hashicorp.com/terraform/language/backend/s3)
  with DynamoDB locking.
* **First apply is infra-only.** EKS takes several minutes to become active.
  The `null_resource.wait_for_cluster` block in the quickstart blocks the Kubernetes/Helm providers until the API server
  is reachable.
* **The Vespa node group is tainted.** The `eks` module provisions a
  dedicated node group for Vespa with a `vespa-dedicated=true:NoSchedule` taint.
  The Helm chart's Vespa pods tolerate it; everything else lands on the main node group.
* **Reference, not a product.** The modules encode the choices we make for
  our own deployments. Read them, copy what's useful, and replace what isn't.

## Next Steps

<CardGroup>
  <Card title="Configure Authentication" icon="shield-check" href="/deployment/authentication/basic">
    Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.
  </Card>

  <Card title="More Onyx Configuration Options" icon="gear" href="/deployment/configuration/configuration">
    Learn about all available configuration options for your Onyx deployment.
  </Card>
</CardGroup>


# Contact Us
Source: https://docs.onyx.app/deployment/miscellaneous/contact_us

Ways to get in touch with the Onyx team

Shoot us a message at [hello@onyx.app](mailto:hello@onyx.app) or join our [Discord](https://discord.gg/TDJ59cGV2X).

To contact the founders, please email [founders@onyx.app](mailto:hello@onyx.app).

<img alt="Onyx" />


# Enterprise Edition
Source: https://docs.onyx.app/deployment/miscellaneous/enterprise_edition

Enterprise Edition features and deployment

Onyx Enterprise Edition unlocks additional features centered on security, user management, and site customization.
Enterprise Edition is designed for larger organizations and teams.

<Tip>
  Onyx Cloud has all Enterprise Edition features!
</Tip>

## Enterprise Edition Features

<CardGroup>
  <Card title="OIDC/SAML" icon="sitemap" href="/deployment/authentication/oidc">
    SSO authentication with OpenID Connect and SAML 2.0 providers
  </Card>

  <Card title="Permission Sync Connectors" icon="sitemap" href="/admins/connectors/overview#permission-syncing-connectors">
    Automatically inherit user permissions from external systems
  </Card>

  <Card title="Whitelabeling" icon="brush" href="/admins/advanced_configs/white_labeling">
    Customize branding, logos, and styling to match your organization
  </Card>

  <Card title="User Groups & RBACs" icon="users" href="/admins/user_management/users_and_groups">
    Organize users and maintain fine-grained RBACs
  </Card>

  <Card title="Group-Based Permissions" icon="users" href="/admins/permissions/understanding_permissions">
    Fine-grained, group-based access control for Connectors, Document Sets, and Agents. Available in v4.7+.
  </Card>

  <Card title="Usage Analytics" icon="chart-line" href="/admins/analytics/overview">
    Detailed insights into user queries and system usage
  </Card>

  <Card title="Encrypted Secrets" icon="key" href="/deployment/configuration/configuration">
    Enterprise-grade encryption for all sensitive credentials and API keys
  </Card>

  <Card title="Enterprise Edition APIs" icon="computer" href="/developers/overview">
    Extended API access for Enterprise Edition features
  </Card>

  <Card title="Priority Support" icon="headphones" href="/deployment/miscellaneous/contact_us">
    Dedicated support with guaranteed response times and white-glove deployment assistance
  </Card>

  <Card title="Hook Extensions" icon="webhook" href="/admins/advanced_configs/hook_extensions">
    Inject custom logic into Onyx's pipeline at defined stages without modifying source code
  </Card>

  <Card title="And More..." icon="ellipsis" href="/deployment/miscellaneous/contact_us">
    Contact us to learn more about Enterprise Edition features!
  </Card>
</CardGroup>

## Who needs Enterprise Edition?

Enterprise Edition is best suited for:

* Organizations with more than 100 users
* Environments requiring SSO integration
* Companies with strict security and compliance requirements
* Teams requiring centralized user management and analytics
* Deployments needing permission inheritance from external systems

## Interested in Enterprise Edition?

If you're unsure whether Enterprise Edition is right for your organization,
we're happy to help you choose the right approach.

If you'd like to try Enterprise Edition, try [Onyx Cloud](https://cloud.onyx.app) for free!

<Note>
  There are no limitations to the features or usage of the Cloud trial.
</Note>

Alternatively, contact us at [hello@onyx.app](mailto:hello@onyx.app) for a free self-hosted trial.


# Release Process & Updates
Source: https://docs.onyx.app/deployment/miscellaneous/release_process

Onyx release process, versioning, and recommended update process

This page explains Onyx's release process, versioning scheme,
and how updates are delivered to different deployment channels.

## Release Channels

<Note>
  Onyx maintains multiple release channels to provide stable and development versions for different use cases.
</Note>

### GitHub

Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/releases) publish images to Docker Hub.
Onyx has two types of releases:

* **Latest stable version** - Production-ready releases
* **Pre-release version** - Beta releases for testing

The `main` branch of the [Onyx repository](https://github.com/onyx-dot-app/onyx) is our development branch.

<Warning>
  Although we try to keep `main` stable through CI/CD tests and code reviews,
  we do not recommend using `main` in production environments.
</Warning>

### Docker Hub

[Docker Hub](https://hub.docker.com/r/onyxdotapp/onyx) hosts the actual container images.
New images are published every night from the `main` branch and when a new release is cut.

To identify the latest images programmatically, use our API endpoint:

```
https://cloud.onyx.app/api/versions
```

This endpoint returns the current latest stable and beta versions available on Docker Hub.

<Tip>
  If you don't specify a version when deploying Onyx, you will get the latest nightly builds.
</Tip>

## Versioning Scheme

Onyx follows [Semantic Versioning (SemVer)](https://semver.org/) with a clear, predictable format.

**Standard Version Format:**

```
major.minor.hotfix
```

**Pre-release Version Format:**

```
major.minor.hotfix-beta.betahotfix
```

**Examples:**

* Stable release: `1.2.3`
* Pre-release: `1.3.0-beta.1`
* Beta hotfix: `1.3.0-beta.2`

<Note>
  - **Major version** - Incremented on breaking changes
  - **Minor version** - Incremented on new features, bugfixes, and backwards-compatible changes
  - **Hotfix version** - Incremented only when backporting bugfixes to releases
</Note>

### Docker Files and Helm Charts

Changes to Docker files and Helm charts increment the version numbers in their respective files.

## Release Schedule

Onyx follows a predictable weekly release cycle.

**Every Monday:**

* The last pre-release version is promoted to stable
* `main` is frozen as the new pre-release

### Hotfix Process

* Critical bug fixes are **backported** to stable releases as necessary
* Hotfixes bypass the normal weekly cycle for urgent production issues
* Both stable and pre-release branches receive hotfixes when applicable

## Update Best Practices

To maintain a stable deployment, we recommend staying on the latest stable release.
These are tagged with a version number like `v1.2.3`.

<Steps>
  <Step title="Check Versions API for Stable Version Tag">
    Compare your current version with the version tag of the latest stable release.
    The versions endpoint is public and does not require authentication.

    ```bash theme={null}
    curl -X GET "https://cloud.onyx.app/api/versions"
    ```

    Look for the `stable: onyx` key in the response.

    ```json Example Response expandable theme={null}
    {
      "stable":{
        "onyx":"v1.8.1",
        "relational_db":"postgres:15.2-alpine",
        "index":"vespaengine/vespa:8.277.17",
        "nginx":"nginx:1.23.4-alpine"},
        "dev":{
          "onyx":"v1.9.0-beta.0",
          "relational_db":"postgres:15.2-alpine",
          "index":"vespaengine/vespa:8.277.17",
          "nginx":"nginx:1.23.4-alpine"
        },
        "migration":{
          "onyx":"airgapped-intfloat-nomic-migration",
          "relational_db":"postgres:15.2-alpine",
          "index":"vespaengine/vespa:8.277.17",
          "nginx":"nginx:1.23.4-alpine"
        }
      }
    }
    ```
  </Step>

  <Step title="Launch Onyx with the Version Tag">
    How you launch the specific Onyx version will depend on your deployment process.

    <Note>
      Don't forget the `v` prefix! I.e. `v1.2.3` is correct, `1.2.3` is incorrect.
    </Note>

    <AccordionGroup>
      <Accordion title="Docker Pull Images">
        Specify the version tag in the environment.

        ```bash theme={null}
        IMAGE_TAG=<v.MAJOR.MINOR.HOTFIX> docker compose -f docker-compose.dev.yml -p onyx-stack up -d --pull always --force-recreate
        ```
      </Accordion>
    </AccordionGroup>

    <Accordion title="Docker Build Images">
      Pull the release branch from GitHub or just the tagged version and build the images.

      The release branch is where the latest stable version is published.
      Release branches are named `release/v<MAJOR>.<MINOR>`.

      In the Onyx repo:

      ```bash From Release Branch theme={null}
      git fetch origin release/v1.2
      git switch release/v1.2

      docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
      ```

      ```bash From Tagged Version theme={null}
      git fetch origin tag v1.2.3
      git switch --detach v1.2.3

      docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
      ```
    </Accordion>

    <Accordion title="Helm">
      To specify a version when deploying with Helm, set the `global: version` value in your `values.yaml` file.

      ```yaml values.yaml theme={null}
      global:
        version: "v1.2.3"
      ```
    </Accordion>
  </Step>
</Steps>


# Overview
Source: https://docs.onyx.app/deployment/overview

An overview of deploying Onyx

## Deployment Modes

Onyx supports two deployment modes:

**Onyx Lite** — A lightweight Chat UI that requires minimal resources (under 1GB of memory).
It is great for users who want to try Onyx quickly or teams only interested in Chat and Agents. Includes LLM chat,
tools, file uploads, and Projects, but does not include the vector database, background workers,
or model inference servers.

**Onyx Standard** — The full Onyx platform, recommended for serious users and larger teams.
Includes everything in Lite plus:

* Vector + Keyword index for RAG
* Background containers for syncing knowledge from connectors
* AI model inference servers for deep learning models used during indexing and inference
* Performance optimizations via Redis and MinIO

## Quickstart

<Card title="Install Script (Recommended)" icon="bolt" href="/deployment/getting_started/quickstart">
  A guided installation script that deploys Onyx in Docker Compose. Supports both Lite and Standard modes.
</Card>

## Resourcing

<Card title="Resourcing Guide" icon="microchip" href="/deployment/getting_started/resourcing">
  Resource requirements, cloud instance selection, and scaling guidance for your Onyx deployment.
</Card>

## Deployment Options

Onyx provides a flexible set of deployment options from self-hosted to fully managed.

<CardGroup>
  <Card title="Self-Host Open Source" icon="code" href="/deployment/getting_started/quickstart">
    Get all of Onyx's core features, including Chat, Agents, Actions, Connectors, Deep Research, and more!
    All of your data remains secure within your Onyx deployment.

    **For teams looking for a powerful free solution**
  </Card>

  <Card title="Onyx Cloud" icon="cloud" href="https://cloud.onyx.app">
    Onyx managed solution with all Enterprise Edition features. Comes with a 2 week free trial (no credit card needed)!

    SOC2 Type II and GDPR compliant.

    **The most effortless way to get Onyx to your whole team**
  </Card>

  <Card title="Self-Host Enterprise Edition" icon="building" href="/deployment/miscellaneous/enterprise_edition">
    Self-Host with all premium features such as Role-Based Access Control (RBAC), automatic sync-ing of permission,
    and advanced knowledge curation options.

    **Best for large teams with strict data requirements**
  </Card>
</CardGroup>


# Create Custom Tool
Source: https://docs.onyx.app/developers/api_reference/actions/create_custom_tool

POST /admin/tool/custom

<Info>
  **Required permission:** Manage Actions (`manage:actions`), or Admin (`admin`).
  A **Group Manager** can also call this. Their scope comes from the agents shared with the groups they manage.
</Info>


# Delete Custom Tool
Source: https://docs.onyx.app/developers/api_reference/actions/delete_custom_tool

DELETE /admin/tool/custom/{tool_id}

<Info>
  **Required permission:** Manage Actions (`manage:actions`), or Admin (`admin`).
  A **Group Manager** can also call this. Their scope comes from the agents shared with the groups they manage.
</Info>


# Get Custom Tool
Source: https://docs.onyx.app/developers/api_reference/actions/get_custom_tool

GET /tool/{tool_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
</Info>


# List OpenAPI Tools
Source: https://docs.onyx.app/developers/api_reference/actions/list_openapi_tools

GET /tool/openapi

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  MCP tools you cannot access are left out of the response.
</Info>


# List Tools
Source: https://docs.onyx.app/developers/api_reference/actions/list_tools

GET /tool

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  MCP tools you cannot access are left out of the response.
</Info>


# Update Custom Tool
Source: https://docs.onyx.app/developers/api_reference/actions/update_custom_tool

PUT /admin/tool/custom/{tool_id}

<Info>
  **Required permission:** Manage Actions (`manage:actions`), or Admin (`admin`).
  A **Group Manager** can also call this. Their scope comes from the agents shared with the groups they manage.
</Info>


# Validate Tool
Source: https://docs.onyx.app/developers/api_reference/actions/validate_tool

POST /admin/tool/custom/validate

<Info>
  **Required permission:** Manage Actions (`manage:actions`), or Admin (`admin`).
  A **Group Manager** can also call this. Their scope comes from the agents shared with the groups they manage.
</Info>


# Create Agent
Source: https://docs.onyx.app/developers/api_reference/agents/create_persona

POST /persona

<Info>
  **Required permission:** Create Agents (`add:agents`), or Admin (`admin`).
  Community Edition grants it to every signed-in user. A **Group Manager** can also call this,
  limited to agents in the groups they manage.
</Info>


# Delete Agent
Source: https://docs.onyx.app/developers/api_reference/agents/delete_persona

DELETE /persona/{persona_id}

<Info>
  **Required permission:** Create Agents (`add:agents`), or Admin (`admin`).
  Community Edition grants it to every signed-in user. A **Group Manager** can also call this,
  limited to agents in the groups they manage.
</Info>


# Get Agents Admin Paginated
Source: https://docs.onyx.app/developers/api_reference/agents/get_agents_admin_paginated

GET /admin/agents
Paginated endpoint for listing agents (formerly personas) (admin view).

Returns items for the requested page plus total count.
Agents are ordered by display_priority (ASC, nulls last) then by ID (ASC).

<Info>
  **Required permission:** `read:agents`, which **Manage Agents** or **Manage Groups** includes. Admin (`admin`)
  also has it. A **Group Manager** can also call this, limited to agents in the groups they manage.
</Info>


# Get Agents Paginated
Source: https://docs.onyx.app/developers/api_reference/agents/get_agents_paginated

GET /agents
Paginated endpoint for listing agents available to the user.

Returns items for the requested page plus total count.
Personas are ordered by display_priority (ASC, nulls last) then by ID (ASC).

NOTE: persona_ids filter is not supported with pagination. Use the
non-paginated endpoint if filtering by specific IDs is needed.

<Info>
  **Required permission:** none beyond authentication. Anonymous users can call this when anonymous access is enabled.
</Info>


# Get Agent
Source: https://docs.onyx.app/developers/api_reference/agents/get_persona

GET /persona/{persona_id}

<Info>
  **Required permission:** none beyond authentication.
</Info>


# List Agents Admin
Source: https://docs.onyx.app/developers/api_reference/agents/list_personas_admin

GET /admin/persona

<Info>
  **Required permission:** `read:agents`, which **Manage Agents** or **Manage Groups** includes. Admin (`admin`)
  also has it. A **Group Manager** can also call this, limited to agents in the groups they manage.
</Info>


# Undelete Agent
Source: https://docs.onyx.app/developers/api_reference/agents/undelete_persona

PATCH /admin/persona/{persona_id}/undelete

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Update Agent
Source: https://docs.onyx.app/developers/api_reference/agents/update_persona

PATCH /persona/{persona_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  The real check is per-agent: you must own the agent, or have been shared it as an editor.
</Info>


# Create New Chat Session
Source: https://docs.onyx.app/developers/api_reference/chat/create_new_chat_session

POST /chat/create-chat-session

<Info>
  **Required permission:** Chat — Write (`write:chat`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Chat — Write scope.
  A service account in no group also holds it. Anonymous users can call this when anonymous access is enabled.
</Info>


# Delete All Chat Sessions
Source: https://docs.onyx.app/developers/api_reference/chat/delete_all_chat_sessions

DELETE /chat/delete-all-chat-sessions

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  This deletes only your own chat sessions.
</Info>


# Delete Chat Session By Id
Source: https://docs.onyx.app/developers/api_reference/chat/delete_chat_session_by_id

DELETE /chat/delete-chat-session/{session_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only delete your own chat sessions.
</Info>


# Fetch Chat File
Source: https://docs.onyx.app/developers/api_reference/chat/fetch_chat_file

GET /chat/file/{file_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only fetch files from your own chat sessions.
</Info>


# Get Chat Session
Source: https://docs.onyx.app/developers/api_reference/chat/get_chat_session

GET /chat/get-chat-session/{session_id}

<Info>
  **Required permission:** Chat — Read (`read:chat`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Chat — Read scope.
  Anonymous users can call this when anonymous access is enabled.
</Info>


# Get User Chat Sessions
Source: https://docs.onyx.app/developers/api_reference/chat/get_user_chat_sessions

GET /chat/get-user-chat-sessions

<Info>
  **Required permission:** Chat — Read (`read:chat`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Chat — Read scope.
</Info>


# Handle Send Chat Message
Source: https://docs.onyx.app/developers/api_reference/chat/handle_send_chat_message

POST /chat/send-chat-message
This endpoint is used to send a new chat message.

Args:
    chat_message_req (SendMessageRequest): Details about the new chat message.
        - When stream=True (default): Returns StreamingResponse with SSE
        - When stream=False: Returns ChatFullResponse with complete data
    request (Request): The current HTTP request context.
    user (User | None): The current user, obtained via dependency injection.
    _ (None): Rate limit check is run if user/group/global rate limits are enabled.

Returns:
    StreamingResponse | ChatFullResponse: Either streams or returns complete response.

<Info>
  **Required permission:** Chat — Write (`write:chat`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Chat — Write scope.
  A service account in no group also holds it. Anonymous users can call this when anonymous access is enabled.
</Info>


# Search Chats
Source: https://docs.onyx.app/developers/api_reference/chat/search_chats

GET /chat/search
Search for chat sessions based on the provided query.
If no query is provided, returns recent chat sessions.

<Info>
  **Required permission:** Chat — Read (`read:chat`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Chat — Read scope.
</Info>


# Stop Chat Session
Source: https://docs.onyx.app/developers/api_reference/chat/stop_chat_session

POST /chat/stop-chat-session/{chat_session_id}
Stop a chat session by setting a stop signal in Redis.
This endpoint is called by the frontend when the user clicks the stop button.

<Info>
  **Required permission:** Chat — Write (`write:chat`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Chat — Write scope.
  A service account in no group also holds it.
</Info>


# Associate Credential To Connector
Source: https://docs.onyx.app/developers/api_reference/files_connectors/associate_credential_to_connector

PUT /manage/connector/{connector_id}/credential/{credential_id}
NOTE(rkuo): internally discussed and the consensus is this endpoint
and create_connector_with_mock_credential should be combined.

The intent of this endpoint is to handle connectors that actually need credentials.

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
</Info>


# Connector Run Once
Source: https://docs.onyx.app/developers/api_reference/files_connectors/connector_run_once

POST /manage/admin/connector/run-once
Used to trigger indexing on a set of cc_pairs associated with a
single connector.

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connectors in the groups they manage.
</Info>


# Create Connector From Model
Source: https://docs.onyx.app/developers/api_reference/files_connectors/create_connector_from_model

POST /manage/admin/connector

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connectors in the groups they manage.
</Info>


# Create Credential From Model
Source: https://docs.onyx.app/developers/api_reference/files_connectors/create_credential_from_model

POST /manage/credential

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to credentials in the groups they manage.
</Info>


# Create Credential With Private Key
Source: https://docs.onyx.app/developers/api_reference/files_connectors/create_credential_with_private_key

POST /manage/credential/private-key

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to credentials in the groups they manage.
</Info>


# Create Deletion Attempt For Connector Id
Source: https://docs.onyx.app/developers/api_reference/files_connectors/create_deletion_attempt_for_connector_id

POST /manage/admin/deletion-attempt

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
</Info>


# Delete Connector By Id
Source: https://docs.onyx.app/developers/api_reference/files_connectors/delete_connector_by_id

DELETE /manage/admin/connector/{connector_id}

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Delete Credential By Id
Source: https://docs.onyx.app/developers/api_reference/files_connectors/delete_credential_by_id

DELETE /manage/credential/{credential_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only delete your own credentials.
</Info>


# Delete Credential By Id Admin
Source: https://docs.onyx.app/developers/api_reference/files_connectors/delete_credential_by_id_admin

DELETE /manage/admin/credential/{credential_id}
Same as the user endpoint, but can delete any credential (not just the user's own)

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Dissociate Credential From Connector
Source: https://docs.onyx.app/developers/api_reference/files_connectors/dissociate_credential_from_connector

DELETE /manage/connector/{connector_id}/credential/{credential_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only act on connector-credential pairs you can already reach.
</Info>


# Force Delete Credential By Id
Source: https://docs.onyx.app/developers/api_reference/files_connectors/force_delete_credential_by_id

DELETE /manage/credential/force/{credential_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only delete your own credentials.
</Info>


# Get Basic Connector Indexing Status
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_basic_connector_indexing_status

GET /manage/connector-status

<Info>
  **Required permission:** none beyond authentication. Anonymous users can call this when anonymous access is enabled.
</Info>


# Get CC Pair Full Info
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_cc_pair_full_info

GET /manage/admin/cc-pair/{cc_pair_id}

<Info>
  **Required permission:** `read:connectors`, which **Manage Connectors & Document Sets** or **Manage Groups** includes.
  Admin (`admin`) also has it. A **Group Manager** can also call this,
  limited to connector-credential pairs in the groups they manage.
</Info>


# Get CC Pair Index Attempts
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_cc_pair_index_attempts

GET /manage/admin/cc-pair/{cc_pair_id}/index-attempts

<Info>
  **Required permission:** `read:connectors`, which **Manage Connectors & Document Sets** or **Manage Groups** includes.
  Admin (`admin`) also has it. A **Group Manager** can also call this,
  limited to connector-credential pairs in the groups they manage.
</Info>


# Get CC Pair Indexing Errors
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_cc_pair_indexing_errors

GET /manage/admin/cc-pair/{cc_pair_id}/errors
Gives back all errors for a given CC Pair. Allows pagination based on page and page_size params.

Args:
    cc_pair_id: ID of the connector-credential pair to get errors for
    include_resolved: Whether to include resolved errors in the results
    page_num: Page number for pagination, starting at 0
    page_size: Number of errors to return per page
    _: Current user, must be curator or admin
    db_session: Database session

Returns:
    Paginated list of indexing errors for the CC pair.

<Info>
  **Required permission:** `read:connectors`, which **Manage Connectors & Document Sets** or **Manage Groups** includes.
  Admin (`admin`) also has it.
</Info>


# Get Cc Source Full Info
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_cc_source_full_info

GET /manage/admin/similar-credentials/{source_type}

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to credentials in the groups they manage.
</Info>


# Get Connector By Id
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_connector_by_id

GET /manage/connector/{connector_id}

<Info>
  **Required permission:** `read:connectors`, which **Manage Connectors & Document Sets** or **Manage Groups** includes.
  Admin (`admin`) also has it.
</Info>


# Get Connector Indexing Status
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_connector_indexing_status

POST /manage/admin/connector/indexing-status

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connectors in the groups they manage.
</Info>


# Get Connector Status
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_connector_status

GET /manage/admin/connector/status

<Info>
  **Required permission:** `read:connectors`, which **Manage Connectors & Document Sets** or **Manage Groups** includes.
  Admin (`admin`) also has it. A **Group Manager** can also call this, limited to connectors in the groups they manage.
</Info>


# Get Connectors
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_connectors

GET /manage/connector

<Info>
  **Required permission:** `read:connectors`, which **Manage Connectors & Document Sets** or **Manage Groups** includes.
  Admin (`admin`) also has it.
</Info>


# Get Connectors By Credential
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_connectors_by_credential

GET /manage/admin/connector
Get a list of connectors. Allow filtering by a specific credential id.

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Get Credential By Id
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_credential_by_id

GET /manage/credential/{credential_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only read your own credentials.
</Info>


# Get Currently Failed Indexing Status
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_currently_failed_indexing_status

GET /manage/admin/connector/failed-indexing-status

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Get Docs By Connector Credential Pair
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_docs_by_connector_credential_pair

GET /onyx-api/connector-docs/{cc_pair_id}

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
</Info>


# Get Indexed Sources
Source: https://docs.onyx.app/developers/api_reference/files_connectors/get_indexed_sources

GET /manage/indexed-sources

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
</Info>


# List Connector Files
Source: https://docs.onyx.app/developers/api_reference/files_connectors/list_connector_files

GET /manage/admin/connector/{connector_id}/files
List all files in a file connector.

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# List Credentials
Source: https://docs.onyx.app/developers/api_reference/files_connectors/list_credentials

GET /manage/credential

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see your own credentials.
  **Manage Connectors & Document Sets** also sees credentials that have no owner and ones marked admin-public.
</Info>


# List Credentials Admin
Source: https://docs.onyx.app/developers/api_reference/files_connectors/list_credentials_admin

GET /manage/admin/credential
Lists all public credentials

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to credentials in the groups they manage.
</Info>


# Prune Cc Pair
Source: https://docs.onyx.app/developers/api_reference/files_connectors/prune_cc_pair

POST /manage/admin/cc-pair/{cc_pair_id}/prune
Triggers pruning on a particular cc_pair immediately

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
</Info>


# Swap Credentials For Connector
Source: https://docs.onyx.app/developers/api_reference/files_connectors/swap_credentials_for_connector

PUT /manage/admin/credential/swap

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Update CC Pair Status
Source: https://docs.onyx.app/developers/api_reference/files_connectors/update_cc_pair_status

PUT /manage/admin/cc-pair/{cc_pair_id}/status
This method returns nearly immediately. It simply sets some signals and
optimistically assumes any running background processes will clean themselves up.
This is done to improve the perceived end user experience.

Returns HTTPStatus.OK if everything finished.

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
</Info>


# Update Connector Files
Source: https://docs.onyx.app/developers/api_reference/files_connectors/update_connector_files

POST /manage/admin/connector/{connector_id}/files/update
Update files in a connector by adding new files and/or removing existing ones.
This is an atomic operation that validates, updates the connector config, and triggers indexing.

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Update Credential Data
Source: https://docs.onyx.app/developers/api_reference/files_connectors/update_credential_data

PUT /manage/admin/credential/{credential_id}

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Update Credential From Model
Source: https://docs.onyx.app/developers/api_reference/files_connectors/update_credential_from_model

PATCH /manage/credential/{credential_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You can only update your own credentials.
</Info>


# Update Credential Private Key
Source: https://docs.onyx.app/developers/api_reference/files_connectors/update_credential_private_key

PUT /manage/admin/credential/private-key/{credential_id}

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Upload Files Api
Source: https://docs.onyx.app/developers/api_reference/files_connectors/upload_files_api

POST /manage/admin/connector/file/upload

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Delete Ingestion Doc
Source: https://docs.onyx.app/developers/api_reference/ingestion/delete_ingestion_doc

DELETE /onyx-api/ingestion/{document_id}

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
</Info>


# Get Ingestion Docs
Source: https://docs.onyx.app/developers/api_reference/ingestion/get_ingestion_docs

GET /onyx-api/ingestion

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
</Info>


# Upsert Ingestion Doc
Source: https://docs.onyx.app/developers/api_reference/ingestion/upsert_ingestion_doc

POST /onyx-api/ingestion

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can also call this, limited to connector-credential pairs in the groups they manage.
  The default pair is public, so a Group Manager cannot ingest into it.
</Info>


# Create Global Token Limit Settings
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/create_global_token_limit_settings

POST /admin/token-rate-limits/global

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Delete Token Limit Settings
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/delete_token_limit_settings

DELETE /admin/token-rate-limits/rate-limit/{token_rate_limit_id}

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Get Global Token Limit Settings
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/get_global_token_limit_settings

GET /admin/token-rate-limits/global

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Get Backend Version
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/get_version

GET /version

<Info>
  **No authentication required.**
</Info>


# Get Latest App Version Tags
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/get_versions

GET /versions
Fetches the latest stable and beta versions of Onyx Docker images.
Since DockerHub does not explicitly flag stable and beta images,
this endpoint can be used to programmatically check for new images.

<Info>
  **No authentication required.**
</Info>


# Healthcheck
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/healthcheck

GET /health

<Info>
  **No authentication required.**
</Info>


# Update Token Limit Settings
Source: https://docs.onyx.app/developers/api_reference/miscellaneous/update_token_limit_settings

PUT /admin/token-rate-limits/rate-limit/{token_rate_limit_id}

<Info>
  **Enterprise Edition Feature**

  This feature requires an Enterprise plan. [View plans](/admins/billing/overview)
  or [contact sales](https://onyx.app/contact-sales) to learn more.
</Info>

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Create Project
Source: https://docs.onyx.app/developers/api_reference/projects/create_project

POST /user/projects/create

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Delete Project
Source: https://docs.onyx.app/developers/api_reference/projects/delete_project

DELETE /user/projects/{project_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Delete User File
Source: https://docs.onyx.app/developers/api_reference/projects/delete_user_file

DELETE /user/projects/file/{file_id}
Delete a user file belonging to the current user.

This will also remove any project associations for the file.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get Chat Session Project Files
Source: https://docs.onyx.app/developers/api_reference/projects/get_chat_session_project_files

GET /user/projects/session/{chat_session_id}/files
Return user files for the project linked to the given chat session.

If the chat session has no project, returns an empty list.
Only returns files owned by the current user and not FAILED.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get Files In Project
Source: https://docs.onyx.app/developers/api_reference/projects/get_files_in_project

GET /user/projects/files/{project_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get Project
Source: https://docs.onyx.app/developers/api_reference/projects/get_project

GET /user/projects/{project_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get Project Details
Source: https://docs.onyx.app/developers/api_reference/projects/get_project_details

GET /user/projects/{project_id}/details

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get Project Instructions
Source: https://docs.onyx.app/developers/api_reference/projects/get_project_instructions

GET /user/projects/{project_id}/instructions

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get Projects
Source: https://docs.onyx.app/developers/api_reference/projects/get_projects

GET /user/projects/

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get User File
Source: https://docs.onyx.app/developers/api_reference/projects/get_user_file

GET /user/projects/file/{file_id}
Fetch a single user file by ID for the current user.

Includes files in any status (including FAILED) to allow status polling.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Get User File Statuses
Source: https://docs.onyx.app/developers/api_reference/projects/get_user_file_statuses

POST /user/projects/file/statuses
Fetch statuses for a set of user file IDs owned by the current user.

Includes files in any status so the client can detect transitions to FAILED.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Link User File To Project
Source: https://docs.onyx.app/developers/api_reference/projects/link_user_file_to_project

POST /user/projects/{project_id}/files/{file_id}
Link an existing user file to a specific project for the current user.

Creates the association in the Project__UserFile join table if it does not exist.
Returns the linked user file snapshot.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Unlink User File From Project
Source: https://docs.onyx.app/developers/api_reference/projects/unlink_user_file_from_project

DELETE /user/projects/{project_id}/files/{file_id}
Unlink an existing user file from a specific project for the current user.

Does not delete the underlying file; only removes the association.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Update Project
Source: https://docs.onyx.app/developers/api_reference/projects/update_project

PATCH /user/projects/{project_id}

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Upload User Files
Source: https://docs.onyx.app/developers/api_reference/projects/upload_user_files

POST /user/projects/file/upload

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Upsert Project Instructions
Source: https://docs.onyx.app/developers/api_reference/projects/upsert_project_instructions

POST /user/projects/{project_id}/instructions
Create or update this project's instructions stored on the project itself.

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  You only see and change your own projects and files.
</Info>


# Execute Open Urls
Source: https://docs.onyx.app/developers/api_reference/search/execute_open_urls

POST /web-search/open-urls
Fetch content for specific URLs using the configured content provider.
Intended to complement `/search-lite` when you need content for a subset of URLs.

<Info>
  **Required permission:** Search — Read (`read:search`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Search — Read scope.
</Info>


# Execute Web Search
Source: https://docs.onyx.app/developers/api_reference/search/execute_web_search

POST /web-search/search
Perform a web search and immediately fetch content for the returned URLs.

Use this when you want both snippets and page contents from one call.

If you want to selectively fetch content (i.e. let the LLM decide which URLs to read),
use `/search-lite` and then call `/open-urls` separately.

<Info>
  **Required permission:** Search — Read (`read:search`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Search — Read scope.
</Info>


# Execute Web Search Lite
Source: https://docs.onyx.app/developers/api_reference/search/execute_web_search_lite

POST /web-search/search-lite
Lightweight search-only endpoint. Returns search snippets and URLs without
fetching page contents. Pair with `/open-urls` if you need to fetch content
later.

<Info>
  **Required permission:** Search — Read (`read:search`), which `basic` includes, so any signed-in user has it.
  A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Search — Read scope.
</Info>


# Activate User Api
Source: https://docs.onyx.app/developers/api_reference/user_management/activate_user_api

PATCH /manage/admin/activate-user

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Bulk Invite Users
Source: https://docs.onyx.app/developers/api_reference/user_management/bulk_invite_users

PUT /manage/admin/users
emails are string validated. If any email fails validation, no emails are
invited and an exception is raised.

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Deactivate User Api
Source: https://docs.onyx.app/developers/api_reference/user_management/deactivate_user_api

PATCH /manage/admin/deactivate-user

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Delete User
Source: https://docs.onyx.app/developers/api_reference/user_management/delete_user

DELETE /manage/admin/delete-user

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Get Auth Type
Source: https://docs.onyx.app/developers/api_reference/user_management/get_auth_type

GET /auth/type

<Info>
  **No authentication required.**
</Info>


# Get Current User Permissions
Source: https://docs.onyx.app/developers/api_reference/user_management/get_current_user_permissions

GET /me/permissions

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
</Info>

Returns the caller's resolved permissions, with implied permissions already expanded.
Use it to check what a token can do before calling an endpoint.

`is_manager` is `true` when the caller is a **Group Manager** of at least one group,
and `managed_group_ids` lists those groups. A Group Manager holds their management permissions only inside those groups.

<Note>
  This endpoint applies to Onyx **v4.7 and later**. It replaces `GET /get-user-role`,
  which was removed with the role model in v4.7. For older versions,
  see [Get User Role](/developers/api_reference/user_management/get_user_role).
</Note>


# Get User Role
Source: https://docs.onyx.app/developers/api_reference/user_management/get_user_role

GET /get-user-role

<Info>
  This endpoint applies only to Onyx versions before **v4.7**. For Onyx v4.7 and later,
  use [Get Current User Permissions](/developers/api_reference/user_management/get_current_user_permissions).
</Info>


# List Accepted Users
Source: https://docs.onyx.app/developers/api_reference/user_management/list_accepted_users

GET /manage/users/accepted

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# List All Users
Source: https://docs.onyx.app/developers/api_reference/user_management/list_all_users

GET /manage/users

<Info>
  **Required permission:** `read:users`, which **Manage Groups** or **Manage LLMs** includes. Admin (`admin`)
  also has it. A **Group Manager** can also call this, and receives the full user list.
</Info>


# List All Users Basic Info
Source: https://docs.onyx.app/developers/api_reference/user_management/list_all_users_basic_info

GET /users

<Info>
  **Required permission:** Basic access (`basic`) — any signed-in user or service account.
  If **Full User Directory Visibility** is set to Admins Only in the Security settings, this also requires `read:users`.
</Info>


# List Invited Users
Source: https://docs.onyx.app/developers/api_reference/user_management/list_invited_users

GET /manage/users/invited

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Remove Invited User
Source: https://docs.onyx.app/developers/api_reference/user_management/remove_invited_user

PATCH /manage/admin/remove-invited-user

<Info>
  **Required permission:** Admin (`admin`).
</Info>


# Set User Admin Access
Source: https://docs.onyx.app/developers/api_reference/user_management/set_user_admin_access

PATCH /manage/admin/users/admin-access

<Info>
  **Required permission:** Admin (`admin`).
</Info>

Admin access is membership in the **Admin** group, so this endpoint adds the user to that group or removes them from it.

<Note>
  This endpoint applies to Onyx **v4.7 and later**. It replaces `PATCH /manage/set-user-role`,
  which was removed with the role model in v4.7. For older versions,
  see [Set User Role](/developers/api_reference/user_management/set_user_role). To grant any other permission,
  add the user to a group that grants it.
</Note>

Onyx rejects the request when it would lock you out of the admin panel or when the account cannot hold admin access:

* You cannot remove yourself from the Admin group. Ask another admin to do it.
* You cannot remove the last admin. Grant another user admin access first.
* This endpoint cannot change admin access for service accounts, bot accounts, external permission accounts,
  or anonymous accounts. To grant an API key admin access, assign its service account to the Admin group.


# Set User Role
Source: https://docs.onyx.app/developers/api_reference/user_management/set_user_role

PATCH /manage/set-user-role

<Info>
  This endpoint applies only to Onyx versions before **v4.7**. For Onyx v4.7 and later,
  use [Set User Admin Access](/developers/api_reference/user_management/set_user_admin_access)
  to toggle Admin group membership. To grant other permissions, add the user to a group that grants them.
</Info>


# Verify User Logged In
Source: https://docs.onyx.app/developers/api_reference/user_management/verify_user_logged_in

GET /me

<Info>
  **Required permission:** none. Authentication is optional: without it,
  this returns the anonymous user's info when anonymous access is enabled, and `401` otherwise.
</Info>


# Contact Us
Source: https://docs.onyx.app/developers/contact_us

Excited to hear from you!

Shoot us a message at [hello@onyx.app](mailto:hello@onyx.app) or join our [Discord](https://discord.gg/TDJ59cGV2X).

To contact the founders, please email [founders@onyx.app](mailto:hello@onyx.app).

<img alt="Onyx" />


# Core Concepts
Source: https://docs.onyx.app/developers/core_concepts

Essential concepts and terminology for working with Onyx APIs

## Actions & MCP

<AccordionGroup>
  <Accordion title="Actions" icon="wrench">
    Actions (also called Tools in the backend)
    are the functions that your Agents can perform to interact with external systems and services.
    They extend your agents' capabilities beyond just the language model.

    Built-in Actions:

    | Name                         | Description                                                             | Requires Config           | Provider Choices                          |
    | ---------------------------- | ----------------------------------------------------------------------- | ------------------------- | ----------------------------------------- |
    | Internal Search              | Search through your organization's indexed documents and knowledge base | Yes                       | Built-in with swappable components        |
    | Web Search                   | Search the internet for real-time information and current events        | Yes                       | Google, Serper, Exa, Firecrawl (optional) |
    | Code Execution               | Execute Python code, analyze data, and generate visualizations          | No                        | Built-in                                  |
    | Image Generation             | Create images from text descriptions using AI models                    | Yes                       | OpenAI, Azure OpenAI                      |
    | Coding Agent <sup>Beta</sup> | Investigate and answer questions about a public GitHub codebase         | Yes (disabled by default) | Built-in                                  |

    <Info>
      SCIM support for common IdPs is coming soon!
    </Info>

    Custom Actions:

    * **API Integrations**: Connect to external REST APIs
    * **Database Operations**: Query and update databases
    * **Workflow Automation**: Trigger business processes
    * **File Operations**: Read, write, and manipulate files

    You can define your own Custom Actions in the Admin Panel using an OpenAPI specification.
  </Accordion>

  <Accordion title="MCP" icon="handshake">
    Model Context Protocol (MCP)
    is an open standard that enables AI assistants to securely access external data sources and tools.
    Onyx can be configured as an MCP client to interact with external systems, databases,
    and APIs in a controlled manner.

    Key features of MCP:

    * **External Data Access**: Connect to databases, APIs, and file systems
    * **Authentication**: Pass through OAuth to ensure secure access to your MCP server.
  </Accordion>

  <Accordion title="(Advanced) Custom Built-in Actions" icon="wrench">
    Sometimes, you need more control over your action than what is possible with a Custom Action.
    Since Onyx is open-source, you can extend the built-in actions to your liking!

    To find templates for built-in actions,
    see `backend/onyx/tools/tool_implementations` in the [Onyx repository](https://github.com/onyx-dot-app/onyx).

    <Warning>
      Extending the codebase is not recommended for most users. Before you start,
      please reach out to us on
      [Slack](https://join.slack.com/t/onyx-dot-app/shared_invite/zt-34lu4m7xg-TsKGO6h8PDvR5W27zTdyhA)
      or [Discord](https://discord.gg/TDJ59cGV2X) for support!
    </Warning>
  </Accordion>
</AccordionGroup>

## Agents

<AccordionGroup>
  <Accordion title="Agents" icon="user">
    Agents are AI assistants with custom instructions, Actions, and data access that extend the base LLM's capabilities.

    <Note>
      The terms *Personas*, *Assistants*,
      and *Agents* are used interchangeably throughout Onyx and refer to the same concept.
    </Note>

    **Built-in Agents:**

    * `id: 0` Search Agent - Uses the Search Tool to answer questions from your knowledge base
    * `id: -1` General Agent - Basic chat with no tools (basic chat with an LLM)
    * `id: -2` Paraphrase Agent - Uses Search Tool and quotes exact snippets from sources
    * `id: -3` Art Agent - Generates images and visual content

    You can create your own Agents in the Admin Panel or by API.

    **Most Chat endpoints require an Agent ID**

    To find your Agent ID, you can:

    * Use the `GET /persona` API endpoint to list all agents
    * In the Admin Panel: Click into an agent and check the first number in the URL
  </Accordion>
</AccordionGroup>

## Chat

<AccordionGroup>
  <Accordion title="Streamed Chat Responses" icon="comment">
    The chat response system uses a packet-based architecture to deliver real-time responses to users.
    Instead of waiting for a complete response,
    the system breaks down the chat interaction into discrete packets that can be streamed incrementally.

    Every packet follows a consistent structure defined by the `Packet` class:

    ```python theme={null}
    class Packet(BaseModel):
      ind: int        # Sequential index for ordering
      obj: PacketObj  # The actual content including type of packet
    ```

    **Streaming Flow:**

    * A chat request triggers the streaming process
    * Various packet types are generated based on the required operations
      (reasoning, tool calls, AI response, documents, citations, etc.)
    * Packets are sent with sequential indices to maintain order
    * The frontend processes packets in real-time to update the UI
    * An `OverallStop` packet signals completion
  </Accordion>

  <Accordion title="Basic Message Packets" icon="message">
    **MessageStart and MessageDelta**

    These packets form the core of the streaming response system:

    * **MessageStart**: Initiates a new message with initial content and final search documents (if any)
    * **MessageDelta**: Delivers incremental text content as it's generated
  </Accordion>

  <Accordion title="Control Packets" icon="gear">
    **Session and Section Management**

    Control packets manage the flow and lifecycle of the streaming process:

    * **OverallStop**: Signals the end of the entire streaming session
    * **SectionEnd**: Marks the completion of a packet type (reasoning, message, citations, etc.)
  </Accordion>

  <Accordion title="Tool Packets" icon="wrench">
    Tool responses are streamed in the same way as the main message response.

    **Search Tools**

    * SearchToolStart and SearchToolDelta handle document search operations

    **Image Generation**

    * ImageGenerationToolStart, ImageGenerationToolDelta, and ImageGenerationToolHeartbeat manage AI image creation

    **Custom Tools**

    * CustomToolStart and CustomToolDelta are used for MCP and custom Actions

    The start packet signals the start of the tool response.
    The delta packets stream the results as they become available.
  </Accordion>

  <Accordion title="Reasoning Packets" icon="lightbulb">
    Any reasoning steps are streamed so the frontend can render them as the system is processing.
    Reasoning packets are generally the first ones sent.

    * **ReasoningStart**: Begins a reasoning section
    * **ReasoningDelta**: Streams the AI's reasoning process
  </Accordion>

  <Accordion title="Citation Packets" icon="quote-right">
    Citation packets associate citation ids with document ids.

    * **CitationStart**: Initiates citation results
    * **CitationDelta**: Delivers source citations and references
  </Accordion>
</AccordionGroup>

## Connectors

<Tip>
  When you see the term *Connector* in Onyx or elsewhere in this documentation,
  we're generally referring to *ConnectorCredentialPairs*
</Tip>

<AccordionGroup>
  <Accordion title="Connectors" icon="plug">
    `Connectors` in Onyx define the data you would like to index

    * `name`: Not actually displayed in the UI if `ConnectorCredentialPairMetadata:name` is set
    * `source`: Which system to connect to (see `DocumentSource` accordion below)
    * `input_type`: How the `Connector` retrieves data (see `InputType` accordion below)
    * `connector_specific_config`: Source-specific settings like folder paths or channels. You will need to see [`/backend/onyx/connectors`](https://github.com/onyx-dot-app/onyx/tree/main/backend/onyx/connectors) for the expected Connector-specific Configurations.
    * `refresh_freq`: How often to check for new or updated content in seconds
    * `prune_freq`: How often to remove old content from Onyx in seconds
    * `indexing_start`: Optional datetime to specify when indexing should begin

    ```python Python theme={null}
    class ConnectorBase(BaseModel):
      name: str
      source: DocumentSource
      input_type: InputType
      connector_specific_config: dict[str, Any]
      refresh_freq: int | None = None
      prune_freq: int | None = None
      indexing_start: datetime | None = None
    ```
  </Accordion>

  <Accordion title="Credentials" icon="key">
    `Credentials` contain the authentication details needed to access data sources. These include API keys,
    OAuth tokens, personal access tokens (PATs),
    or service account credentials that allow Onyx to securely connect to your external systems.

    Types of `Credentials`:

    * **API Keys**: Simple token-based authentication
    * **OAuth Tokens**: Delegated authorization with refresh capabilities
    * **Service Accounts**: Machine-to-machine authentication
    * **Personal Access Tokens**: User-specific access credentials
  </Accordion>

  <Accordion title="ConnectorCredentialPairs" icon="link">
    Behind the scenes, `Connectors` and `Credentials` are combined into a `ConnectorCredentialPair` (CC-pair).
    A CC-pair is an active connection that can sync data from your external sources into Onyx.
    CC-pairs are what you see and manage on the Admin `Connectors` page.

    CC-pair functionality:

    * **Active Connections**: Live data synchronization between source and Onyx
    * **Status Monitoring**: Track sync health and performance
    * **Access Control**: Manage who can see data from this connection
    * **Configuration Management**: Update sync settings and credentials

    <Warning>
      If you're creating `Connectors` through the API, you must associate them with a `Credential` (CC-pair)
      to make them active!
    </Warning>
  </Accordion>

  <Accordion title="ConnectorCredentialPairMetadata" icon="gear">
    `ConnectorCredentialPairMetadata` defines the configuration and access settings for a CC-pair.

    Configuration options:

    * `name`: Optional display name for the CC-pair (overrides the `Connector` name)
    * `access_type`: Who can access data from this CC-pair (see `AccessType` accordion below)
    * `auto_sync_options`: Optional configuration for automatic synchronization settings
    * `groups`: List of group IDs that have access to this CC-pair

    ```python Python theme={null}
    class ConnectorCredentialPairMetadata(BaseModel):
      name: str | None = None
      access_type: AccessType
      auto_sync_options: dict[str, Any] | None = None
      groups: list[int] = Field(default_factory=list)
    ```
  </Accordion>
</AccordionGroup>

## Documents

<AccordionGroup>
  <Accordion title="DocumentBase" icon="page">
    `DocumentBase` is a core structure used throughout Onyx for storing and managing document data.
    Note that the embeddings are stored in Vespa separately.

    * `id`: Unique identifier. Generated by Onyx if not provided
    * `sections`: List of content sections (see `TextSection` and `ImageSection`)
    * `source`: The system this document originated from (see `DocumentSource`)
    * `semantic_identifier`: Displayed in the UI as the name of the Document
    * `metadata`: Arbitrary `string` or `list[string]` that will be saved as tags for this Document
    * `doc_updated_at`: UTC timestamp when the document was last updated
    * `chunk_count`: Number of chunks the document is split into for processing
    * `primary_owners`: Metadata about people associated with the Document
    * `secondary_owners`: Metadata about people associated with the Document
    * `title`: Used for search (defaults to `semantic_identifier` if not specified)
    * `from_ingestion_api`: Whether this document came from the Ingestion API
    * `additional_info`: Connector-specific information that other parts of the code may need
    * `external_access`: Permission sync data (Enterprise Edition only)

    <Note>
      The Ingestion API extends the DocumentBase definition to include `cc_pair_id` to automatically associate a
      document with a CC-pair.
    </Note>

    ```python Python expandable theme={null}
    class DocumentBase(BaseModel):
      """Used for Onyx ingestion api, the ID is inferred before use if not provided"""

      id: str | None = None
      sections: list[TextSection | ImageSection]
      source: DocumentSource | None = None
      semantic_identifier: str
      metadata: dict[str, str | list[str]]

      doc_updated_at: datetime | None = None
      chunk_count: int | None = None

      primary_owners: list[BasicExpertInfo] | None = None
      secondary_owners: list[BasicExpertInfo] | None = None
      title: str | None = None
      from_ingestion_api: bool = False
      additional_info: Any = None

      external_access: ExternalAccess | None = None
    ```
  </Accordion>

  <Accordion title="DocumentSource" icon="file">
    `DocumentSource` is an enum that defines the valid sources for a document.
    Uploading files to the Ingestion API and creating `Connectors` programmatically require specifying a
    `DocumentSource`.

    ```python Python expandable theme={null}
    class DocumentSource(str, Enum):
      INGESTION_API = "ingestion_api"     # Special case, document passed in via Onyx APIs without specifying a source type
      SLACK = "slack"
      WEB = "web"
      GOOGLE_DRIVE = "google_drive"
      GMAIL = "gmail"
      REQUESTTRACKER = "requesttracker"
      GITHUB = "github"
      GITBOOK = "gitbook"
      GITLAB = "gitlab"
      GURU = "guru"
      BOOKSTACK = "bookstack"
      CONFLUENCE = "confluence"
      JIRA = "jira"
      SLAB = "slab"
      PRODUCTBOARD = "productboard"
      FILE = "file"
      NOTION = "notion"
      ZULIP = "zulip"
      LINEAR = "linear"
      HUBSPOT = "hubspot"
      DOCUMENT360 = "document360"
      GONG = "gong"
      GOOGLE_SITES = "google_sites"
      ZENDESK = "zendesk"
      LOOPIO = "loopio"
      DROPBOX = "dropbox"
      SHAREPOINT = "sharepoint"
      TEAMS = "teams"
      SALESFORCE = "salesforce"
      DISCOURSE = "discourse"
      AXERO = "axero"
      CLICKUP = "clickup"
      MEDIAWIKI = "mediawiki"
      WIKIPEDIA = "wikipedia"
      ASANA = "asana"
      S3 = "s3"
      R2 = "r2"
      GOOGLE_CLOUD_STORAGE = "google_cloud_storage"
      OCI_STORAGE = "oci_storage"
      XENFORO = "xenforo"
      NOT_APPLICABLE = "not_applicable"
      DISCORD = "discord"
      FRESHDESK = "freshdesk"
      FIREFLIES = "fireflies"
      EGNYTE = "egnyte"
      AIRTABLE = "airtable"
      HIGHSPOT = "highspot"

      IMAP = "imap"

      # Special case just for integration tests
      MOCK_CONNECTOR = "mock_connector"
    ```
  </Accordion>

  <Accordion title="TextSection" icon="text">
    `TextSection` is a portion of a Document in Onyx.

    * `text`: The actual text content of the section
    * `link`: Optional URL that this text section relates to or was sourced from

    ```python Python theme={null}
    class TextSection(Section):
      text: str
      link: str | None = None
    ```
  </Accordion>

  <Accordion title="ImageSection" icon="image">
    `ImageSection` is an image extracted from a Document in Onyx.

    * `image_file_id`: UUID of the image file stored in Onyx's file store
    * `text`: Optional text description or caption for the image
    * `link`: Optional URL that this image section relates to or was sourced from

    ```python Python theme={null}
    class ImageSection(Section):
      image_file_id: str
      text: str | None = None
      link: str | None = None
    ```
  </Accordion>

  <Accordion title="AccessType" icon="shield">
    `AccessType` defines who can access data from a `Connector` in Onyx.

    * `PUBLIC`: All Onyx users may access data from this `Connector`
    * `PRIVATE`: Only the user who created the `Connector` and specified Groups may access data from this `Connector`
    * `SYNC`: Only `Connectors` with permission-sync support can be set to SYNC. The `Connector` will sync access permissions with the source system.

    ```python Python theme={null}
    class AccessType(str, Enum):
      PUBLIC = "public"
      PRIVATE = "private"
      SYNC = "sync"
    ```
  </Accordion>

  <Accordion title="InputType" icon="gear">
    `InputType` defines how a `Connector` retrieves data from its source system.

    * `LOAD_STATE`: Single load of data from the source
    * `POLL`: Continuous polling for new data from the source (starts with a full load)
    * `EVENT`: Not implemented for most `Connectors`
    * `SLIM_RETRIEVAL`: For permission-syncing `Connectors`

    ```python Python theme={null}
    class InputType(str, Enum):
      LOAD_STATE = "load_state"
      POLL = "poll"
      EVENT = "event"
      SLIM_RETRIEVAL = "slim_retrieval"
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Guide: Index files with the Ingestion API" icon="lightbulb" href="/developers/guides/index_files_ingestion_api">
    Learn how to index files with the Ingestion API
  </Card>

  <Card title="Guide: Send a Chat Message" icon="comment" href="/developers/guides/chat_new_guide">
    Simple example of sending a message programmatically
  </Card>
</CardGroup>


# Send a Message to Onyx
Source: https://docs.onyx.app/developers/guides/chat_new_guide

Sending messages programmatically to Onyx

<Note>
  `/chat/send-message` and `/chat/send-message-simple-api` have been removed. Use this API instead.
</Note>

The `/chat/send-chat-message` API is used to send a message to Onyx.
It is the same API that the Onyx frontend uses to send and receive messages.
You have the option of receiving a streaming response or the complete response as a string.

This guide was explain all of the parameters you can pass in to the API and provide a code sample.

## Request Parameters

| Parameter            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`            | The user message to send to the Agent.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `llm_override`       | Pass an object to override the default LLM settings for this request. If `None`, you will get the default Onyx behavior. <br /><br />You can pass or exclude any of the following fields: <br />• `model_provider` <br />• `model_version` <br />• `temperature` <br /><br />If you pass an invalid configuration (e.g., specifying `claude-sonnet-4.5` when the default `model_provider` is OpenAI), your request will fail.                           |
| `allowed_tool_ids`   | Agents are created with a set of Actions they are allowed to invoke. You can further configure this set for your immediate interaction using this parameter. See the list of Actions and their IDs via the [GET /tool](/developers/api_reference/actions/list_tools) endpoint. Pass in an empty list to disable all Actions. Pass in `None` to allow all the Actions which are configured for the Agent.                                                |
| `forced_tool_id`     | Force the Agent to use a specific Action for this request. The Agent may run other Actions before returning its final response, but it will be guaranteed to use this one. Leave empty to let the Agent decide which Actions to use.                                                                                                                                                                                                                    |
| `file_descriptors`   | A list of files to include along with your request. File IDs can be found via the [POST /user/projects/file/upload](/developers/api_reference/projects/upload_user_files) and the [GET /user/projects/file/](/developers/api_reference/projects/get_user_file) endpoints.                                                                                                                                                                               |
| `search_filters`     | Filters to narrow down the internal search results used by the Agent. All filter arguments are optional and can be combined: <br /><br />• `source_type` – Source types like `web`, `slack`, `google_drive`, `confluence` <br />• `document_set` – The name of the document sets to search within <br />• `time_cutoff` – ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` <br />• `tags` – Format: `{"tag_key": "tag_value"}`                                   |
| `deep_research`      | Enables Deep Research mode for this request. <br /><br />**Note:** This mode consumes significantly more tokens, so be careful accessing it via the API.                                                                                                                                                                                                                                                                                                |
| `parent_message_id`  | The ID of the parent message in the chat history (primary-key for the previous message in the chat history tree). If not passed in, your new message is assumed to be sequentially after the last message. <br /><br />**Warning:** If set to `None`, the chat history is reset and the new message is considered the first message in the chat history.                                                                                                |
| `chat_session_id`    | To continue an existing conversation, pass in the chat session ID where the message should be sent. If left blank, a new chat session will be created according to `chat_session_info`.                                                                                                                                                                                                                                                                 |
| `chat_session_info`  | Details about the chat session which will be used for all messages in the session. Fields can be left blank to use defaults. <br /><br />• `persona_id` – The ID of the Agent to use for the chat session <br />• `project_id` – ID of a Project if the chat should be scoped to a Project                                                                                                                                                              |
| `stream`             | If true, responds with an SSE stream of individual packets (same set used for the Onyx UI). Fields like the Answer, reasoning tokens, and iterative Tool Calls need to be pieced together from streamed tokens.                                                                                                                                                                                                                                         |
| `include_citations`  | If true, responses will include citations for the sources used to generate the answer.                                                                                                                                                                                                                                                                                                                                                                  |
| `additional_context` | A string of extra context injected into the LLM call for this request. The context is passed to the model but is **not stored in the database** and will not appear in chat history.<br />Use this to supply ephemeral, request-scoped information (e.g. the user's current page URL, session metadata, or any runtime context) without polluting the persistent conversation history.<br />Pass `null` or omit the field to use no additional context. |

## Response Format

### Streaming Response

Onyx returns various types of packets in the streaming response depending on the LLM's behavior.

See our
[streaming\_models.py](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/streaming_models.py)
on GitHub for the complete list of packet types and their corresponding fields.

```python expandable theme={null}
class StreamingType(Enum):
    """Enum defining all streaming packet types."""

    SECTION_END = "section_end"
    STOP = "stop"
    TOP_LEVEL_BRANCHING = "top_level_branching"
    ERROR = "error"

    MESSAGE_START = "message_start"
    MESSAGE_DELTA = "message_delta"
    SEARCH_TOOL_START = "search_tool_start"
    SEARCH_TOOL_QUERIES_DELTA = "search_tool_queries_delta"
    SEARCH_TOOL_DOCUMENTS_DELTA = "search_tool_documents_delta"
    OPEN_URL_START = "open_url_start"
    OPEN_URL_URLS = "open_url_urls"
    OPEN_URL_DOCUMENTS = "open_url_documents"
    IMAGE_GENERATION_START = "image_generation_start"
    IMAGE_GENERATION_HEARTBEAT = "image_generation_heartbeat"
    IMAGE_GENERATION_FINAL = "image_generation_final"
    PYTHON_TOOL_START = "python_tool_start"
    PYTHON_TOOL_DELTA = "python_tool_delta"
    CUSTOM_TOOL_START = "custom_tool_start"
    CUSTOM_TOOL_DELTA = "custom_tool_delta"
    REASONING_START = "reasoning_start"
    REASONING_DELTA = "reasoning_delta"
    REASONING_DONE = "reasoning_done"
    CITATION_INFO = "citation_info"

    DEEP_RESEARCH_PLAN_START = "deep_research_plan_start"
    DEEP_RESEARCH_PLAN_DELTA = "deep_research_plan_delta"
    RESEARCH_AGENT_START = "research_agent_start"
    INTERMEDIATE_REPORT_START = "intermediate_report_start"
    INTERMEDIATE_REPORT_DELTA = "intermediate_report_delta"
    INTERMEDIATE_REPORT_CITED_DOCS = "intermediate_report_cited_docs"
```

### Non-streaming Response

```python theme={null}
class ChatFullResponse(BaseModel):
    """Complete non-streaming response with all available data."""

    # Core response fields
    answer: str
    answer_citationless: str
    pre_answer_reasoning: str | None = None
    tool_calls: list[ToolCallResponse] = []

    # Documents & citations
    top_documents: list[SearchDoc]
    citation_info: list[CitationInfo]

    # Metadata
    message_id: int
    chat_session_id: UUID | None = None
    error_msg: str | None = None
```

## Sample Request

<CodeGroup>
  ```python Python expandable theme={null}
  import requests

  API_BASE_URL = "https://cloud.onyx.app/api"  # or your own domain
  API_KEY = "YOUR_KEY_HERE"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  response = requests.post(
      f"{API_BASE_URL}/chat/send-chat-message",
      headers=headers,
      json={
          "message": "What is Onyx?",
      }
  )

  data = response.json()
  print("Answer:", data["answer"])
  print("Message ID:", data["message_id"])
  ```

  ```bash Shell expandable theme={null}
  #!/bin/bash

  API_BASE_URL="https://cloud.onyx.app/api"  # or your own domain
  API_KEY="YOUR_KEY_HERE"

  RESPONSE=$(curl -s -X POST "${API_BASE_URL}/chat/send-chat-message" \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "What is Onyx?"
    }'
  )

  echo "Answer:" $(echo "$RESPONSE" | jq -r '.answer')
  echo "Message ID:" $(echo "$RESPONSE" | jq -r '.message_id')
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Guide: Use the Ingestion API" icon="upload" href="/developers/guides/index_files_ingestion_api">
    Use the lightweight ingestion API to index documents
  </Card>

  <Card title="Guide: Create a Connector" icon="link" href="/developers/guides/create_connector">
    Learn how to create and configure Connectors programmatically
  </Card>
</CardGroup>


# Create Connectors
Source: https://docs.onyx.app/developers/guides/create_connector

Learn how to create and configure connectors programmatically

<Tip>
  This is an advanced guide for automating connector creation.
  We highly recommend trying the Admin Panel or File Ingestion API first.
</Tip>

To see available connectors, see the [Connectors page](/admins/connectors).

## Guide

Skip to the [Full Code](#full-code) section if you don't want the step-by-step guide.

In this example, we'll automate creating Jira Connectors for a selection of projects.

**You will need an API key that can manage connectors.** Its service account must be in the Admin group,
or in a group granting **Manage Connectors & Document Sets**.
Every request in this guide is gated on `manage:connectors`.
See [Understanding Permissions](/admins/permissions/understanding_permissions).

<Steps>
  <Step title="Prepare your request">
    <CodeGroup>
      ```python Python theme={null}
      import requests

      API_BASE_URL = "https://cloud.onyx.app/api"   # or your own domain
      API_KEY = "YOUR_KEY_HERE"

      headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
      }
      ```

      ```bash Shell theme={null}
      API_BASE_URL="https://cloud.onyx.app/api"
      API_KEY="YOUR_KEY_HERE"
      ```
    </CodeGroup>
  </Step>

  <Step title="Prepare your ConnectorSpecificConfig">
    Each Connector type has a different `ConnectorSpecificConfig`. To find the correct configuration,
    find your relevant Connector in
    [`backend/onyx/connectors/`](https://github.com/onyx-dot-app/onyx/tree/main/backend/onyx/connectors).

    For Jira, since we're indexing a selection of projects, rather than all projects,
    we'll need to specify `jira_base_url`, `project_key`, and optionally `comment_email_blacklist`.

    ```json JSON theme={null}
    {
      "jira_base_url": "string",
      "project_key": "string | null",
      "comment_email_blacklist": ["string"] | null
    }
    ```

    <Note>
      The `ConnectorSpecificConfig` are the same fields you fill out in the Admin Panel when creating a Connector.
    </Note>
  </Step>

  <Step title="Prepare your Connector payload">
    In addition to the `ConnectorSpecificConfig`,
    we also need to satisfy the schema for the `ConnectorUpdateRequest` object. See [Core Concepts:
    Connectors](/developers/core_concepts#connectors) for more details.

    In this example, we'll set the `access_type`, `name`, `source`, `input_type`, `refresh_freq`, and `prune_freq`.

    <CodeGroup>
      ```python Python theme={null}
      connector_payload = {
        "name": f"jira-{project_key}",
        "source": "jira",
        "input_type": "poll",
        "access_type": "PUBLIC",
        "connector_specific_config": {
          "jira_base_url": JIRA_BASE_URL,
          "project_key": project_key,
          "comment_email_blacklist": ["legal@company.com"]
        },
        "refresh_freq": 3600,  # Refresh every hour (3600 seconds)
        "prune_freq": 86400,   # Prune every day (86400 seconds)
      }
      ```

      ```json JSON theme={null}
      {
        "name": "jira-TECH",
        "source": "jira",
        "input_type": "poll",
        "access_type": "PUBLIC",
        "connector_specific_config": {
          "jira_base_url": "https://your-company.atlassian.net",
          "project_key": "TECH",
          "comment_email_blacklist": ["legal@company.com"]
        },
        "refresh_freq": 3600,
        "prune_freq": 86400
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Make the request">
    <Tip>
      Save the Connector ID from the response! You will need this later.
    </Tip>

    <CodeGroup>
      ```python Python expandable theme={null}
      import requests
      import json
      from datetime import datetime

      PROJECTS_TO_INDEX = [
        "TECH",
        "SALES",
        "OPS",
      ]

      JIRA_BASE_URL = "https://your-company.atlassian.net"
      connector_ids = []

      for project_key in PROJECTS_TO_INDEX:
        connector_payload = {
          "name": f"jira-{project_key}",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": JIRA_BASE_URL,
            "project_key": project_key,
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,  # Refresh every hour (3600 seconds)
          "prune_freq": 86400,   # Prune every day (86400 seconds)
        }

        response = requests.post(
          f"{API_BASE_URL}/manage/admin/connector",
          headers=headers,
          json=connector_payload
        )

        if response.status_code == 200:
          connector_data = response.json()
          connector_id = connector_data.get('id')
          connector_ids.append(connector_id)
          print(f"Successfully created connector for project {project_key}")
          print(f"Connector ID: {connector_id}")
        else:
          print(f"Failed to create connector for project {project_key}")
          print(f"Status: {response.status_code}")
          print(f"Error: {response.text}")
      ```

      ```bash Shell expandable theme={null}
      # Create connector for TECH project
      curl -X POST "${API_BASE_URL}/manage/admin/connector" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "jira-TECH",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": "https://your-company.atlassian.net",
            "project_key": "TECH",
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,
          "prune_freq": 86400
        }'

      # Create connector for SALES project
      curl -X POST "${API_BASE_URL}/manage/admin/connector" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "jira-SALES",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": "https://your-company.atlassian.net",
            "project_key": "SALES",
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,
          "prune_freq": 86400
        }'

      # Create connector for OPS project
      curl -X POST "${API_BASE_URL}/manage/admin/connector" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "jira-OPS",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": "https://your-company.atlassian.net",
            "project_key": "OPS",
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,
          "prune_freq": 86400
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Find your Credentials for the Connector">
    The easiest way to create a Credential is in the Admin Panel.

    * Click Add a Connector
    * Select your relevant Connector
    * Follow the instructions to create a Credential

    Once your Credential is created, the Credential ID will be displayed to you.

    Certain Connectors may not require a Credential such as the File and Web connectors. `credential_id:
            0` is a default empty Credential you can use for these Connectors.

    To list your Credentials, you can use the `GET manage/admin/credential` endpoint.

    <CodeGroup>
      ```python Python theme={null}
      response = requests.get(
        f"{API_BASE_URL}/manage/admin/credential",
        headers=headers
      )

      credentials = response.json()
      jira_credential_id = next(cred for cred in credentials if cred['source'] == 'jira')['id']
      ```

      ```bash Shell theme={null}
      curl -X GET "${API_BASE_URL}/manage/admin/credential" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json"
      ```
    </CodeGroup>
  </Step>

  <Step title="Associate the Credential with the Connector">
    <Note>
      If you do not do this step, your `Connector` is not fully created and you will not see it in the Admin Panel!
    </Note>

    <CodeGroup>
      ```python Python theme={null}
      for connector_id in connector_ids:
        try:
          response = requests.put(
            f"{API_BASE_URL}/manage/admin/connector/{connector_id}/credential/{jira_credential_id}",
            headers=headers,
          )

          if response.status_code == 200:
            print(f"Successfully associated credential with connector {connector_id}")
          else:
            print(f"Failed to associate credential with connector {connector_id}")
            print(f"Status: {response.status_code}. Error: {response.text}")
        except Exception as e:
          print(f"Failed to associate credential with connector {connector_id}: {e}")
      ```

      ```bash Shell theme={null}
      # Replace CONNECTOR_ID and CREDENTIAL_ID with actual values
      curl -X PUT "${API_BASE_URL}/manage/admin/connector/CONNECTOR_ID/credential/CREDENTIAL_ID" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json"
      ```
    </CodeGroup>
  </Step>
</Steps>

## Full Code

<CodeGroup>
  ```python Python expandable theme={null}
  import requests
  import json
  from datetime import datetime

  # Configuration
  API_BASE_URL = "https://cloud.onyx.app/api"   # or your own domain
  API_KEY = "YOUR_KEY_HERE"

  headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
  }

  # Projects to create connectors for
  PROJECTS_TO_INDEX = [
    "TECH",
    "SALES",
    "OPS",
  ]

  JIRA_BASE_URL = "https://your-company.atlassian.net"
  connector_ids = []

  # Step 1: Create connectors for each project
  print("Creating connectors...")
  for project_key in PROJECTS_TO_INDEX:
    connector_payload = {
      "name": f"jira-{project_key}",
      "source": "jira",
      "input_type": "poll",
      "access_type": "PUBLIC",
      "connector_specific_config": {
        "jira_base_url": JIRA_BASE_URL,
        "project_key": project_key,
        "comment_email_blacklist": ["legal@company.com"]
      },
      "refresh_freq": 3600,  # Refresh every hour (3600 seconds)
      "prune_freq": 86400,   # Prune every day (86400 seconds)
    }

    response = requests.post(
      f"{API_BASE_URL}/manage/admin/connector",
      headers=headers,
      json=connector_payload
    )

    if response.status_code == 200:
      connector_data = response.json()
      connector_id = connector_data.get('id')
      connector_ids.append(connector_id)
      print(f"Successfully created connector for project {project_key}")
      print(f"Connector ID: {connector_id}")
    else:
      print(f"Failed to create connector for project {project_key}")
      print(f"Status: {response.status_code}")
      print(f"Error: {response.text}")

  # Step 2: Get credentials
  print("\nFetching credentials...")
  response = requests.get(
    f"{API_BASE_URL}/manage/admin/credential",
    headers=headers
  )

  if response.status_code == 200:
    credentials = response.json()
    # Find Jira credential (assumes you have one created)
    jira_credential = next((cred for cred in credentials if cred['source'] == 'jira'), None)

    if jira_credential:
      jira_credential_id = jira_credential['id']
      print(f"Found Jira credential with ID: {jira_credential_id}")
    else:
      print("No Jira credential found. Please create one in the Admin Panel first.")
      exit(1)
  else:
    print(f"Failed to fetch credentials: {response.status_code}")
    print(f"Error: {response.text}")
    exit(1)

  # Step 3: Associate credentials with connectors
  print("\nAssociating credentials with connectors...")
  for connector_id in connector_ids:
    try:
      response = requests.put(
        f"{API_BASE_URL}/manage/admin/connector/{connector_id}/credential/{jira_credential_id}",
        headers=headers,
      )

      if response.status_code == 200:
        print(f"Successfully associated credential with connector {connector_id}")
      else:
        print(f"Failed to associate credential with connector {connector_id}")
        print(f"Status: {response.status_code}. Error: {response.text}")
    except Exception as e:
      print(f"Failed to associate credential with connector {connector_id}: {e}")

  print(f"\nCompleted! Created {len(connector_ids)} connectors with IDs: {connector_ids}")
  ```

  ```bash Shell expandable theme={null}
  #!/bin/bash

  # Configuration
  API_BASE_URL="https://cloud.onyx.app/api"
  API_KEY="YOUR_KEY_HERE"

  # Array of projects to create connectors for
  PROJECTS=("TECH" "SALES" "OPS")
  JIRA_BASE_URL="https://your-company.atlassian.net"

  # Array to store connector IDs
  CONNECTOR_IDS=()

  echo "Creating connectors..."

  # Step 1: Create connectors for each project
  for PROJECT in "${PROJECTS[@]}"; do
    echo "Creating connector for project: $PROJECT"

    RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "${API_BASE_URL}/manage/admin/connector" \
      -H "Authorization: Bearer ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d "{
        \"name\": \"jira-${PROJECT}\",
        \"source\": \"jira\",
        \"input_type\": \"poll\",
        \"access_type\": \"PUBLIC\",
        \"connector_specific_config\": {
          \"jira_base_url\": \"${JIRA_BASE_URL}\",
          \"project_key\": \"${PROJECT}\",
          \"comment_email_blacklist\": [\"legal@company.com\"]
        },
        \"refresh_freq\": 3600,
        \"prune_freq\": 86400
      }"
    )

    HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
    BODY=$(echo "$RESPONSE" | head -n -1)

    if [ "$HTTP_CODE" -eq 200 ]; then
      CONNECTOR_ID=$(echo "$BODY" | jq -r '.id')
      CONNECTOR_IDS+=("$CONNECTOR_ID")
      echo "Successfully created connector for project $PROJECT"
      echo "Connector ID: $CONNECTOR_ID"
    else
      echo "Failed to create connector for project $PROJECT"
      echo "Status: $HTTP_CODE"
      echo "Error: $BODY"
    fi
  done

  # Step 2: Get credentials
  echo -e "\nFetching credentials..."
  CRED_RESPONSE=$(curl -s -w "\n%{http_code}" -X GET "${API_BASE_URL}/manage/admin/credential" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json")

  CRED_HTTP_CODE=$(echo "$CRED_RESPONSE" | tail -n1)
  CRED_BODY=$(echo "$CRED_RESPONSE" | head -n -1)

  if [ "$CRED_HTTP_CODE" -eq 200 ]; then
    JIRA_CREDENTIAL_ID=$(echo "$CRED_BODY" | jq -r '.[] | select(.source == "jira") | .id' | head -n1)

    if [ "$JIRA_CREDENTIAL_ID" != "null" ] && [ -n "$JIRA_CREDENTIAL_ID" ]; then
      echo "Found Jira credential with ID: $JIRA_CREDENTIAL_ID"
    else
      echo "No Jira credential found. Please create one in the Admin Panel first."
      exit 1
    fi
  else
    echo "Failed to fetch credentials: $CRED_HTTP_CODE"
    echo "Error: $CRED_BODY"
    exit 1
  fi

  # Step 3: Associate credentials with connectors
  echo -e "\nAssociating credentials with connectors..."
  for CONNECTOR_ID in "${CONNECTOR_IDS[@]}"; do
    echo "Associating credential with connector: $CONNECTOR_ID"

    ASSOC_RESPONSE=$(curl -s -w "\n%{http_code}" -X PUT "${API_BASE_URL}/manage/admin/connector/${CONNECTOR_ID}/credential/${JIRA_CREDENTIAL_ID}" \
      -H "Authorization: Bearer ${API_KEY}" \
      -H "Content-Type: application/json")

    ASSOC_HTTP_CODE=$(echo "$ASSOC_RESPONSE" | tail -n1)
    ASSOC_BODY=$(echo "$ASSOC_RESPONSE" | head -n -1)

    if [ "$ASSOC_HTTP_CODE" -eq 200 ]; then
      echo "Successfully associated credential with connector $CONNECTOR_ID"
    else
      echo "Failed to associate credential with connector $CONNECTOR_ID"
      echo "Status: $ASSOC_HTTP_CODE"
      echo "Error: $ASSOC_BODY"
    fi
  done

  echo -e "\nCompleted! Created ${#CONNECTOR_IDS[@]} connectors with IDs: ${CONNECTOR_IDS[*]}"
  ```
</CodeGroup>


# Index Files with the Ingestion API
Source: https://docs.onyx.app/developers/guides/index_files_ingestion_api

Learn how to programmatically index documents using Onyx's ingestion API

<Tip>
  The ingestion API is a lightweight way to index documents. If you need more control,
  consider creating a Connector in the Admin Panel or following the [Create a
  Connector](/developers/guides/create_connector) API guide.
</Tip>

## When to use the Ingestion API?

Use the Ingestion API for:

* **Unsupported sources**: Add content from systems that don't have built-in Connectors
* **Supplemental data**: Add extra context to existing Connector data (like README files for GitLab)
* **Editing documents**: Modify documents in Onyx when the Admin cannot update the original document
  in the source
* **Programmatic workflows**: Integrate document indexing into your existing data pipelines

## Guide

Skip to the [Full Code](#full-code) section if you don't want the step-by-step guide.

In this example, we'll index local files with the Ingestion API.

<Note>
  The Ingestion API base URL is `https://cloud.onyx.app/api/onyx-api/ingestion` or your own domain.
</Note>

<Info>
  **Required permission:** Manage Connectors & Document Sets (`manage:connectors`), or Admin (`admin`).
  A **Group Manager** can ingest into connector-credential pairs in the groups they manage,
  but not into the default pair, which is public.
</Info>

<Steps>
  <Step title="Prepare your Connector">
    Since we want these files to appear in the Connectors page, we'll need to first create a Connector.
    For this example, we'll create a File Connector with a dummy text file.

    If you already have a Connector you would like to associate your Ingestion files with,
    click on the Connector and copy the `cc_pair_id` from the URL.

    `https://cloud.onyx.app/admin/connector/308` -> `cc_pair_id` is `243`
  </Step>

  <Step title="Prepare your request">
    <CodeGroup>
      ```python Python theme={null}
      import requests

      API_BASE_URL = "https://cloud.onyx.app/api" # or your own domain
      API_KEY = "YOUR_KEY_HERE"

      headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
      }
      ```

      ```bash Shell theme={null}
      # Set your API configuration
      API_BASE_URL="https://cloud.onyx.app/api"
      API_KEY="YOUR_KEY_HERE"
      ```
    </CodeGroup>
  </Step>

  <Step title="Process your documents into the proper JSON object">
    <Tip>
      If you want your documents to show up in the Connectors page, you must specify a `cc_pair_id` in the payload!
    </Tip>

    See [Core Concepts: Documents](/developers/core_concepts#documents) for details on the `IngestionDocument` object.

    <AccordionGroup>
      <Accordion title="Minimum valid payload">
        ```json JSON theme={null}
        {
          "document": {
            "id": "my_unique_id_1",
            "semantic_identifier": "Onyx FAQ v1",
            "sections": [
              { "text": "What is Onyx?\nOnyx is..." }
            ],
            "source": "file",
            "metadata": {
              "category": "faq"
            }
          },
          "cc_pair_id": 243
        }
        ```
      </Accordion>

      <Accordion title="Full payload with all optional fields">
        <CodeGroup>
          ```json JSON theme={null}
          {
            "document": {
              "id": "my_unique_id_1",
              "semantic_identifier": "Onyx FAQ - Title shown in UI",
              "title": "Onyx FAQ v1 - Title for Search",
              "sections": [
                {
                  "text": "What is Onyx?\nOnyx is...",
                  "link": "https://docs.onyx.app/faq#what-is-onyx"
                },
                {
                  "text": "How do I get started?\nTo get started...",
                  "link": "https://docs.onyx.app/faq#getting-started"
                },
                {
                  "image_file_id": "uuid_generated_by_onyx_file_store",
                  "text": "Advanced - Must upload image first! POST /user/file/upload",
                  "link": "https://docs.onyx.app/faq#about"
                }
              ],
              "source": "file",
              "metadata": {
                "category": "faq",
                "tags": ["frequently-asked", "help"]
              },
              "doc_updated_at": "2025-09-19T08:20:00Z",
              "chunk_count": 15,
              "primary_owners": [
                {
                  "display_name": "Alex Chen",
                  "first_name": "Alex",
                  "middle_initial": null,
                  "last_name": "Chen",
                  "email": "alex@onyx.app"
                }
              ],
              "secondary_owners": [
                {
                  "display_name": "Sarah Johnson",
                  "first_name": "Sarah",
                  "middle_initial": "M",
                  "last_name": "Johnson",
                  "email": "sarah@onyx.app"
                }
              ],
              "from_ingestion_api": true
            },
            "cc_pair_id": 243
          }
          ```
        </CodeGroup>
      </Accordion>
    </AccordionGroup>

    <CodeGroup>
      ```python Python expandable theme={null}
      import os
      from pathlib import Path
      import PyPDF2
      import pandas as pd
      from docx import Document as DocxDocument

      def read_files_from_folder(folder_path, cc_pair_id=243):
        """
        Read PDF, TXT, DOCX, CSV, and XLSX files and create minimal ingestion payloads
        """
        documents = []
        folder = Path(folder_path)

        # Supported file extensions
        supported_extensions = {'.pdf', '.txt', '.docx', '.csv', '.xlsx'}

        for file_path in folder.rglob('*'):
          if file_path.is_file() and file_path.suffix.lower() in supported_extensions:
            try:
              # Extract text based on file type
              if file_path.suffix.lower() == '.txt':
                with open(file_path, 'r', encoding='utf-8') as f:
                  content = f.read()

              elif file_path.suffix.lower() == '.pdf':
                with open(file_path, 'rb') as f:
                  reader = PyPDF2.PdfReader(f)
                  content = ""
                  for page in reader.pages:
                    content += page.extract_text() + "\n"

              elif file_path.suffix.lower() == '.docx':
                doc = DocxDocument(file_path)
                content = "\n".join([paragraph.text for paragraph in doc.paragraphs])

              elif file_path.suffix.lower() in ['.csv', '.xlsx']:
                df = pd.read_csv(file_path) if file_path.suffix.lower() == '.csv' else pd.read_excel(file_path)
                content = df.to_string(index=False)

              # Skip empty files
              if not content.strip():
                continue

              # Create minimal viable payload
              document_payload = {
                "document": {
                  "semantic_identifier": file_path.name,
                  "sections": [
                    {"text": content}
                  ],
                  "source": "file",
                  "metadata": {
                    "file_type": file_path.suffix.lower()
                  }
                },
                "cc_pair_id": cc_pair_id
              }

              documents.append(document_payload)
              print(f"Processed: {file_path.name}")

            except Exception as e:
              print(f"Error reading {file_path.name}: {e}")
              continue

        return documents

      # Example usage
      LOCAL_FOLDER = "./documents"  # Change to your folder path
      CC_PAIR_ID = 243  # Use your actual cc_pair_id

      # Read and process files
      documents_to_ingest = read_files_from_folder(LOCAL_FOLDER, CC_PAIR_ID)
      print(f"\nFound {len(documents_to_ingest)} documents ready for ingestion")
      ```

      ```bash Shell theme={null}
      # Create the JSON payload
      cat > document_payload.json << 'EOF'
      {
        "document": {
          "id": "ingestion_document_1",
          "sections": [
            {
              "text": "This is the contents of the document that will be processed and saved into the Onyx filestore and Vespa index.",
              "link": "https://docs.onyx.app/introduction#what-is-onyx"
            },
            {
              "text": "You can include multiple content sections each with their own link or combine them.",
              "link": "https://docs.onyx.app/introduction#main-features"
            }
          ],
          "source": "file",
          "semantic_identifier": "Onyx Ingestion Example",
          "metadata": {
            "tag": "informational",
            "topics": ["onyx", "api"]
          },
          "doc_updated_at": "2025-09-19T08:20:00Z"
        },
        "cc_pair_id": 243
      }
      EOF
      ```
    </CodeGroup>
  </Step>

  <Step title="Make the request to the /ingestion endpoint">
    <CodeGroup>
      ```python Python theme={null}
      successful_ingestions = 0
      failed_ingestions = 0

      for i, document_data in enumerate(documents_to_ingest):
        print(f"Ingesting document {i+1}/{len(documents_to_ingest)}: {document_data['document']['semantic_identifier']}")

        response = requests.post(
          f"{API_BASE_URL}/onyx-api/ingestion",
          headers=headers,
          json=document_data
        )

        if response.status_code == 200:
          print(f"Successfully ingested: {document_data['document']['semantic_identifier']}")
          successful_ingestions += 1
        else:
          print(f"Failed to ingest {document_data['document']['semantic_identifier']}: {response.status_code}")
          print(f"   Error: {response.text}")
          failed_ingestions += 1

      print(f"\nIngestion complete: {successful_ingestions} successful, {failed_ingestions} failed")
      ```

      ```bash Shell theme={null}
      curl --location "${API_BASE_URL}/onyx-api/ingestion" \
      --header 'Content-Type: application/json' \
      --header "Authorization: Bearer ${API_KEY}" \
      --data @document_payload.json
      ```
    </CodeGroup>
  </Step>
</Steps>

<Tip>
  The API will return a success response if the document is accepted for processing.
  The actual indexing happens asynchronously.
</Tip>

### Full Code

```python Python expandable theme={null}
import requests
import os
from pathlib import Path
import time
import PyPDF2
import pandas as pd
from docx import Document as DocxDocument

API_BASE_URL = "https://cloud.onyx.app/api"  # or your own domain
API_KEY = "YOUR_KEY_HERE"
CC_PAIR_ID = 243  # Replace with your actual cc_pair_id
LOCAL_FOLDER = "./documents"  # Change this to your folder path

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def read_files_from_folder(folder_path, cc_pair_id=243):
    """
    Read PDF, TXT, DOCX, CSV, and XLSX files and create minimal ingestion payloads
    """
    documents = []
    folder = Path(folder_path)

    if not folder.exists():
        print(f"Folder does not exist: {folder_path}")
        return documents

    supported_extensions = {'.pdf', '.txt', '.docx', '.csv', '.xlsx'}

    print(f"Reading files from: {folder.absolute()}")

    for file_path in folder.rglob('*'):
        if file_path.is_file() and file_path.suffix.lower() in supported_extensions:
            try:
                # Extract text based on file type
                if file_path.suffix.lower() == '.txt':
                    with open(file_path, 'r', encoding='utf-8') as f:
                        content = f.read()

                elif file_path.suffix.lower() == '.pdf':
                    with open(file_path, 'rb') as f:
                        reader = PyPDF2.PdfReader(f)
                        content = ""
                        for page in reader.pages:
                            content += page.extract_text() + "\n"

                elif file_path.suffix.lower() == '.docx':
                    doc = DocxDocument(file_path)
                    content = "\n".join([paragraph.text for paragraph in doc.paragraphs])

                elif file_path.suffix.lower() in ['.csv', '.xlsx']:
                    df = pd.read_csv(file_path) if file_path.suffix.lower() == '.csv' else pd.read_excel(file_path)
                    content = df.to_string(index=False)

                # Skip empty files
                if not content.strip():
                    print(f"Skipping empty file: {file_path.name}")
                    continue

                # Create minimal viable payload
                document_payload = {
                    "document": {
                        "semantic_identifier": file_path.name,
                        "sections": [
                            {"text": content}
                        ],
                        "source": "file",
                        "metadata": {
                            "file_type": file_path.suffix.lower()
                        }
                    },
                    "cc_pair_id": cc_pair_id
                }

                documents.append(document_payload)
                print(f"Processed: {file_path.name}")

            except Exception as e:
                print(f"Error reading {file_path.name}: {e}")
                continue
    return documents

# Read all documents from folder
print("Starting file ingestion process...")
documents_to_ingest = read_files_from_folder(LOCAL_FOLDER, CC_PAIR_ID)

if not documents_to_ingest:
    print("No documents found to ingest. Check your folder path and file types.")
    exit(1)

print(f"Found {len(documents_to_ingest)} documents to ingest")

# Make the ingestion requests for all documents
successful_ingestions = 0
failed_ingestions = 0

print("\nStarting ingestion...")
for i, document_data in enumerate(documents_to_ingest):
    print(f"[{i+1}/{len(documents_to_ingest)}] Ingesting: {document_data['document']['semantic_identifier']}")

    response = requests.post(
        f"{API_BASE_URL}/onyx-api/ingestion",
        headers=headers,
        json=document_data
    )

    if response.status_code == 200:
        result = response.json()
        print(f"Success: {document_data['document']['semantic_identifier']}")
        if result.get('already_existed'):
            print("   Document was updated (already existed)")
        else:
            print("   New document created")
        successful_ingestions += 1
    else:
        print(f"Failed: {document_data['document']['semantic_identifier']}")
        print(f"   Status: {response.status_code}")
        print(f"   Error: {response.text}")
        failed_ingestions += 1

print(f"\nIngestion Summary:")
print(f"   Successful: {successful_ingestions}")
print(f"   Failed: {failed_ingestions}")
print(f"   Total: {len(documents_to_ingest)}")
```

### Extra Example

This script crawls a specified directory for JSON files and sends the contents to the Ingestion API.

```python Python expandable theme={null}
#!/usr/bin/env python3
"""
Ingestion Script
"""

import argparse
import json
import logging
import sys
from pathlib import Path
from typing import Any, List, Optional

import requests
from requests.exceptions import RequestException
from tqdm import tqdm  # type: ignore

def setup_logging() -> None:
    """Configure logging for the application."""
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        handlers=[logging.StreamHandler()],
    )

def parse_arguments() -> argparse.Namespace:
    """Parse command line arguments."""
    parser = argparse.ArgumentParser(
        description="Crawl a directory for JSON files and send them to an API endpoint."
    )
    parser.add_argument(
        "-d", "--directory",
        required=True,
        type=str,
        help="Directory to crawl for JSON files"
    )
    parser.add_argument(
        "-t", "--tracking-file",
        required=True,
        type=str,
        help="File to track processed document IDs (one per line)"
    )
    parser.add_argument(
        "-u", "--url",
        type=str,
        help="API endpoint URL to send JSON data to",
        default="http://localhost:8080/api"
    )
    parser.add_argument(
        "--headers",
        type=str,
        help="JSON string of headers to include in the request"
    )
    parser.add_argument(
        "--timeout",
        type=int,
        default=30,
        help="Request timeout in seconds (default: 30)"
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Don't actually send requests, just print what would be sent"
    )
    parser.add_argument(
        "--cc-pair-id",
        type=int,
        help="Connector credential pair ID to associate the documents with"
    )

    return parser.parse_args()

def find_json_files(directory: str) -> List[Path]:
    """
    Find all JSON files in the specified directory and its subdirectories.

    Args:
        directory: The directory to search in

    Returns:
        A list of Path objects for all JSON files found
    """
    directory_path = Path(directory)
    if not directory_path.exists() or not directory_path.is_dir():
        raise ValueError(f"The specified path '{directory}' is not a valid directory")

    json_files = list(directory_path.glob("**/*.json"))
    return json_files

def load_processed_ids(tracking_file: str) -> set:
    """
    Load already processed document IDs from the tracking file.

    Args:
        tracking_file: Path to the tracking file

    Returns:
        A set of document IDs that have already been processed
    """
    tracking_path = Path(tracking_file)

    if not tracking_path.exists():
        print(f"Tracking file '{tracking_file}' not found. Creating new file.")
        tracking_path.parent.mkdir(parents=True, exist_ok=True)
        tracking_path.touch()
        return set()

    try:
        with open(tracking_path, "r", encoding="utf-8") as f:
            processed_ids = {line.strip() for line in f if line.strip()}
        return processed_ids
    except Exception as e:
        logging.getLogger(__name__).warning(f"Error reading tracking file: {e}. Starting with empty set.")
        return set()

def save_processed_id(tracking_file: str, document_id: str) -> None:
    """
    Save a processed document ID to the tracking file.

    Args:
        tracking_file: Path to the tracking file
        document_id: The document ID to save
    """
    try:
        with open(tracking_file, "a", encoding="utf-8") as f:
            f.write(f"{document_id}\n")
    except Exception as e:
        logging.getLogger(__name__).error(f"Error saving document ID to tracking file: {e}")

def transform_json_to_document_format(file_path: Path, cc_pair_id: int | None = None) -> dict:
    """
    Transform a JSON file into the document format required by the API.

    Args:
        file_path: Path to the JSON file
        cc_pair_id: Optional connector credential pair ID

    Returns:
        A dictionary in the required document format
    """
    logger = logging.getLogger(__name__)

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            data = json.load(f)

        # Create the document structure
        document: dict[str, Any] = {
            "document": {
                "id": data["id"],
                "sections": [
                    {
                        "text": data["page_content"],
                        "link": data["source"]
                    }
                ],
                "semantic_identifier": data["title"],
                "metadata": {
                    "tags": data["metadata"]["tags"]
                },
                "source": "web"
            }
        }

        # Add cc_pair_id if provided
        if cc_pair_id is not None:
            document["cc_pair_id"] = cc_pair_id
            logger.debug(f"Added cc_pair_id {cc_pair_id} to document from {file_path}")

        return document

    except Exception as e:
        logger.error(f"Error transforming {file_path}: {str(e)}")
        return {}

def send_json_to_api(
    file_path: Path,
    api_url: str,
    tracking_file: str,
    document_id: str,
    headers: Optional[dict] = None,
    timeout: int = 30,
    dry_run: bool = False,
    cc_pair_id: Optional[int] = None
) -> bool:
    """
    Read a JSON file, transform it to the required format, and send to the API.

    Args:
        file_path: Path to the JSON file
        api_url: URL of the API endpoint
        tracking_file: Path to the tracking file
        document_id: The document ID to track
        headers: Optional headers to include in the request
        timeout: Request timeout in seconds
        dry_run: If True, don't actually send the request
        cc_pair_id: Optional connector credential pair ID

    Returns:
        True if successful, False otherwise
    """
    logger = logging.getLogger(__name__)

    try:
        # Transform the JSON to the required format
        transformed_data = transform_json_to_document_format(file_path, cc_pair_id)

        if not transformed_data:
            logger.error(f"Failed to transform data from {file_path}")
            return False

        if dry_run:
            logger.info(f"DRY RUN: Would send transformed data from {file_path} to {api_url}")
            save_processed_id(tracking_file, document_id)
            return True

        response = requests.post(
            api_url,
            json=transformed_data,
            headers=headers or {},
            timeout=timeout
        )

        response.raise_for_status()
        logger.info(f"Successfully sent transformed data from {file_path} to API")

        # Save the document ID to tracking file on successful processing
        save_processed_id(tracking_file, document_id)
        return True

    except json.JSONDecodeError:
        logger.error(f"Failed to parse JSON from {file_path}")
    except RequestException as e:
        logger.error(f"API request failed for {file_path}: {str(e)}")
    except Exception as e:
        logger.error(f"Unexpected error processing {file_path}: {str(e)}")

    return False

def main() -> int:
    """Main function to run the script."""
    setup_logging()
    logger = logging.getLogger(__name__)

    try:
        args = parse_arguments()

        # Parse headers if provided
        headers = None
        if args.headers:
            try:
                headers = json.loads(args.headers)
            except json.JSONDecodeError:
                logger.error("Failed to parse headers JSON string")
                return 1

        # Log cc_pair_id if provided
        if args.cc_pair_id is not None:
            logger.info(f"Using connector credential pair ID: {args.cc_pair_id}")

        # Load already processed document IDs
        processed_ids = load_processed_ids(args.tracking_file)
        logger.info(f"Loaded {len(processed_ids)} already processed document IDs")

        # Find all JSON files
        logger.info(f"Searching for JSON files in {args.directory}")
        json_files = find_json_files(args.directory)
        logger.info(f"Found {len(json_files)} JSON files")

        if not json_files:
            logger.warning("No JSON files found. Exiting.")
            return 0

        # Filter out already processed files
        unprocessed_files = []
        for file_path in json_files:
            try:
                # Extract document ID from the JSON file
                with open(file_path, "r", encoding="utf-8") as f:
                    data = json.load(f)
                document_id = data.get("id")

                if not document_id:
                    logger.warning(f"No 'id' field found in {file_path}, skipping")
                    continue

                if document_id not in processed_ids:
                    unprocessed_files.append((file_path, document_id))
                else:
                    logger.debug(f"Skipping already processed document: {document_id}")
            except Exception as e:
                logger.warning(f"Error reading document ID from {file_path}: {e}, skipping")
                continue

        logger.info(f"Found {len(unprocessed_files)} unprocessed files out of {len(json_files)} total files")

        if not unprocessed_files:
            logger.info("All files have already been processed. Exiting.")
            return 0

        # Process each unprocessed JSON file
        success_count = 0
        failure_count = 0

        for file_path, document_id in tqdm(unprocessed_files, desc="Processing files"):
            success = send_json_to_api(
                file_path=file_path,
                api_url=args.url,
                tracking_file=args.tracking_file,
                document_id=document_id,
                headers=headers,
                timeout=args.timeout,
                dry_run=args.dry_run,
                cc_pair_id=args.cc_pair_id
            )

            if success:
                success_count += 1
            else:
                failure_count += 1

        # Report results
        logger.info(f"Processing complete. Success: {success_count}, Failures: {failure_count}")

        return 0 if failure_count == 0 else 1

    except KeyboardInterrupt:
        logger.info("Process interrupted by user")
        return 130
    except Exception as e:
        logger.exception(f"Unhandled exception: {str(e)}")
        return 1

if __name__ == "__main__":
    main()
```


# LLM Gateway
Source: https://docs.onyx.app/developers/guides/llm_gateway

Route application LLM requests through the models and access controls configured in Onyx

The Onyx LLM Gateway gives applications one endpoint for the language models your organization has configured in Onyx.
Requests use your Onyx identity, so model access and usage attribution stay in one place.

Use the gateway when you want an application, automation,
or coding tool to use organization-approved models without storing a separate provider key.

<Note>
  The LLM Gateway is available with Onyx Enterprise.
  An administrator must configure at least one visible language model before it can serve requests.
</Note>

## What the gateway provides

* An [OpenAI-compatible Chat Completions endpoint](https://platform.openai.com/docs/api-reference/chat/completions).
* An [OpenAI Responses endpoint](https://platform.openai.com/docs/api-reference/responses).
* An [Anthropic Messages endpoint](https://platform.claude.com/docs/en/api/messages) and [token-count endpoint](https://platform.claude.com/docs/en/api/messages/count_tokens).
* The models that your Onyx identity can access.
* Usage attribution through the existing Onyx usage views.
* The same model access controls and token limits that apply in Onyx.

The gateway does not replace your model-provider configuration.
An administrator still configures providers and decides which models are visible in [Language
Models](/admins/ai_models/overview).

<img alt="Onyx Admin Panel showing available language-model providers" />

## Before you begin

You need all of the following:

* An Onyx administrator has configured a language model and made it visible.
* Your Onyx account has access to that model.
* A Personal Access Token (PAT) with the **LLM Gateway** scope.

Create a [Personal Access Token](/developers/overview#personal-access-tokens) from **Settings** > **Accounts & Access**.
Choose **Limited access** and select **LLM Gateway**. Treat the token as a password. Onyx shows it only once.

<Tip>
  Use a scoped PAT for an application or local development.
  It limits the token to gateway requests while preserving the model access of the user who created it.
</Tip>

## Gateway address

For a standard Onyx deployment, use:

```text theme={null}
https://your-onyx-domain.com/api/gateway/v1
```

Self-hosted deployments can expose the API at a different public path. Use the public API address for your deployment,
followed by `/gateway/v1`.

Every request uses a Bearer token:

```bash theme={null}
export ONYX_GATEWAY_URL="https://your-onyx-domain.com/api/gateway/v1"
export ONYX_GATEWAY_API_KEY="onyx_pat_..."
```

## Find an available model

The easiest way to find a model ID is in **Settings** > **LLM Gateway**.
The section appears only when at least one model is visible and accessible to your account.

Open a provider, then copy the ID beside the model that you want to use.
The copied value already has the required format:

<img alt="Onyx LLM Gateway settings with an expanded provider and model IDs" />

```text theme={null}
<provider-id>/<model-name>
```

For example, `12/gpt-5-mini` means:

* `12` is the Onyx ID for the configured provider.
* `gpt-5-mini` is the model name configured for that provider.

Use the copied value exactly as the `model` value in your client. Do not replace the provider ID with the provider name.

Use **Settings** to find a model ID for each client configuration.

## OpenAI Chat Completions

Point OpenAI-compatible clients at the gateway URL. This example uses the official OpenAI JavaScript SDK.

```ts TypeScript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONYX_GATEWAY_API_KEY,
  baseURL: process.env.ONYX_GATEWAY_URL,
});

const completion = await client.chat.completions.create({
  model: "12/gpt-5-mini",
  messages: [{ role: "user", content: "Write a one-line release note." }],
});

console.log(completion.choices[0].message.content);
```

The same request with `stream: true` uses server-sent events.

## OpenAI Responses

The gateway also supports the OpenAI Responses API. Use the same base URL and model ID.

```ts TypeScript theme={null}
const response = await client.responses.create({
  model: "12/gpt-5-mini",
  input: "Summarize the purpose of this service in one sentence.",
});

console.log(response.output_text);
```

<Info>
  Gateway responses are stateless. Send the context that a later turn needs;
  do not rely on a previous response ID being stored by Onyx.
</Info>

## Anthropic Messages

For Anthropic-compatible clients,
send requests to the gateway's `messages` endpoint with the same Bearer token and model ID.

```bash theme={null}
curl "$ONYX_GATEWAY_URL/messages" \
  -H "Authorization: Bearer $ONYX_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "18/claude-haiku-4-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Reply with one friendly greeting."}
    ]
  }'
```

To estimate the input tokens for an Anthropic Messages request,
send the same request shape to `POST /messages/count_tokens`.

## Use with coding agents

Use the gateway with [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
or [Codex](https://developers.openai.com/codex) to give coding-agent requests the same model access controls,
usage attribution, and token limits as other gateway traffic.

### Claude Code

Set the gateway's parent endpoint as the Anthropic base URL, then use a Claude model ID from **Settings**:

```bash theme={null}
export ANTHROPIC_BASE_URL="https://your-onyx-domain.com/api/gateway"
export ANTHROPIC_AUTH_TOKEN="$ONYX_GATEWAY_API_KEY"
export ANTHROPIC_MODEL="18/claude-haiku-4-5"
export ANTHROPIC_SMALL_FAST_MODEL="18/claude-haiku-4-5"

claude
```

Claude Code appends `/v1/messages`, which resolves to the gateway's Anthropic Messages endpoint.
Use a model ID from your own Settings page. Provider IDs differ by deployment.

### Codex

Create a [Codex profile](https://developers.openai.com/codex) at `~/.codex/onyx.config.toml`:

```toml theme={null}
model = "12/gpt-5-mini"
model_provider = "onyx_gateway"

[model_providers.onyx_gateway]
name = "Onyx Gateway"
base_url = "https://your-onyx-domain.com/api/gateway/v1"
wire_api = "responses"
env_key = "ONYX_GATEWAY_API_KEY"
```

Then export the PAT and start Codex with that profile:

```bash theme={null}
export ONYX_GATEWAY_API_KEY="onyx_pat_..."
codex -p onyx
```

The configured model must be an OpenAI-compatible model ID from **Settings**.

### OpenCode

Add the gateway as an OpenAI-compatible provider in your project's `opencode.json`:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "model": "onyx_gateway/12/gpt-5-mini",
  "provider": {
    "onyx_gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Onyx Gateway",
      "options": {
        "baseURL": "https://your-onyx-domain.com/api/gateway/v1",
        "apiKey": "{env:ONYX_GATEWAY_API_KEY}"
      },
      "models": {
        "12/gpt-5-mini": {
          "name": "GPT-5 mini via Onyx"
        }
      }
    }
  }
}
```

Export a PAT before starting OpenCode:

```bash theme={null}
export ONYX_GATEWAY_API_KEY="onyx_pat_..."
opencode
```

The `@ai-sdk/openai-compatible` provider uses the gateway's Chat Completions endpoint.
Replace the example model with one from your Gateway Settings.

## Usage and limits

Gateway requests use the calling user's Onyx permissions. If the user loses access to a model,
the gateway no longer exposes or accepts that model for the user.

Administrators can review token use and estimated model cost in **Admin Panel**

> **Usage**. They can also apply global, group, or user token limits there.
> Those limits apply before the gateway sends a generation request to a model provider.

<img alt="Onyx Admin Panel controls for global, user, and group spending limits" />

## Common errors

| Error             | What to check                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `401` or `403`    | Use a valid PAT with the LLM Gateway scope. Check that the user still has model access.      |
| Model not found   | Copy the model ID again from Gateway Settings. The provider ID is part of the identifier.    |
| Rate limited      | Ask an administrator to review the user, group, or workspace token limit.                    |
| Model unavailable | Ask an administrator to configure the provider or make the model visible in Language Models. |

## Next steps

<CardGroup>
  <Card title="Configure language models" icon="sliders" href="/admins/ai_models/overview">
    Add providers and control which models are visible.
  </Card>

  <Card title="Create a Personal Access Token" icon="key" href="/developers/overview#personal-access-tokens">
    Create and manage the token used by your application.
  </Card>
</CardGroup>


# Overview & Auth
Source: https://docs.onyx.app/developers/overview

Overview of Onyx APIs

**Nearly every Onyx feature is accessible through the Onyx API.**

Onyx APIs are built on REST principles with JSON request/response formats.
All endpoints require authentication and follow relatively consistent patterns.

Make API requests to:

`https://cloud.onyx.app/api` or `https://your-self-hosted-onyx.com/api`

<Note>
  Onyx follows [SemVer 2.0.0](https://semver.org/). Breaking changes will be indicated by major version increments.
</Note>

<Info>
  This page applies to Onyx **v4.7 and later**, which replaced API key roles with group-based permissions.
  For older versions, see [Overview & Auth before v4.7](/developers/overview_legacy).
</Info>

## Authentication

Every request authenticates with a Bearer token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://cloud.onyx.app/api/me/permissions
```

Onyx has two kinds of token. An **API Key** belongs to a service account. A **Personal Access Token** belongs to you.

### API Keys

API Keys are created by admins from the Admin Panel. Each key exists as a distinct **service account** user in Onyx,
so you can trace activity, keep chat sessions private, and scope resources to a specific key.

A service account has no permissions of its own.
Its access comes from the **groups** you assign to it when you create the key.

| Groups assigned | What the key can do                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| None            | Chat only. It can create sessions and send messages, but it cannot search and cannot reach any admin endpoint.                                 |
| Basic           | Chat, search, projects, and its own agents.                                                                                                    |
| Admin           | Every endpoint, including the ones prefixed with `admin/`.                                                                                     |
| A custom group  | Whatever that group grants. A group with **Manage Connectors & Document Sets**, for example, unlocks the connector and document set endpoints. |

Permissions add together. A key in several groups receives the union of their permissions.

<Warning>
  A key in the **Admin** group has unrestricted access to your Onyx instance.
  Prefer a group that grants only the permissions your integration needs.
</Warning>

<Info>
  Custom groups and configurable group permissions are an Enterprise Edition feature.
</Info>

See [Service Accounts](/admins/user_management/api_keys) for setup instructions.

### Personal Access Tokens

Personal Access Tokens (PATs) let a user authenticate API requests as themselves.

To create a token, go to **Settings** > **Accounts & Access** and click **Create New Token**. Give it a name,
choose an expiration (7 days, 30 days, 365 days, or never), and choose its permissions:

| Permissions    | Behavior                                      |
| -------------- | --------------------------------------------- |
| Full access    | The token inherits all of your permissions.   |
| Limited access | The token is capped to the scopes you select. |

A limited token can pick from these scopes:

| Scope             | Permission        | Allows                                                                                          |
| ----------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| Search — Read     | `read:search`     | Use the search and web search endpoints.                                                        |
| Chat — Read       | `read:chat`       | View chat sessions and messages.                                                                |
| Chat — Write      | `write:chat`      | Create sessions and send messages. Includes Chat — Read.                                        |
| LLM Gateway — Use | `use:llm_gateway` | Call the [LLM Gateway](/developers/guides/llm_gateway) from external tools. Enterprise Edition. |

Scopes only narrow access. A limited token receives the scopes you selected **and** your own permissions,
never more than you can do yourself. A limited token is also rejected on any endpoint outside its scopes,
even one you can reach in the browser.

<Note>
  Creating a token requires the **Create User Access Token** permission, which an admin grants to a group.
  Admins always have it.
</Note>

<Warning>
  Your token is displayed only once at creation. Copy it immediately and store it securely.
</Warning>

You can view, audit, and revoke your tokens at any time from **Settings** > **Accounts & Access**.

## Permissions

Every endpoint page in the [API Reference](/developers/api_reference/chat/get_chat_session)
states the permission it requires. Permissions come from the groups a user or service account belongs to:
`basic` from the Basic group that every user joins, and `admin` from the Admin group, which passes every check.

<Info>
  This permission model applies to Onyx **v4.7 and later**. For how groups, group permissions, and Group Managers work,
  see [Understanding Permissions](/admins/permissions/understanding_permissions).
</Info>

Endpoint pages and `GET /me/permissions` identify a permission by its value.
Each value maps to a permission an admin grants to a group in the Admin Panel:

| Admin Panel                       | Permission                                  |
| --------------------------------- | ------------------------------------------- |
| Manage LLMs                       | `manage:llms`                               |
| Manage Connectors & Document Sets | `manage:connectors`, `manage:document_sets` |
| Manage Actions                    | `manage:actions`                            |
| Manage Groups                     | `manage:user_groups`                        |
| Manage Service Accounts           | `manage:service_account_api_keys`           |
| Manage Slack/Discord Bots         | `manage:bots`                               |
| Create Agents                     | `add:agents`                                |
| Manage Agents                     | `manage:agents`                             |
| View Agent Analytics              | `read:agent_analytics`                      |
| View Query History                | `read:query_history`                        |
| Create User Access Token          | `create:user_api_keys`                      |

A management permission also grants the reads it needs — `manage:connectors` includes `read:connectors` —
so a caller resolves to more permissions than were granted.

### Checking what a token can do

`GET /me/permissions` returns the caller's resolved permissions:

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://cloud.onyx.app/api/me/permissions
```

```json theme={null}
{
  "permissions": ["basic", "manage:connectors", "read:chat", "read:connectors", "..."],
  "is_manager": false,
  "managed_group_ids": []
}
```

A request that fails a permission check returns `403`:

```json theme={null}
{
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "detail": "You do not have the required permissions for this action."
}
```

## API Reference and Playground

In the [API Reference](/developers/api_reference/chat/get_chat_session),
we have curated a subset of useful Onyx API endpoints.
You can experiment with the endpoints on each page or follow one of our [Guides](/developers/guides/chat_new_guide).

You can find all Onyx API endpoints in the built-in OpenAPI explorer:

`https://cloud.onyx.app/api/docs` or `https://your-onyx-domain.com/api/docs`

<Warning>
  The explorer is purely for reference. It is not a fully-featured API client.
  Ignore the tenant\_id parameter and use your API key as a Bearer token.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Core Concepts" icon="lightbulb" href="/developers/core_concepts">
    Learn the fundamental concepts and terminology for working with Onyx APIs
  </Card>

  <Card title="Guide: Send a Chat Message" icon="comment" href="/developers/guides/chat_new_guide">
    Simple example of sending a message programmatically
  </Card>
</CardGroup>


# Actions & MCP
Source: https://docs.onyx.app/overview/core_features/actions

Extend the capabilities of Onyx Agents

## Overview

**Actions** give Agents the ability to interact with external systems.

Onyx comes with 5 built-in Actions and allows users to configure additional ones via
[OpenAPI](https://en.wikipedia.org/wiki/OpenAPI_Specification)
and [Model Context Protocol](https://modelcontextprotocol.io/) (MCP).

The built-in Actions include:

| Name                         | Description                                                             | Requires Config           | Provider Choices                          |
| ---------------------------- | ----------------------------------------------------------------------- | ------------------------- | ----------------------------------------- |
| Internal Search              | Search through your organization's indexed documents and knowledge base | Yes                       | Built-in with swappable components        |
| Web Search                   | Search the internet for real-time information and current events        | Yes                       | Google, Serper, Exa, Firecrawl (optional) |
| Code Execution               | Execute Python code, analyze data, and generate visualizations          | No                        | Built-in                                  |
| Image Generation             | Create images from text descriptions using AI models                    | Yes                       | OpenAI, Azure OpenAI                      |
| Coding Agent <sup>Beta</sup> | Investigate and answer questions about a public GitHub codebase         | Yes (disabled by default) | Built-in                                  |

## Custom Actions

<img alt="MCP Config" />

Onyx offers flexible options for configuring both custom Actions and their associated authentication.

Admins can choose to:

* Use a single shared authentication, giving all users the same level of access to Actions.
* Require each user to complete their own authentication flow, so Actions respect individual user permissions.

Onyx supports both token-based authentication and OAuth.

<img alt="MCP Auth" />

## Actions Button

<img alt="Action Toggle" />

In the Chat input bar, Actions are grouped by the MCP server or OpenAPI schema they are registered with.
Users have the flexibility to turn on/off the Actions that the Agent/LLM has access to on the fly.


# Custom Agents
Source: https://docs.onyx.app/overview/core_features/agents

Create custom AI Agents for unique use cases

Agents are a combination of user specified instructions, knowledge, and [Actions](/overview/core_features/actions).
Think of them as AI team members that are optimized for a specific task.

Onyx Agents can be for individual use or shared with other users or
[user-groups](/admins/user_management/users_and_groups) within Onyx.

<img alt="Agent Example" />

## When to use an Agent

Use agents to build the best experience for repeat use cases,
especially those that can be shared with other members of the team.

Some common examples include:

* Onboarding Assistant
* AI Helpdesk
* Engineer Copilot
* Legal Reviewer

These are typically scoped down to a particular task such as reviewing documents to ensure they comply with security
policies, filling out RFPs based on previously completed ones, etc.

## Creating an Agent

### Instructions (Prompting)

<Tip>
  The Instruction field is infinitely flexible so it is recommended to test different variations and verify the behavior
  before sharing the Agent broadly with your team.
</Tip>

Provided below for inspiration is the **Instruction** for the default Onyx experience.

<Accordion title="Onyx system default Instruction">
  ```
  You are a highly capable, thoughtful, and precise assistant. Your goal is to deeply understand the user's intent, ask clarifying questions when needed, think step-by-step through complex problems, provide clear and accurate answers, and proactively anticipate helpful follow-up information. Always prioritize being truthful, nuanced, insightful, and efficient.
  The current date is [[CURRENT_DATETIME]]

  You use different text styles, bolding, emojis (sparingly), block quotes, and other formatting to make your responses more readable and engaging.
  You use proper Markdown and LaTeX to format your responses for math, scientific, and chemical formulas, symbols, etc.: '$$\n[expression]\n$$' for standalone cases and '\( [expression] \)' when inline. For code you prefer to use Markdown and specify the language.
  You can use Markdown horizontal rules (---) to separate sections of your responses.
  You can use Markdown tables to format your responses for data, lists, and other structured information.
  ```

  Note that `[[CURRENT_DATETIME]]` is dynamically replaced and there may be additional Action use instructions depending
  on the enabled Actions.
</Accordion>

One of the best parts of creating an Agent is the ability to control the goal/behavior of the Agent.
The instructions are purely in natural language and can include things like:

* Always provide your results in a table.
* Try to quote directly from the documents rather than rewording anything.
* Flag information from documents that are older than 3 months.

### Knowledge

<Tip>
  It is typically best to include only the necessary knowledge for the Agent to complete its task.
  The more scoped down the documents, the more reliable the performance.
</Tip>

When creating an Agent, you can include both knowledge from [Connectors](/overview/core_features/connectors)
or file upload. The knowledge from connectors will be kept up to date as documents change in the external sources.

### Actions

<Note>
  If any of the built-in actions (Web Search, Internal Search, Image Generation, Code Execution) are missing,
  contact your Onyx admin.
  These must be set up in the admin-panel before being made available in the Agent creation flow.
</Note>

[Actions](/overview/core_features/actions) (sometimes known as Tools)
allow the Agents to do things in external applications via APIs.
Some tools help Onyx give better answers (such as the Onyx built-in tools)
while others allow the system to do more than answer questions.

Some example common Actions include:

* Updating ticket statuses based on the conversation and if the user's needs were addressed.
* Checking the status of a service to give real-time answers.
* Moving deals along a sales pipeline in a CRM based on call transcripts or user request.


# Chat UI
Source: https://docs.onyx.app/overview/core_features/chat

Overview of Onyx's primary user interface

<Tip>
  On the top left of the page (just right of the sidebar), you can select the mode of the UI.
  Replace "Auto" with "Chat" to always go into this Chat UI.
</Tip>

<img alt="Onyx Chat Interface" />

Onyx provides a natural language chat interface as the main way of interacting with the features.
The page below contains an overview of the main components and features.

## Input Bar

### Chat with Files / URLs

<img alt="Files Input" />

The leftmost button of the input bar lets users add context into the Chat session.
Users can choose between uploading files or selecting URLs as well as reusing previous files or URLs.

<Note>
  URLs behind Logins, Captcha, or Paywalls that are not scrapeable are not accessible.
  Consider using a [Connector](/overview/core_features/connectors) instead.
</Note>

### Actions Selector

<img alt="Actions Input" />

The second button lets users disable or force the use of Actions. There are 4 built-in Actions:

* **[Internal Search](/overview/core_features/internal_search)**:
  Enables the LLM to search the indexed knowledge from [Connectors](/overview/core_features/connectors).
* **[Web Search](/overview/core_features/web_search)**: Enables the LLM to search the internet.
  Requires an admin to set up an API key for a search provider.
* **[Code Execution](/overview/core_features/code_interpreter)**:
  Enables the LLM to use a sandboxed Python runtime to execute code and run data analysis.
* **[Image Generation](/overview/core_features/image_generation)**: Allows the LLM to generate images.
  Requires setting up an image generation API.

The Actions below the separator represent custom admin configured Actions.
See [Actions & MCP](/overview/core_features/actions) to learn about custom Actions.

### Deep Research

<img alt="Deep Research" />

Toggle **Deep Research** using the hourglass icon. When turned on, the LLM will be able to run many cycles of thinking,
research, and actions to give the best possible result for the user.
This mode is intended for complicated questions that may need to pull together many sources together or requires
significant reasoning.

<Note>
  Deep Research may take up to several minutes and could cost many times (>10x) the token cost of a normal inference.
</Note>

### Model Selector

<img alt="Model Selector" />

Onyx supports all major LLM providers as well as self-hosting options like Ollama, VLLM, etc. For select models,
users can also configure the creativity and reasoning level.

## Sidebar Contents

The left sidebar contains:

* `New Session` button to clear the history and start a new Chat or [Search](/overview/core_features/internal_search) session.
* `Projects` to help users organize chats and reuse different sets of documents. See section below for more info.
* `Agents` section to start a new session with yours or your team's custom [Agents](/overview/core_features/agents).
* `Sessions` section containing a list of the most recent conversations.

The right sidebar contains sources and citations that were used in generating the answer.
These can come from either `Internal Search` or `Web Search` or both.
Documents in the right sidebar can also be selected to be included in full for the next message in the Chat session.

<Tip>
  It's often useful to ask a question to find a document, then select it to do a deep dive on it.
</Tip>

## Projects

<img alt="Projects" />

**Projects** are a collection of instructions (prompts) and files as well as a grouping for chats.
Use projects to organize ongoing work,
or as a handy way to reuse instructions and files without going through the Agent creation flow.

## Miscellaneous Chat Features

**Chat Sharing** - share chats with other team members by using the share-chat button in the top right (left of the
Sources sidebar).

**Feedback** - give feedback viewable to the admins using the thumbs-up/thumbs-down buttons when hovering an LLM
response

**Regenerate** - modify your inputs by clicking the user messages or regenerate the LLM response with another model.

**Copying** - copy the LLM output or markdown/code blocks by clicking on the copy button which shows on hover.


# Code Execution
Source: https://docs.onyx.app/overview/core_features/code_interpreter

Safe and sandboxed Python runtime available to the LLM

The code execution action gives Onyx's LLMs the ability to write and execute Python code,
unlocking capabilities such as performing complex calculations, running data analysis on uploaded files,
and generating or modifying documents.

<Tip>
  The code execution action is built-in functionality available to all deployments without any configuration needed.
</Tip>

<img alt="Code Execution" />

<Info>
  The LLM determines when to use code execution based on the user's query — no explicit invocation is needed.
  It can also be attached to custom [Agents](/admins/agents/overview), giving the LLM the option to use it as needed.
</Info>

## Features

The code execution action runs in a secure,
sandboxed Python environment with all dangerous functionality removed (such as network access and filesystem access
outside of the sandbox).

* **Libraries**: Comes with pre-installed libraries such as numpy, pandas, scipy, matplotlib, and more.
* **File Input**: Pass arbitrary file types along with the code to run against them.
* **File Output**: Files can be created and provided back to the user.
* **STDIN/STDOUT Capture**: All program outputs are captured and displayed to the user.
* **Graph Rendering**: The Onyx [Chat UI](/overview/core_features/chat)
  renders returned graphs and other visualizations directly in the conversation.

## Configuration

To learn more about managing the code execution server,
see the [admin configuration guide](/admins/actions/code_interpreter).


# Coding Agent
Source: https://docs.onyx.app/overview/core_features/coding_agent

Investigate and answer questions about a GitHub codebase

<Note>
  The Coding Agent is a **beta** feature.
  It is disabled by default and currently supports **public** GitHub repositories. See [Configuration](#configuration)
  below to enable it.
</Note>

## Overview

The Coding Agent gives Onyx the ability to investigate a GitHub repository and answer questions about its codebase.
Given a repository and a question,
it clones the repo into an isolated sandbox and explores the code with shell commands before returning a written answer.

This unlocks workflows such as:

* **Understanding a codebase**: Ask how a feature is implemented or where a piece of logic lives.
* **Onboarding**: Get a high-level explanation of a project's structure and key modules.
* **Code investigation**: Trace how data flows through the application or how two components interact.
* **Answering "where / how / why" questions**: Locate relevant files and summarize what the code does.

<Info>
  The LLM determines when to use the Coding Agent based on the user's query. Like other Actions,
  it can be attached to custom [Agents](/admins/agents/overview), giving the LLM the option to use it as needed.
  Be explicit in your prompt about the repository you want analyzed.
</Info>

## How It Works

When the Coding Agent is invoked, it:

<Steps>
  <Step title="Clones the repository">
    The target GitHub repository is cloned into an isolated sandbox environment.
  </Step>

  <Step title="Investigates the code">
    An iterative loop powered by an LLM executes shell commands to explore the codebase.
  </Step>

  <Step title="Returns an answer">
    A final, written answer is produced based on what it found.
  </Step>
</Steps>

The Coding Agent runs in the same sandboxed environment as the [Code
Interpreter](/overview/core_features/code_interpreter), so it requires a connected bash/code execution server.

## Configuration

Because the Coding Agent is a beta Action, it is **disabled by default**.
An admin can enable it from the **Actions** tab of the Admin Panel,
and then attach it to the relevant [Agents](/admins/agents/overview).

To learn more about enabling and managing the Coding Agent,
see the [admin configuration guide](/admins/actions/coding_agent).

## Limitations

* **Public repositories only**: Private repositories are not yet supported and will fail to clone. Support for private
  repositories is planned.
* **Beta**: Behavior and configuration may change as the feature matures.


# Connectors
Source: https://docs.onyx.app/overview/core_features/connectors

Ingest knowledge from connected applications

<Tip>
  [Click here to see a full list of all supported connectors.](/admins/connectors/overview#supported-connectors)
</Tip>

<a href="/admins/connectors/overview#supported-connectors">
  <img alt="Connectors" />
</a>

## What are Connectors?

Onyx uses Connectors to build an understanding of your documents, team,
and higher level concepts so that answers are grounded and specific to your organization's knowledge.

Connectors:

* Keep all updates synced between external systems and Onyx.
* Pull in metadata and additional signals to ensure answer relevance.
* Respect all user permissions (Enterprise Edition only).

## Common Connector Questions

<Card title="What are the supported connectors?" icon="list" href="/admins/connectors/overview#supported-connectors">
  Click this card to see the full list of supported connectors.

  You can also push documents directly into Onyx via [API](/developers/guides/index_files_ingestion_api)
  or via File Upload.
</Card>

<Card title="How do I ensure my data is secure?" icon="lock" href="/admins/connectors/overview#security">
  All processing and storage of documents and metadata happen within Onyx.

  There are options to use LLMs or third party providers during the indexing flow but by default everything is
  processing entirely locally.

  Click this card to see more about security.
</Card>

<Card title="Why are connectors/indexing important?" icon="circle-nodes" href="/overview/core_features/internal_search">
  In the same way LLMs are pre-trained on massive amounts of internet data,
  Onyx builds an understanding of all of the documents, concepts, and people within your organization.

  This allows Onyx to provide more accurate answer to questions that relate to internal knowledge compared to using the
  applications' provided search APIs at query time.

  Click this card to learn more about Internal Search in Onyx.
</Card>


# Overview
Source: https://docs.onyx.app/overview/core_features/craft

Turn a goal into finished work with an AI coworker in a secure sandbox

Craft is an AI coworker that can take a goal from prompt to finished deliverable. It plans the work, gathers context,
writes and runs code, creates files, and iterates on the result in a secure sandbox.

| Ask Craft to                      | Example result                                                        |
| --------------------------------- | --------------------------------------------------------------------- |
| **Research and synthesize**       | A customer brief grounded in company knowledge and current App data.  |
| **Create a polished deliverable** | A presentation, report, spreadsheet, document, image, or export file. |
| **Build an interactive tool**     | A dashboard, data explorer, calculator, or other shareable web app.   |
| **Complete work in another tool** | A drafted email, updated project issue, saved file, or pull request.  |

<img alt="A Craft session with a generated dashboard open in the Output panel" />

<Tip>
  Looking to enable Craft for your Onyx deployment? See the [deployment](/deployment/local/craft)
  and [admin](/admins/managing_features/craft) guides.
</Tip>

Craft runs generated code in a sandbox isolated from your computer and Onyx infrastructure.
Your organization controls the information Craft can access and the actions it can take.
See [Craft Architecture](/security/architecture/craft) for the full trust and network model.

## Start a Craft session

Each new session gets a separate workspace where Craft can create files, run code, and preview web apps.
It can also use company knowledge, User Library files, available Skills, and connected Apps to complete your request.

<img alt="A Craft session with the agent loop on the left and a live dashboard preview on the right" />

<Note>
  If you don't see Craft in your Onyx sidebar, it hasn't been enabled for your workspace.
  Ask an admin to turn on Craft and confirm that a supported model provider is available.
</Note>

### Write a strong first prompt

Pick a model, describe the result you want, and provide the context Craft should use.

<img alt="The Craft home screen with the prompt box, model selector, and links to connect data sources" />

You can't change models after sending the first message, so choose one before you send.

| Include                    | What to tell Craft                                                              |
| -------------------------- | ------------------------------------------------------------------------------- |
| **End product**            | Whether you need a web app, report, deck, brief, data explorer, or export file. |
| **Audience and purpose**   | Who will use the result and what they need from it.                             |
| **Source material**        | Company sources, connected Apps, examples, or files Craft should reference.     |
| **Important requirements** | The sections, tone, charts, filters, file names, or output format that matter.  |

<Tip>
  Craft is designed to keep moving and often makes reasonable assumptions.
  Put important constraints in the first prompt, then refine the result as it works.
</Tip>

### Example: build an all-hands deck

> Build an all-hands slide deck for Q2. Pull the wins from Slack, reference
> prospects and customers from HubSpot, cite figures from our sales sync doc,
> and use our all-hands template.

Craft can gather the requested context, follow the presentation Skill and your company template,
delegate slides to subagents, and assemble the final deck.

<img alt="A Craft session building a pitch deck and delegating individual slides to parallel subagents" />

## Follow the work

The chat panel streams Craft's progress while it works:

| Activity      | What it shows                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| **Tasks**     | The plan Craft is working through, checked off as it progresses.                                           |
| **Thinking**  | How Craft is approaching the next step.                                                                    |
| **Working**   | Tool calls, such as searching company knowledge or reading a file from an App.                             |
| **Running**   | Commands in the sandbox, such as writing code, installing packages, or starting a development server.      |
| **Subagents** | Focused agents working in parallel on parts of a larger job, such as individual slides or report sections. |

Open a subagent from the header menu to read its transcript. Your messages still go to the main session.
A status in the header shows when the sandbox is initializing, running, or restoring.

You can guide the run at any time:

| Control               | What it does                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **Approve an action** | Lets you review an App action when your organization's policy requires approval.                     |
| **Queue a follow-up** | Gives Craft another instruction to pick up after its current turn.                                   |
| **Interrupt**         | Stops the current run when you press **Esc**. Your messages and files remain so you can redirect it. |

## Give Craft context

Craft can start with only a prompt,
but concrete references help it find the right information and match the result you have in mind.
Use **+** in the input bar to attach files or select a Skill or App. You can also drag files into the chat.

| Source                  | Best for                                                                 |
| ----------------------- | ------------------------------------------------------------------------ |
| **Onyx knowledge**      | Company content you already have permission to access.                   |
| **Public web**          | Current public information and websites Craft needs to navigate.         |
| **Session attachments** | Files needed only for this session, such as a CSV, PDF, notes, or image. |
| **User Library**        | Reusable files you want available across sessions, such as templates.    |
| **Skills**              | Reusable instructions, examples, and files that teach Craft a method.    |
| **Apps**                | Live information and approved actions in connected external services.    |

Session attachments stay with one session. User Library files remain available for reuse across sessions.

When the Browser Skill is available, Craft can open public websites, follow links, interact with pages,
and take screenshots. It uses its own browser in the sandbox, not your browser session or saved logins.

<Accordion title="File and storage limits">
  These are the default limits. Your admin can adjust them for self-hosted deployments.

  **Session attachments**

  | Limit                          | Default |
  | ------------------------------ | ------- |
  | Maximum file size              | 50 MB   |
  | Maximum files per session      | 20      |
  | Maximum total size per session | 200 MB  |

  **User Library**

  | Limit                    | Default |
  | ------------------------ | ------- |
  | Maximum file size        | 500 MB  |
  | Maximum files per upload | 100     |
  | Maximum total storage    | 10 GB   |

  The User Library accepts regular files and ZIP uploads.
  ZIP files are extracted so Craft can work with the files inside.
</Accordion>

<Warning>
  Don't upload secrets, private tokens, or production credentials as files.
  Connect an [App](/overview/core_features/craft_apps) when Craft needs authenticated access to an external service.
  Raw App credentials never enter the sandbox workspace.
</Warning>

## Review the result

Open **Output** from the upper-right corner of the session to inspect what Craft created.

| Tab           | What it shows                                                                     |
| ------------- | --------------------------------------------------------------------------------- |
| **Preview**   | A live web app that updates as Craft changes its files.                           |
| **Files**     | The full session workspace, including source code, data, and intermediate work.   |
| **Artifacts** | Finished outputs intended for download or sharing, usually written to `outputs/`. |

<img alt="The Output panel showing the Preview, Files, and Artifacts tabs with the session workspace files" />

You can download individual files, download a folder or web app as a ZIP file,
export Markdown as a .docx file, and preview images, PDFs, presentations, and text files.

### Share a web app

Web apps run in the sandbox and are shared through Onyx rather than exposed directly.
Select **Share** in the Preview tab, then choose who can open the app:

| Scope            | Access                                     |
| ---------------- | ------------------------------------------ |
| **Private**      | Only you can open the shared app.          |
| **Organization** | Anyone signed in to your Onyx can open it. |

Sharing includes the generated web app only. It does not share the conversation or other session files.

### Refine the result

Continue in the same session to request changes in plain language:

* **Update the layout:** “Add a filter for the last 30 days and move the summary cards to the top.”
* **Change the writing:** “Rewrite the executive summary for a non-technical audience and cut it to three sentences.”
* **Prepare the final file:** “Add a one-paragraph summary to the report and save the final version to `outputs/`.”

## Go further with Craft

<CardGroup>
  <Card title="Skills" icon="wand-magic-sparkles" href="/overview/core_features/craft_skills">
    Give Craft reusable instructions, examples, templates, and helper files.
  </Card>

  <Card title="Apps" icon="plug" href="/overview/core_features/craft_apps">
    Connect external services for live information and approved actions.
  </Card>

  <Card title="Scheduled Tasks" icon="calendar-clock" href="/overview/core_features/craft_scheduled_tasks">
    Run a tested Craft prompt automatically on a recurring schedule.
  </Card>

  <Card title="For admins" icon="user-shield" href="/admins/managing_features/craft">
    Enable Craft and configure models, Skills, Apps, and governance controls.
  </Card>
</CardGroup>


# Apps
Source: https://docs.onyx.app/overview/core_features/craft_apps

Connect external tools so Craft can retrieve live context and take approved actions

Apps give Craft controlled access to the tools where your work already happens. After you connect an app,
Craft can retrieve live information from your account and, when allowed, create or update content on your behalf.

Examples include finding customer context in HubSpot, drafting a reply in Gmail, creating a Linear issue,
writing a document to Google Drive, or opening a pull request in GitHub.

<img alt="The Craft Apps page showing connected apps and another app available to connect" />

## Apps, company knowledge, and files

These sources serve different purposes in a Craft session:

| Source                  | Best for                                                                 | Can change the source?                                                            |
| ----------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| **Apps**                | Live information and actions in your connected account.                  | Yes, when the app and action policy allow it.                                     |
| **Onyx knowledge**      | Searching indexed company content you already have permission to access. | No. Search is read-only.                                                          |
| **Session attachments** | Files needed for one session.                                            | Craft works on a sandboxed copy.                                                  |
| **User Library**        | Templates and reference files you reuse across sessions.                 | Craft reads synchronized library files and writes new work to the session output. |

## Available apps

Your Apps page shows only the apps your organization has enabled. Onyx includes built-in support for:

| App                 | Example uses                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| **Slack**           | Search conversations, read messages, post updates, and upload files.                                |
| **Google Calendar** | Check availability and read, create, update, or delete events.                                      |
| **Google Drive**    | Find and read files, export content, and create or edit files and Google Docs.                      |
| **Gmail**           | Search mail, read threads and attachments, manage drafts, and send messages.                        |
| **Linear**          | Read issues and projects, create issues, and add comments.                                          |
| **GitHub**          | Inspect repositories, issues, and pull requests; create issues, branches, files, and pull requests. |
| **HubSpot**         | Search contacts, companies, and deals, and create or update CRM records.                            |
| **Notion**          | Search and read workspace content, then create or update pages, databases, blocks, and comments.    |

Your organization can also provide custom apps for APIs or services that are not in the built-in catalog.
The actions available to you depend on the access granted by the external service and your organization's policies.

## Connect an app

<Steps>
  <Step title="Open Apps">
    Select **Apps** in the Craft sidebar. Connected accounts appear first;
    everything else your organization has enabled appears under **Browse apps**.
  </Step>

  <Step title="Connect your account">
    Select **Connect**. Built-in apps open the service's authorization flow.
    A custom app may instead ask for fields defined by your admin.
  </Step>

  <Step title="Review access">
    In the external service, confirm the account and permissions you are granting. When setup finishes,
    the app moves to **Connected**.
  </Step>

  <Step title="Use it in a session">
    Describe the app in your prompt, or select **+** > **Apps** and choose it. For example:
    “Summarize the launch discussion in Slack and draft a follow-up in Gmail.”
  </Step>
</Steps>

Craft can also recognize that an unconnected app is needed while it works. In that case,
a connection card appears in the session with **Connect** and **Not now** options.
Connect the app to let the current task continue, or choose **Not now** and ask Craft to use another source.

<Tip>
  Connect the account you want Craft to act as. For example,
  the Gmail account you authorize is the account Craft reads from and uses for drafts or sends.
</Tip>

## Guide Craft to the right data

Connecting an app makes it available; your prompt should still identify the relevant scope. Include concrete names,
dates, channels, repositories, projects, folders, or records whenever possible.

| Goal                     | Example prompt                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **Ground a deliverable** | “Build a Q2 account review using the Acme deal in HubSpot, the `#acme-account` Slack channel, and the latest notes in Drive.” |
| **Prepare, then act**    | “Review the launch thread in Slack, draft a concise follow-up email, and wait for my approval before sending it.”             |
| **Update a workflow**    | “Find unresolved launch blockers in Linear, group them by owner, and add a comment to issues that have no next step.”         |
| **Ship code work**       | “Inspect the open GitHub issue, make the requested documentation change, and open a pull request for review.”                 |

## Review approval requests

Your organization controls every app action with one of three policies:

| Policy           | What you experience                                                   |
| ---------------- | --------------------------------------------------------------------- |
| **Auto-approve** | Craft performs the action without pausing. Common for low-risk reads. |
| **Ask**          | Craft pauses and shows an approval card before sending the request.   |
| **Deny**         | Craft cannot perform the action and reports that it was blocked.      |

When an action uses **Ask**, expand the approval card to review the app, action, description,
and request payload before deciding.

<img alt="A Craft approval card for posting a Slack message with options to approve once, approve for the session, or reject" />

| Choice                  | Effect                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| **Approve once**        | Allows only the displayed request.                                                                      |
| **Approve for session** | Allows matching actions for the rest of the current session. It does not create a permanent permission. |
| **Reject**              | Blocks the request. Craft receives the rejection and can suggest another approach.                      |

Before approving, confirm:

* The app and connected account are the ones you intended.
* The destination, such as a channel, recipient, repository, calendar, or record, is correct.
* The content and payload match what you asked Craft to do.
* The action is not broader or more destructive than necessary.

<Warning>
  Prefer **Approve once** for sends, deletes, customer-facing changes, calendar changes,
  and other consequential actions. If an approval expires before you respond, the request fails closed and does not run.
</Warning>

## Apps in Scheduled Tasks

A [Scheduled Task](/overview/core_features/craft_scheduled_tasks) runs without you present.
Select its expected apps under **Pre-approved apps** so those apps can act without waiting for a live response.

Pre-approval applies only to that Scheduled Task. An app action with a **Deny** policy remains blocked,
and an app you did not pre-approve can leave the run waiting for approval.

## Disconnect an app

Open **Apps**, find the account under **Connected**, and select **Disconnect**.
Craft can no longer make authenticated requests through that connection.
You can reconnect later by completing the connection flow again.

<Info>
  Raw app credentials never enter Craft's sandbox workspace.
  The sandbox proxy injects them only into approved outbound requests. For the full trust and network model,
  see [Craft Architecture](/security/architecture/craft).
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="An app does not appear">
    Your organization has not enabled it, or its setup is incomplete.
    Ask an admin to review the app configuration and your access.
    Admins can use the [Craft Apps setup guide](/admins/managing_features/craft_apps).
  </Accordion>

  <Accordion title="The connection flow fails">
    Confirm you selected the intended external account, allowed the setup window to open,
    and granted the requested access. For a custom app, verify the credential fields with your admin.
    Then return to Apps and try again.
  </Accordion>

  <Accordion title="Craft cannot perform an action">
    The action may be denied by policy, outside the connected account's access, rejected,
    or expired while awaiting approval. Craft does not retry a blocked action automatically;
    adjust the request or contact an admin if the action should be available.
  </Accordion>

  <Accordion title="A Scheduled Task is awaiting approval">
    Edit the task and confirm the required app is selected under **Pre-approved apps**. If it is already selected,
    an admin may have denied that action or the run may need a different app.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="For admins" icon="user-shield" href="/admins/managing_features/craft_apps">
    Enable built-in or custom apps, configure credentials, and set action policies.
  </Card>

  <Card title="Use Skills" icon="wand-magic-sparkles" href="/overview/core_features/craft_skills">
    Give Craft reusable methods, examples, templates, and helper files.
  </Card>
</CardGroup>


# Scheduled Tasks
Source: https://docs.onyx.app/overview/core_features/craft_scheduled_tasks

Run a Craft prompt automatically on a recurring schedule

A Scheduled Task runs a Craft prompt for you on a recurring schedule.
Each run starts a fresh Craft session in the background, records its result in run history,
and continues whether or not you have Onyx open.

Use Scheduled Tasks for work that has a predictable cadence and a clear definition of done.

| Use case                     | Example                                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Send a daily briefing**    | Summarize new customer escalations every morning and send the important items to a Slack channel.            |
| **Monitor for changes**      | Check an inbox, project, or data source regularly and report only material changes that need attention.      |
| **Build a recurring report** | Gather the latest numbers each week, update a standard report, and save it to the right destination.         |
| **Maintain a workflow**      | Review open work on a schedule, identify stale items, and add an approved comment or follow-up where needed. |

<Tip>
  Test the prompt in a normal Craft session first. Schedule it only after it reliably finds the right information,
  produces the intended output, and handles missing data safely.
</Tip>

## What each run can access

Scheduled Tasks run as the person who created them. Each run uses that person's current:

* Onyx permissions and company knowledge access.
* Connected Apps and external-account permissions.
* Available Skills.
* User Library files.

A run starts in a new session,
so it does **not** inherit the conversation or attachments from the session where you tested the prompt.
Move reusable reference files to your User Library, or point the prompt to company knowledge or a connected App.

<Note>
  A Scheduled Task does not automatically send you its result. If the output should go to Slack, Gmail, Google Drive,
  or another destination, say so in the prompt and configure that App for unattended use. Otherwise,
  review the output from the task's run history.
</Note>

## Create a Scheduled Task

Open **Scheduled Tasks** from the Craft sidebar, then select **New Scheduled Task**.

<Steps>
  <Step title="Name the task">
    Use a name that makes the cadence and result easy to recognize, such as “Weekday customer escalations digest.”
  </Step>

  <Step title="Write a self-contained prompt">
    Describe what Craft should inspect, the time window, what qualifies for inclusion, the desired output,
    and where to deliver it. Type **/** to select a specific Skill or connected App from the prompt picker.
  </Step>

  <Step title="Choose a schedule">
    Use **Interval** to run every set number of minutes or hours. Use **Daily / Weekly** to choose a time and,
    optionally, specific days of the week.
  </Step>

  <Step title="Review pre-approved Apps">
    Select only the Apps the task must use without you present. Connect required Apps before creating the task.
  </Step>

  <Step title="Save and test">
    Select **Save** to wait for the next scheduled time, or **Save and run now** to queue the first run immediately.
  </Step>
</Steps>

<img alt="The New Scheduled Task form with name, prompt, schedule, and pre-approved Apps" />

### Write a prompt that can run unattended

Craft cannot ask you a useful follow-up while a Scheduled Task runs in the background.
Front-load the decisions it would otherwise need from you:

| Include                | Example                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **Scope**              | “Review messages in `#customer-escalations` and open P1 issues in Linear.”               |
| **Time window**        | “Include activity from the last 24 hours.”                                               |
| **Selection criteria** | “Include only items that are blocked, overdue, or need an executive decision.”           |
| **Output**             | “Use a table with account, owner, issue, impact, and next step.”                         |
| **Destination**        | “Post the final digest to `#support-leads` in Slack.”                                    |
| **Fallback**           | “If there are no qualifying items, post ‘No new escalations’ and do not invent content.” |

For example:

> Review the `#customer-escalations` Slack channel and open P1 issues in Linear for activity from the last 24 hours.
> Include only items that are blocked, overdue, or need an executive decision. Group them by account and list the owner,
> impact, and next step. Post the final digest to `#support-leads`. If nothing qualifies, post “No new escalations.”

<Tip>
  Use a relative time window that matches the cadence, such as “during the last 24 hours” for a daily task.
  Fixed dates quickly become stale in a recurring prompt.
</Tip>

### Understand schedule timing

Daily and weekly times are interpreted using your browser's local time when you save the task.
Interval schedules run on repeating clock boundaries rather than a fixed delay after the previous run finishes.

<Note>
  The saved schedule does not automatically adjust when your UTC offset changes.
  Review and resave time-based tasks after traveling, changing time zones, or a daylight-saving transition.
</Note>

## Pre-approve Apps carefully

App actions configured as **Ask** normally pause for your approval. Because a Scheduled Task runs unattended,
selecting an App under **Pre-approved Apps** allows the task to perform those actions without asking during the run.

| App policy       | During a Scheduled Task                                                                 |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Auto-approve** | The action runs without prompting, whether or not the App is selected for pre-approval. |
| **Ask**          | The action runs unattended only when that App is pre-approved for the task.             |
| **Deny**         | The action remains blocked. Pre-approval cannot override a Deny policy.                 |

Pre-approval applies to the **App**, not to one specific action. If you pre-approve Slack, for example,
any Slack action governed by **Ask** can run when it matches the task prompt and the connected account's access.

<Warning>
  Keep the prompt and pre-approved App list as narrow as possible.
  Be especially cautious with Apps that can send messages, modify customer data, delete content, or publish externally.
  Onyx records a notification when a Scheduled Task uses a pre-approved App action.
</Warning>

For more about connections and action policies, see [Apps](/overview/core_features/craft_apps).

## Review run history

Open a task to see its pre-approved Apps and run history. The table shows when each run started,
its status and duration, a short summary, and whether it came from the schedule or **Run now**.

Select a run after it creates a session to inspect its messages, files, previews, and artifacts.
Queued runs do not have a session yet, and skipped runs never create one, so those rows cannot be opened.

| Status                | Meaning                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Queued**            | Waiting for a worker to start the run.                                                                                  |
| **Running**           | Craft is actively working in the generated session.                                                                     |
| **Succeeded**         | Craft completed the run normally.                                                                                       |
| **Failed**            | The run hit an error or exceeded its execution window. Open its session when available to investigate.                  |
| **Skipped**           | The run did not start, usually because a previous run was still queued or running, or Craft was disabled for the owner. |
| **Awaiting approval** | The run reached an App action that required approval but was not pre-approved. It will not resume automatically.        |

Watch for Onyx notifications when a run fails or reaches **Awaiting approval**.
Failed and approval-blocked runs are not retried automatically.

<Warning>
  For an **Awaiting approval** run, open the generated session to see which action stopped it.
  Then edit the task's pre-approved Apps—or narrow the prompt so it avoids that action—and use **Run now** to try again.
</Warning>

## Manage a task

From the task detail page, you can:

| Action      | What it does                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| **Run now** | Queues a one-off run without changing the recurring schedule. This also works while the task is paused. |
| **Pause**   | Stops future scheduled runs. It does not cancel a run that is already queued or running.                |
| **Resume**  | Reactivates the schedule and computes the next run from the current time.                               |
| **Edit**    | Changes the name, prompt, schedule, or pre-approved Apps for future runs.                               |
| **Delete**  | Removes the task and stops future runs. Sessions created by previous runs remain in your Craft history. |

Deleting a task does not cancel a run that is already queued or running.
If you only need to stop future runs temporarily, pause it instead.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A run succeeded, but I did not receive anything">
    Open the run session from history and inspect its output. If the task should deliver somewhere else,
    add an explicit destination to the prompt, connect that App,
    and pre-approve it when the delivery action uses **Ask**.
  </Accordion>

  <Accordion title="A run was skipped">
    Check the row summary. If the previous run was still queued or running,
    make the prompt smaller or use a less frequent schedule.
    A run can also be skipped when Craft is disabled for the task owner.
  </Accordion>

  <Accordion title="A run failed">
    Open the generated session when available. Confirm required Apps are still connected,
    Skills and User Library files still exist, and the prompt can finish within one run. After correcting the task,
    select **Run now**.
  </Accordion>

  <Accordion title="The task ran at an unexpected time">
    Daily and weekly schedules use the browser's local time at save time.
    Edit and resave the task after a time-zone or daylight-saving change. For an interval schedule,
    remember that runs align to repeating clock boundaries.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Connect Apps" icon="plug" href="/overview/core_features/craft_apps">
    Connect delivery destinations and understand approvals before running work unattended.
  </Card>

  <Card title="For admins" icon="user-shield" href="/admins/managing_features/craft">
    Enable Craft and review the deployment, worker, App, and governance requirements.
  </Card>
</CardGroup>


# Skills
Source: https://docs.onyx.app/overview/core_features/craft_skills

Give Craft reusable instructions, examples, and files for repeatable work

Skills teach Craft **how to do a kind of work**. A skill can provide a workflow, quality standards, examples, templates,
scripts, and other supporting files that Craft can reuse across sessions.

For example, a slide skill can tell Craft how to choose layouts, apply a template, validate the finished deck,
and save the presentation in the right format. You provide the goal and source material; the skill provides the method.

<Note>
  Skills do not connect external accounts or hold credentials. To let Craft read from or act in tools like Slack, Gmail,
  or GitHub, connect an [App](/overview/core_features/craft_apps).
</Note>

<img alt="The Skills page in Craft" />

## How Craft uses skills

Craft can choose an available skill automatically when your request matches its description.
You can also select one explicitly when you want Craft to follow a particular workflow.

<Steps>
  <Step title="Choose a skill">
    In a Craft session, select **+**, then **Skills**, and choose a skill.
    You can also type **/** followed by the skill name. The selected skill appears as a chip above the input.
  </Step>

  <Step title="Describe the result">
    Tell Craft what to produce and provide the audience, source material, and requirements that matter.
    Selecting a skill does not replace a clear prompt.
  </Step>

  <Step title="Review and refine">
    Craft reads the skill instructions before doing covered work. Review the result,
    then ask for changes in plain language.
  </Step>
</Steps>

| Goal                            | How to use a Skill                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Build a presentation**        | Select the `pptx` Skill, attach a company deck as a template, and ask Craft to build a presentation from your source material.             |
| **Search company knowledge**    | Ask a company-specific question and let the `company-search` Skill retrieve information you already have permission to access.             |
| **Navigate a website**          | Select the Browser Skill and ask Craft to open a site, follow links, interact with pages, or take screenshots.                             |
| **Generate a visual**           | Select the image generation Skill and describe the subject, composition, style, aspect ratio, and where the visual will be used.           |
| **Standardize repeatable work** | Use a custom Skill to capture your team's process for reports, briefs, reviews, or another workflow you want Craft to repeat consistently. |

## Browse and inspect skills

Open **Skills** from the Craft sidebar to search everything available to you.
Select a skill card to preview its instructions before using it.

| Label           | What it means                                                                                |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Built-in**    | Maintained by Onyx. Availability can depend on your deployment and configured providers.     |
| **Custom**      | Created in your organization and shared with you, your group, or everyone.                   |
| **Personal**    | Created and owned by you. It starts private, but you can share it if your permissions allow. |
| **Unavailable** | Visible for reference, but Craft cannot use it until its dependency is configured.           |

Built-in skills currently cover presentations, company search, image generation, and website navigation.
The exact list you see depends on what your organization has enabled.

<Tip>
  A skill's description tells Craft when to use it. If Craft repeatedly misses a custom skill,
  make the description concrete about the tasks it covers, or select the skill explicitly in your prompt.
</Tip>

## Create a personal skill

Create a personal Skill when you have instructions, examples, or reference files you want to reuse across sessions.
Open **Skills**, select **Create skill**, then choose how you want to begin:

| Starting point                      | Choose                 | What happens                                                                                            |
| ----------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- |
| You want to write the Skill in Onyx | **Start from scratch** | The Skill editor opens so you can write the details and instructions, then add supporting files.        |
| You already have a Skill            | **Upload a skill**     | Upload `SKILL.md`, a ZIP, or a Skill folder. Onyx reads the instructions and creates the Skill for you. |

Every new Skill is personal and private. After creating it, you can share it from the Skill editor.

### Start from scratch

<Steps>
  <Step title="Add the details">
    Enter a name and describe when Craft should use the Skill. Onyx uses the name to create the Skill's identifier,
    converting spaces and punctuation to hyphens when needed.
  </Step>

  <Step title="Write the instructions">
    Describe the workflow Craft should follow, including important constraints, expected outputs, and checks.
    Switch between the Markdown editor and preview to review the finished instructions.
  </Step>

  <Step title="Add supporting files">
    Add references, examples, templates, scripts, or assets under **Supporting files**. You can select files or a ZIP,
    or drag in a folder. Onyx unpacks ZIP files and preserves the directory structure.
  </Step>

  <Step title="Create the Skill">
    Select **Create**. Onyx saves the instructions as `SKILL.md` and opens the Skill editor, where you can manage files,
    sharing, and availability.
  </Step>
</Steps>

<Info>
  If you already have a Skill,
  use **Import skill** at the top of the creation page to fill in the form and add its files.
  If you have already entered content, Onyx asks before replacing the name, description, instructions,
  and supporting files with the imported Skill.
</Info>

### Upload an existing Skill

Upload `SKILL.md` directly when the Skill contains instructions only. When it includes supporting files,
upload a ZIP or drag in a folder with `SKILL.md` at the top level.

```text theme={null}
weekly-customer-update/
├── SKILL.md
├── examples/
│   └── finished-update.md
└── templates/
    └── update-template.md
```

At minimum, `SKILL.md` needs a name and description in YAML frontmatter, followed by the instructions Craft should use:

```md theme={null}
---
name: Weekly customer update
description: Create a concise weekly customer update from meeting notes and account activity.
---

# Weekly customer update

1. Summarize material changes since the previous update.
2. Separate customer decisions, open risks, and next steps.
3. Name an owner and due date for every next step.
4. Follow the format in `templates/update-template.md`.
```

<Steps>
  <Step title="Prepare the bundle">
    Put the instructions in `SKILL.md` and keep supporting files in the same folder. For a folder or ZIP,
    use a lowercase, hyphenated name such as `weekly-customer-update`; that name becomes the Skill's identifier.
    For a standalone `SKILL.md`, Onyx creates the identifier from its frontmatter `name`.
  </Step>

  <Step title="Upload the Skill">
    Open **Skills**, select **Create skill** > **Upload a skill**, and select `SKILL.md` or a ZIP.
    You can also drag `SKILL.md`, a ZIP, or a Skill folder into the upload area. Upload one Skill at a time,
    then select **Create**.
  </Step>

  <Step title="Review the Skill">
    Onyx opens the Skill editor after creating it. Review the name, description, instructions,
    and file tree before using or sharing the Skill.
  </Step>
</Steps>

### Update a Skill

Open a personal Skill to edit its name, description, or instructions. Under **Supporting files**, you can:

* Add individual files, ZIP files, or folders. New files are added to the existing bundle, and matching paths are
  replaced.
* Browse the bundle as a directory tree and remove files you no longer need. `SKILL.md` cannot be removed.
* Upload content that includes `SKILL.md` to replace the current name, description, instructions, and files. Onyx asks
  you to confirm before replacing the existing Skill content.

Changes are synchronized to people who can use the Skill. You can also disable the Skill without deleting it,
change its sharing, transfer ownership, or delete it.

<Warning>
  Never put passwords, API keys, tokens, or production credentials in a skill bundle.
  Use [Apps](/overview/core_features/craft_apps) for authenticated access to external services.
  Review every script and file before uploading a bundle you did not create.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="A skill is missing from the picker">
    Confirm the skill is enabled and shared with you. Unavailable built-in skills do not appear in the session picker.
    If the skill depends on a model or deployment feature, ask an admin to configure that dependency.
  </Accordion>

  <Accordion title="Craft did not use the skill I expected">
    Select the skill from **+** > **Skills** or type **/** and choose it before sending your prompt.
    Also name the desired output and important constraints; a skill supplies a method, not the goal itself.
  </Accordion>

  <Accordion title="My Skill will not upload">
    Upload one Skill at a time. Put `SKILL.md` at the top level of the folder. In a ZIP,
    place it at the archive root or directly inside one enclosing folder.
    Confirm that its frontmatter contains non-empty `name` and `description` fields. For a folder or ZIP,
    check that its name is lowercase and hyphenated. If you started from scratch, try a different Skill name.
    A custom Skill cannot use the same identifier as an existing or built-in Skill.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="For admins" icon="user-shield" href="/admins/managing_features/craft_skills">
    Publish organization skills, configure availability, and review custom bundles.
  </Card>

  <Card title="Connect Apps" icon="plug" href="/overview/core_features/craft_apps">
    Give Craft controlled access to external tools and approve actions safely.
  </Card>
</CardGroup>


# Image Generation
Source: https://docs.onyx.app/overview/core_features/image_generation

Create visuals according to user prompts

## Overview

The image generation feature allows users to create PNG images according to their prompts which can be rendered in the
chat and easily downloaded.

<img alt="Image Generation" />

## Configuration

Currently, Onyx supports five models for image generation, through OpenAI, Azure or Vertex (Google). In the future,
we will be adding support for other options such as Stability AI.

**GPT-Image-1.5**: Newest model, best for production-quality generation,
with strong prompt control and reliable in-image text/structured layouts

**GPT-Image-1**: Newer model, better prompt adherence. Likely a better default for most use cases.

**Nano Banana**: Flash Gemini model designed for fast and efficient image generation. Great for fast,
creative exploration and simple tasks.

**Nano Banana Pro**: Advanced Gemini model with professional and high-fidelity 4K output.
Great for complex tasks where consistency and details are key.

**DALL-E 3**: Older model, slightly better for more imaginative and rich styles.

## Usage

Configure your image generation models in the Admin Panel under **Configuration** → **Image Generation**.

Once configured, you can invoke the Image Generation action from any Agent or AI model in Onyx.

<Tip>
  Be explicit in prompting for specific Actions you want your Agent to invoke.
</Tip>


# RAG and Search
Source: https://docs.onyx.app/overview/core_features/internal_search

Enterprise Search across all your applications

One of Onyx's most standout features is the ability to enrich the LLM's general world knowledge with context unique to
your team. Onyx uses [Connectors](/overview/core_features/connectors)
to index knowledge from your team's applications to build an understanding of the documents, people,
and concepts within your organization.

Documents, metadata, and access permissions are all kept up to date in near real time.

## Search UI

<Tip>
  On the top left of the page, you can select the mode of the UI.
  Replace "Auto" with "Search" to always go into this view.
</Tip>

<img alt="Onyx Search Interface" />

<Info>
  Onyx's context retrieval respects user level permissions which is only configurable via the Enterprise Edition.
</Info>

Onyx's knowledge connectivity can be used via both the **Search** and [Chat](/overview/core_features/chat) interface.
The Search interface provides a better view of documents and is better for quickly accessing documents when the intent
is not to get an answer.

Users do not need to explicitly select this mode — when a query is classified by Onyx as a document search,
it will automatically go into this UI experience.

### Filters

The Search UI also provides more advanced filtering options:

<img alt="Top Search Filters" />

The top bar allows users to filter by time ranges (date range / time offset), authors, and tags (e.g. `Folder:
Engineering`).

<img alt="Top Search Filters" />

The side filters allow users to filter by the source type of the documents.

## Chat UI

Context from your applications are also available in the Chat UI and to Onyx Agents.
Deep Research mode is also a Chat UI feature.

Click [here](/overview/core_features/chat) to learn more about the Chat experience.


# Voice Mode
Source: https://docs.onyx.app/overview/core_features/voice_mode

Interact with Onyx using voice

## Overview

<img alt="Voice Mode listening" />

Voice Mode lets you interact with Onyx using speech instead of text. Speak your questions and hear responses read back.
Ideal for hands-free use, brainstorming, or quickly getting answers while multitasking.

## Speech-to-Text

To use Voice Mode, click the **microphone** icon in the input bar.
Onyx will begin listening for your input and transcribe your speech in real time.

* **Speak naturally**: Onyx transcribes your speech as you talk.
* **Pause**: Use the pause button to temporarily stop and resume when ready.

<Note>
  Voice Mode requires microphone access in your browser. You will be prompted to grant permission on first use.
</Note>

## Text-to-Speech

<img alt="Voice Mode speaking" />

Once your message is sent, Onyx generates a response and reads it back as audio.
The full text is displayed alongside the audio playback.

<img alt="Read Aloud button" />

If you don't have auto-playback enabled, you can press the **Read Aloud** button to have the response read back to you.

## User Settings

You can configure your voice preferences in the user settings panel:

<img alt="Voice Mode Settings" />

* **Auto-send**: When enabled, your message is automatically sent when you pause speaking,
  so you don't need to click send. When disabled, pausing does not send your message. Instead,
  click the microphone button to finish recording and send.
* **Auto-playback**: When enabled, the microphone will automatically start listening again as soon as the response
  finishes speaking, enabling a continuous hands-free flow. When disabled,
  the response is generated as text only and must be played manually.
* **Speed**: Adjust the playback speed of voice responses with a slider ranging from **0.5x** (slower)
  to **2x** (faster).


# Web Search
Source: https://docs.onyx.app/overview/core_features/web_search

AI-powered web search

## Overview

<img alt="Web Search" />

Onyx can access the internet for questions that require up to date information or for niche information that the LLM may
not be certain about.

Users can toggle the **Web Search** Action on the fly to override the LLM's decision.
If [Internal Search](/overview/core_features/internal_search) was used during the research process,
Onyx will seamlessly combine web sources with internal documents in both the answer generation and for displaying in the
UI.

## Requirements

To provide Web Search functionality,
Onyx requires both the ability to get search results and to be able to parse websites for more complete context.
This is broken down into 1) *the search provider* and 2) *the web scraper*.

### Search Providers

Onyx provides multiple search providers (pricing subject to change, please double check):

| Name       | Provider         | Price                                  | Benefit                                                                                        |
| ---------- | ---------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Exa        | Exa.ai           | \$5/1000 queries                       | AI-optimized with better semantic capabilities.                                                |
| Serper     | Serper.dev       | Free tier + \$0.30/1000 queries        | Fast and cost-effective.                                                                       |
| Brave      | Brave Search API | Usage-based                            | Independent search index with strong web coverage and simple API-based setup.                  |
| Google PSE | Google           | Free tier + \$5/1000 queries           | Official Google search results, high-trust option for security-conscious teams.                |
| SearXNG    | SearXNG          | Self-hosted / infrastructure cost only | Self-hostable metasearch option that can aggregate multiple engines and keep searches private. |

### Web Scrapers

As the Search Providers only give short snippets and metadata,
a scraper is used to fetch the full site contents for more complete/reliable answers.

| Name             | Requires Config         | Benefits                                                                                              |
| ---------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| Onyx Web Crawler | No                      | Built-in crawler that works for most pages, keeps queries in your deployment, and is free to use.     |
| Firecrawl        | Yes, API key + base URL | More performant with better edge case handling.                                                       |
| Exa              | Yes, API key            | Fetches and summarizes page content through Exa for teams already using Exa as their search provider. |


# FAQ
Source: https://docs.onyx.app/overview/getting_started/faq

Frequently asked questions about using Onyx

## General Questions

<AccordionGroup>
  <Accordion title="What kind of questions can I ask Onyx?">
    You can ask Onyx about general world knowledge known to the LLM,
    knowledge from [connected applications](/overview/core_features/internal_search),
    or things searchable on the web (if [Web Search](/overview/core_features/web_search) is configured)
  </Accordion>

  <Accordion title="How is my private data being processed?">
    Please check the [Security](/security/architecture/system_description) tab to learn more.
    Onyx is built with security and data privacy as a core commitment.
  </Accordion>

  <Accordion title="How do I know if Onyx is right for me?">
    Onyx is built for teams of all sizes whether it's a single user looking for a local Chat UI or a global enterprise
    needing a unified GenAI solution for the entire workforce.
    Onyx emphasizes data privacy and security as well as reliable responses by connecting to knowledge whether private
    or from the web.
  </Accordion>

  <Accordion title="Can I run Onyx offline?">
    Yes, however Onyx needs an LLM to function properly.
    You can air gap the entire system but you would need to run a local LLM.
    Note that we strongly recommend using a recent and non-quantized LLM for the best experience.
  </Accordion>
</AccordionGroup>

## Technical Issues

<AccordionGroup>
  <Accordion title="Why is my Onyx deployment not coming up?">
    The most common culprit is under-resourcing the deployment.
    Please refer to the [Resourcing](/deployment/getting_started/resourcing) page to double check.
  </Accordion>

  <Accordion title="Responses are really slow, is this expected?">
    No! Onyx is intended to provide a fast and snappy experience. If the responses are slow,
    it may be due to a couple issues.

    * The LLM attached to the system is slow, has low throughput, or does not support streaming.
    * You've configured locally running models that are not the default but you do not have a GPU available to the
      system. Typically this is from setting a local reranking or embedding model.
  </Accordion>
</AccordionGroup>

## Knowledge and Search

<AccordionGroup>
  <Accordion title="Why can't Onyx find information that I know exists?">
    If it's an internal document,
    it may be because the indexing of the application has not completed or because the access controls are incorrectly
    set. In cases of failure, the system always defaults to least permissive.
    The most common failure is that the [connector](/admins/connectors/overview) is incorrectly configured.
  </Accordion>

  <Accordion title="Does Onyx keep its knowledge up to date?">
    Onyx connectors will fetch updates on a set schedule (typically 30 minutes),
    this polling frequency can be configured by the admin for each connector. The documents, metadata,
    and access permissions all receive updates.
  </Accordion>

  <Accordion title="Why is Onyx refusing to search the internet?">
    Web Search must be configured by an admin to be usable.
    It requires setting up one of the supported Search providers and also a scraper (though this is optional as Onyx
    provides one built in).
  </Accordion>
</AccordionGroup>


# Quickstart
Source: https://docs.onyx.app/overview/getting_started/quickstart

Recommended way to deploy Onyx in minutes

## Onyx CLI

The recommended way to install Onyx is the guided installer built into the [Onyx CLI](/overview/onyx_anywhere/cli):

```bash theme={null}
uv tool install onyx-cli && onyx-cli deploy install
```

The installer will:

* Check your system resources and requirements (installing Docker on Linux if needed)
* Let you choose between **Lite** and **Standard** deployment modes
* Prompt for the version of Onyx to deploy
* Set up the deployment configuration in `~/.config/onyx`
* Pull the Onyx containers, start them, and wait until every service is healthy

After installation, the same command group manages the deployment: `onyx-cli deploy upgrade`, `status`, `logs`, `stop`,
and `uninstall`.

<Card title="Deploy with the Onyx CLI" icon="terminal" href="/deployment/local/onyx_cli">
  Full documentation for `onyx-cli deploy` and its lifecycle commands.
</Card>

## Installation Scripts

The installation scripts are thin wrappers around the CLI:
they install `onyx-cli` if needed and run `onyx-cli deploy install`, producing the same deployment as the command above.
Use them when you want a single copy-paste one-liner:

<Tabs>
  <Tab title="Linux / macOS">
    ```bash theme={null}
    curl -fsSL https://onyx.app/install_onyx.sh | bash
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://onyx.app/install_onyx.ps1 | iex
    ```
  </Tab>
</Tabs>

Or download the script and run it manually:

<CardGroup>
  <Card title="Linux / macOS (Bash)" icon="terminal" href="https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.sh">
    Download **install.sh** and run it with `bash install.sh`.
  </Card>

  <Card title="Windows (PowerShell)" icon="windows" href="https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.ps1">
    Download **install.ps1** and run it with `.\install.ps1` in PowerShell.
  </Card>
</CardGroup>

<Info>
  Older versions of the scripts were standalone and installed into a directory called **onyx\_data**.
  The Onyx CLI detects those deployments and manages them in place — see [migrating an existing
  deployment](/deployment/local/onyx_cli#migrating-an-existing-deployment).
</Info>

## Next Steps

<CardGroup>
  <Card title="Set Up the Desktop App" icon="desktop" href="/deployment/local/desktop_app">
    Install the Onyx desktop application for a native experience on Windows, macOS, and Linux.
  </Card>

  <Card title="Deploy Onyx on AWS EC2" icon="aws" href="/deployment/cloud/aws/ec2">
    Follow our guide to deploy Onyx on an AWS EC2 instance.
  </Card>
</CardGroup>


# Use Cases
Source: https://docs.onyx.app/overview/getting_started/use_cases

Ideas for an AI-powered workplace.

<Tip>
  [See how Ramp uses Onyx](https://www.onyx.app/blog/ramp-case-study)
  to automatically resolve 93% of internal and customer questions!
</Tip>

## AI-Powered Team

Give your team secure access to all major LLMs such as GPT, Claude, Gemini, Deepseek, Llama,
and more - all with access to advanced utilities.

<AccordionGroup>
  <Accordion title="Chat with uploaded files and URLs">
    Use LLMs to help quickly summarize documents, explain key concepts, or create derivative works.
  </Accordion>

  <Accordion title="Access up to date information">
    Get answers to any topic using a combination of Web Search and internal knowledge or run a deeper exploration with
    Deep Research.
  </Accordion>

  <Accordion title="Run data analysis">
    Execute code to run complex data crunching tasks, generate graphs to help visualize results,
    and chat with the LLM to interpret the results.
  </Accordion>

  <Accordion title="Generate mockups and accelerate creative work">
    Generate images, draft content from scratch, or refine existing works with AI suggestions.
  </Accordion>
</AccordionGroup>

## Enterprise Search

Quickly access knowledge across all of your team's applications from wikis to chats and everything in between.

<AccordionGroup>
  <Accordion title="Find documents in seconds">
    A single interface to find knowledge across the entire organization.
  </Accordion>

  <Accordion title="Identify opportunities in knowledge management">
    Leverage analytics and users feedback to identify holes in your team's knowledge base.
    Reduce misinformation and downstream costs.
  </Accordion>

  <Accordion title="Accelerate teammate onboarding">
    Let new team members unblock themselves and reduce distractions for more senior members.
  </Accordion>
</AccordionGroup>

## Sales

Help your sales team stay up to date and focus on closing.

<AccordionGroup>
  <Accordion title="Get up to speed before customer calls">
    Instantly access customer history, past interactions,
    and account details before any call or ask questions against past call transcripts.
  </Accordion>

  <Accordion title="Investigate competitors with Deep Research">
    Gather competitive intelligence and stay ahead of the market.
  </Accordion>

  <Accordion title="Analyze your sales pipeline">
    Create custom Agents to run deep analysis on your pipeline based on all connected knowledge.
  </Accordion>
</AccordionGroup>

## Support

Keep customers happy with faster resolutions and more reliable support.

<AccordionGroup>
  <Accordion title="Resolve customer requests faster">
    AI helps your team quickly surface past tickets and runbooks to craft accurate answers for users.
  </Accordion>

  <Accordion title="Provide more correct answers">
    Onyx ensures that all knowledge is kept up to date with any product or documentation changes.
  </Accordion>

  <Accordion title="Automate handling of repeat questions">
    Build automations on Onyx to automatically resolve up to >90% of customer tickets.
  </Accordion>
</AccordionGroup>

## Engineering

Help your team ship with speed and confidence through access to GenAI and internal knowledge.

<AccordionGroup>
  <Accordion title="Generate code and explain technical concepts">
    Accelerate development by having an AI copilot for every developer.
  </Accordion>

  <Accordion title="Learn about internal APIs, libraries, and technical specs">
    Have Onyx find and explain design docs, internal services,
    and relevant other projects to ensure devs have full context for every project.
  </Accordion>

  <Accordion title="Reduce repeat work">
    Quickly check against past tickets and projects to avoid duplicate work and accumulation of tech debt.
  </Accordion>
</AccordionGroup>


# Contact Us
Source: https://docs.onyx.app/overview/miscellaneous/contact_us

Excited to hear from you!

Shoot us a message at [hello@onyx.app](mailto:hello@onyx.app) or join our [Discord](https://discord.gg/TDJ59cGV2X).

To contact the founders, please email [founders@onyx.app](mailto:hello@onyx.app).

<img alt="Onyx" />


# Open Source Statement
Source: https://docs.onyx.app/overview/miscellaneous/open_source_statement

Onyx's commitment to open source principles

## Our Mission

Our mission is to make Generative AI and knowledge accessible to every team worldwide.
As large language models—both proprietary and open-source—become increasingly widespread,
Onyx serves as the interface to their knowledge and reasoning capabilities.

Onyx enriches the utility of the LLM by providing additional context (both web and team internal),
built-in tools like code execution, and user created Actions.

## Why Open Source?

<Card title="Security" icon="shield-check">
  We believe teams should feel safe with the AI platform that they adopt. That's why Onyx is fully transparent.
  You'll have peace of mind knowing exactly how your data is processed and stored,
  and all of this happening within the Onyx deployment.
</Card>

<Card title="Flexibility" icon="puzzle-piece">
  With GenAI being such a fundamental piece of modern company strategy,
  we want to offer the most flexible and future proof option.
  We understand that every team is unique in their needs so we're building Onyx with an emphasis on customizability,
  both for building on top of the platform and directly modifying it.
</Card>

<Card title="Control" icon="hand-fist">
  Open source also gives control over to your team. With the GenAI space rapidly evolving,
  your vendor of choice may not always be aligned with your team's direction.
  OSS combines the benefits of building in-house with getting product updates for free.
  Open source also prevents lock in so that you can leverage any LLM provider (or your own LLM).
</Card>

## Commercial Viability

We are a team of builders and we want to have as many people find value from our software as possible.
This is our singular goal and everything that we do derives from this.
To push the boundaries of user experience and AI innovation,
we've assembled a core team of world-class developers who share this vision.

To borrow from Sid Sijbrandij (Co-Founder, GitLab):

> "We need to think in the interests of the project, while tending to the realities of running a business to support it... After all, we know that to sustain the project, we need to make it commercially viable."

We believe in radical transparency—both in how we build open software and in the commercial realities of competing in
this rapidly evolving space.

<Note>
  Every organization, regardless of size or budget, will always have access to Onyx's core capabilities—including RAG,
  deep research, custom agents, and more—completely free.
</Note>

For organizations with special requirements—such as usage auditing, granular access controls,
and white-labeling—we offer the Enterprise Edition, available both as a self-hosted solution and through Onyx Cloud.

The Enterprise Edition sustains our mission,
enabling us to keep the vast majority of Onyx's features free and open for everyone.

## On Contributions

Onyx is a project built in collaboration with our community and we openly welcome contributions.
It is a point of emphasis of our team to ensure that the Onyx project continues to be easy for teams to contribute to or
maintain in house. This comes down to:

* Intentional high level architecture.
* Strong product direction and refusal to accept bloat for niche use cases.
* A consistent and high quality of engineering best practices across the code base.

To that end,
we ask that contributors work on smaller issues to start and get approval from the maintainers for larger feature
contributions.


# Chrome Extension
Source: https://docs.onyx.app/overview/onyx_anywhere/chrome_extension

Accessing Onyx via a Chrome Extension

Use the Onyx extension to ask questions from anywhere. You can also replace your new-tab page with a custom Onyx page:

Features include:

* Onyx Search on new tabs
* Onyx as a sidebar to any page in Chrome
* Contextual search on selected text

<img
  alt="Onyx Chrome extension
new-tab search and sidebar"
/>

<Note>
  In the future,
  the Onyx Chrome Extension will allow you to ask questions about the full page you are currently on and optionally
  index the recent pages into the Onyx knowledge base.
</Note>

## Getting Started

Once your administrator has set up the Chrome extension for your organization, you can start using it immediately.

**For Onyx Cloud users**: Install directly from the Chrome Web Store

**For self-hosted users**: Your administrator will provide installation instructions

## Using the Extension

### **New Tab Experience**

* Replace your default new tab with Onyx search
* Quick search across your organization's knowledge

### **Sidebar Mode**

* Open Onyx as a sidebar on any webpage
* Ask questions about your current work without leaving the page
* Perfect for research and context-sensitive queries

### **Selection Search**

* Highlight any text on a webpage
* Click the Onyx icon that appears
* Instantly search or ask questions about the selected text in the sidebar

### **Shortcuts**

* **Mac**: `Cmd+Shift+O` to toggle New Tab, `Ctrl+O` to open Sidebar
* **Windows/Linux**: `Ctrl+Shift+O` to toggle New Tab, `Alt+O` to open Sidebar
* **Omnibox**: Type `onyx` then `Tab` in the address bar to search directly

## Settings and Options

To customize your extension experience:

<Steps>
  <Step title="Open extension menu">
    Click the three dots (...) next to the Onyx extension
  </Step>

  <Step title="Open Options">
    Select **Options**
  </Step>

  <Step title="Configure preferences">
    Configure your preferences for search and new tab behavior
  </Step>
</Steps>

## Deployment

For detailed deployment instructions, including self-hosted installation and enterprise deployment,
see the [Chrome Extension Deployment Guide](/deployment/configuration/chrome_extension).

<Info>
  **Need help with setup?** Contact your Onyx administrator for installation assistance or configuration questions.
</Info>


# CLI
Source: https://docs.onyx.app/overview/onyx_anywhere/cli

Interact with Onyx from the command line

<img alt="Onyx CLI terminal interface" />

The Onyx CLI is a terminal interface for chatting with your Onyx agents and querying your knowledge base.
Built with Go using [Bubble Tea](https://github.com/charmbracelet/bubbletea),
it provides both an interactive TUI and non-interactive commands for scripting and automation.

## Installation

### PyPI (recommended)

```shell theme={null}
uv tool install onyx-cli
```

Or with pip:

```shell theme={null}
pip install onyx-cli
```

<Card title="PyPI Package" icon="python" href="https://pypi.org/project/onyx-cli/">
  uv tool install onyx-cli
</Card>

### Build from Source

Requires [Go 1.26+](https://go.dev/dl/).

```shell theme={null}
git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/cli
go build -o onyx-cli .
sudo mv onyx-cli /usr/local/bin/
```

## Setup

Run the interactive setup to configure your server URL and API key:

```shell theme={null}
onyx-cli configure
```

This prompts for your Onyx server URL and API key, tests the connection,
and saves config to `~/.config/onyx-cli/config.json`.

### Generating an Access Token

Navigate to **User Settings > Accounts & Access > New Access Token** (`/app/settings/accounts-access`)
to create an access token for the CLI.

<img alt="Accounts & Access page showing the Access Tokens section" />

<img alt="Create Access Token modal with token name and expiration options" />

### Environment Variables

Environment variables override config file values. This is useful for CI/CD pipelines and scripting.

| Variable          | Required | Description                                         |
| ----------------- | -------- | --------------------------------------------------- |
| `ONYX_SERVER_URL` | No       | Server base URL (default: `https://cloud.onyx.app`) |
| `ONYX_API_KEY`    | Yes      | API key for authentication                          |
| `ONYX_PERSONA_ID` | No       | Default agent/persona ID                            |

### Validate Configuration

Verify that your configuration is correct and the server is reachable:

```shell theme={null}
onyx-cli validate-config
```

## Commands

| Command                    | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `onyx-cli`                 | Launch the interactive chat TUI (default)        |
| `onyx-cli ask`             | Ask a one-shot question (non-interactive)        |
| `onyx-cli agents`          | List available agents                            |
| `onyx-cli configure`       | Configure server URL and API key                 |
| `onyx-cli validate-config` | Validate configuration and test connection       |
| `onyx-cli deploy`          | Install and manage a self-hosted Onyx deployment |

### Interactive Chat

```shell theme={null}
onyx-cli
```

Opens a full-screen terminal UI for conversational interaction with your Onyx agents.

### One-Shot Questions

Ask a question and get a response without entering the TUI:

```shell theme={null}
onyx-cli ask "What is our company's PTO policy?"
```

Use `--agent-id` to target a specific agent:

```shell theme={null}
onyx-cli ask --agent-id 5 "Summarize our Q4 roadmap"
```

Use `--json` for structured NDJSON output (useful for scripting):

```shell theme={null}
onyx-cli ask --json "List all active API integrations"
```

| Flag               | Description                                |
| ------------------ | ------------------------------------------ |
| `--agent-id <int>` | Agent ID to use (overrides default)        |
| `--json`           | Output NDJSON events instead of plain text |

### List Agents

```shell theme={null}
onyx-cli agents
onyx-cli agents --json
```

Prints a table of available agent IDs, names, and descriptions.

### Self-Hosted Deployment

The `deploy` command group installs and manages a self-hosted Docker Compose deployment of Onyx — a guided installer
plus `upgrade`, `status`, `logs`, `stop`, and `uninstall` commands:

```shell theme={null}
onyx-cli deploy install
```

<Card title="Deploy with the Onyx CLI" icon="server" href="/deployment/local/onyx_cli">
  Full documentation for `onyx-cli deploy` and its lifecycle commands.
</Card>

## Slash Commands (Interactive TUI)

When using the interactive chat, the following slash commands are available:

| Command          | Description                   |
| ---------------- | ----------------------------- |
| `/help`          | Show help message             |
| `/new`           | Start a new chat session      |
| `/agent`         | List and switch agents        |
| `/attach <path>` | Attach a file to next message |
| `/sessions`      | List recent chat sessions     |
| `/clear`         | Clear the chat display        |
| `/configure`     | Re-run connection setup       |
| `/connectors`    | Open connectors in browser    |
| `/settings`      | Open settings in browser      |
| `/quit`          | Exit Onyx CLI                 |

## Using as an AI Coding Assistant Skill

The Onyx CLI can be used as a tool by AI coding assistants (such as Claude Code and Cursor)
to query your knowledge base directly from within your development environment.
A pre-built skill definition is available in the Onyx repository at
[`.cursor/skills/onyx-cli/SKILL.md`](https://github.com/onyx-dot-app/onyx/blob/main/cli/internal/embedded/SKILL.md).

Once configured, the AI assistant can call `onyx-cli ask` to look up company-specific information — policies,
internal docs, connected data sources — without leaving the editor.

### When the skill is invoked

The skill is triggered when you ask your AI assistant about:

* Company-specific information (policies, processes, documentation)
* Internal knowledge bases or connected data sources
* Anything referencing Onyx, "search Onyx", or querying company documents

It is **not** used for general programming questions or questions about code in the current repository.

### Configuration for agents

The simplest approach is to run `onyx-cli configure` once manually — after that,
AI assistants can invoke `onyx-cli ask` directly without any additional setup.

```shell theme={null}
onyx-cli configure
```

Alternatively, you can configure via environment variables,
which override the config file and are useful for CI/CD or sandboxed environments:

```shell theme={null}
export ONYX_SERVER_URL="https://your-onyx-server.com"
export ONYX_API_KEY="your-api-key"
```

### JSON output for structured parsing

Use `--json` to get NDJSON event output, which is easier for agents to parse programmatically:

```shell theme={null}
onyx-cli ask --json "List all active API integrations"
```

| Event Type          | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `message_delta`     | Content token — concatenate all `content` fields for the full answer |
| `stop`              | Stream complete                                                      |
| `error`             | Error with `error` message field                                     |
| `search_tool_start` | Onyx started searching documents                                     |
| `citation_info`     | Source citation with `citation_number` and `document_id`             |

## Keyboard Shortcuts

| Key                        | Action                    |
| -------------------------- | ------------------------- |
| `Enter`                    | Send message              |
| `Escape`                   | Cancel current generation |
| `Ctrl+O`                   | Toggle source citations   |
| `Ctrl+D`                   | Quit (press twice)        |
| `Scroll` / `Shift+Up/Down` | Scroll chat history       |
| `Page Up` / `Page Down`    | Scroll half page          |


# Desktop App
Source: https://docs.onyx.app/overview/onyx_anywhere/desktop_app

Accessing Onyx via the desktop application

Use the Onyx desktop app for a integrated, seamless experience on your computer.
Access your organization's knowledge base without opening a browser:

Features include:

* Quick-launch from your system tray or dock
* Desktop notifications

<img alt="Onyx Desktop App" />

<Note>
  The Onyx Desktop App provides the same powerful features as the web interface,
  optimized for desktop use with OS integrations.
</Note>

## Download

<CardGroup>
  <Card title="Windows" icon="windows" href="https://github.com/onyx-dot-app/onyx/releases/latest/download/Onyx_x64.exe">
    Download .exe
  </Card>

  <Card title="macOS" icon="apple" href="https://github.com/onyx-dot-app/onyx/releases/latest/download/Onyx_universal.dmg">
    Download .dmg
  </Card>

  <Card title="Linux" icon="linux" href="https://github.com/onyx-dot-app/onyx/releases/latest/download/Onyx_amd64.deb">
    Download .deb
  </Card>
</CardGroup>

<Tip>
  Additional architectures and formats (.msi, .rpm, .app.tar.gz)
  available on the [GitHub Releases page](https://github.com/onyx-dot-app/onyx/releases/latest).
</Tip>

## Getting Started

**For Onyx Cloud users**: Download from the links above

**For self-hosted users**: Your administrator may provide pre-configured installation files,
or you can configure your Onyx server URL on first launch

<Info>
  **Need help?** Contact your Onyx administrator for installation assistance or configuration questions.
</Info>


# Discord Bot
Source: https://docs.onyx.app/overview/onyx_anywhere/discord_bot

Access Onyx within Discord

## Overview

The Onyx Discord bot allows you to use Onyx AI chat directly on any Discord server.

Use the official OnyxBot connected to our Cloud, or deploy your own Discord bot with your self-hosted Onyx instance.

<img alt="Discord Bot" />

## Features

* Install on any server you manage
* Configure behavior per server and channel and custom agents
* Reply or thread-only mode
* Works in forums, threads, and channels

## Try it out

Follow the [installation guide](/admins/miscellaneous/discord_bot)
to install the OnyxBot on your Discord server ([installation
link](https://discord.com/oauth2/authorize?client_id=1460722463431327804)).

To test it out, join the [Onyx community Discord](https://discord.gg/rkCS5RY4)
and tag **@OnyxBot** from the #support channel!


# MCP Server
Source: https://docs.onyx.app/overview/onyx_anywhere/mcp_server

Access Onyx from Claude, Cursor, and other AI tools via the Model Context Protocol

## Overview

The Onyx MCP Server lets you connect any MCP-compatible AI tool to your Onyx knowledge base. Ask Claude, Cursor,
Windsurf, or any other MCP client to search your company's documents without leaving your workflow.

<Tip>
  Onyx can also act as an MCP client! See the [MCP Actions](/admins/actions/mcp)
  guide to connect external MCP servers to your Onyx Agents.
</Tip>

## What You Can Do

* **Search your knowledge base** — query Confluence, Google Drive, Slack, GitHub, Jira, and 40+ other sources
* **Search the web** — find current events and public information
* **Fetch full page content** — retrieve complete text from any URL

All of your existing Onyx permissions and access controls are enforced automatically.

## Supported Clients

Any client that supports the Model Context Protocol over HTTP works with Onyx, including:

* [Claude Desktop](https://claude.ai/download)
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
* [Cursor](https://cursor.com)
* [Windsurf](https://codeium.com/windsurf)
* Any other [MCP-compatible client](https://modelcontextprotocol.io/)

## Quick Setup

Add this to your MCP client's configuration:

```jsonc theme={null}
{
  "mcpServers": {
    "onyx": {
      "url": "https://cloud.onyx.app/mcp", // or your self-hosted Onyx domain
      "headers": {
        "Authorization": "Bearer YOUR_ONYX_TOKEN_HERE"
      }
    }
  }
}
```

Replace `YOUR_ONYX_TOKEN_HERE` with a [Personal Access Token](/developers/overview#personal-access-tokens)
or [API Key](/admins/user_management/api_keys).

## Learn More

<CardGroup>
  <Card title="Full MCP Server Guide" icon="book-open" href="/deployment/configuration/mcp_server">
    Detailed setup instructions, tool reference, troubleshooting, and self-hosting configuration
  </Card>

  <Card title="Personal Access Tokens" icon="key" href="/developers/overview#personal-access-tokens">
    Create a token to authenticate with the MCP server
  </Card>
</CardGroup>


# Mobile App (Coming Soon)
Source: https://docs.onyx.app/overview/onyx_anywhere/mobile_app

Access Onyx from mobile devices

<Note>
  Currently Onyx is a responsive application and so your Onyx deployment will work on your smartphone or tablet via your
  browser app.

  While is is not as nice of an experience as a native app,
  it can be used in the meantime while the Onyx Mobile App is under development.
</Note>

## Mobile App

The Onyx mobile app is currently under development.

This native mobile application will bring the full power of Onyx to your smartphone and tablet devices.


# Slack Bot
Source: https://docs.onyx.app/overview/onyx_anywhere/slack

Accessing Onyx within Slack

## Overview

<img alt="Slack" />

Bring Onyx's AI capabilities directly into your conversations via Slack App.

Onyx allows for highly flexible Slack configurations so that you use all of your Onyx Agents directly in your favorite
channels.

## Supported Features

* Support for unlimited Slack Apps. This way you can associate Slack Apps with Onyx Agents for specific use cases.
* Channel level configurations. Every channel can have different default behavior based on the channel's purpose.
* Answers using internal or web knowledge are backed by citations and link back to the original sources.
* Works in Threads, Channels and DMs.

<Tip>
  Try asking Onyx to summarize Threads by tagging the Onyx Slack Bot in the Thread!
</Tip>

## Try it out

The Onyx Slack Bot is always live and serving answers to the community in our public Slack.

To test it out,
join the [community Slack](https://join.slack.com/t/onyx-dot-app/shared_invite/zt-34lu4m7xg-TsKGO6h8PDvR5W27zTdyhA)
and see the #ask-onyx channel or tag **@OnyxBot** from anywhere.

<img alt="OnyxBot" />


# Website Widget
Source: https://docs.onyx.app/overview/onyx_anywhere/website_widget

Embed Onyx AI chat on any website

## Overview

Bring Onyx's AI capabilities directly to your website with an embeddable chat widget. Built with [Lit](https://lit.dev/)
web components for maximum compatibility and minimal bundle size.

The widget integrates seamlessly with any website,
providing your visitors instant access to AI-powered conversations without leaving your page.

## Features

* **Lightweight** - \~100-150kb gzipped bundle
* **Fully Customizable** - Colors, branding, and styling to match your site
* **Responsive** - Desktop popup, mobile fullscreen
* **Shadow DOM Isolation** - No style conflicts with your existing CSS
* **Real-time Streaming** - Server-sent events (SSE) for fast responses
* **Session Persistence** - Conversations survive page reloads
* **Two Display Modes** - Floating launcher or inline embed
* **Source Citations** - Optional citation badges linking to source documents

## Quick Start

Add these few lines to your website:

```html theme={null}
<!-- Load the widget -->
<script type="module" src="https://cdn.onyx.app/widget/1.1/dist/onyx-widget.js"></script>

<!-- Configure and display -->
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="your_api_key_here"
  mode="launcher"
>
</onyx-chat-widget>
```

That's it! The widget will appear as a floating button in the bottom-right corner of your page.

<Warning>
  **Always use a limited-scope API key for the widget.** The API key is visible in client-side code,
  so it should have restricted permissions and rate limits. Never use admin or full-access keys.
</Warning>

## Display Modes

### Launcher Mode (Default)

<video alt="Onyx Widget Chat Popup" />

A floating button appears in the bottom-right corner. Clicking it opens a chat popup.

* **Desktop**: 400x600px popup above the button
* **Mobile**: Full-screen overlay for optimal mobile experience

```html theme={null}
<onyx-chat-widget mode="launcher"></onyx-chat-widget>
```

### Inline Mode

<video alt="Onyx Widget Inline Mode" />

The widget embeds directly in your page layout. Perfect for dedicated support pages or knowledge bases.

```html theme={null}
<div style="width: 400px; height: 600px;">
  <onyx-chat-widget mode="inline"></onyx-chat-widget>
</div>
```

<Tip>
  The widget will fill its container's dimensions in inline mode. Set the container size to control the widget size.
</Tip>

## Configuration Options

### Required Attributes

| Attribute     | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `backend-url` | string | Your Onyx backend API URL  |
| `api-key`     | string | API key for authentication |

### Optional Attributes

| Attribute           | Type    | Default       | Description                                      |
| ------------------- | ------- | ------------- | ------------------------------------------------ |
| `agent-id`          | number  | `undefined`   | Specific agent/persona to use                    |
| `agent-name`        | string  | `"Assistant"` | Display name in header                           |
| `logo`              | string  | Onyx logo     | URL to custom logo image                         |
| `primary-color`     | string  | `#1c1c1c`     | Primary brand color (buttons, accents)           |
| `background-color`  | string  | `#e9e9e9`     | Widget background color                          |
| `text-color`        | string  | `#000000bf`   | Text color (75% opacity black)                   |
| `mode`              | string  | `"launcher"`  | Display mode: `"launcher"` or `"inline"`         |
| `include-citations` | boolean | `false`       | Show citation badges linking to source documents |

<Warning>
  **Citations and private documents:** When `include-citations` is enabled,
  the widget will cite any documents accessible to the configured agent or API key.
  If the agent has access to private or internal documents,
  citation links may point to resources that end users cannot view. Scope the agent's document access appropriately,
  or disable citations for public-facing deployments with sensitive sources.
</Warning>

### Configuration Examples

**Basic Setup:**

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123">
</onyx-chat-widget>
```

**Full Customization:**

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123"
  agent-id="42"
  agent-name="Support Bot"
  logo="https://yoursite.com/logo.png"
  primary-color="#FF6B35"
  background-color="#FFFFFF"
  text-color="#1A1A1A"
  mode="launcher"
  include-citations="true"
>
</onyx-chat-widget>
```

## Customization

### Styling

The widget uses CSS custom properties for theming.
All styles are scoped within Shadow DOM to prevent conflicts with your site's CSS.

**Default Colors:**

| CSS Variable           | Default     | Description           |
| ---------------------- | ----------- | --------------------- |
| `--onyx-primary`       | `#1c1c1c`   | Buttons, accents      |
| `--onyx-primary-hover` | `#000000`   | Hover state           |
| `--onyx-background`    | `#e9e9e9`   | Widget background     |
| `--onyx-text`          | `#000000bf` | Text (75% opacity)    |
| `--onyx-text-light`    | `#ffffff`   | White text on dark    |
| `--onyx-border`        | `#00000033` | Borders (20% opacity) |

**Override via attributes:**

```html theme={null}
<onyx-chat-widget
  primary-color="#FF6B35"
  background-color="#FFFFFF"
  text-color="#1A1A1A"
>
</onyx-chat-widget>
```

## Architecture

The widget communicates directly with your Onyx backend using Server-Sent Events (SSE)
for real-time streaming responses:

**Widget loads** - Lightweight JavaScript bundle initializes the web component

**Session created** - Widget creates a chat session via the Onyx API

**User sends message** - Request is sent to your Onyx backend

**Streaming response** - AI response streams back in real-time via SSE

**Markdown rendered** - Responses are formatted with full markdown support

## Browser Support

* Chrome/Edge 90+ (Chromium)
* Firefox 90+
* Safari 15+
* Mobile Safari (iOS 15+)
* Mobile Chrome (Android)

## Deployment

For detailed deployment instructions, including self-hosted setup and API key security best practices,
see the [Website Widget Deployment Guide](/deployment/configuration/website_widget).

<Info>
  **Need help with setup?** Contact your Onyx administrator for API key configuration or deployment assistance.
</Info>


# Access Controls
Source: https://docs.onyx.app/security/architecture/access_controls

Resource protection from users

## Single Sign On (SSO)

In both Community and Enterprise Editions of Onyx, you can configure basic authentication with email and password.

Additionally, you can configure SSO through popular identity providers such as Google, Okta, and Azure EntraID (OAuth,
OIDC, and SAML are all supported).

## Role-Based Access Control (RBAC)

RBAC protection to documents and resources are only available in the Enterprise Edition of Onyx.
The following resources can be gated by users and groups.

* Agents
* Actions
* Document access
* Usage rate limits

## Document Access

Different access to documents is only available in the Enterprise Edition of Onyx.
The two ways of gating access to documents are:

* Automatically mirroring them from external sources (such as Google Drive, Salesforce, etc.).
* Directly assigning access to users or groups of users. Often less convenient but requires less
  calls to external APIs which may be preferred in certain deployments.

## Permissions

Permissions are granted to groups, and a user receives the permissions of every group they belong to.

* **Basic**: the default group every user joins. Standard access to chat, search, and personal resources
* **Admin**: the group that grants full system access, audit, and configuration capabilities
* **Custom groups**: grant specific capabilities, such as managing connectors, agents, or query history
  (only available on Enterprise Edition)
* **Group Manager**: a user who manages one group's members and resources, without any
  organization-wide permissions

For the full model, see [Understanding Permissions](/admins/permissions/understanding_permissions).


# Craft Architecture
Source: https://docs.onyx.app/security/architecture/craft

Understand Craft isolation, data flows, credentials, approvals, and sharing

Craft adds an untrusted code-execution environment to Onyx. Onyx controls the sandbox lifecycle,
keeps credentials outside the sandbox, and mediates access to company knowledge, external services,
and generated web apps.

<img alt="Craft runtime architecture showing the browser, Onyx control plane, per-user sandbox, sandbox proxy, model providers, search, external Apps, and generated web apps" />

## Components and trust boundaries

| Component              | Role and access                                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Browser**            | Sends prompts and files, receives the event stream, shows approvals, and renders generated web apps.                   |
| **Onyx control plane** | Authenticates users, checks access, manages sessions and sandboxes, stores state, and proxies generated web apps.      |
| **Per-user sandbox**   | Runs model-generated code and tools. Each Craft session has a separate workspace inside the user's sandbox.            |
| **Sandbox proxy**      | Receives sandbox HTTP and HTTPS traffic, blocks internal destinations, injects credentials, and enforces App policies. |
| **Onyx storage**       | Stores session records, approvals, tasks, encrypted credentials, uploaded files, Skill bundles, and snapshots.         |
| **External services**  | Model providers, public websites, and configured Apps receive outbound requests through the sandbox proxy.             |

The sandbox is the untrusted boundary. It receives the files and instructions needed to complete work, but not raw Onyx,
model-provider, or App credentials.

## Request lifecycle

<Steps>
  <Step title="Onyx authorizes the request">
    The browser sends the prompt, attachments, model choice, and selected capabilities to the Onyx API.
    Onyx checks the user's Craft and model access.
  </Step>

  <Step title="Onyx prepares the workspace">
    Onyx creates or restores the user's sandbox, creates a directory for the session,
    and synchronizes the Skills and User Library files available to that user.
  </Step>

  <Step title="The agent runs in the sandbox">
    The sandbox calls the selected model, runs code and tools, and writes files into the session workspace.
    Onyx streams agent events back to the browser.
  </Step>

  <Step title="Network requests pass through the proxy">
    The sandbox proxy identifies the sandbox and session, blocks internal destinations,
    and injects credentials or requests approval when the destination requires it.
  </Step>

  <Step title="Onyx serves the result">
    Users inspect and download files through authenticated Onyx APIs.
    Onyx proxies generated web apps from the sandbox after checking the app's sharing scope.
  </Step>
</Steps>

## Sandbox and workspace isolation

Craft maintains one sandbox per user and a separate workspace for each session. The workspace contains attachments,
generated code, intermediate files, outputs, and the session's agent instructions.

Skills and User Library files are synchronized into a managed area of the sandbox and linked into each session.
Attachments belong only to their session, while User Library files remain available across the user's sessions.
Skill bundles can contain executable scripts, so they should be reviewed as code before being shared.

When a sandbox becomes idle, Onyx snapshots its session state to the configured file store and stops the runtime.
Onyx restores that state when the user returns. Snapshots support sleep and restore;
they are not user-facing version history.

| Backend            | Isolation boundary                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Kubernetes**     | A sandbox pod in a dedicated namespace, with scoped RBAC, an in-pod firewall, and NetworkPolicies.                         |
| **Docker Compose** | A sandbox container on a dedicated bridge, with an in-container firewall and no connection to the default Compose network. |

The Docker backend requires read-write Docker socket access from the API server and background worker.
This access is effectively root access to the host,
which is why Docker Compose is intended for small deployments on a trusted host.

## Network egress

The sandbox firewall permits DNS and the sandbox proxy path. Sandbox HTTP and HTTPS requests do not have a second,
direct route to the network.

The proxy applies different behavior based on the destination:

| Destination                           | Proxy behavior                                                                                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Onyx API**                          | Allows the configured API host and port and injects the sandbox's scoped Onyx credential.                                                     |
| **Supported model provider**          | Injects an accessible provider key for Anthropic, OpenAI, or OpenRouter.                                                                      |
| **Configured App**                    | Matches the URL and action, applies its policy, then injects organization or user credentials.                                                |
| **Other public destination**          | Forwards the request without privileged credentials or an App approval.                                                                       |
| **Private or non-global destination** | Blocks the request, including loopback, private networks, link-local addresses, and cloud metadata. The configured Onyx API is the exception. |

<Info>
  The proxy is an egress control and credential boundary, not a public-internet allowlist.
  Craft can browse websites and install packages from public destinations without an App connection.
</Info>

Kubernetes adds NetworkPolicies as a second control around sandbox-to-proxy and DNS traffic.
Docker sandboxes use a dedicated bridge that cannot resolve or reach Onyx's Compose services by name.
See the [Kubernetes](/deployment/local/craft_kubernetes) and [Docker Compose](/deployment/local/craft_docker_compose)
deployment guides for operator requirements.

## Credential handling

The sandbox receives placeholder values for credentials that Onyx manages. The proxy resolves the sandbox identity,
retrieves the correct credential, and adds it only to a matching outbound request.

| Credential                  | Stored by Onyx                                            | Injected for                               |
| --------------------------- | --------------------------------------------------------- | ------------------------------------------ |
| **Onyx sandbox credential** | Encrypted with the sandbox record                         | The configured Onyx API host and port      |
| **Model provider key**      | With the user's accessible provider configuration         | The matching supported model-provider host |
| **App credential**          | Encrypted organization or per-user App credential storage | URLs attributed to that App                |

Raw credentials exist in Onyx-controlled storage and briefly in proxy memory while a request is prepared.
They are not written into the sandbox workspace, Skill bundle, or generated files by the injection process.

## Company knowledge

Craft searches company knowledge through the Onyx API rather than connecting the sandbox directly to the vector database
or indexed sources. Onyx evaluates the request as the sandbox owner and applies that user's document permissions.

Enabling Craft, sharing a Skill, or connecting an App does not expand the user's indexed document access.
Search results can still become part of a prompt, generated file, or web app,
so users must review outputs before sharing them.

## Apps and approvals

Requests attributed to an App use the policies configured by an Admin:

| Policy           | Enforcement                                                        |
| ---------------- | ------------------------------------------------------------------ |
| **Auto-approve** | The proxy forwards the matched action without pausing.             |
| **Ask**          | The proxy parks the request until the user approves or rejects it. |
| **Deny**         | The proxy blocks the request.                                      |

For an **Ask** action, the approval flow is:

<Steps>
  <Step title="Park the request">
    The proxy stops the request before injecting App credentials.
  </Step>

  <Step title="Request a decision">
    Onyx sends an approval card to the session. The user approves once, approves matching actions for the session,
    or rejects the request.
  </Step>

  <Step title="Forward or block">
    The proxy forwards an approved request with credentials, or fails the request closed after rejection or expiry.
  </Step>
</Steps>

If a request matches multiple built-in App actions, the strictest policy wins: **Deny**, then **Ask**,
then **Auto-approve**. An uncataloged request to a built-in App falls back to **Ask**.
Custom Apps use **Ask** for every request matching their configured URL patterns.

Scheduled Tasks have no user present to answer an approval. A task owner can pre-approve an App for that task;
this permits the App's **Ask** actions during the run.
Pre-approval does not override **Deny** and applies to the whole App, not one action.

## Generated web apps

Onyx serves generated web apps through an authenticated proxy instead of exposing sandbox ports directly.
The proxy checks the session's sharing scope before forwarding a request:

| Scope            | Access                                    |
| ---------------- | ----------------------------------------- |
| **Private**      | Session owner only                        |
| **Organization** | Authenticated users in the Onyx workspace |

Sharing exposes the generated web app, not the Craft conversation or the session's file browser. However,
information written into the app itself is visible to everyone who can open it.

Before sending a request to the generated app server, the proxy removes the viewer's cookies, authorization headers,
CSRF headers, forwarding headers, and identity headers. It also strips `set-cookie` from the generated app's response.
The preview runs in a sandboxed iframe, with scripts, forms, and user-initiated navigation enabled.

<Warning>
  Generated client-side code runs in the viewer's browser.
  Browser-side requests are not sandbox egress and do not pass through the sandbox proxy.
  Review a generated app before sharing it with the organization.
</Warning>

## State and operational data

| Store                      | Craft data                                                                                               |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| **PostgreSQL**             | Sessions, sandbox records, sharing state, approvals, App configuration, tasks, and encrypted credentials |
| **Redis**                  | Streaming coordination, approval signaling, locks, and short-lived caches                                |
| **File store**             | Attachments, User Library content, Skill bundles, and sandbox snapshots                                  |
| **Active sandbox storage** | Session workspaces, generated files, agent state, and running web apps                                   |

<Warning>
  Treat Craft logs and traces as potentially sensitive. Depending on logging configuration, they can include prompts,
  file names, URLs, tool results, model interactions, and approval metadata.
</Warning>

## Security considerations

| Risk                                              | Mitigation                                                                                                    |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Model-generated code behaves unexpectedly         | Keep the sandbox boundary and proxy controls intact; review outputs before using or sharing them.             |
| A Skill contains unsafe instructions or scripts   | Review custom Skill bundles before granting broader access.                                                   |
| A user approves an unintended App action          | Keep consequential actions on **Ask** or **Deny** and make Scheduled Task pre-approvals narrow.               |
| Generated content includes sensitive company data | Document permissions protect retrieval, but users remain responsible for generated files and shared web apps. |
| Prompts and context leave Onyx                    | Review the data handling terms and configuration of each model provider and external App.                     |
| Docker socket compromise affects the host         | Use Kubernetes for broader deployments and restrict Docker Compose to trusted, controlled hosts.              |

<CardGroup>
  <Card title="Deploying Craft" icon="server" href="/deployment/local/craft">
    Choose a sandbox backend and configure its security controls.
  </Card>

  <Card title="Managing Craft" icon="sliders" href="/admins/managing_features/craft">
    Configure access, Apps, Skills, models, and workspace instructions.
  </Card>
</CardGroup>


# Data Flows
Source: https://docs.onyx.app/security/architecture/data_flows

How data and queries are handled and stored

## Indexing Flow

Documents from connectors and user uploads are processed by the Onyx indexing pipeline.
With default configurations no data ever leaves the deployment.

<img alt="Onyx Indexing Flow" />

<Note>
  The LLM-based contextual retrieval and the informativeness model are not enabled by default.
</Note>

Not shown in the diagram, MinIO (which runs locally)
acts as an intermediate store for the document before the downstream processing steps like chunking.

Onyx does also allow configuring the following options:

<Info>
  Note that overriding the default configurations may means that documents will be sent to your selected third party
  services for processing
</Info>

* API based embedding model. Teams may choose to do this instead of choosing between running their
  own GPUs, using a less capable embedding model, or accepting a slower initial indexing.
* Image captioning service. Connecting a vision-capable model lets files with embedded images, as
  well as standalone image files, be captioned into text so they can be represented for retrieval.
* Connecting an LLM for contextual retrieval. This uses the LLM to prepend a short, document-aware
  summary to each chunk so it carries the surrounding context,
  which improves retrieval accuracy for chunks that would otherwise be ambiguous on their own.

## Query Flow

<img alt="Onyx Query Flow" />

When users query Onyx, the LLM determines if the system should fetch additional context or respond to the user directly.

If additional context is needed, the system can run an internal search (outlined above),
invoke a built-in action (such as code execution or web search), or call an action configured by your admins.

By default, the system does not communicate data to any external systems outside of the admin configured LLM.

### Configurable External Services

Admins of the system can configure support for external services to enrich the user experience.

<Tip>
  It is recommended to enable these functionalities to let your users get the most of out Onyx.
</Tip>

**Web Search**: Sends search queries to a configured search provider. Supported providers include Google PSE, Serper,
and Exa AI to get links and snippets. A crawler is used to fetch the full contents of the page,
Onyx has a built in one and also supports Firecrawl.

**Image Generation**: Sends prompts to a third party image generation endpoint like OpenAI's Dalle model.

**Custom Actions**: API calls available to the LLM, configured by the Admin users of your Onyx deployment.


# Data Storage
Source: https://docs.onyx.app/security/architecture/data_storage

How data is persisted in the Onyx system

<Info>
  For Onyx cloud, all data is encrypted at rest with AES-256 encryption and TLS 1.3 for data in transition
</Info>

As a set of containers, Onyx's data persistence relies on data volumes.
There are also data retention rules which can be configured in the admin panel expire data based on time.

<Warning>
  If self-hosting, you are responsible for the encryption and locking down of the containers.
  Most cloud providers have these settings on by default,
  but you should confirm these security settings are enabled in your environment.
</Warning>

## Relational Database - Postgres

Stores:

* User information, preferences, settings, etc.
* Query History
* Credentials to LLMs, connectors, actions (these are encrypted in Enterprise Edition)
* Document access control information
* Entities/Relationships extracted from documents (only if knowledge graph is turned on)

**Encryption**: Relies on the disk encryption of the deployment

**Access**: Protected by database user authentication with configurable credentials and optional IAM authentication

## Vector Database + Search Engine - OpenSearch

Stores:

* Documents and metadata
* Vector representations of documents
* Document access control information

**Encryption**: Relies on the disk encryption of the deployment

**Access**: Protected by OpenSearch authentication and access controls

## Object Storage - MinIO

Stores:

* Original documents from connectors and user uploads (PDFs, Word docs, etc.)
* Document attachments and media files
* Temporary files during document processing

**Encryption**: Relies on the disk encryption of the deployment

**Access**: Protected by MinIO access keys, bucket policies, and S3-compatible authentication


# FAQ
Source: https://docs.onyx.app/security/architecture/faq

General questions about Onyx security

### Are documents and queries sent to third-party LLMs?

Yes, however you can configure only the LLM providers of your choice or connect Onyx to a self-hosted LLM.

### Is any data used for model training?

There is no training or fine tuning of any models.

### Where is my data stored?

Data storage location depends on your deployment choice.
See the [Data Storage page](/security/architecture/data_storage) for more information.

### Does Onyx have access to my data?

For self-hosted deployments, the Onyx team does not receive **any** of your team's data.
There is aggregated telemetry but this can also be turned off.

### Does the app support SSO (SAML, OIDC, SCIM)?

SAML and OIDC are supported as part of the Community and Enterprise Editions of Onyx. SCIM is on the roadmap,
please check with the team on the latest status.

### What encryption standards does Onyx use?

Onyx Cloud uses AES-256-GCM for data at rest and TLS 1.3 for data in transit. For Self-hosted,
the admin deploying the system is responsible for configuring these.

### What is Onyx's security incident notification process?

Security incidents are communicated to customers according to severity and impact,
with detailed incident reports and remediation steps provided. For Community Edition users,
incidents are shared via our standard community channels (Slack, Discord, Mailing-list)

### Does the vendor cache, index, or replicate internal documents?

Yes, this indexing is required to provide the reliable context retrieval that is key to many core user flows.

### How often are penetration tests performed? Are results available?

Penetration tests are done yearly and results are sharable upon execution of an NDA. Similarly,
container scans are run regularly and results are available.

### What compliance standards does Onyx meet?

Onyx is SOC2 Type II and GDPR compliant.


# System Description
Source: https://docs.onyx.app/security/architecture/system_description

High level view of Onyx components

## Overview

The Onyx application is a set of Docker Containers which can be deployed on any infra and for any scale.

<Tip>
  As an open source project,
  Onyx is designed with security and data privacy as a foundational principle so that teams can trust the software even
  without needing partnership guarantees.
</Tip>

## System Architecture

<img alt="Onyx Architecture" />

## Core Components

### Application Layer

* **Frontend web client**: Next.js-based web application providing the user interface for the Onyx
  platform
* **API Server**: Python FastAPI web server to handle business logic and requests
* **Background Workers**: Python workers to handle async jobs like fetching document updates, etc.

### Model Servers

* **Inference Model Server**: Serves the embedding and reranking models used at query time to
  retrieve and order context
* **Indexing Model Server**: A dedicated model server that handles embedding of documents during
  indexing, isolating heavy indexing workloads from live query traffic

### Data Layer

* **Relational Database**: Postgres database to store application data, user sessions, and system
  state
* **Search Engine**: OpenSearch providing keyword (BM25) search + vector store for retrieving
  context for queries
* **In Memory Cache**: Redis, used to optimize performance
* **File Store**: MinIO blob store for user uploaded files and documents pulled from connectors

### Infrastructure Layer

* **Request Router**: Nginx reverse proxy for load balancing and request routing

## Component Replacements

Some components of the Onyx stack are easily replaceable while others are not.

**MinIO** can be replaced with S3 or any similar object storage service.
The file store interface is abstracted to make this straightforward.

**Redis** can be replaced with a managed Redis service like AWS ElastiCache.
Other in-memory caches could work but would require code changes.

**Postgres** can be replaced with a managed Postgres service such as AWS RDS.
It is much more challenging and not advised to switch to a different relational DB due to language specific features and
optimizations.

**OpenSearch** can be replaced with a multi-node OpenSearch cluster (typically not necessary)
or a managed OpenSearch service such as AWS OpenSearch Service.
OpenSearch is tightly integrated with the context retrieval functionalities and switching to a different search engine
would require significant development effort to maintain the same functionality.

**Nginx** can be removed and replaced with your own routing proxy.


# Contact Us
Source: https://docs.onyx.app/security/contact_us

Excited to hear from you!

Shoot us a message at [hello@onyx.app](mailto:hello@onyx.app) or join our [Discord](https://discord.gg/TDJ59cGV2X).

To contact the founders, please email [founders@onyx.app](mailto:hello@onyx.app).

<img alt="Onyx" />


# Compliance
Source: https://docs.onyx.app/security/onyx_cloud/compliance

Certifications

Onyx is SOC2 Type II and GDPR compliant.

To request access to the reports, please email [hello@onyx.app](mailto:hello@onyx.app).


# Multi Tenant
Source: https://docs.onyx.app/security/onyx_cloud/multi_tenant

Self-serve cloud

<Tip>
  The Onyx multi-tenant cloud is accessible via the [self-serve sign-up](https://cloud.onyx.app/signup).

  It's the easiest way to get started with Onyx and comes with a free trial (no credit card required).
</Tip>

## Hosting

Onyx Cloud is hosted on AWS with a couple managed services replacing the default deployment.

# Deployment Details

The default region is US-east.

Postgres, Redis, Vespa, and MinIO are replaced by managed services.

#### Subprocessors

* **AWS**: Cloud hosting.

* **Vespa**: Vector and full text search.

* **Grafana**: Monitoring for resources, latencies, and outages.

* **OpenAI**: Provided as a default LLM option. Admins can disable this or bring their own key.

* **Anthropic**: Provided as a default LLM option. Admins can disable this or bring their own key.


# Single Tenant
Source: https://docs.onyx.app/security/onyx_cloud/single_tenant

Enterprise cloud

<Tip>
  To get access to single-tenant cloud, please book a call on our [website](https://www.onyx.app).

  Enterprise tier requires a minimum of 100 licenses.
</Tip>

## Hosting

Onyx single tenant cloud ensure complete data separation and can be hosted in any region of choice.
Single tenant deployments are fully managed by the Onyx team on AWS.
There are no additional third parties or subprocessors.

The deployment is resourced according to your team's needs with auto-scaling to ensure high availability during peaks.

Onyx offers a single instance deployment or a Kubernetes deployment depending on anticipated usage and scale.

## Access

If you would like access to Onyx Single Tenant Cloud without a demo, please email [hello@onyx.app](mailto:hello@onyx.app) with the following:

* Your organization name
* Number of licenses desired
* Anticipated use cases
* What SSO configuration you would like to set up

From there the Onyx team will follow up for access and next steps.


# Data Processing
Source: https://docs.onyx.app/security/self_hosted/data_processing

How sensitive data is processed

*This page covers information that is more relevant to self-hosting.
For a more comprehensive overview of how data is processed in Onyx,
check out [Data Flows](/security/architecture/data_flows) and [Data Storage](/security/architecture/data_storage)*

### Complete Data Isolation

All data processing occurs within your infrastructure, ensuring complete control over your data.
No sensitive data leaves your network except for the specific communications you configure.

Note, anonymous telemetry is enabled by default but can be turned off at deployment time.

### Local Model Execution

* **Data Processing**: Document parsing, chunking, and metadata extraction done on-premises
* **Embedding/Reranking Models**: All document embeddings happens locally
* **LLM Integration**: Bring your own LLM - no data sent to external services unless explicitly
  configured
* **Custom Models**: Other models used by Onyx are trained to be runnable on both CPU or GPU.

## Data Flow Security

### Inbound Data

* **Connector Data**: Document content and metadata updates get pulled in from configured external
  applications
* **Model Downloads**: If you configure a non-default embedding or reranking model, it will need to
  be downloaded over the network (it still runs locally).
* **User Interactions**: Chat messages and actions taken in the UI.
* **User Uploads**: Documents uploaded in the Chat interface by the user get processed and stored
  locally.

### Outbound Data

* **LLM Inference**: Queries, chat history, and documents sent to the LLM for processing.
* **Actions**: Calls to external APIs configured by the admin users in your Onyx deployment.
* **Web Search**: Queries passed to a search provider and scraper of choice.

You can also configure external document processing services, embedding/reranking APIs, image captioning models, etc.
but these are purely optional and have built-in equivalents.


# FAQ
Source: https://docs.onyx.app/security/self_hosted/faq

Common questions specifically for self-hosting

<Tip>
  Additional FAQ questions are found in the [Architecture section](/security/architecture/faq)
</Tip>

## Deployment Security

### In what cases should a team self-host?

Self-hosting Onyx offers maximum security by keeping all data within your own infrastructure,
giving you full control over data processing, storage, and network access configurations.

For teams with the highest security requirements, self-hosting is often the preferred choice. However,
it requires more operational overhead compared to the Cloud offering,
so we generally recommend Cloud unless self-hosting is specifically needed.

Teams may also choose to self-host if they don't require Enterprise Edition capabilities. While this can reduce costs,
it does mean foregoing certain advanced security features available in the Enterprise Edition.

### Can I run Onyx completely offline in an air-gapped fashion?

Yes, but you would need to also host your own LLM for Onyx to connect to.
It is always recommended to use a large LLM over quantized or light versions of major models.

### How do I keep my Onyx deployment up to date or get security patches?

Every Onyx deployment is backwards compatible and very rarely require any manual intervention outside of running a
redeployment command. Visit the [Deployment section](/deployment/overview) for more details.

### Is it possible to configure monitoring for Self-Hosted Onyx

Yes, Onyx supports Prometheus and can easily be hooked up to monitoring applications like Grafana.
For monitoring LLM usage, Onyx uses LangGraph so it can also integrate with LangSmith


# Welcome to Onyx!
Source: https://docs.onyx.app/welcome

Open Source AI Platform for Work

## What is Onyx?

Onyx is your team's entry point to Generative AI,
offering a natural language interface for any LLM while integrating seamlessly with your knowledge and applications.
Build tailored AI Agents, search for documents, browse the web, and more — all in one place.

<img alt="Onyx Chat Interface" />

### Quickstart

<Columns>
  <Card title="Deploy Onyx Locally" icon="server" href="/deployment/getting_started/quickstart">
    Checkout our quickstart guide to self-host Onyx in minutes.
  </Card>

  <Card title="Try Onyx Cloud" icon="cloud" href="https://cloud.onyx.app">
    Sign up for a free trial of Onyx Cloud, no credit card required.
  </Card>
</Columns>

## Major Features

<Tip>
  The best way to quickly get familiar with Onyx is to check out the features below!
</Tip>

<Columns>
  <Card title="Chat" icon="comment" href="/overview/core_features/chat">
    Conversational interface to your LLMs, Agents, and knowledge.
  </Card>

  <Card title="Agents" icon="robot" href="/overview/core_features/agents">
    Create AI agents tailored to your use cases with custom instructions, knowledge, and actions.
  </Card>

  <Card title="Internal Search" icon="magnifying-glass" href="/overview/core_features/internal_search">
    Search through your organization's knowledge and connected applications.
  </Card>

  <Card title="Web Search" icon="globe" href="/overview/core_features/web_search">
    Enrich the knowledge of the LLM with the latest information from the internet.
  </Card>

  <Card title="Actions" icon="play" href="/overview/core_features/actions">
    Enable Actions connected to your team's applications to let Agents automate work.
  </Card>

  <Card title="Code Execution" icon="code" href="/overview/core_features/code_interpreter">
    Execute code directly within your chat sessions for complex calculations and data analysis.
  </Card>
</Columns>

<Info>
  To learn about other features, check out the [Core Features](/overview/core_features/chat)
  section or visit the [Admin Docs](/admins/overview) for an even more in depth breakdown.
</Info>

## Why Onyx?

Why choose Onyx over ChatGPT, Microsoft Copilot, Google Gemini, or Glean?

* **Reliable Responses from Internal Knowledge:**
  Onyx builds a knowledge index using LLM-native techniques. Powered with contextual retrieval, advanced RAG,
  hybrid search, and AI-generated knowledge graphs, Onyx ensures the most relevant results and the least hallucinations.

* **Open Source:**
  Onyx is made for security, data privacy, and ease of self-hosting. It's easy and free to get started.
  For teams investing in a long-term GenAI strategy,
  Onyx can be easily extended or customized to your team's future needs.

* **Highly Configurable:**
  Onyx is designed to be flexible, so you can optimize the experience for your team. Plug and play any LLM model,
  connect only the data you need, and enable the features you want your team to use.

## Ready to Get Started?

**Next Steps:**

<Columns>
  <Card title="Deploy Onyx Locally" icon="server" href="/deployment/getting_started/quickstart">
    Checkout our quickstart guide to self-host Onyx in minutes.
  </Card>

  <Card title="Try Onyx Cloud" icon="cloud" href="https://cloud.onyx.app">
    Sign up for a free trial of Onyx Cloud, no credit card required.
  </Card>
</Columns>