[FEATURE] Enterprise bootstrap mirror mode for installing and updating the APM CLI through Artifactory-compatible proxies

[yogurtearl]

Is your feature request related to a problem? Please describe.

Yes. APM has a strong enterprise story after the CLI is already installed: package dependency downloads can be routed through a registry proxy, direct fallback can be disabled, and internal marketplaces can be used for discovery.

The remaining gap is the bootstrap path for installing and updating the APM CLI itself.

In locked-down enterprise environments, developer workstations and CI runners often cannot reach public hosts directly. A company may require all third-party downloads to pass through approved Artifactory-compatible proxies for caching, audit, malware scanning, retention, and repeatable builds.

Today the documented install paths are split across public upstreams:

• shell installer via aka.ms
• GitHub release metadata and release assets
• Homebrew tap and formula resolution
• Scoop bucket resolution
• PyPI package installation for apm-cli

That makes initial rollout hard even when apm install itself can later use enterprise proxy settings. The first command a developer runs may still need public egress, or each organization has to create its own wrapper documentation and environment-specific workaround.

The problem is not that APM lacks package proxying. The problem is that APM does not appear to have one documented, testable, end-to-end enterprise bootstrap contract that says:

install and update the APM CLI, and then install packages, without any direct public-network dependency.

Describe the solution you'd like

Add a first-class enterprise bootstrap mirror mode for the APM CLI.

The desired outcome is a documented and tested path where an enterprise can install and update APM with every network request routed through approved mirrors/proxies.

Suggested shape:

1. Define a small set of installer/update override variables.

   Example:

   • APM_RELEASE_BASE_URL
   • APM_RELEASE_METADATA_URL
   • APM_INSTALLER_BASE_URL
   • APM_PYPI_INDEX_URL
   • APM_BOOTSTRAP_ONLY=1 or APM_NO_DIRECT_FALLBACK=1

   Exact names are flexible. The important contract is that the installer and apm self-update can be pointed at internal mirrors and can be told to fail closed instead of falling back to public hosts.

2. Make the Unix and Windows installers honor the mirror settings.

   In enterprise mode, the installer should be able to fetch release metadata and release assets from an Artifactory-compatible generic repository or mirror endpoint instead of directly from public release hosts.

   If APM_NO_DIRECT_FALLBACK=1 is set, the installer should fail with an actionable error rather than attempting a public fallback.

3. Make apm self-update use the same mirror contract.

   A user should not need a separate mechanism for day-0 install and later upgrades. If the CLI was installed through a mirror, updates should be able to use the same mirror and the same fail-closed behavior.

4. Document the recommended enterprise paths.

   The docs should include copy/pasteable examples for:

   • binary installer through an internal generic mirror
   • pipx install apm-cli through an internal PyPI proxy
   • Homebrew tap/formula mirroring guidance
   • Scoop bucket mirroring guidance
   • combining CLI bootstrap mirroring with PROXY_REGISTRY_URL, PROXY_REGISTRY_ONLY, and internal marketplaces for package installs

5. Add a verification command or documented test.

   It would be helpful to have either a command or a documented CI recipe that proves an environment is configured correctly.

   Example intent:

   • install APM from the internal mirror
   • run apm self-update --dry-run or equivalent
   • run apm install with PROXY_REGISTRY_ONLY=1
   • fail if any request would go to public hosts such as GitHub, aka.ms, PyPI, Homebrew, or Scoop upstreams

6. Keep this generic.

   This should not be specific to any one company or one Artifactory path layout. A fictional example host like https://artifactory.mycorp.example/... is enough. The feature should work with Artifactory-compatible repositories, internal static mirrors, or other enterprise artifact gateways.

A possible end-state developer experience:

export APM_RELEASE_BASE_URL="https://artifactory.mycorp.example/generic/apm-releases"
export APM_RELEASE_METADATA_URL="https://artifactory.mycorp.example/generic/apm-releases/latest.json"
export APM_NO_DIRECT_FALLBACK=1

curl -sSL "https://artifactory.mycorp.example/generic/apm-install/install.sh" | sh

export PROXY_REGISTRY_URL="https://artifactory.mycorp.example/github-proxy"
export PROXY_REGISTRY_ONLY=1

apm install

For Python-based installs:

pipx install apm-cli \
  --pip-args="--index-url https://artifactory.mycorp.example/api/pypi/python-proxy/simple"

This gives enterprises a single rollout story:

• bootstrap the CLI through approved infrastructure
• update the CLI through approved infrastructure
• install APM packages through approved infrastructure
• fail closed when the proxy/mirror is incomplete

Describe alternatives you've considered

1. Use pipx install apm-cli with a corporate PyPI proxy.

   This works well for environments that permit Python tooling, and it should remain documented. It does not cover teams that prefer the native binary installer, Homebrew, Scoop, or a standardized CLI bootstrap flow.

2. Use the existing PROXY_REGISTRY_URL settings.

   This solves package dependency downloads after APM is installed. It does not fully solve initial CLI installation or CLI self-update.

3. Mirror the GitHub release assets manually and write an internal wrapper script.

   This is possible, but every enterprise has to rediscover the same URL override rules, failure modes, and validation checks. It also creates drift from the official install path.

