Your always-on AI coworkers that move between text, calls, and Slack.
TypeScript
fix: connect OpenDots to local Intelligence evaluation (#93)
Jerel Velarde8e59caffd7e0
diff --git a/.env.example b/.env.exampleindex 34b3f3a..afc348c 100644--- a/.env.example+++ b/.env.example@@ -9,14 +9,18 @@ OWNER_ID=opendots-owner# Required for an external HOST binding (24+ characters); enables local login too.# OWNER_TOKEN=-# `copilotkit project select` rewrites this line to CPK_INTELLIGENCE_API_KEY.+# `copilotkit project select` or `local connect` writes CPK_INTELLIGENCE_API_KEY.# The server accepts either name and prefers a non-empty CPK_INTELLIGENCE_API_KEY.INTELLIGENCE_API_KEY=# INTELLIGENCE_API_URL=+# `local connect` writes this endpoint; it takes precedence over the legacy name.+# INTELLIGENCE_GATEWAY_WS_URL=# INTELLIGENCE_WS_URL=OPENAI_API_KEY=OPENAI_BASE_URL=https://api.openai.com/v1OPENAI_MODEL=+# Optional opt-out of SDK usage telemetry (separate from conversation persistence).+# COPILOTKIT_TELEMETRY_DISABLED=true# Optional isolated read-only public-page browser for WEB_SEARCH_PROVIDER=browser.BROWSER_URL=http://127.0.0.1:4311diff --git a/README.md b/README.mdindex e77572a..25ad8f0 100644--- a/README.md+++ b/README.md@@ -14,7 +14,7 @@ Built with [CopilotKit](https://github.com/CopilotKit/CopilotKit) and [AG-UI](ht<a href="https://trendshift.io/repositories/275323" target="_blank"><img src="https://trendshift.io/api/badge/trendshift/repositories/275323/daily?language=TypeScript" alt="CopilotKit/OpenDots | Trendshift #2 TypeScript Repository Of The Day" width="250" height="55"/></a>-Fully self-hostable. Clone this template and customize it however you want.+Host OpenDots on your own infrastructure. Conversations require CopilotKit Intelligence: use the hosted service, the [local Docker evaluation](docs/SETUP.md#local-intelligence-evaluation), or a licensed [self-hosted deployment](https://docs.copilotkit.ai/intelligence/self-hosting). Clone this template and customize it however you want.[**Building on OpenDots? Meet with the CopilotKit team →**](https://www.copilotkit.ai/talk-to-an-engineer?ref=opendots_readme)@@ -164,7 +164,7 @@ npm run devOpen **http://127.0.0.1:5173**. You can create Spaces, write pages, and configure Dots before connecting services. To start chatting, connect an Intelligence project and a model.-Sign in to CopilotKit and select or create the Intelligence project. Run these commands in the `OpenDots` folder:+Choose where to store conversations before connecting. For local Docker evaluation, follow [Local Intelligence evaluation](docs/SETUP.md#local-intelligence-evaluation). For hosted Intelligence, sign in and select or create a project in the `OpenDots` folder:```shnpx copilotkit@latest login@@ -177,6 +177,14 @@ Do not run `copilotkit onboard` in this folder. OpenDots already contains its CoSee [Setup](docs/SETUP.md) for configuration, Slack, calls, the browser service, and Docker.+## Data and privacy++Conversation messages, tool calls, and run events are persisted in the configured Intelligence deployment. The hosted setup sends them to CopilotKit's cloud; the local evaluation setup uses Intelligence on your machine. OpenDots has no standalone SQLite conversation store. SQLite stores pages, workspace metadata, and thread bindings separately.++The configured model provider receives conversation context, including authorized page content and tool results. Local Intelligence does not make a remote model local: configure the app's model and the Automatic Learning model separately. Public-web research sends queries and selected URLs to Parallel by default; set `WEB_SEARCH_PROVIDER=disabled` to disable those tools. Speech and messaging integrations send data to their configured providers when used.++CopilotKit SDK telemetry collects usage metadata separately from conversation persistence. Set `COPILOTKIT_TELEMETRY_DISABLED=true` to opt out; see [CopilotKit telemetry](https://docs.copilotkit.ai/telemetry). Review [CopilotKit's privacy policy](https://www.copilotkit.ai/privacy-policy) and the policies and retention settings of each service you configure. Installing or renewing local Intelligence still requires CopilotKit sign-in and internet access.+## Features| Area | Included |diff --git a/compose.yml b/compose.ymlindex 9b5cf82..dca1147 100644--- a/compose.yml+++ b/compose.yml@@ -12,7 +12,9 @@ services:INTELLIGENCE_API_KEY: ${INTELLIGENCE_API_KEY:-}CPK_INTELLIGENCE_API_KEY: ${CPK_INTELLIGENCE_API_KEY:-}INTELLIGENCE_API_URL: ${INTELLIGENCE_API_URL:-}+ INTELLIGENCE_GATEWAY_WS_URL: ${INTELLIGENCE_GATEWAY_WS_URL:-}INTELLIGENCE_WS_URL: ${INTELLIGENCE_WS_URL:-}+ COPILOTKIT_TELEMETRY_DISABLED: ${COPILOTKIT_TELEMETRY_DISABLED:-false}VOICE_API_KEY: ${VOICE_API_KEY:-}VOICE_MODEL: ${VOICE_MODEL:-}VOICE_NAME: ${VOICE_NAME:-marin}diff --git a/docs/SETUP.md b/docs/SETUP.mdindex 8a79efe..dd5e096 100644--- a/docs/SETUP.md+++ b/docs/SETUP.md@@ -25,7 +25,11 @@ Open http://127.0.0.1:4310. Keep the server running for background work.## Conversation services-OpenDots stores conversations in a CopilotKit Intelligence project. To get the project key, run these commands in the OpenDots folder after `cp .env.example .env`:+OpenDots requires CopilotKit Intelligence for conversations. Choose local evaluation below, a licensed [self-hosted deployment](https://docs.copilotkit.ai/intelligence/self-hosting), or hosted Intelligence. Pages and workspace metadata remain in SQLite; conversation history is stored separately. See [Data and privacy](../README.md#data-and-privacy).++### Hosted Intelligence++To get a hosted project key, run these commands in the OpenDots folder after `cp .env.example .env`:```shnpx copilotkit@latest login@@ -36,21 +40,47 @@ npx copilotkit@latest project selectDo not run `copilotkit onboard` in this folder. Onboarding is for apps that do not have CopilotKit yet. OpenDots already has its integration.+### Local Intelligence evaluation++The [local evaluation preview](https://docs.copilotkit.ai/intelligence/self-hosting-local) runs Intelligence in Docker Desktop on macOS. Allocate at least 4 CPUs, 12 GiB RAM, and 40 GiB free storage. OpenDots needs Node.js 24. A CopilotKit account is required; the free Developer plan qualifies for a renewable 30-day evaluation license. This is not a production installation.++Run from the OpenDots folder after `cp .env.example .env`, with Docker Desktop running:++```sh+npx copilotkit@latest login+npx copilotkit@latest local setup+npx copilotkit@latest local connect+npx copilotkit@latest local connect --approve-connection+```++`local connect` previews the changes; the approved command writes the local API URL, gateway WebSocket URL, and project key to `.env`. OpenDots accepts these directly. Do not run `project select` afterward: it selects a hosted project. Add `OPENAI_API_KEY` and `OPENAI_MODEL` for the app, then restart `npm run dev`. Setup's Learning model is separate from the app's model.++Send a message and verify it appears in the local dashboard (`npx copilotkit@latest local login`). Use `local status` to inspect service health. Threads, Automatic Learning, and Channels are included; User Memory and Product Analytics are not. Channels require a public HTTPS address reachable by Slack or Teams.++To restore the previous app connection, run `npx copilotkit@latest local cancel` and restart the app. This keeps the stack and its data. Use `local stop` to stop the stack, or `local renew` to renew its evaluation license. Existing hosted conversations are not copied into the local project.++For this preview, run OpenDots directly on your Mac with `npm run dev`; Intelligence runs in Docker. The CLI's `localhost` URLs do not work from an OpenDots container. A containerized app needs an API address reachable from its container and a gateway address reachable from both the server and the browser, because the runtime advertises that gateway to browser clients. Changing the gateway to a Docker-only hostname is not sufficient.++### Connection settings+Edit `.env` on the server and restart after changes:-| Variable | Purpose |-| --------------------------------------------- | --------------------------------------------------------- |-| `INTELLIGENCE_API_KEY` | Project credential for conversation persistence |-| `INTELLIGENCE_API_URL`, `INTELLIGENCE_WS_URL` | Endpoint overrides for your Intelligence deployment |-| `OPENAI_API_KEY`, `OPENAI_MODEL` | Model credential and model identifier |-| `OPENAI_BASE_URL` | Compatible model API endpoint |-| `OWNER_ID` | Stable identity used for this deployment's conversations |-| `DATABASE_PATH` | SQLite file containing pages, workspace and work metadata |-| `OWNER_TOKEN` | Application access token; required for external bindings |-| `APP_ORIGIN` | Exact browser origin when using a proxy or custom domain |+| Variable | Purpose |+| ---------------------------------------------------- | ---------------------------------------------------------------------- |+| `INTELLIGENCE_API_KEY` | Project credential for conversation persistence |+| `INTELLIGENCE_API_URL` | API endpoint override for your Intelligence deployment |+| `INTELLIGENCE_GATEWAY_WS_URL`, `INTELLIGENCE_WS_URL` | Gateway WebSocket override (CLI name preferred; legacy name supported) |+| `OPENAI_API_KEY`, `OPENAI_MODEL` | Model credential and model identifier |+| `OPENAI_BASE_URL` | Compatible model API endpoint |+| `OWNER_ID` | Stable identity used for this deployment's conversations |+| `DATABASE_PATH` | SQLite file containing pages, workspace and work metadata |+| `OWNER_TOKEN` | Application access token; required for external bindings |+| `APP_ORIGIN` | Exact browser origin when using a proxy or custom domain |`npx copilotkit project select` deletes an `INTELLIGENCE_API_KEY` line and writes the same credential as `CPK_INTELLIGENCE_API_KEY`. The server reads either name. A non-empty `CPK_INTELLIGENCE_API_KEY` takes precedence over `INTELLIGENCE_API_KEY`.+A non-empty `INTELLIGENCE_GATEWAY_WS_URL` takes precedence over `INTELLIGENCE_WS_URL`. Without either WebSocket override, OpenDots uses the hosted gateway. Set both the API and gateway endpoints when connecting a self-hosted deployment.+The model environment variable names follow the configured provider adapter. Provider credentials belong in `.env`, not client-side variables or source code. Conversation history lives in the configured Intelligence project; copying the SQLite file alone does not back up that history.## Pages and page conversations@@ -86,6 +116,8 @@ For a separate browser, persistent files, and optional shell for each specialistOpenDots uses `@copilotkit/channels` with a managed Slack connection, following the runtime and channel pattern in [OpenTag](https://github.com/CopilotKit/OpenTag). The application declares the channel and its specialist agent; Intelligence manages the Slack adapter and delivery. You do not need a separate Slack webhook server or Socket Mode connection in OpenDots.+The CLI project-selection commands below are for hosted Intelligence. For local evaluation, configure Channels in the local dashboard and follow the [local Channels requirements](https://docs.copilotkit.ai/intelligence/self-hosting-local#connect-slack-or-microsoft-teams), including a public HTTPS address. Do not replace the local project key with `project select`.+### Create the managed channelSelect the same Intelligence project used by this application, then create a uniquely named channel:diff --git a/src/server/index.ts b/src/server/index.tsindex 5149f5f..91eb421 100644--- a/src/server/index.ts+++ b/src/server/index.ts@@ -10,6 +10,7 @@ import { WorkspaceStore } from './workspace.js';import { Platform } from './platform.js';import {intelligenceApiKeyFromEnv,+ intelligenceWsUrlFromEnv,type PlatformConfig,} from './platform-config.js';const host = process.env.HOST ?? '127.0.0.1';@@ -31,7 +32,7 @@ const workspace = new WorkspaceStore(const config: PlatformConfig = {intelligenceKey: intelligenceApiKeyFromEnv(process.env),intelligenceApiUrl: process.env.INTELLIGENCE_API_URL || undefined,- intelligenceWsUrl: process.env.INTELLIGENCE_WS_URL || undefined,+ intelligenceWsUrl: intelligenceWsUrlFromEnv(process.env),apiKey: process.env.OPENAI_API_KEY,model: process.env.OPENAI_MODEL,baseUrl: process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1',diff --git a/src/server/platform-config.ts b/src/server/platform-config.tsindex 0502f91..95ad923 100644--- a/src/server/platform-config.ts+++ b/src/server/platform-config.ts@@ -11,7 +11,23 @@ export const INTELLIGENCE_KEY_MISSING_LABEL = `${INTELLIGENCE_API_KEY_ENV_NAMES[export function intelligenceApiKeyFromEnv(env: Record<string, string | undefined>,): string | undefined {- for (const name of INTELLIGENCE_API_KEY_ENV_NAMES) {+ return firstNonEmptyEnvValue(env, INTELLIGENCE_API_KEY_ENV_NAMES);+}++export function intelligenceWsUrlFromEnv(+ env: Record<string, string | undefined>,+): string | undefined {+ return firstNonEmptyEnvValue(env, [+ 'INTELLIGENCE_GATEWAY_WS_URL',+ 'INTELLIGENCE_WS_URL',+ ]);+}++function firstNonEmptyEnvValue(+ env: Record<string, string | undefined>,+ names: readonly string[],+): string | undefined {+ for (const name of names) {const value = env[name]?.trim();if (value) return value;}diff --git a/tests/intelligence-key.test.ts b/tests/intelligence-key.test.tsindex ee0db3f..bd56feb 100644--- a/tests/intelligence-key.test.ts+++ b/tests/intelligence-key.test.ts@@ -3,6 +3,7 @@ import { Platform } from '../src/server/platform.js';import {INTELLIGENCE_KEY_MISSING_LABEL,intelligenceApiKeyFromEnv,+ intelligenceWsUrlFromEnv,setupStatus,type PlatformConfig,} from '../src/server/platform-config.js';@@ -71,3 +72,30 @@ it('reports either accepted name from the same label used by setup status and thworkspace.close();}});++it('uses the local CLI gateway URL instead of a stale hosted override', () => {+ expect(+ intelligenceWsUrlFromEnv({+ INTELLIGENCE_GATEWAY_WS_URL: ' ws://localhost:5080 ',+ INTELLIGENCE_WS_URL: 'wss://hosted.example.com',+ }),+ ).toBe('ws://localhost:5080');+});++it('keeps the existing WebSocket override when the CLI value is absent or blank', () => {+ expect(+ intelligenceWsUrlFromEnv({+ INTELLIGENCE_WS_URL: ' wss://hosted.example.com ',+ }),+ ).toBe('wss://hosted.example.com');+ expect(+ intelligenceWsUrlFromEnv({+ INTELLIGENCE_GATEWAY_WS_URL: ' ',+ INTELLIGENCE_WS_URL: 'ws://localhost:5080',+ }),+ ).toBe('ws://localhost:5080');+ expect(intelligenceWsUrlFromEnv({})).toBeUndefined();+ expect(+ intelligenceWsUrlFromEnv({ INTELLIGENCE_GATEWAY_WS_URL: ' ' }),+ ).toBeUndefined();+});