How OpenWork Handles API Communication: Architecture and Implementation

OpenWork isolates all network requests through three specialized helper functions—externalFetch, loopbackFetch, and runtimeDiagnosticFetch—defined in apps/server/src/server-fetch.ts to ensure environment-appropriate transport selection and prevent accidental misuse.

The OpenWork project (different-ai/openwork) implements a strict abstraction layer for API communication that distinguishes between external third-party requests, internal loopback traffic, and diagnostic probes. This architecture ensures that server-side code uses the optimal fetch implementation for each runtime environment while maintaining security boundaries.

The Three-Tier Fetch Architecture

OpenWork categorizes every network request into one of three distinct transport types, each handled by a dedicated utility function.

External API Calls with externalFetch

The externalFetch function serves as the primary gateway for all outbound HTTP requests to third-party services such as OpenAI, Google APIs, and the OpenWork backend. It dynamically selects the best fetch implementation based on the current runtime environment.

In apps/server/src/server-fetch.ts, the function is implemented as:

export function externalFetch(input: string, init?: RequestInit): Promise<Response> {
  externalFetchPromise ??= resolveExternalFetch();
  return externalFetchPromise.then((resolvedFetch) => resolvedFetch(input, init));
}

The resolver checks process.versions.electron to determine if the code is running inside an Electron context. When detected, it imports Electron's net module and uses net.fetch; otherwise, it falls back to the standard Node.js globalThis.fetch. This automatic selection ensures optimal networking behavior whether the server runs as a standalone Node process or embedded within an Electron application.

Local Loopback Traffic with loopbackFetch

For traffic that must remain on the same machine—specifically addresses targeting 127.0.0.1 or localhost—OpenWork provides loopbackFetch. This function bypasses TLS validation and avoids the Chromium networking stack entirely, providing the fastest possible local transport for internal engine communication.

export function loopbackFetch(
  input: Parameters<typeof globalThis.fetch>[0],
  init?: Parameters<typeof globalThis.fetch>[1],
): ReturnType<typeof globalThis.fetch> {
  return globalThis.fetch(input, init);
}

This utility is employed for internal engine traffic, such as calls to the OpenCode engine or other services hosted on the same host, ensuring minimal overhead for local inter-process communication.

Runtime Diagnostics with runtimeDiagnosticFetch

The runtimeDiagnosticFetch function provides a pure-runtime diagnostic probe that records which fetch transport is actually being used (Node-undici, Bun-fetch, Electron-net, etc.). This function is strictly intended for internal diagnostics rather than production API calls.

export function runtimeDiagnosticFetch(
  input: string | URL | Request,
  init?: RequestInit,
): Promise<Response> {
  return globalThis.fetch(input, init);
}

The companion function runtimeDiagnosticTransportInfo() returns metadata such as {runtimeFamily: "electron-node", transport: "node-undici"}, enabling precise debugging of transport layer behavior.

Implementation Details and Environment Detection

The core resolution logic in apps/server/src/server-fetch.ts detects the runtime environment through the process.versions.electron property. When present, the function dynamically imports electron/net and utilizes net.fetch for enhanced security and proxy handling within Electron contexts. In standard Node.js environments, it relies on the native fetch global introduced in modern Node versions.

This abstraction prevents bare fetch calls from being used directly in the server codebase. The repository enforces this rule through an automated test in apps/server/src/no-bare-fetch.test.ts, which fails if any file in apps/server/src uses the global fetch directly rather than the appropriate wrapper.

Usage Examples in Production Code

OpenAI Realtime API Integration

The main server entry point in apps/server/src/server.ts uses externalFetch for voice-realtime sessions:

import { externalFetch } from "./server-fetch.js";

const response = await externalFetch(
  `${config.baseUrl}/voice/realtime/session`,
  { headers, signal: controller.signal }
);

This ensures that OpenAI API calls utilize the correct networking stack regardless of whether the application runs in Electron or Node.js.

Google Workspace API Access

The Google Workspace extension demonstrates external API communication for cloud services:

// extensions/google-workspace.ts
import { externalFetch } from "../server-fetch.js";

const response = await externalFetch(
  `https://www.googleapis.com/drive/v3/files/${encodeURIComponent(driveFile.id)}?alt=media`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);

Worker Heartbeat Mechanism

Background worker processes use externalFetch in apps/server/src/worker-activity-heartbeat.ts to maintain communication with the OpenWork backend, ensuring consistent behavior across different deployment targets.

Diagnostic Transport Verification

To verify which fetch implementation is active at runtime:

import { runtimeDiagnosticFetch, runtimeDiagnosticTransportInfo } from "./server-fetch.js";

const transportInfo = runtimeDiagnosticTransportInfo();
const response = await runtimeDiagnosticFetch("https://example.com/health");

Enforcement and Best Practices

OpenWork enforces strict usage patterns through automated testing. The no-bare-fetch.test.ts file contains assertions that scan the apps/server/src directory to ensure no files import or use the global fetch directly. This governance guarantees that:

• All external egress routes through externalFetch for proper Electron/Node compatibility
• Local traffic explicitly uses loopbackFetch for performance optimization
• Diagnostic operations are clearly separated from production code paths

Summary

• OpenWork centralizes API communication through three specialized functions in apps/server/src/server-fetch.ts: externalFetch, loopbackFetch, and runtimeDiagnosticFetch.
• Environment-aware selection allows externalFetch to automatically choose between Electron's net.fetch and native Node.js fetch based on process.versions.electron.
• Loopback optimization provides a dedicated fast path for local traffic via loopbackFetch, bypassing unnecessary network stack overhead.
• Automated enforcement via no-bare-fetch.test.ts prevents accidental use of bare fetch calls in server code.
• Production usage spans OpenAI APIs, Google Workspace integration, and internal worker heartbeats, demonstrating the abstraction's versatility across different service types.

Frequently Asked Questions

Why does OpenWork use different fetch implementations for external versus loopback traffic?

External traffic requires environment-specific handling—Electron applications need net.fetch for proper proxy and security policy integration, while Node.js processes use standard fetch. Loopback traffic uses a simplified path to avoid TLS validation overhead and Chromium networking delays, ensuring maximum speed for local inter-process communication within the same host.

How does OpenWork prevent developers from accidentally using the wrong fetch method?

The repository includes an automated test in apps/server/src/no-bare-fetch.test.ts that scans the server source code and fails if any file uses the global fetch directly. This enforcement ensures all network requests explicitly use externalFetch, loopbackFetch, or runtimeDiagnosticFetch, maintaining the architectural integrity of the API communication layer.

What happens when OpenWork runs inside Electron versus standalone Node.js?

When process.versions.electron is detected, externalFetch dynamically imports the electron/net module and uses net.fetch for all outbound requests. In standalone Node.js environments, it uses the native globalThis.fetch. This runtime detection happens once at startup and applies consistently across all subsequent API calls in the application lifecycle.

Can I use runtimeDiagnosticFetch for production API calls?

No, runtimeDiagnosticFetch is explicitly designed for internal diagnostics and testing. It provides transport metadata through runtimeDiagnosticTransportInfo() but does not include the environment-specific optimizations or error handling present in externalFetch. Production code should always use externalFetch for third-party APIs and loopbackFetch for local services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}