4. Use Homebrew or Scoop with internal mirror configuration.

   This may work in some environments, but it depends on package-manager-specific behavior and does not provide one APM-owned contract for fail-closed bootstrap and update behavior.

5. Allow direct public fallback.

   That is convenient for open networks but not acceptable in stricter enterprise environments. The feature should support explicit fail-closed behavior so configuration gaps are visible.

Additional context

This request is meant to complement the existing enterprise registry proxy model, not replace it.

The current enterprise story is strong once APM is installed: dependency fetches can be routed through a proxy, direct fallback can be blocked, and internal marketplaces can be used. The missing piece is making the CLI bootstrap/update path equally governable.

A minimal acceptable version could be mostly documentation plus installer/self-update URL overrides:

• document pipx through a PyPI proxy
• document binary install through a mirrored release base URL
• document Homebrew/Scoop mirror expectations
• make direct fallback explicitly disableable
• add tests or a smoke-test recipe that proves no public egress is required

A more complete version could add a single command such as:

apm doctor enterprise-bootstrap

or:

apm doctor network --no-public-egress

that validates the configured bootstrap, update, registry proxy, and marketplace settings.

This would make APM easier to approve in companies where all third-party tooling must come through internal artifact infrastructure before it can be used by developers or CI.

[github-actions]

Triage Panel Verdict -- Issue #1680

Thank you @yogurtearl for a well-structured feature request. The panel has reviewed it.

---

Issue summary

Feature: First-class enterprise bootstrap mirror mode -- env-var overrides for CLI install URLs and apm self-update, with a fail-closed option (APM_NO_DIRECT_FALLBACK=1) so that all bootstrap network requests route through Artifactory-compatible internal mirrors.

Root gap identified: APM already supports enterprise proxy routing for package dependency downloads (via PROXY_REGISTRY_URL / PROXY_REGISTRY_ONLY), but the CLI bootstrap and self-update path still requires direct public egress (GitHub releases, aka.ms, PyPI, Homebrew, Scoop). This makes initial rollout in locked-down environments harder than it needs to be.

---

Panel analysis

DevX UX Expert
The proposed env-var surface (APM_RELEASE_BASE_URL, APM_RELEASE_METADATA_URL, APM_NO_DIRECT_FALLBACK) follows the established pattern already in the codebase. The apm doctor enterprise-bootstrap / apm doctor network --no-public-egress diagnostic idea is a strong self-service validation tool that would reduce enterprise support overhead. The request is clear and actionable; the main open question is which exact URLs are overridable in v0 vs deferred.

Supply Chain Security Expert
This is an additive supply-chain security improvement. Routing CLI bootstrap through internally-controlled Artifactory proxies enables malware scanning, audit trails, build reproducibility, and compliance evidence. The fail-closed flag converts silent fallback (a security gap) into a loud failure (a visible config error). This is the correct enterprise posture and there are no security regressions in the proposal.

OSS Growth Hacker
"Tool makes outbound calls to public internet during install" is one of the most common IT rejection vectors for OSS adoption in enterprise environments. This feature directly removes that blocker. The +1 within hours of posting signals real demand. A documented, testable enterprise bootstrap path would significantly expand the APM adoption funnel in organizations that are currently blocked by network policy.

Python Architect
The implementation is well-decomposable:

1. URL-override env vars in Unix/Windows installer scripts and apm self-update logic.
2. Fail-closed guard (if APM_NO_DIRECT_FALLBACK=1 and a public URL would be needed, emit an actionable error and exit non-zero).
3. Documentation with copy-pasteable examples.
4. Optional doctor-style verification subcommand (can ship in a subsequent PR).

The env-var approach is portable and adds no required config-file schema changes.

APM CEO (arbiter)
Clear ACCEPT. This extends APM's enterprise story in the natural direction without breaking existing behavior. The minimal acceptable scope -- URL overrides for binary installer + apm self-update + docs + fail-closed flag -- is a finite, bounded implementation. Before coding starts, a brief interface spec comment should nail down: (a) final env var names, (b) which URLs are overridable in v0 vs deferred (Homebrew/Scoop mirroring may be out of scope for v0), (c) error message format when fail-closed triggers. Tagging status/needs-design to gate on that spec.

---

Decision

ACCEPT -- pending design brief

The feature concept is accepted. The panel recommends the author or an interested maintainer post a short design comment covering:

1. Final env var names (to avoid renaming after adoption).
2. v0 scope: which download paths are overridable (release asset, release metadata, installer script, PyPI index) vs explicitly deferred (Homebrew tap, Scoop bucket).
3. Fail-closed error format: what message does the user see and which exit code is returned?
4. Whether apm doctor network --no-public-egress ships with the initial PR or as a follow-on.

Once the interface contract is agreed on, this is a bounded implementation suitable for a contributor PR.

---

Triage outcome

Dimension	Decision
Type	type/feature (already present)
Area	area/distribution, area/enterprise
Theme	theme/governance, theme/security
Priority	priority/high -- enterprise adoption blocker pattern
Status	status/needs-design, status/triaged
Milestone	Not assigned -- maintainer to set after design brief; likely 2-3 sprints out from design agreement

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 1.3M · ◷

[yogurtearl]

What are the next steps here?