Python: Fix/ Document Chatkit limitations clearly

python/packages/chatkit/README.md

@@ -20,6 +20,37 @@ pip install agent-framework-chatkit --pre
 
 This will install `agent-framework-core` and `openai-chatkit` as dependencies.
 
+## Requirements and Limitations
+
+### Frontend Requirements
+
+The ChatKit integration requires the OpenAI ChatKit frontend library, which has the following requirements:
+
+1. **Internet Connectivity Required**: The ChatKit UI is loaded from OpenAI's CDN (`cdn.platform.openai.com`). This library cannot be self-hosted or bundled locally.
+
+2. **External Network Requests**: The ChatKit frontend makes requests to:
+   - `cdn.platform.openai.com` - UI library (required)
+   - `chatgpt.com/ces/v1/projects/oai/settings` - Configuration
+   - `api-js.mixpanel.com` - Telemetry (metadata only, not user messages)
+
+3. **Domain Registration for Production**: Production deployments require registering your domain at [platform.openai.com](https://platform.openai.com/settings/organization/security/domain-allowlist) and configuring a domain key.
+
+### Air-Gapped / Regulated Environments
+
+**The ChatKit frontend is not suitable for air-gapped or highly-regulated environments** where outbound connections to OpenAI domains are restricted.
+
+**What IS self-hostable:**
+
+- The backend components (`chatkit-python`, `agent-framework-chatkit`) are fully open source and have no external dependencies
+
+**What is NOT self-hostable:**
+
+- The frontend UI (`chatkit.js`) requires connectivity to OpenAI's CDN
+
+For environments with network restrictions, consider building a custom frontend that consumes the ChatKit server protocol, or using alternative UI libraries like `ai-sdk`.
+
+See [openai/chatkit-js#57](https://github.com/openai/chatkit-js/issues/57) for tracking self-hosting feature requests.
+
 ## Example Usage
 
 Here's a minimal example showing how to integrate Agent Framework with ChatKit:

python/samples/demos/chatkit-integration/README.md

@@ -138,6 +138,31 @@ async for event in stream_widget(thread_id=thread.id, widget=widget):
 - Azure OpenAI service configured
 - Azure CLI for authentication (`az login`)
 
+### Network Requirements
+
+> **Important:** This sample uses the OpenAI ChatKit frontend, which requires internet connectivity to OpenAI services.
+
+The frontend makes outbound requests to:
+
+- `cdn.platform.openai.com` - ChatKit UI library (required)
+- `chatgpt.com` - Configuration endpoint
+- `api-js.mixpanel.com` - Telemetry
+
+**This sample is not suitable for air-gapped or network-restricted environments.** The ChatKit frontend library cannot be self-hosted. See [Limitations](#limitations) for details.
+
+### Domain Key Configuration
+
+For **local development**, the sample uses a default domain key (`domain_pk_localhost_dev`).
+
+For **production deployment**:
+
+1. Register your domain at [platform.openai.com](https://platform.openai.com/settings/organization/security/domain-allowlist)
+2. Create a `.env` file in the `frontend` directory:
+
+   ```
+   VITE_CHATKIT_API_DOMAIN_KEY=your_domain_key_here
+   ```
+
 ### Backend Setup
 
 1. **Install Python packages:**
@@ -261,6 +286,31 @@ Try these example queries:
 - "What's the current time?"
 - Upload an image and ask "What do you see in this image?"
 
+## Limitations
+
+### Air-Gapped / Regulated Environments
+
+The ChatKit frontend (`chatkit.js`) is loaded from OpenAI's CDN and cannot be self-hosted. This means:
+
+- **Not suitable for air-gapped environments** where `*.openai.com` is blocked
+- **Not suitable for regulated environments** that prohibit external telemetry
+- **Requires domain registration** with OpenAI for production use
+
+**What you CAN self-host:**
+
+- The Python backend (FastAPI server, `ChatKitServer`, stores)
+- The `agent-framework-chatkit` integration layer
+- Your LLM infrastructure (Azure OpenAI, local models, etc.)
+
+**What you CANNOT self-host:**
+
+- The ChatKit frontend UI library
+
+For more details, see:
+
+- [openai/chatkit-js#57](https://github.com/openai/chatkit-js/issues/57) - Self-hosting feature request
+- [openai/chatkit-js#76](https://github.com/openai/chatkit-js/issues/76) - Domain key requirements
+
 ## Learn More
 
 - [Agent Framework Documentation](https://aka.ms/agent-framework)

python/samples/demos/chatkit-integration/frontend/index.html

@@ -4,6 +4,11 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ChatKit + Agent Framework Demo</title>
+    <!--
+      IMPORTANT: The ChatKit UI library is loaded from OpenAI's CDN and cannot be self-hosted.
+      This requires internet connectivity and is not suitable for air-gapped environments.
+      See: https://github.com/openai/chatkit-js/issues/57
+    -->
     <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
     <style>
       * {

python/samples/demos/chatkit-integration/frontend/src/App.tsx

@@ -1,6 +1,12 @@
 import { ChatKit, useChatKit } from "@openai/chatkit-react";
 
 const CHATKIT_API_URL = "/chatkit";
+
+// Domain key for ChatKit integration
+// - Local development: Uses default "domain_pk_localhost_dev"
+// - Production: Register your domain at https://platform.openai.com/settings/organization/security/domain-allowlist
+//   and set VITE_CHATKIT_API_DOMAIN_KEY in your .env file
+// See: https://github.com/openai/chatkit-js/issues/76
 const CHATKIT_API_DOMAIN_KEY =
   import.meta.env.VITE_CHATKIT_API_DOMAIN_KEY ?? "domain_pk_localhost_dev";