71 lines
5.5 KiB
Plaintext
71 lines
5.5 KiB
Plaintext
---
|
|
title: "Network diagnostics"
|
|
description: "Diagnose DNS, TLS, proxy, catalog, and Den outbound issues in locked-down OpenWork deployments."
|
|
---
|
|
|
|
Use this page when OpenWork reaches the wrong server, cannot complete TLS, is blocked by a proxy, or needs proof that Den can reach an approved diagnostic origin. For non-network runtime, MCP, and stale-tool problems, use [Diagnostic prompts](/start-here/troubleshooting/diagnostic-prompts).
|
|
|
|
## Windows desktop network doctor
|
|
|
|
`scripts/support/openwork-doctor.ps1` is a Windows PowerShell 5.1-compatible, no-admin, read-only report for customer IT. It checks DNS, TCP 443, the live TLS certificate chain with `SslStream`, served certificates with `openssl` when available, WinHTTP/.NET proxy settings, PowerShell/OS version, and `NODE_EXTRA_CA_CERTS`.
|
|
|
|
Run it directly from the raw repository URL when the machine can reach GitHub:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -Command "`$p=Join-Path `$env:TEMP 'openwork-doctor.ps1'; Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/different-ai/openwork/dev/scripts/support/openwork-doctor.ps1' -OutFile `$p; & `$p -WebUrl 'https://openwork.example.com' -ApiUrl 'https://api.openwork.example.com' -ExpectedIssuerMatch 'DigiCert'"
|
|
```
|
|
|
|
If raw download is blocked, copy `scripts/support/openwork-doctor.ps1` to the machine through your approved offline channel and run:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\openwork-doctor.ps1 -WebUrl 'https://openwork.example.com' -ApiUrl 'https://api.openwork.example.com' -ExpectedIssuerMatch 'DigiCert'
|
|
```
|
|
|
|
Use your Den web origin for `-WebUrl`. Use the separate Den API origin only if your deployment publishes one; in a single-origin deployment, the API path is usually behind the web origin's `/api/den` proxy.
|
|
|
|
### Interpreting common verdicts
|
|
|
|
| Verdict | What it usually means | First fix to check |
|
|
| --- | --- | --- |
|
|
| `LIKELY TLS INTERCEPTION` | The leaf issuer is an internal or proxy CA instead of the expected public issuer. | Allowlist the OpenWork hosts through the proxy, or install the enterprise root in every OpenWork trust surface that needs it. |
|
|
| `LIKELY MISSING INTERMEDIATE OR UNTRUSTED ROOT` | The server may be serving a leaf without the intermediate, or the machine lacks the issuing root. | Fix the server `fullchain`/certificate bundle first, then verify client trust. |
|
|
| `MISSING INTERMEDIATE CONFIRMED BY OPENSSL` | OpenSSL could not build the served chain. | Replace the server certificate bundle with a complete chain. |
|
|
| `LIKELY DNS ISSUE` | The hostname does not resolve on that machine. | Check VPN state, split-horizon DNS, and whether the internal hostnames exist. |
|
|
| `PROXY DETECTED` | WinHTTP or .NET routes the URL through a proxy. | Verify proxy authentication, host allowlisting, and expected system proxy behavior. |
|
|
|
|
## Cloud catalog diagnostic trust
|
|
|
|
Settings → Debug includes a cloud catalog diagnostic that probes the managed `openwork-cloud` MCP entry and verifies that Cloud exposes exactly `search_capabilities` and `execute_capability`.
|
|
|
|
For self-hosted Den origins, set `OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS` before OpenWork launches:
|
|
|
|
```bash
|
|
OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS=https://openwork.example.com
|
|
```
|
|
|
|
The value is a comma-separated list of bare origins: scheme, host, and optional port only. Entries must use `https:` except loopback origins, which may use `http:`.
|
|
|
|
If the Den origin is not trusted, the diagnostic is skipped and sends no credentialed request to that untrusted origin. Cloud MCP itself is unaffected; this variable only controls the diagnostic probe. Set it in the launcher, MDM profile, service wrapper, or shell environment before launch because the in-app environment store strips `OPENWORK_*` and `OPENCODE_*` keys.
|
|
|
|
## Den outbound diagnostic
|
|
|
|
Den can run an optional, admin-triggered outbound diagnostic from the Den process. It exercises the real container DNS, proxy, TLS trust, firewall, service mesh, and NetworkPolicy path.
|
|
|
|
- The default diagnostics origin is `https://diagnostic.openworklabs.com`.
|
|
- A workspace owner or super-admin starts the check; it is not a background dependency for Den.
|
|
- The diagnostic token must be synthetic and at least 24 characters. Do not use provider or customer credentials.
|
|
- To use an internal diagnostics origin, deploy the diagnostics app at an internally reachable supported runtime/origin, then set `DEN_DIAGNOSTICS_ORIGIN` and `DEN_DIAGNOSTICS_BEARER_TOKEN` for Den. The service README currently documents its runtime and retention model; do not assume a generic Kubernetes package unless your deployment path has been validated.
|
|
|
|
```dotenv
|
|
DEN_DIAGNOSTICS_ORIGIN=https://diagnostics.example.internal
|
|
DEN_DIAGNOSTICS_BEARER_TOKEN=<24-or-more-character-synthetic-token>
|
|
```
|
|
|
|
On Node.js 24.5 or newer, Den proxy configuration belongs in process-start environment such as `NODE_USE_ENV_PROXY=1`, `HTTPS_PROXY`, and `NO_PROXY`. Use `NODE_EXTRA_CA_CERTS` or Helm `customCa` when TLS inspection uses a private root. See [Certificate trust and proxies](/start-here/certificate-trust-and-proxies).
|
|
|
|
## Related diagnostics
|
|
|
|
- [Outbound network access](/start-here/outbound-network-access) lists the destination inventory and what breaks when a host is blocked.
|
|
- [Private network deployment](/start-here/private-network-deployment) explains the common VPN/private Den topology and internal MCP policy switch.
|
|
- [Diagnostic prompts](/start-here/troubleshooting/diagnostic-prompts) covers non-network runtime, MCP, and stale-tool debugging.
|