Separate “registry outage Twitter” from your own asymmetric routing
The open-source Agents CLI publishes official installation paths spanning uvx, pipx, plain pip, and optional npm skills loaders. Practically speaking, uvx google-agents-cli setup drags the Python shim first, resolving metadata from registry mirrors and downloading wheels from CDN hosts such as files.pythonhosted.org while also consulting GitHub-hosted metadata when versions pin specific artifacts.
Concurrently—or seconds later—a Node-assisted route may chase tarballs inside npm namespaces, resolve Git tags, or hydrate skills directories that expect low-latency git/npx operations. Communities often interpret any hang as PyPI turbulence, yet on congested ISP paths each leg behaves differently depending on TTL, QUIC availability, IPv6 preference, or whether CONNECT-aware libraries respect HTTP_PROXY.
Before escalating to infra teams, categorize failure shapes. Connection-level stalls that never emit HTTP statuses usually signal routing exhaustion; immediate HTTP error codes referencing authentication or quotas point to GCP configuration.
Duplicate the installers with narrower commands: isolate uv caches with UV_CACHE_DIR pointed at a disposable directory, rerun with verbose logging enabled, compare wall-clock durations against naive curl -Iv https://pypi.org/simple/google-agents-cli/ from the identical shell profile.
If PyPI curls succeed while npm metadata retrieval fails—or vice versa—you already know GEOIP catches are misaligned rather than blaming Google uptime dashboards.
Why dual Python and Node onboarding punishes fragile proxies
Agent Platform documentation insists on pairing modern Python interpreters with Astral uv because reproducible PEP 723 flows matter for scaffolding Google-backed starter kits referencing the ADK. Node remains mandatory for skills ingestion even when you seldom type JavaScript manually.
That combination defeats “set once and forget” terminal proxy stories: npm honors .npmrc proxies differently than uv honoring HTTPS_PROXY, and ephemeral subprocess orchestration launching through extension hosts may drop exported variables altogether.
Browser sessions can still authenticate to AI Studio happily while your terminal starves—Chromium leverages macOS or Windows PAC tables reliably, whereas Go-based CLIs spawned from editors might not inherit the same namespaces. Clash TUN sidesteps duplicated configuration by relocating policy enforcement below userland quirks: once the tunnel owns default routes eligible for interception, whichever HTTP client wakes up observes identical SNIs flowing through YAML rule ordering.
Elevate interception with Meta-class Clash TUN
Enable TUN in Clash Verge Rev, Mihomo-compatible GUIs, or headless systemd units documented across this site. Prefer the stack you understand—whether kernel system or isolated gvisor—rather than blindly toggling knobs after each updater release; trade-offs appear in detail inside Meta TUN stack comparison.
After rebooting helper daemons or approving macOS extensions, revisit connection logs confirming inbound flows list your terminal PID names when running Agents CLI.
Sanity-check interception with deterministic HTTPS probes before rerunning installers: sequential curls against PyPI mirrors, tarball hosts, OAuth surfaces that back Google identities, plus optional Gemini API pings if downstream evaluation depends on outbound inference. Successful TLS handshakes should converge within predictable milliseconds under healthy exits; outliers justify rotating proxy groups intentionally rather than reloading YAML randomly.
WSL caveat: Agent Platform upstream positions WSL 2 as the supported desktop environment on Windows. Windows TUN does not magically steer Linux NIC traffic; either forward through Mixed listeners documented in our WSL2 proxy guide or install Clash natively inside the distro—document whichever approach your security team mandates.
Reorder split routing for registries ahead of GEOIP defaults
Maintain a narrowly scoped outbound group—say Registry-Outbound backed by failover testing instead of leaderboard chasing—and pin suffix coverage for namespaces that actually manifest in logs rather than mythical blocklists scraped from Reddit.
Canonical starting points frequently include PyPI CDN suffixes (pypi.io, pypi.org, pythonhosted.org and files.pythonhosted.org), npm CDN edges (npmjs.org, tarball subdomains surfaced by npm view), Git namespaces (github.com, githubusercontent.com, GHCR endpoints), plus Google-managed surfaces tying together Agent Runtime registration.
Position these lines above blunt GEOIP/MATCH flows so domestic CDNs intended for unrelated media do not capture AI tooling traffic accidentally when latency looks temptingly lower.
# Example registry-aware block — replace Registry-Outbound
DOMAIN-SUFFIX,pypi.io,Registry-Outbound
DOMAIN-SUFFIX,pypi.org,Registry-Outbound
DOMAIN-SUFFIX,pythonhosted.org,Registry-Outbound
DOMAIN-SUFFIX,npmjs.org,Registry-Outbound
DOMAIN-SUFFIX,githubusercontent.com,Registry-Outbound
DOMAIN-SUFFIX,github.com,Registry-Outbound
DOMAIN-SUFFIX,googleapis.com,Registry-Outbound
# Refine via DOMAIN lines once logs show narrower hosts.
Overlay additional DOMAIN entries when manifests reference regional mirrors or Artifact Registry gateways for container images; never assume static lists hold forever across provider refactors.
Use Clash dashboards to preview matched policies for representative URLs extracted from installer logs—not generic marketing domains—avoiding regressions triggered by renaming paths under Google Cloud infrastructure.
Tighten npm and uv behavior after—not before—the dataplane aligns
Once TUN traffic visibly reaches the outbound you expect, consider incremental refinements tailored to npm and Astral tooling. Configure corporate-friendly registry mirrors cautiously via npm config set registry; verify checksum integrity because tampered mirrors defeat security auditing for supply-chain-heavy agent builds.
For uv, document environment variables aligning with Astral conventions—explicit HTTP_PROXY/HTTPS_PROXY pairs can remain empty when TUN already captures plaintext routing, simplifying debugging because fewer layers rewrite TLS.
Persist trusted CA bundles if inspecting traffic through HTTPS-decrypting gateways; mismatched interception chains often disguise themselves as indefinite TLS negotiation rather than actionable HTTP status codes from Agents CLI. Maintain reproducible snippets in team wikis so newcomers stop mixing manual exports with contradictory enterprise PAC files that ignore loopback exclusions.
Prevent FakeIP regressions across Python and npm resolvers
FakeIP excels when deterministic domain tags drive routing, yet incomplete fake-ip-filter lists resurrect randomness: some Node clients prefer system stub resolvers bundled with systemd-resolved while Python wheels query Clash-internal DNS concurrently.
Reconcile namespaces by inspecting both resolver outputs for identical authoritative answers when diagnosing stubborn stalls.
Dive deeper inside Meta core DNS leak prevention, then reconcile local LAN bypass entries so internal corporate git mirrors coexist with outbound registry splits.
During Agent Platform prototyping you may authenticate against AI Studio-derived API keys mirrored through marketing domains diverging from direct aistudio hostnames logged earlier; annotate those hosts when OAuth bounce chains split across continents.
Evidence-based iteration: Export Clash CSV logs correlating timestamps with Agents CLI stdout snippets; annotate first-match rule identifiers so downstream teammates inherit narrative context instead of orphaned YAML diffs lacking justification.
Operational verification playbook
Treat regressions scientifically. After altering YAML fragments, rerun a fixed battery: PyPI HEAD requests across multiple mirrors; npm pack dry runs against large scoped packages verifying tarball URLs; authenticated GETs validating Google-managed metadata endpoints reachable only after bearer tokens propagate.
Only then execute uvx google-agents-cli setup interactively watching each stage annotate network dependencies.
- Cold-boot baseline: disable Clash briefly, quantify timeout frequencies, annotate ISP noise floors.
- Enable TUN, disable competing VPN overlays temporarily: confirm virtual interfaces handshake without sysctl conflicts.
- Add registry suffix directives above GEOIP exits: reload profile verifying match precedence using preview tooling.
- Iterate DNS tweaks: align fake-ip-filter with observed SNIs, adjust DoH upstreams sparingly.
- Instrument npm caches: inspect
npm-debug.logartifacts only after capturing failing metadata JSON from the registry. - Rebuild uv caches cleanly: delete transient directories to avoid falsely blaming stale hashes.
- Smoke-test agent flows: run quick
agents-cli create --prototypeexamples after scaffolding completes to isolate runtime-only failures.
FAQ
Why does Agents CLI stall when npm install succeeds alone?
Separate TLS stacks hydrate distinct artifacts; GEOIP precedence may classify one egress as offshore while pinning another domestically despite identical corporate policies verbally stated in Slack threads.
Is exporting HTTP_PROXY for uv sufficient?
Frequently enough during lab experiments, unreliable once orchestrators spawn sanitized environments or QUIC surfaces bypass CONNECT-aware stacks.
Which hostnames warrant explicit YAML coverage?
Anchor on CDN suffix combinations listed earlier, augment with telemetry-derived identifiers when Google rotates asset hosting tiers.
Does WSL obey Windows routing automatically?
No—forward explicitly or dedicate Linux-side Clash installs per documented bridging patterns.
Tradeoffs and sober expectations
Transparent tunnels increase attack surface scrutiny from corporate desktop teams weighing kernel extensions skeptically versus browser-only SOCKS profiles. Routing everything labeled “technology” offshore may violate data residency mandates especially when scaffolding touches regulated industries; annotate compliance reviews concurrently with YAML edits.
Agents CLI cannot magically overcome genuine upstream outages, exhausted API quotas misconfigured IAM bindings, or operator mistakes confusing Application Default Credentials with raw Gemini keys. It can nevertheless remove the pervasive class wherein half-configured proxies split PyPI and npm legs into opposing directions, gifting teams ambiguous timeout theater around otherwise healthy Google-hosted services documented for Agent Platform.
Closing outlook
Reliable agent tooling hinges on reproducible scaffolding more than flashy chat demos; if uvx cannot finish because one resolver path disagrees about where npm tarballs originate, downstream evaluation harnesses collapse before innovators reach deployment templates.
Consistent Meta profiles—especially TUN-backed interception—translate opaque stalls into breadcrumb-rich connection logs aligning with deterministic remediation checklists teammates can rerun months later without rediscovering tribal knowledge.
Competing proxies often bifurcate policy between slick desktop apps and brittle shell exports, costing hours deciphering nondeterministic child processes that ignore environment duplication. By contrast Clash centralizes authoritative YAML alongside interactive dashboards bridging browser and terminal worlds: enable TUN, maintain registry-first split ordering, reconcile DNS thoughtfully, revisit verification scripts quarterly. If Agent Platform onboarding still wastes afternoons fighting half-proxied wheels, download Clash and transpose the playbook above—the same toolchain already proven for GitHub-heavy coding agents—to make google-agents-cli installation as mundane as cloning any other modern monorepo.