docs: correct Antigravity IDE setup instructions (no third-party model providers) (#4258)

## Description

Follow-up to the merged #3817. As flagged in the post-merge thread, the
Antigravity IDE doesn’t expose third-party model-provider settings, so
the setup text was telling users to add a custom model provider in a
panel that doesn’t exist. The instructions now describe what the
integration actually covers (MCP registration and the
`/v1internal:streamGenerateContent` endpoint for `google-antigravity`
clients) and distinguish the IDE from the Antigravity CLI (`agy`), which
is the surface that accepts a custom endpoint via
`GOOGLE_GEMINI_BASE_URL`.

Follow-up fix (Devin review on this PR): the `agy` note mentioned
`GOOGLE_GEMINI_BASE_URL` but only printed the OpenAI-compatible URL. It
now prints the Gemini-compatible base URL (scheme://host, the Gemini API
convention) as an explicit `GOOGLE_GEMINI_BASE_URL=...` assignment, and
the OpenAI block is labeled for OpenAI-speaking clients.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom wrap antigravity` help text and printed setup instructions
no longer reference IDE model-provider settings; they point at MCP
registration and the native endpoint, and name the CLI separately.
- The `agy` note now shows the Gemini-compatible base URL explicitly
(`GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:<port>`), with the project
prefix (`/p/<name>`) applied like the other URLs.
- `docs/content/docs/proxy.mdx` Antigravity section corrected the same
way.
- Tests updated to assert the corrected wording.

## Testing

- [x] Unit tests pass (`pytest`)

### Test Output

```text
$ pytest tests/test_provider_antigravity.py -q
12 passed, 1 warning in 2.07s

$ pytest tests/test_mcp_registry/test_antigravity_registrar.py -q
25 passed, 1 warning in 0.82s
```

(`test_cli/test_wrap_antigravity.py` was not run locally — `typer` is
not installed in this environment; CI covers it.)

## Real Behavior Proof

- Environment: docs/string-only change; no runtime behavior affected.
- What was checked: the removed claim ("add a custom OpenAI-compatible
model provider in Antigravity’s model-provider settings") was verified
false three ways — the reporter’s own `~/.gemini/settings.json` has no
model-provider keys; Antigravity IDE 2.5.5 exposes no third-party
model-provider settings panel (upstream report plus current docs); and
the `google-antigravity` clients the new text names really do speak
Cloud Code Assist (`POST /v1internal:streamGenerateContent` is served by
the proxy — see `CLOUDCODE_HANDLER_ROUTES` in `route_specs.py`).
- Observed result: `render_setup_lines(8787)` now prints the corrected
IDE/MCP/native-traffic text,
`GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787` for `agy`, and the OpenAI
block labeled for OpenAI-speaking clients; the 37 tests above pass.
- Not tested: a live Antigravity IDE run — no Mac with the IDE installed
in this environment, and nothing in this change touches a runtime path,
so there is no behavior to smoke-test.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — documentation/strings only.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: no; rendered CLI text only.
- Kill switch / disable path: n/a.
- Unsafe override required: n/a.
- Qualification impact: none.
- Rollback path: revert the commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project’s style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Docs-only PR; the remaining `wrap` CLI test module is covered by CI.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4258"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
This commit is contained in:
AP
2026-10-20 21:48:29 -05:00
committed by GitHub
parent 506ba16c4a
commit 4c7acba593
5 changed files with 59 additions and 34 deletions
+14 -9
View File
@@ -528,16 +528,21 @@ headroom wrap antigravity # Start proxy + print Antigravity setup instr
headroom mcp install --agent antigravity # Register the Headroom MCP server in Antigravity
```
`wrap antigravity` prints a custom OpenAI-compatible model-provider base URL
to add in Antigravity's model-provider settings; Antigravity fetches the model
list from `GET /v1/models` on its own. Native Cloud Code Assist traffic
(`google-antigravity` clients) is accepted on
[`POST /v1internal:streamGenerateContent`](#post-v1internalstreamgeneratecontent)
and routed upstream like any other Cloud Code request.
The Antigravity IDE does not support third-party model providers — its
agent models are Google-managed, so there is no settings panel to point
at the proxy. What the proxy does offer Antigravity users:
MCP registration writes to Antigravity's global `mcp_config.json` under
`~/.gemini/` (preferring the install's current location when one already
exists) and refuses to overwrite a config file that does not parse as JSON.
- MCP tools: `mcp install` writes the Headroom server into Antigravity's
global `mcp_config.json` under `~/.gemini/` (preferring the install's
current location when one already exists) and refuses to overwrite a
config file that does not parse as JSON.
- Native traffic: `google-antigravity` clients are accepted on
[`POST /v1internal:streamGenerateContent`](#post-v1internalstreamgeneratecontent)
and routed upstream like any other Cloud Code request.
The Antigravity CLI (`agy`), unlike the IDE, accepts a custom endpoint
via its `GOOGLE_GEMINI_BASE_URL` setting — the one Antigravity surface
where a custom model endpoint is supported.
### `POST /v1/compress`
+8 -10
View File
@@ -7905,21 +7905,19 @@ def antigravity(
verbose: bool,
prepare_only: bool,
) -> None:
"""Start Headroom proxy for use with Antigravity IDE.
"""Start Headroom proxy for use with the Antigravity IDE.
\b
Antigravity reads its model endpoints from its model-provider settings,
not from environment variables. This command starts the proxy and prints
the settings to add as a custom OpenAI-compatible model provider.
\b
After running this command, open Antigravity and add a custom model
provider with the printed base URL. Antigravity fetches the model list
from GET /v1/models automatically.
The Antigravity IDE does not support third-party model providers —
its agent models are Google-managed. This command starts the proxy
and prints what the integration actually covers: MCP server
registration (`headroom mcp install --agent antigravity`) and the
native `POST /v1internal:streamGenerateContent` endpoint for
`google-antigravity` clients.
\b
Example:
headroom wrap antigravity # Start proxy + Antigravity settings
headroom wrap antigravity # Start proxy + Antigravity setup
headroom wrap antigravity --port 9999 # Custom proxy port
"""
if prepare_only:
+25 -10
View File
@@ -22,9 +22,9 @@ def build_proxy_targets(port: int, project: str | None = None) -> AntigravityPro
"""Build the local proxy URLs shown to Antigravity users.
``project`` (the wrap launch directory) is encoded as a ``/p/<name>``
base-URL prefix because Antigravity's custom model-provider settings
cannot send custom headers; the proxy strips it and attributes savings
per project.
base-URL prefix because clients pointing at these URLs cannot be
counted on to send custom headers; the proxy strips it and attributes
savings per project.
"""
return AntigravityProxyTargets(
openai_base_url=with_project_prefix(codex_proxy_base_url(port), project),
@@ -35,17 +35,32 @@ def build_proxy_targets(port: int, project: str | None = None) -> AntigravityPro
def render_setup_lines(port: int, project: str | None = None) -> list[str]:
"""Render the Antigravity setup instructions for the local proxy."""
targets = build_proxy_targets(port, project)
# The Gemini-compatible base URL (scheme://host; Gemini clients append
# /v1beta/...) — the one agy expects for GOOGLE_GEMINI_BASE_URL.
gemini_base_url = with_project_prefix(f"http://127.0.0.1:{port}", project)
lines = [
" Headroom proxy is running. Configure Antigravity:",
" Headroom proxy is running. Antigravity setup:",
"",
" Antigravity reads model endpoints from its model-provider settings,",
" not from environment variables. Add a custom OpenAI-compatible",
" model provider pointing at the proxy:",
" The Antigravity IDE does not support third-party model providers —",
" its agent models are Google-managed, so there is no settings panel",
" to point at the proxy. What the proxy does offer Antigravity users:",
"",
" - MCP tools: `headroom mcp install --agent antigravity` registers",
" the Headroom MCP server in Antigravity's global mcp_config.json.",
" - Native traffic: the proxy accepts `google-antigravity` client",
" traffic on POST /v1internal:streamGenerateContent, routed",
" upstream like any other Cloud Code request.",
"",
" The Antigravity CLI (agy), unlike the IDE, accepts a custom",
" endpoint via its GOOGLE_GEMINI_BASE_URL setting — point it at",
" the proxy's Gemini-compatible base URL:",
"",
f" GOOGLE_GEMINI_BASE_URL={gemini_base_url}",
"",
" For OpenAI-speaking clients, the proxy's OpenAI-compatible",
" base URL is:",
"",
f" Base URL: {targets.openai_base_url}",
" API Key: your-openai-api-key",
"",
" Antigravity fetches the model list from GET /v1/models automatically,",
" so there is nothing else to register.",
]
return lines + project_attribution_lines(project)
+3 -2
View File
@@ -17,11 +17,12 @@ def test_wrap_help_lists_antigravity() -> None:
assert "antigravity" in result.output
def test_wrap_antigravity_help_mentions_custom_model_provider() -> None:
def test_wrap_antigravity_help_says_ide_has_no_third_party_providers() -> None:
result = CliRunner().invoke(main, ["wrap", "antigravity", "--help"])
assert result.exit_code == 0, result.output
assert "Antigravity" in result.output
assert "OpenAI-compatible" in result.output
assert "does not support third-party model providers" in result.output
assert "custom OpenAI-compatible model provider" not in result.output
def test_wrap_antigravity_prepare_only_exits_cleanly() -> None:
+9 -3
View File
@@ -56,10 +56,16 @@ def test_antigravity_render_setup_lines_contains_proxy_url() -> None:
assert "Antigravity" in joined
def test_antigravity_render_setup_lines_mentions_custom_provider() -> None:
def test_antigravity_setup_lines_do_not_claim_ide_provider_settings() -> None:
joined = "\n".join(render_setup_lines(8787))
assert "OpenAI-compatible" in joined
assert "/v1/models" in joined
assert "does not support third-party model providers" in joined
assert "Add a custom OpenAI-compatible" not in joined
assert "model-provider settings" not in joined
assert "mcp install --agent antigravity" in joined
assert "/v1internal:streamGenerateContent" in joined
assert "GOOGLE_GEMINI_BASE_URL" in joined
assert "GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787" in joined
assert "For OpenAI-speaking clients" in joined
def test_antigravity_render_setup_lines_project_attribution() -> None: