Skip to content

docs: a proxy is not the answer to an unreachable endpoint - #189

Merged
Sev7eNup merged 1 commit into
mainfrom
docs/llm-proxy-vs-firewall
Aug 12, 2026
Merged

docs: a proxy is not the answer to an unreachable endpoint#189
Sev7eNup merged 1 commit into
mainfrom
docs/llm-proxy-vs-firewall

Conversation

@Sev7eNup

Copy link
Copy Markdown
Owner

Why

Both AI-features documents put the outbound-proxy section ahead of the stage-by-stage connection diagnosis. A reader arriving with "the endpoint in our corporate network is unreachable" meets the proxy first — and configures one.

That is not hypothetical. It is what happened in the case that produced #185, #186 and #187: an LLM endpoint sitting in a different network segment without a firewall rule was read as a proxy problem. Several rounds and two releases later, the actual cause turned out to be the missing rule. A proxy answers "outbound traffic may only leave this network through the proxy"; it does nothing for a route that is blocked.

What

A short note at the top of both proxy sections stating what a proxy is and is not for, pointing at the stage diagnosis (LLM endpoint DNS: / TCP: / TLS:) that answers the question in seconds — the cheaper first step. The repo document names the real incident in one sentence, so the next reader does not have to rediscover it.

Docs only, no code. Anchors verified against the actual headings; the docs site generates ids via rehype-slug/github-slugger and Docs UI build passes.

Note on the three PRs this closes out

Asked to judge whether to keep or revert them, my recommendation was to keep all three:

  • Say which stage of reaching the LLM endpoint failed #186 (stage diagnosis) — validated by this very incident. Its TCP-stage message reads "the connection attempt was dropped rather than refused, which is what a firewall or a network segment boundary looks like from here" — that is the root cause, stated in seconds instead of after 360 s.
  • Verify the data directory the way the service will, before starting it #187 (installer ACL verification) — unrelated to the LLM story; fixes an install failure that actually occurred.
  • Let the AI features go out through a corporate proxy #185 (proxy) — the honest borderline case: it grew out of my misdiagnosis and nobody in that deployment needs it today. Kept because it closes a genuine independent gap (UseProxy = false was hard-coded, so a mandatory proxy could not be used at all), because Mode: Off equivalence is covered by unit tests and an end-to-end test in the production handler shape, and because the failing calls on 1.2.2/1.2.3 reached a TCP timeout — field evidence that the Off path connects directly.

This PR is the one change that came out of that review.

Both AI-features documents put the outbound-proxy section ahead of the
stage-by-stage diagnosis, so a reader arriving with "the endpoint in our
corporate network is unreachable" meets the proxy first and configures one.

That is not a hypothetical: it happened. An endpoint sitting in another network
segment without a firewall rule was read as a proxy problem and cost several
rounds before the missing rule was found. A proxy answers "outbound traffic MAY
only leave this network through the proxy"; it does nothing for a route that is
blocked.

Both sections now say so up front and point at the stage diagnosis, which
answers the question in seconds - the cheaper first step.
@Sev7eNup
Sev7eNup merged commit 7d692f9 into main Aug 12, 2026
8 checks passed
@Sev7eNup
Sev7eNup deleted the docs/llm-proxy-vs-firewall branch August 12, 2026 20:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant