freeride-gateway 0.3.0a1__tar.gz

freeride_gateway-0.3.0a1/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ruff / mypy
+.ruff_cache/
+.mypy_cache/
+
+# FreeRide local state (must NEVER be committed)
+.freeride/
+freeride.egg-info/

freeride_gateway-0.3.0a1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: freeride-gateway
+Version: 0.3.0a1
+Summary: Free-AI gateway: OpenAI-compatible local proxy that orchestrates free-tier inference across multiple providers
+Project-URL: Homepage, https://github.com/Shaivpidadi/FreeRideV3
+Project-URL: Repository, https://github.com/Shaivpidadi/FreeRideV3
+Author: Shaishav Pidadi
+License-Expression: MIT
+Keywords: ai,gateway,llm,openai,openrouter,proxy
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: e2e
+Requires-Dist: openai>=2; extra == 'e2e'
+Description-Content-Type: text/markdown
+
+# FreeRide
+
+**Free AI for everyone.** A local OpenAI-compatible gateway that orchestrates free-tier inference across multiple providers — OpenRouter, NVIDIA NIM, and more — and routes around outages and rate limits transparently.
+
+```
+[any agent] ──HTTP──> [FreeRide on localhost] ──HTTPS──> OpenRouter
+                                                    └──> NVIDIA NIM
+                                                    └──> (more providers)
+```
+
+Point any OpenAI-compatible client at `http://localhost:11343/v1` with API key `any` and you get free AI. When one provider rate-limits or fails, FreeRide invisibly fails over to the next. Streaming, tool calls, vision, and structured outputs all pass through.
+
+## Why
+
+You can already get free models from OpenRouter, NIM, Groq, etc. — but each has different rate limits, different free-detection rules, and different rate-limit semantics. Hitting one's daily cap means your agent stalls until tomorrow. FreeRide unifies them behind one OpenAI-shaped endpoint and rotates across providers and keys so your agent never sees a 429.
+
+Crucially:
+
+- **Local-first.** The gateway runs on your machine. Your prompts and completions never touch any FreeRide-operated server.
+- **Free-only by religion.** No paid fallback paths. No upsells.
+- **BYO keys.** You bring your own free-tier keys for each provider; FreeRide just routes.
+- **Telemetry off by default.** Optional, audit-friendly aggregate beacon (token counts, no content) — opt-in only via `freeride telemetry on`.
+
+## Install
+
+```bash
+pip install freeride-gateway            # latest stable (after 0.3.0 final)
+pip install --pre freeride-gateway      # alpha / pre-release (current)
+```
+
+The PyPI distribution is named `freeride-gateway`; the CLI binary it installs is `freeride`. Python ≥ 3.10.
+
+For local development, clone and `pip install -e .` from the repo root.
+
+## Quick start
+
+### 1. Get free API keys
+
+| Provider | Sign-up | Required env var |
+|---|---|---|
+| OpenRouter | https://openrouter.ai/keys | `OPENROUTER_API_KEY` |
+| NVIDIA NIM | https://build.nvidia.com/explore/discover | `NVIDIA_API_KEY` |
+
+You only need one to get started; more = better failover.
+
+### 2. Start the gateway
+
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-..."
+export NVIDIA_API_KEY="nvapi-..."  # optional
+
+freeride serve
+# freeride gateway listening on http://127.0.0.1:11343
+#   providers: openrouter, nvidia_nim
+#   point any OpenAI-compatible agent at:
+#     OPENAI_API_BASE=http://127.0.0.1:11343/v1
+#     OPENAI_API_KEY=any
+```
+
+### 3. Point your agent at it
+
+The fastest way is via a built-in binder:
+
+```bash
+freeride bind aider       # writes ~/.aider.conf.yml
+freeride bind continue    # writes ~/.continue/config.yaml
+freeride bind hermes      # writes ~/.hermes/cli-config.yaml
+freeride bind openclaw    # writes ~/.openclaw/openclaw.json
+```
+
+Or point any OpenAI-shaped client manually:
+
+```bash
+export OPENAI_API_BASE=http://localhost:11343/v1
+export OPENAI_API_KEY=any
+```
+
+That's it. Your agent now uses free AI with cross-provider failover.
+
+### 4. (Optional) Multi-key rotation
+
+```bash
+# JSON-array form to register multiple keys per provider
+export OPENROUTER_API_KEY='["sk-or-v1-key1", "sk-or-v1-key2"]'
+```
+
+When one key hits 429, FreeRide marks it cooling and uses the next on the next request. Cooldowns persist across restarts.
+
+## How it works
+
+### Cross-provider failover
+
+When you call `chat/completions`, FreeRide tries providers in registration order. For each provider it walks the available (non-cooling) keys; on `RATE_LIMIT` or `AUTH` it marks the key cooling and tries the next. On `MODEL_NOT_FOUND` it advances to the next provider. Once a provider produces a successful response (or a streaming response's first chunk), FreeRide commits and returns it to the client.
+
+The client never sees the failures — the response includes a `_freeride_provider` field (or `X-FreeRide-Provider` header on streaming responses) so you can audit which provider actually served any given request.
+
+### Streaming
+
+Streaming uses **buffer-first-chunk failover**: FreeRide holds the first SSE event from upstream until it confirms the stream started successfully. If upstream errors before producing the first chunk, FreeRide tries the next (provider, key) tuple. Once the first chunk has shipped to the client, mid-stream errors propagate as a truncated stream (rare in practice; documented limitation).
+
+### Telemetry
+
+Off by default. When you opt in (`freeride telemetry on`), FreeRide POSTs an aggregate beacon hourly with:
+
+```json
+{
+  "installation_id": "uuid-v4",
+  "version": "0.3.0",
+  "os": "darwin",
+  "tokens_served": 412034,
+  "request_count": 187,
+  "providers_active": ["openrouter", "nvidia_nim"],
+  "uptime_hours": 8
+}
+```
+
+**Never sent**: prompts, completions, model IDs, API keys, hostnames. Run `freeride telemetry` (no args) to inspect the exact payload before deciding.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `freeride serve` | Start the gateway on `localhost:11343` |
+| `freeride bind <agent>` | Write the gateway URL into the agent's config (atomic; preserves unrelated keys) |
+| `freeride telemetry [on\|off]` | Manage opt-in beacon (default OFF) |
+| `freeride list` | List available free models, ranked (v2 behavior) |
+| `freeride status` | Show current OpenClaw config + cache age (v2 behavior) |
+| `freeride auto` | Auto-configure best free model for OpenClaw (v2 behavior) |
+| `freeride rotate` | Live-test current primary; swap if it fails (v2 behavior) |
+| `freeride-watcher` | Background daemon that probes and rotates on failure (v2 behavior) |
+
+The v2 commands keep working for existing OpenClaw users; the new commands (`serve`, `bind`, `telemetry`) are the v3 surface.
+
+## Supported providers
+
+- **OpenRouter** ✅ — chat, streaming, tools, vision, structured outputs
+- **NVIDIA NIM** ✅ — chat, streaming (curated free-model allowlist; `NVIDIA_NIM_FREE_MODELS_OVERRIDE` env var to expand)
+- *Groq*, *Cloudflare Workers AI*, *HuggingFace Inference Providers*: Provider Protocol fits all three (see `knowledge/providers/SURVEY.md`); plugin implementations welcome.
+
+## Supported agents
+
+| Agent | `freeride bind <agent>` | Hot reload |
+|---|---|---|
+| OpenClaw | ✅ | restart needed |
+| Aider | ✅ (--scope home/cwd/git) | restart needed |
+| Continue | ✅ | yes |
+| Hermes (NousResearch/hermes-agent) | ✅ | restart needed |
+| OpenCode | extended; not yet shipped | — |
+
+Or any other OpenAI-compatible client via `OPENAI_API_BASE` + `OPENAI_API_KEY=any`.
+
+## Project documents
+
+- [`knowledge/PLAN_GATEWAY.md`](knowledge/PLAN_GATEWAY.md) — design plan, decisions, telemetry spec
+- [`knowledge/EXECUTION_PLAN.md`](knowledge/EXECUTION_PLAN.md) — phased execution playbook (90+ tasks)
+- [`knowledge/providers/`](knowledge/providers/) — per-provider technical references
+- [`knowledge/CONSUMERS.md`](knowledge/CONSUMERS.md) — per-agent bind reference
+- [`knowledge/HERMES.md`](knowledge/HERMES.md) — Hermes identification + bind plan
+
+## Contributing
+
+The Provider Protocol is `freeride.core.provider.Provider` with `api_version = 1`. To add a new provider:
+
+1. Implement the Protocol in `freeride/providers/<name>.py`
+2. Register your class in `tests/conformance/test_provider_conformance.py`'s `CONFORMANT_PROVIDERS` list
+3. Add `freeride/providers/<name>_model_metadata.py` if the catalog endpoint doesn't expose context length / capabilities
+
+The conformance suite covers the load-bearing invariants automatically.
+
+## License
+
+MIT.

freeride_gateway-0.3.0a1/README.md

@@ -0,0 +1,172 @@
+# FreeRide
+
+**Free AI for everyone.** A local OpenAI-compatible gateway that orchestrates free-tier inference across multiple providers — OpenRouter, NVIDIA NIM, and more — and routes around outages and rate limits transparently.
+
+```
+[any agent] ──HTTP──> [FreeRide on localhost] ──HTTPS──> OpenRouter
+                                                    └──> NVIDIA NIM
+                                                    └──> (more providers)
+```
+
+Point any OpenAI-compatible client at `http://localhost:11343/v1` with API key `any` and you get free AI. When one provider rate-limits or fails, FreeRide invisibly fails over to the next. Streaming, tool calls, vision, and structured outputs all pass through.
+
+## Why
+
+You can already get free models from OpenRouter, NIM, Groq, etc. — but each has different rate limits, different free-detection rules, and different rate-limit semantics. Hitting one's daily cap means your agent stalls until tomorrow. FreeRide unifies them behind one OpenAI-shaped endpoint and rotates across providers and keys so your agent never sees a 429.
+
+Crucially:
+
+- **Local-first.** The gateway runs on your machine. Your prompts and completions never touch any FreeRide-operated server.
+- **Free-only by religion.** No paid fallback paths. No upsells.
+- **BYO keys.** You bring your own free-tier keys for each provider; FreeRide just routes.
+- **Telemetry off by default.** Optional, audit-friendly aggregate beacon (token counts, no content) — opt-in only via `freeride telemetry on`.
+
+## Install
+
+```bash
+pip install freeride-gateway            # latest stable (after 0.3.0 final)
+pip install --pre freeride-gateway      # alpha / pre-release (current)
+```
+
+The PyPI distribution is named `freeride-gateway`; the CLI binary it installs is `freeride`. Python ≥ 3.10.
+
+For local development, clone and `pip install -e .` from the repo root.
+
+## Quick start
+
+### 1. Get free API keys
+
+| Provider | Sign-up | Required env var |
+|---|---|---|
+| OpenRouter | https://openrouter.ai/keys | `OPENROUTER_API_KEY` |
+| NVIDIA NIM | https://build.nvidia.com/explore/discover | `NVIDIA_API_KEY` |
+
+You only need one to get started; more = better failover.
+
+### 2. Start the gateway
+
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-..."
+export NVIDIA_API_KEY="nvapi-..."  # optional
+
+freeride serve
+# freeride gateway listening on http://127.0.0.1:11343
+#   providers: openrouter, nvidia_nim
+#   point any OpenAI-compatible agent at:
+#     OPENAI_API_BASE=http://127.0.0.1:11343/v1
+#     OPENAI_API_KEY=any
+```
+
+### 3. Point your agent at it
+
+The fastest way is via a built-in binder:
+
+```bash
+freeride bind aider       # writes ~/.aider.conf.yml
+freeride bind continue    # writes ~/.continue/config.yaml
+freeride bind hermes      # writes ~/.hermes/cli-config.yaml
+freeride bind openclaw    # writes ~/.openclaw/openclaw.json
+```
+
+Or point any OpenAI-shaped client manually:
+
+```bash
+export OPENAI_API_BASE=http://localhost:11343/v1
+export OPENAI_API_KEY=any
+```
+
+That's it. Your agent now uses free AI with cross-provider failover.
+
+### 4. (Optional) Multi-key rotation
+
+```bash
+# JSON-array form to register multiple keys per provider
+export OPENROUTER_API_KEY='["sk-or-v1-key1", "sk-or-v1-key2"]'
+```
+
+When one key hits 429, FreeRide marks it cooling and uses the next on the next request. Cooldowns persist across restarts.
+
+## How it works
+
+### Cross-provider failover
+
+When you call `chat/completions`, FreeRide tries providers in registration order. For each provider it walks the available (non-cooling) keys; on `RATE_LIMIT` or `AUTH` it marks the key cooling and tries the next. On `MODEL_NOT_FOUND` it advances to the next provider. Once a provider produces a successful response (or a streaming response's first chunk), FreeRide commits and returns it to the client.
+
+The client never sees the failures — the response includes a `_freeride_provider` field (or `X-FreeRide-Provider` header on streaming responses) so you can audit which provider actually served any given request.
+
+### Streaming
+
+Streaming uses **buffer-first-chunk failover**: FreeRide holds the first SSE event from upstream until it confirms the stream started successfully. If upstream errors before producing the first chunk, FreeRide tries the next (provider, key) tuple. Once the first chunk has shipped to the client, mid-stream errors propagate as a truncated stream (rare in practice; documented limitation).
+
+### Telemetry
+
+Off by default. When you opt in (`freeride telemetry on`), FreeRide POSTs an aggregate beacon hourly with:
+
+```json
+{
+  "installation_id": "uuid-v4",
+  "version": "0.3.0",
+  "os": "darwin",
+  "tokens_served": 412034,
+  "request_count": 187,
+  "providers_active": ["openrouter", "nvidia_nim"],
+  "uptime_hours": 8
+}
+```
+
+**Never sent**: prompts, completions, model IDs, API keys, hostnames. Run `freeride telemetry` (no args) to inspect the exact payload before deciding.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `freeride serve` | Start the gateway on `localhost:11343` |
+| `freeride bind <agent>` | Write the gateway URL into the agent's config (atomic; preserves unrelated keys) |
+| `freeride telemetry [on\|off]` | Manage opt-in beacon (default OFF) |
+| `freeride list` | List available free models, ranked (v2 behavior) |
+| `freeride status` | Show current OpenClaw config + cache age (v2 behavior) |
+| `freeride auto` | Auto-configure best free model for OpenClaw (v2 behavior) |
+| `freeride rotate` | Live-test current primary; swap if it fails (v2 behavior) |
+| `freeride-watcher` | Background daemon that probes and rotates on failure (v2 behavior) |
+
+The v2 commands keep working for existing OpenClaw users; the new commands (`serve`, `bind`, `telemetry`) are the v3 surface.
+
+## Supported providers
+
+- **OpenRouter** ✅ — chat, streaming, tools, vision, structured outputs
+- **NVIDIA NIM** ✅ — chat, streaming (curated free-model allowlist; `NVIDIA_NIM_FREE_MODELS_OVERRIDE` env var to expand)
+- *Groq*, *Cloudflare Workers AI*, *HuggingFace Inference Providers*: Provider Protocol fits all three (see `knowledge/providers/SURVEY.md`); plugin implementations welcome.
+
+## Supported agents
+
+| Agent | `freeride bind <agent>` | Hot reload |
+|---|---|---|
+| OpenClaw | ✅ | restart needed |
+| Aider | ✅ (--scope home/cwd/git) | restart needed |
+| Continue | ✅ | yes |
+| Hermes (NousResearch/hermes-agent) | ✅ | restart needed |
+| OpenCode | extended; not yet shipped | — |
+
+Or any other OpenAI-compatible client via `OPENAI_API_BASE` + `OPENAI_API_KEY=any`.
+
+## Project documents
+
+- [`knowledge/PLAN_GATEWAY.md`](knowledge/PLAN_GATEWAY.md) — design plan, decisions, telemetry spec
+- [`knowledge/EXECUTION_PLAN.md`](knowledge/EXECUTION_PLAN.md) — phased execution playbook (90+ tasks)
+- [`knowledge/providers/`](knowledge/providers/) — per-provider technical references
+- [`knowledge/CONSUMERS.md`](knowledge/CONSUMERS.md) — per-agent bind reference
+- [`knowledge/HERMES.md`](knowledge/HERMES.md) — Hermes identification + bind plan
+
+## Contributing
+
+The Provider Protocol is `freeride.core.provider.Provider` with `api_version = 1`. To add a new provider:
+
+1. Implement the Protocol in `freeride/providers/<name>.py`
+2. Register your class in `tests/conformance/test_provider_conformance.py`'s `CONFORMANT_PROVIDERS` list
+3. Add `freeride/providers/<name>_model_metadata.py` if the catalog endpoint doesn't expose context length / capabilities
+
+The conformance suite covers the load-bearing invariants automatically.
+
+## License
+
+MIT.

freeride_gateway-0.3.0a1/freeride/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0a1"

freeride_gateway-0.3.0a1/freeride/binders/__init__.py

@@ -0,0 +1,18 @@
+"""Per-agent binder helpers — write one URL into one config file.
+
+These are deliberately *not* a generic Consumer plugin abstraction (see
+PLAN_GATEWAY.md §6). Each binder is a small, ad-hoc adapter that knows
+exactly how to point its specific agent at the FreeRide gateway. The
+common pattern is:
+
+* Locate the agent's config file (env-var override > default path)
+* Read it (atomic; preserve all unrelated keys)
+* Set the gateway URL + api_key="any"
+* Atomic-write back
+
+The contract is one function per agent, signature::
+
+    def bind(gateway_url: str, *, api_key: str = "any") -> str
+
+Returning a one-line status string the CLI prints.
+"""

freeride_gateway-0.3.0a1/freeride/binders/aider.py

@@ -0,0 +1,84 @@
+"""``freeride bind aider`` — point Aider at the gateway.
+
+Per ``knowledge/CONSUMERS.md``: Aider's config search order is
+git-root → cwd → home, so we default to the home-scoped
+``~/.aider.conf.yml``. The user can pass a ``scope`` to force one of
+the other locations.
+
+Aider requires a restart after config changes (no hot reload).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+from freeride.core.state import atomic_write
+
+
+Scope = Literal["home", "cwd", "git"]
+
+
+def _aider_config_path(scope: Scope) -> Path:
+    if scope == "home":
+        return Path.home() / ".aider.conf.yml"
+    if scope == "cwd":
+        return Path.cwd() / ".aider.conf.yml"
+    # git: walk up from cwd looking for a .git directory
+    cur = Path.cwd().resolve()
+    while True:
+        if (cur / ".git").exists():
+            return cur / ".aider.conf.yml"
+        if cur.parent == cur:
+            # No git root found; fall back to cwd.
+            return Path.cwd() / ".aider.conf.yml"
+        cur = cur.parent
+
+
+def _read_yaml_lines(path: Path) -> list[str]:
+    """Read existing aider config preserving all other lines.
+
+    We avoid pulling in PyYAML by doing line-based edits — Aider's
+    config file is a flat key:value YAML, no nested structures. This
+    keeps the binder dep-free.
+    """
+    if not path.exists():
+        return []
+    return path.read_text().splitlines()
+
+
+def _set_or_append(lines: list[str], key: str, value: str) -> list[str]:
+    """Replace the first matching ``key:`` line, or append at end."""
+    out: list[str] = []
+    seen = False
+    for line in lines:
+        if not seen and line.lstrip().startswith(f"{key}:"):
+            out.append(f"{key}: {value}")
+            seen = True
+        else:
+            out.append(line)
+    if not seen:
+        out.append(f"{key}: {value}")
+    return out
+
+
+def bind(
+    gateway_url: str,
+    *,
+    api_key: str = "any",
+    scope: Scope = "home",
+    config_path: Path | None = None,
+) -> str:
+    path = config_path or _aider_config_path(scope)
+    lines = _read_yaml_lines(path)
+    lines = _set_or_append(lines, "openai-api-base", gateway_url)
+    lines = _set_or_append(lines, "openai-api-key", api_key)
+
+    atomic_write(path, "\n".join(lines) + "\n")
+    return (
+        f"Aider config at {path} updated.\n"
+        f"  openai-api-base: {gateway_url}\n"
+        f"  openai-api-key: {api_key}\n"
+        f"  Aider has no hot-reload — restart aider for changes to take effect."
+    )

freeride_gateway-0.3.0a1/freeride/binders/continue_.py

@@ -0,0 +1,120 @@
+"""``freeride bind continue`` — append a model entry to Continue's config.
+
+Per ``knowledge/CONSUMERS.md``: current Continue uses ``~/.continue/config.yaml``
+(legacy ``config.json`` may exist on older installs). The provider type
+must be ``openai`` (NOT ``openai-compatible``). Continue hot-reloads on
+next prompt — no restart needed.
+
+We support both YAML and JSON paths. If both exist we update YAML
+(the current canonical format). If neither exists we create the YAML.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from freeride.core.state import atomic_write
+
+
+_DEFAULT_DIR = Path.home() / ".continue"
+_YAML_NAME = "config.yaml"
+_JSON_NAME = "config.json"
+
+_FREERIDE_TITLE = "freeride"
+
+
+def _yaml_block(gateway_url: str, api_key: str) -> str:
+    """Return a single ``models:`` entry block as YAML — appended to whatever
+    list already exists. Avoids requiring PyYAML for the common path.
+    """
+    return (
+        f"  - title: {_FREERIDE_TITLE}\n"
+        f"    provider: openai\n"
+        f"    model: free\n"
+        f"    apiBase: {gateway_url}\n"
+        f"    apiKey: {api_key}\n"
+        f"    roles: [chat, edit, autocomplete]\n"
+    )
+
+
+def _bind_yaml(path: Path, gateway_url: str, api_key: str) -> None:
+    if not path.exists():
+        atomic_write(path, "models:\n" + _yaml_block(gateway_url, api_key))
+        return
+
+    text = path.read_text()
+    # Strip any prior freeride entry (idempotent re-runs).
+    if f"title: {_FREERIDE_TITLE}\n" in text or f"title: {_FREERIDE_TITLE}" in text.splitlines()[-1] if text else False:
+        # Simple drop of the previous block: split on lines, skip 6
+        # consecutive lines starting with "  - title: freeride".
+        lines = text.splitlines()
+        out: list[str] = []
+        skip = 0
+        for line in lines:
+            if skip > 0:
+                skip -= 1
+                continue
+            if line.strip() == f"- title: {_FREERIDE_TITLE}" or line.strip() == f"- title: {_FREERIDE_TITLE}\n":
+                skip = 5  # 5 indented lines after the - title line
+                continue
+            out.append(line)
+        text = "\n".join(out)
+        if not text.endswith("\n"):
+            text += "\n"
+
+    if "models:" not in text:
+        text = (text.rstrip() + "\n" if text else "") + "models:\n"
+
+    # Append the freeride block right after the "models:" line.
+    new_text = text.rstrip() + "\n" + _yaml_block(gateway_url, api_key)
+    atomic_write(path, new_text)
+
+
+def _bind_json(path: Path, gateway_url: str, api_key: str) -> None:
+    try:
+        config = json.loads(path.read_text()) if path.exists() else {}
+    except json.JSONDecodeError:
+        config = {}
+
+    models = config.setdefault("models", [])
+    models = [m for m in models if m.get("title") != _FREERIDE_TITLE]
+    models.append(
+        {
+            "title": _FREERIDE_TITLE,
+            "provider": "openai",
+            "model": "free",
+            "apiBase": gateway_url,
+            "apiKey": api_key,
+            "roles": ["chat", "edit", "autocomplete"],
+        }
+    )
+    config["models"] = models
+    atomic_write(path, json.dumps(config, indent=2))
+
+
+def bind(
+    gateway_url: str,
+    *,
+    api_key: str = "any",
+    config_dir: Path | None = None,
+) -> str:
+    base = config_dir or _DEFAULT_DIR
+    base.mkdir(parents=True, exist_ok=True)
+    yaml_path = base / _YAML_NAME
+    json_path = base / _JSON_NAME
+
+    if yaml_path.exists() or not json_path.exists():
+        # Default modern path: YAML
+        _bind_yaml(yaml_path, gateway_url, api_key)
+        chosen = yaml_path
+    else:
+        _bind_json(json_path, gateway_url, api_key)
+        chosen = json_path
+
+    return (
+        f"Continue config at {chosen} updated.\n"
+        f"  Added model: freeride (provider=openai, apiBase={gateway_url})\n"
+        f"  Roles: chat, edit, autocomplete\n"
+        f"  Continue hot-reloads — no restart needed."
+    )