ops: air-gapped and private-cloud operation, proved by an egress-denied CI job #320

What this is

Make the SDK work, and be provably working, inside an air-gapped or private
cloud (PCE) deployment: no implicit reach for a public endpoint, no silent
degradation, and a way to prove it in CI rather than assert it in a README.

Why it is needed

Regulated buyers — public sector, defence, health, finance — run Anypoint in
Private Cloud Edition or fully air-gapped, and this is a procurement gate rather
than a preference. If the SDK cannot demonstrate it, the platform underneath it
does not get evaluated.

The concern is not that the SDK is designed to phone home. It is that nothing
today proves it does not, and the failure mode is quiet. Concrete exposures:

• Every base URL must be overridable and none may default to a public host.
  Config resolution supports this; there is no test asserting no default reaches
  a public endpoint.
• OTel exporters default to endpoints that may not exist inside the enclave.
  A telemetry export that hangs turns an observability nicety into a latency bug
  in the request path.
• Optional imports (opentelemetry, framework SDKs) are resolved at runtime.
  Any that attempts a network call on import fails in a confusing way.
• Framework SDKs themselves may contact their vendor for telemetry or model
  metadata. The SDK hands back the framework's own native object by design, so it
  cannot prevent this — but it can document it per adapter, which is more
  useful than an unqualified claim.
• Error and remediation strings that link to public documentation are dead
  ends for an operator with no route to the internet.

Scope

• An offline conformance run: the full suite against the local simulator with
  outbound network denied at the socket layer. This is the deliverable — a CI job
  that fails on any egress, so the claim is enforced rather than repeated.
• Audit every default in config.py and _verify.py for a public host.
• A documented, tested telemetry configuration for an in-enclave collector,
  including the behaviour when the collector is unreachable (degrade, never block).
• A per-adapter statement of whether the underlying framework SDK phones home,
  and how to disable it where the framework allows.
• Air-gapped installation guidance: extras, wheels, and what the base-only
  install genuinely requires.

Sketch

from donkey_kit import Donkey

# Everything private. No public host anywhere in the resolved config.
donkey = Donkey.from_env()          # DONKEY_LLM_PROXY_URL=https://gw.internal/llm
model = donkey.langgraph.chat_model("gpt-4o")           # deep adapter

# .donkey-kit.toml — an enclave profile
[llm]
base_url = "https://omni-gw.corp.internal/llm"
[registry]
base_url = "https://anypoint.corp.internal/exchange"
[telemetry]
otlp_endpoint = "http://otel-collector.corp.internal:4317"
on_export_failure = "drop"     # never block the request path

Proving it, which is the part that actually sells:

pytest -q --no-network            # fails on any egress attempt
donkey doctor --offline     # reports every resolved endpoint and its origin

Raw client — same guarantee; there is no adapter in the path to add one:

client = donkey.llm.client()

TypeScript parity (planned, Phase 5): the same egress-denied CI job, since a
Node-side default endpoint would reopen the gap on the other surface.

Acceptance

• A CI job runs the suite with egress denied and passes.
• No default in config.py or _verify.py resolves to a public host; asserted by test.
• Telemetry export failure degrades and never blocks a request.
• Per-adapter phone-home behaviour documented.
• doctor --offline prints every resolved endpoint and where it came from.
• Remediation strings do not depend on public links being reachable.

Cross-surface impact

• core: config.py, _verify.py, telemetry.py.
• llm / registry / tools: endpoint defaults.
• integrations: the per-adapter phone-home statement.
• TypeScript parity (planned): flag.
• Provisioning CLI: doctor --offline.
• Nextra docs site: an air-gapped deployment page — a sales asset as much as a doc.
• docs/verified-apis.md: PCE endpoint shapes may differ from cloud; a row if so.

Related

• a2a: donkey dev — a gateway in front of the laptop, real or simulated #227 / verify: self-managed gateway image availability and licensing for local development #258 / verify: whether the local simulator can be hosted on a2d-ai.com #279 — the local gateway and simulator this leans on.
• core/config: DonkeyConfig resolution order and all-at-once validation #10 — config resolution.