feat(proxy): ship standalone developer sidecar

[antoinezambelli]

Summary

Forge 0.9.1 adds a self-contained developer-sidecar distribution for Forge Proxy without changing the 0.9 forwarding, routing, or guardrail contract.

The punchline is intentionally simple: curl -fsSL https://raw.githubusercontent.com/antoinezambelli/forge/main/install.sh | sh, then forge-proxy init—no Python, pip, or repository checkout. Windows gets the equivalent one-line PowerShell installer.

This PR:

• packages forge-proxy for Windows x64, Linux x64/glibc, and macOS ARM64 with a private Python 3.14 runtime;
• adds one-command POSIX and PowerShell installation without requiring Python or pip;
• adds managed profiles and init, check, update, and uninstall commands;
• installs immutable version slots behind one stable command;
• supports stable updates and explicit-version installation or recovery;
• adds checksum-verified manifests, cross-platform candidate gates, exact-tag publication, and post-publication stable promotion; and
• documents the standalone path while preserving the Python library for WorkflowRunner, middleware, development, and existing Proxy users.

The package version is bumped to 0.9.1.

Why

Proxy has become Forge’s most-used integration surface, but using it still requires cloning the repository or installing and managing a Python environment.

The standalone distribution turns Proxy into an ordinary developer sidecar: install one self-contained command, configure a backend profile, and point an OpenAI- or Anthropic-compatible client at it. Existing clients do not need to integrate Forge’s Python API or rewrite their harness.

The artifact deliberately does not install a backend executable, model, GPU or driver stack, service, credentials, or client configuration. Those remain operator- or wrapper-owned.

Installation and profiles

The public bootstraps resolve either the latest verified standalone release or an explicit Forge version, download the matching platform artifact, verify its manifest and checksum, and hand installation to the frozen executable.

Installation:

• never consumes interactive onboarding input;
• creates an immutable version slot;
• publishes one forge-proxy command;
• integrates that command with the user’s PATH;
• performs a packaged self-check; and
• prints explicit init and check next steps.

forge-proxy init writes sparse TOML profiles using Forge’s existing Proxy configuration contract. Profiles and direct CLI flags remain separate complete configuration sources rather than overlays.

forge-proxy check validates managed profiles and exercises a temporary local /forge/health listener without contacting or installing a backend.

Update and removal

• forge-proxy update follows the verified stable Proxy pointer.
• forge-proxy update --version X.Y.Z targets an explicit newer Forge release.
• Exact-version bootstrap installation provides recovery without a separate rollback command.
• Failed downloads, checksum mismatches, and pre-promotion failures leave the active installation unchanged.
• Uninstall removes installer-owned executable state and PATH integration while preserving profiles.

Forge releases may omit standalone artifacts. Every Proxy release uses an exact Forge version, tag, and GitHub Release; the stable Proxy pointer may therefore lag the latest Forge/PyPI version.

Release assurance

Release-candidate and exact-tag workflows:

• build native artifacts on Windows, Linux, and macOS;
• exercise both directory and one-file packaging;
• run packaged OpenAI- and Anthropic-shaped smoke checks;
• run the complete isolated install/update/recovery/failure/uninstall lifecycle;
• execute the identical Linux artifact on Ubuntu 22.04, Debian 12, and Fedora;
• assemble and re-verify one complete immutable artifact set; and
• publish the stable pointer only after exact-version installation succeeds.

Compatibility

Existing python -m forge.proxy invocations remain supported. Proxy inference, retries, metadata forwarding, model routing, context reporting, and guardrails retain their Forge 0.9 behavior.

The source package continues to support Python 3.12 and 3.13 and now officially includes Python 3.14. Python 3.14 is used as the private runtime inside standalone artifacts.

Local validation

• Full Python 3.14 unit suite: 1,530 passed, 1 skipped
• Deterministic mocked-backend Proxy smoke: 19/19
• Focused release and installation documentation checks: 46 passed
• Windows x64 PyInstaller directory and one-file builds: passed
• Packaged OpenAI, Anthropic, health, help, version, shutdown, and extraction-cleanup smoke: passed
• Isolated Windows installation lifecycle: 20/20 steps passed
  • profile preservation;
  • unavailable-download rejection;
  • checksum-mismatch rejection;
  • version-mismatch rejection before promotion;
  • PATH restoration;
  • uninstall cleanup; and
  • untouched non-Forge user state.

Cross-platform GitHub candidate gates and an independent local Linux lifecycle run remain required before merge.

🤖 Generated with Codex and human-reviewed.