From b211cd08f2f8ac27e94e73a927462ffc2b4d83a2 Mon Sep 17 00:00:00 2001 From: mathias Date: Tue, 2 Jun 2026 11:40:50 +0000 Subject: [PATCH] docs: add build + runtime network egress requirements Lists the egress the build assumes (Go module proxy, toolchain download, raw.githubusercontent for golangci-lint, github for non-proxied modules) and the runtime assumes (LiteLLM gateway, brain-mcp, YouTube/Vimeo APIs, per-user BYO-AI hosts only on opt-in), so a locked-down koala act_runner or dev env knows what to allow or which GOPROXY to set. Notes the claude.ai sandbox allowlist is separate and unrelated. --- docs/homelab-integration.md | 43 +++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/homelab-integration.md b/docs/homelab-integration.md index 3dce04e..e9fbf27 100644 --- a/docs/homelab-integration.md +++ b/docs/homelab-integration.md @@ -68,6 +68,49 @@ This maps directly onto the copied `llm` package: `Client` is the OpenAI-compati LiteLLM relocating from piguard into k3s/ai-stack on koala — **confirm current location** if latency or endpoint matters. +## Network egress the build and runtime assume + +If the koala act_runner (or a dev environment) has locked-down egress, these must be reachable +or the build/run fails. Split into build-time and runtime because they're different lists and +fail at different stages. + +### Build-time (CI `check`/`build`, and local `go`/`task` work) + +- `proxy.golang.org`, `sum.golang.org` — Go module proxy + checksum DB. The default `GOPROXY`. + If a homelab GOPROXY (e.g. Athens) exists, point `GOPROXY` at it and this pair is not needed + directly — **confirm** whether one is run. +- `go.dev`, `dl.google.com` — Go toolchain download (the CI `setup-go` step / `go-version-file`). + Not needed if the runner already has the matching Go installed. +- `raw.githubusercontent.com` — the CI installs golangci-lint via its install script from here + (`.gitea/workflows/ci.yml`). +- `github.com`, `codeload.github.com` — any module not served by the proxy (incl. golangci-lint + and, later, `golang.org/x/oauth2` and its deps) is fetched from GitHub. +- `objects.githubusercontent.com` — GitHub release asset downloads (some installers redirect here). + +A configured `GOPROXY` collapses most of the module-fetch entries into one host. Recording the +homelab's actual `GOPROXY`/`GONOSUMCHECK` policy here once known would remove the **confirm**. + +### Runtime (the running service) + +- `koala:4000` (or the NodePort / post-relocation address) — LiteLLM gateway, the Primary. +- brain-mcp host (`*-mcp.d-ma.be`, **confirm**) — only when the brain sink is enabled. +- `www.googleapis.com` / YouTube Data API + `oauth2.googleapis.com` (token exchange/refresh) — + the YouTube provider adapter. +- `api.vimeo.com` — the Vimeo provider adapter. +- BYO-AI endpoints, per configured provider and **only when a user opts in**: + `api.anthropic.com`, `api.openai.com`, `generativelanguage.googleapis.com`. +- 1Password / ESO reach for secret resolution follows the homelab's existing ESO egress, not + Tapir-specific — no new rule expected. + +Note: a user with **no** BYO configured means the service never needs the third-party AI hosts +(the local-first guarantee, `docs/use-cases/ai_routing.feature`). Don't allow them by default; +allow per-provider when a user connects one. + +> The claude.ai chat sandbox (where planning sessions run code) has its **own** separate egress +> allowlist — unrelated to koala. It blocked `go.dev` during scaffolding, which is why the +> scaffold was reviewed but not compile-verified in-chat; verification belongs on koala via +> `task check` regardless. + ## Deployment / GitOps (when Tapir reaches deploy) - The homelab is **Flux GitOps**: manifests in `mathias/infra` under `k3s/`, Flux watches `main`.