# Review Topic Secure Gateway Url Wrapping

> Load when a PR adds or modifies an outbound HTTP call (requests.*, aiohttp, httpx, urllib), constructs a URL from API_BASE_URL / METRICS_COLLECTOR_BASE_URL / HOSTED_*_URL / any *.roboflow.com host, adds an env var or setting that holds an endpoint URL, builds an InferenceHTTPClient, or touches wrap_url / roboflow_secure_gateway_proxy_url_builder / SECURE_GATEWAY handling.

- Skill: `roboflow/review-topic-secure-gateway-url-wrapping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add roboflow/review-topic-secure-gateway-url-wrapping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/roboflow/review-topic-secure-gateway-url-wrapping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: roboflow (https://skillmd.com/u/roboflow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/roboflow/review-topic-secure-gateway-url-wrapping

---


# Review topic: Secure-gateway URL wrapping

## Why this exists

Air-gapped deployments set `SECURE_GATEWAY` (legacy `LICENSE_SERVER`) and can
reach ONLY the gateway host. Every Roboflow-bound request must be rewritten to
`{gateway}/proxy?url=<quoted url>` via `wrap_url()`
(`inference/core/utils/url_utils.py`) on the server side, or via
`roboflow_secure_gateway_proxy_url_builder`
(`inference_models/inference_models/weights_providers/roboflow.py`) inside
`inference_models`. A single unwrapped call site dead-ends behind the gateway —
usually as a hang or a retry loop, discovered only in a customer's air-gapped
environment (see #2658, which fixed three such gaps; #2263 for the offline
loading fallout).

## When this applies

Load when the diff shows ANY of these content signals (paths are hints, not the
trigger):

- A new or moved outbound HTTP call: `requests.get/post/put/head/delete`,
  `aiohttp`/`ClientSession`, `httpx`, `urllib.request.urlopen`, websockets.
- A URL built from `API_BASE_URL`, `METRICS_COLLECTOR_BASE_URL`,
  `HOSTED_DETECT_URL` / `HOSTED_INSTANCE_SEGMENTATION_URL` /
  `HOSTED_CLASSIFICATION_URL` / `HOSTED_CORE_MODEL_URL` /
  `HOSTED_SEMANTIC_SEGMENTATION_URL`, or any literal `*.roboflow.com` host.
- A new env var, pydantic setting, or config field whose value is an endpoint
  URL that will later be requested.
- A new `InferenceHTTPClient(api_url=...)` construction in server-side code.
- Any change to `wrap_url`, `roboflow_secure_gateway_proxy_url_builder`,
  `SECURE_GATEWAY` / `LICENSE_SERVER` parsing, or `/proxy?url=` handling.

## Review checklist

Tag each finding. Fix BLOCK before merge; raise FLAG; NIT is optional.

- **BLOCK** — A new request to a Roboflow-owned endpoint whose URL does not
  pass through `wrap_url()` (server code) or the weights-provider
  `proxy_url_builder` (`inference_models`) before the socket is opened.
  Trace the URL from construction to the `requests`/`aiohttp` call; "it is
  wrapped somewhere upstream" must be verifiable at a specific line. (Rule 1.)
- **BLOCK** — An endpoint URL sourced from an env var or setting where only
  the DEFAULT value is wrapped. Overrides must be wrapped at consumption time
  (validator or call site), not at field-definition time — a user-supplied
  `TELEMETRY_*`-style override otherwise bypasses the gateway. (Rule 2.)
- **BLOCK** — A network call that runs at module import time (version checks,
  registry warm-ups) with no timeout, or without honoring
  `SECURE_GATEWAY` / `OFFLINE_MODE` / its dedicated disable flag. Behind a
  packet-dropping firewall an untimed import-time call stalls server startup
  for the OS TCP timeout. (Rule 3.)
- **BLOCK** — A new consumer of hosted inference endpoints (`HOSTED_*_URL`,
  via `InferenceHTTPClient` or otherwise) with no `SECURE_GATEWAY` gate. The
  SDK client joins request paths onto `api_url`, which cannot compose with
  `/proxy?url=<encoded>` — hosted targets are unreachable behind a gateway, so
  the path must fail fast or fall back (see the remote+hosted → local fallback
  in `inference/core/env.py`). (Rule 4.)
- **FLAG** — Hand-rolled wrapping (f-string building `/proxy?url=` directly)
  instead of calling `wrap_url()`. The helper is idempotent and handles
  scheme-qualified vs bare-host gateways; inline copies drift. (Rule 5.)
- **FLAG** — A wrapped URL persisted to disk/db (queues, caches) and re-wrapped
  on read, or an endpoint stored pre-wrapped where `SECURE_GATEWAY` could
  differ between writer and reader processes. Persist raw URLs; wrap at send
  time. (Rule 6.)
- **FLAG** — A new third-party integration (Google/Stability/Twilio/Modal/
  webhook-style) reachable from a workflow or server path with no timeout or
  with errors that propagate as crashes rather than typed failures — behind a
  gateway these hosts are unreachable and the block must degrade cleanly.
  (Rule 7.)
- **NIT** — A new outbound integration not mentioned in the `SECURE_GATEWAY`
  section of `docs/quickstart/docker_configuration_options.md` when its
  gateway behavior is user-visible.

### Not blocking

- Calls to localhost / 127.0.0.1 / Unix sockets / LAN devices (PLC, ONVIF,
  local event-ingestion) — the gateway constraint is about egress.
- User-supplied media/webhook URLs fetched on behalf of the user (these are
  covered by `review-topic-input-boundary-security`); flag only if a NEW
  Roboflow-owned endpoint hides among them.
- Test files, docstrings, and examples containing URLs.
- `inference_models` package files downloaded from provider-returned URLs —
  those arrive pre-wrapped from `parse_package_artefacts` when the gateway is
  configured; do not demand a second wrap.

## Standards (one canonical statement per rule)

1. **Wrap at the socket, verifiably.** Every Roboflow-bound URL must flow
   through `wrap_url()` / `proxy_url_builder` on a traceable line before the
   request executes. The audit that produced this skill found the entire
   `roboflow_api.py` surface wrapped but 42 workflow `run_remotely` blocks and
   the version check unwrapped (#2658) — coverage claims must be per-call-site,
   not per-module.
2. **Defaults are not configuration.** Wrapping applied to a default value
   (field default, module constant) silently exempts every override. Wrap in
   the validator or at the call site so env-provided endpoints route through
   the gateway too (`TelemetrySettings` fix in #2658).
3. **Import-time network calls need a bound and a switch.** Any call that can
   run during `import inference.*` must carry an explicit `timeout=` and be
   disabled by `SECURE_GATEWAY` / `OFFLINE_MODE` / its own flag. The GitHub
   version check ran untimed at import and could stall startup for minutes on
   air-gapped networks (#2658).
4. **Hosted endpoints cannot be proxied — gate them.** Until `inference_sdk`
   understands the gateway `/proxy` contract, any server-side path that would
   contact `HOSTED_*_URL` under `SECURE_GATEWAY` must be rerouted or refused
   with a clear warning at configuration time, not left to fail per request.
5. **One wrapper implementation per package.** Server code calls `wrap_url()`;
   `inference_models` code uses the weights-provider builder. New inline
   `/proxy?url=` string construction is drift waiting to happen.
6. **Wrap late, store raw.** `SECURE_GATEWAY` is process configuration;
   persisted URLs outlive processes. Anything writing URLs to sqlite queues,
   caches, or model artifacts stores the raw URL and wraps at send time —
   `wrap_url` idempotence is a safety net, not a design.
7. **Unreachable third parties must degrade, not crash.** Blocks contacting
   non-Roboflow services are expected to fail behind a gateway — with a
   timeout, a typed/structured error, and no retry storm.