Skip to Content

Electron applications

Use the JavaScript Client SDK; an Electron app does not require a separate Modem protocol. Decide whether the customer client lives in the renderer or main process, then keep session ownership in that place.

Choose the boundary

PlacementSession lifetimeIntegration
Trusted rendererBrowser storage or in-memoryStandard Client SDK and browser sign-in flow
Main processYour app’s protected session storeExpose task-specific operations through preload IPC

Never ship an admin API key or provider credential in either process. The app authenticates a customer; Modem stores the provider credentials.

For a renderer client, use session storage. A file: or custom-scheme page is not an approved hosted GitHub HTTPS return origin. Use a supported trusted web/loopback callback flow, or your configured identity provider’s desktop login flow. client.oauth itself needs browser window, Web Crypto and session storage; it cannot run unchanged in the main process.

Main-process client

Use an identity token obtained by your application’s sign-in integration:

import { createCustomerClient, ExternalServiceProvider } from '@preternatural-js/client-sdk' const client = createCustomerClient({ environment: 'production', projectId: 'your-project-id', authentication: { type: 'identity-token-provider', getIdentityToken: () => getCurrentIdentityToken() } }) async function complete(prompt: string) { return client.chat.complete({ scope: { provider: ExternalServiceProvider.openai, productId: 'your-product-id', modelIdentifier: 'gpt-4o-mini' }, messages: [{ role: 'user', content: prompt }] }) }

getCurrentIdentityToken() is your identity provider integration, not a Modem login method. Browser storage helpers read nothing in the main process; use a custom session store backed by your application storage if persistence is needed. Renewed tokens must replace the saved session, and sign-out must clear it.

Expose a method such as complete(prompt) through contextBridge, rather than exposing the session or arbitrary ipcRenderer.send. The main handler must validate the sending frame, request shape and allowed operation. Keep contextIsolation enabled and nodeIntegration disabled for renderer content, following Electron’s context isolation  and security  guidance.

Streaming and lifecycle

Send stream chunks over a chat-specific channel with a cancellation operation. Keep one AbortController per request, cancel when its window/chat closes, and remove listeners on completion. Do not reuse a process-global current stream for multiple windows.

When switching users, call client.session.clear() or replace the session. Old requests end with CustomerSessionChangedError; do not attach their late output to the next user’s chat. A new application launch must restore a session or sign in; a still-running main process and a reloaded renderer have different lifetimes.

Before release, verify cold launch, reload, sign-out across windows, expired-token renewal, stream cancellation and the packaged app’s real callback origin. A browser-only development run does not establish those desktop behaviors.

Last updated on