# How to Troubleshoot OpenWork Agent-Context Connectivity and Egress Issues

> Troubleshoot OpenWork agent-context connectivity and egress issues with our layered diagnostics system. Isolate network, TLS, and registration failures effectively.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-04

---

**OpenWork diagnoses agent-context connectivity and egress problems through a layered Agent-Context Diagnostics system that performs three independent checks—Cloud Catalog Probe, Cloud-Endpoint Transport Probe, and Differential Runtime-Engine Check—to isolate network, TLS, and registration failures.**

When your OpenWork client cannot reach the OpenWork Cloud MCP or local engines fail to register, you need systematic visibility into where the chain breaks. The `different-ai/openwork` repository implements a comprehensive diagnostics stack exposed via the `POST /workspace/:id/diagnostics/agent-context` endpoint in [`apps/server/src/agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-diagnostics.ts). This system returns a unified report that distinguishes between egress proxy blocks, certificate validation errors, catalog mismatches, and engine lifecycle issues.

## Understanding the Three-Layer Diagnostic Architecture

The Agent-Context Diagnostics engine performs three independent probes that run inside the **runtime** (the OpenWork process executing the workspace). Each layer targets a specific failure domain.

### Layer 1: Cloud Catalog Probe

The **Cloud Catalog Probe** retrieves the OpenWork Cloud catalog and validates that required tools—specifically `search_capabilities` and `execute_capability`—are present. This check runs via a network request from the runtime to the Cloud endpoint.

If this probe fails with **HTTP 401 or 403**, the stored credential lacks permission or the organization connection is invalid. A **HTTP 451** response indicates an egress proxy or firewall block. A `cloud_catalog_mismatch` status means the catalog structure does not match the expected schema, requiring a refresh from **Settings → Connect**.

### Layer 2: Cloud-Endpoint Transport Probe

Before transmitting credentials, the runtime performs a credential-free TLS handshake against the Cloud MCP `/mcp/agent` endpoint. This **Cloud-Endpoint Transport Probe** validates TLS 1.2 and TLS 1.3 connectivity.

Common failure codes include:
- `tls_incomplete_chain` — Intermediate certificate missing from the server chain.
- `tls_untrusted_ca` — Corporate TLS inspection root not trusted by the runtime.
- `timeout` during TLS 1.3 — Egress proxy stalls the handshake.

To resolve CA issues, append the corporate root certificate to `NODE_EXTRA_CA_CERTS` or disable inspection for `*.openwork.dev`.

### Layer 3: Differential Runtime-Engine Check

The **Differential Check** compares the transport probe result against the **engine snapshot**—the merged configuration that the engine reports about its own reachability. This identifies split-brain scenarios where the runtime can reach the Cloud but the engine cannot, or vice versa.

A status of `engine_evidence_stale_or_unavailable` indicates the engine has not recorded fresh registration evidence, typically resolved by restarting the workspace engine.

## Diagnosing Common Connectivity and Egress Failures

The diagnostics report aggregates findings from [`agent-context-cloud-probe.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-cloud-probe.ts), [`agent-context-transport-probe.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-transport-probe.ts), and [`agent-context-engine-inspection.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-engine-inspection.ts) into actionable entries with `status`, `owner`, and `action` fields.

### Network and Egress Proxy Blocks

When the transport probe returns `tls_error` or timeout statuses, verify DNS resolution and firewall egress rules. If your corporate proxy intercepts TLS, ensure the proxy root is trusted or bypassed for OpenWork domains. The `OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS` environment variable can whitelist on-prem Den installations.

### Cloud Catalog Mismatches

If the probe reports `cloud_catalog_mismatch`, re-connect OpenWork Cloud from **Settings → Connect** to refresh the local catalog cache. If the error persists, contact OpenWork support to verify the canonical Cloud catalog state.

### Stale Engine Registration

When the differential check shows the runtime reachable but the engine unreachable, restart the selected workspace engine. Run `openwork engine start` for the specific workspace or stop/start the OpenWork server process to generate fresh registration evidence in the engine snapshot.

### Credential and Permission Errors

HTTP 401 (`unauthorized`) or 403 (`forbidden`) from the catalog probe indicates token expiration or scope mismatch. Re-authenticate via **Settings → Connect** and confirm the account belongs to the correct organization with required MCP scopes.

### MCP Endpoint Misconfiguration

Errors like `invalid_endpoint` or `untrusted_endpoint` suggest the Cloud MCP URL is malformed. Verify in **Settings → Connect** that the endpoint uses `https://` and ends with `/mcp/agent`. For on-prem deployments, ensure the origin is added to `OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS`.

## Running Agent-Context Diagnostics Programmatically

You can trigger the diagnostics endpoint from custom clients to monitor connectivity health.

### Web Client Implementation

```typescript
import { fetch } from "node-fetch";

async function runDiagnostics(workspaceId: string, baseUrl: string, bearer: string) {
  const url = `${baseUrl}/workspace/${encodeURIComponent(workspaceId)}/diagnostics/agent-context`;
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${bearer}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      // Optional: request specific probes via schema defined in agent-context-diagnostics-request-schema.ts
    }),
  });

  if (!response.ok) throw new Error(`Diagnostics request failed: ${response.status}`);
  const report = await response.json();
  
  // report.checks contains entries with id, status, owner, and action
  console.log("Diagnostics report:", report);
}

```

### React UI Integration

```tsx
import { useEffect, useState } from "react";
import { fetchAgentContextDiagnosticsResponse } from "@/app/lib/agent-context-diagnostics";

export function AgentContextDiagnosticsReport({ workspaceId }: { workspaceId: string }) {
  const [report, setReport] = useState<AgentContextDiagnosticsReport | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetchAgentContextDiagnosticsResponse(workspaceId)
      .then(setReport)
      .catch((e) => setError(e.message));
  }, [workspaceId]);

  if (error) return <div className="text-red-600">⚠️ {error}</div>;
  if (!report) return <div className="animate-pulse">Loading…</div>;

  return (
    <ul className="space-y-2">
      {report.checks.map((c) => (
        <li key={c.id} className={c.status === "failed" ? "text-red-600" : "text-green-600"}>
          <strong>{c.id}</strong>: {c.message}
          {c.action && <p className="ml-4">{c.action}</p>}
        </li>
      ))}
    </ul>
  );
}

```

The desktop client wraps this logic in `apps/desktop/electron/agent-context-diagnostics-fetch.mjs`, validated by the test suite in `agent-context-diagnostics-fetch.test.mjs`.

## Core Implementation Files in the OpenWork Repository

The diagnostics stack spans server, client, and type definitions:

- **[`apps/server/src/agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-diagnostics.ts)** — Main endpoint implementation that assembles the full report.
- **[`apps/server/src/agent-context-diagnostics-schema.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-diagnostics-schema.ts)** — Zod schemas for request and response validation.
- **[`apps/server/src/agent-context-cloud-probe.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-cloud-probe.ts)** — Catalog retrieval and tool validation logic.
- **[`apps/server/src/agent-context-transport-probe.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-transport-probe.ts)** — TLS handshake execution and error classification.
- **[`apps/server/src/agent-context-engine-inspection.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-engine-inspection.ts)** — Engine snapshot reading and differential comparison.
- **`apps/desktop/electron/agent-context-diagnostics-fetch.mjs`** — Desktop client helper for server communication.
- **[`apps/app/src/react-app/domains/settings/pages/agent-context-diagnostics-report.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/domains/settings/pages/agent-context-diagnostics-report.tsx)** — Settings UI component rendering the report.
- **[`packages/types/src/agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/agent-context-diagnostics.ts)** — Shared TypeScript interfaces.
- **[`evals/packages/behaviors/src/diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/evals/packages/behaviors/src/diagnostics.ts)** — CI test harness for automated diagnostics validation.

## Summary

- OpenWork isolates connectivity issues through **three distinct probes**: Cloud Catalog validation, TLS transport handshake, and Runtime-Engine differential analysis.
- **HTTP 451** and TLS timeout errors typically indicate egress proxy or firewall interference requiring certificate trust configuration via `NODE_EXTRA_CA_CERTS`.
- **`cloud_catalog_mismatch`** and **401/403** errors resolve by re-authenticating OpenWork Cloud or refreshing the catalog from Settings.
- **`engine_evidence_stale_or_unavailable`** indicates the engine needs restart to record fresh registration evidence.
- The **`POST /workspace/:id/diagnostics/agent-context`** endpoint in [`agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-diagnostics.ts) returns structured reports with specific remediation actions for each failure domain.

## Frequently Asked Questions

### What does HTTP 451 indicate in OpenWork diagnostics?

HTTP 451 signals that an egress proxy or firewall is blocking access to the OpenWork Cloud endpoint. Unlike 401 or 403 (which indicate authentication issues), 451 suggests network-level filtering. Verify corporate firewall rules and ensure `*.openwork.dev` domains are allowlisted, or configure `NODE_EXTRA_CA_CERTS` if TLS inspection is intercepting the connection.

### How do I fix TLS certificate errors when probing the Cloud MCP endpoint?

When [`agent-context-transport-probe.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-transport-probe.ts) returns `tls_incomplete_chain`, `tls_untrusted_ca`, or TLS timeout errors, the runtime cannot validate the server certificate. Add your organization's root CA certificate to the `NODE_EXTRA_CA_CERTS` environment variable, or disable TLS inspection for OpenWork Cloud domains. For on-prem Den deployments, add the custom origin to `OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS`.

### What is the difference between the runtime and engine checks?

The **runtime** refers to the OpenWork process executing your workspace code, while the **engine** is the persistent service managing MCP registrations and configuration. The differential check compares whether both can reach the Cloud MCP. If the runtime passes but the engine fails, the issue is engine-side registration (resolved by restart); if both fail, the problem is network or endpoint configuration.

### Where can I find the agent-context diagnostics endpoint?

The server endpoint is implemented in [`apps/server/src/agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-diagnostics.ts) and exposed at `POST /workspace/:id/diagnostics/agent-context`. It aggregates data from [`agent-context-cloud-probe.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-cloud-probe.ts), [`agent-context-transport-probe.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-transport-probe.ts), and [`agent-context-engine-inspection.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-engine-inspection.ts) to produce a unified report consumed by both the desktop client (`agent-context-diagnostics-fetch.mjs`) and the React settings UI.