Antigravity IDE setup

View source on GitHub

The VS Code-based Antigravity IDE and the standalone Electron desktop agent have different runtimes. Use these commands for the IDE; use deploy.mjs for the standalone app. The IDE adapter changes the verified jetski.cloudCodeUrl user setting and starts an independent local proxy. It does not replace vendor code.

The current verified release is Antigravity IDE 2.5.5, based on VS Code 1.107.0. ide:check reports these separately as ideVersion and version. Install the IDE edition from the download page.

Check, configure and launch

Build this repository with Node.js 22.13 or newer:

npm ci --ignore-scripts
npm run build
npm run ide:check -- --resources "/path/to/Antigravity IDE/resources"
npm run ide:apply -- --resources "/path/to/Antigravity IDE/resources"
npm run proxy:start -- --open
npm run ide:launch -- --resources "/path/to/Antigravity IDE/resources"

--resources also accepts an installation root or a macOS .app. Close the IDE before applying settings, then use ide:launch to start it. Launch waits for the owned proxy to become healthy before opening the verified IDE executable. It passes the configured user-data directory so the correct settings are loaded. It does not install an OS startup task: opening the ordinary IDE shortcut still requires the proxy to be running.

Preflight requires recognized Antigravity product metadata and an unpacked app/out/main.js entry point. It accepts an extension that declares jetski.cloudCodeUrl, or the inspected IDE 2.5.5 core implementation. That release uses the setting internally without declaring it in the extension manifest; preflight verifies its release commit, product/extension identity and both core and language-server endpoint code. Unsupported layouts fail before settings change. An IDE packaged only in app.asar is not supported by this adapter.

The default loopback port is 50999. To change it, supply --port 51001 to ide:apply and proxy:start; launch reads the configured port. Restore before changing an already managed endpoint. A busy port is an error, never a silent fallback to a different port.

Optional arguments:

apply/restore support explicit named-profile settings, but ide:launch only supports USER_DATA_DIR/User/settings.json. For a named profile, start the proxy and select that profile in the IDE yourself.

Complete the IDE’s own Google sign-in and onboarding. The adapter preserves this login flow. Its proxy starts account setup on the production Cloud Code endpoint and follows the returned tier’s endpoint choice; routing state is isolated per bearer digest and expires after one hour. A browser authentication-success page can appear before IDE account setup finishes, so confirm sign-in in the IDE too.

After a proxy restart, bearer refresh or routing-cache expiry, the proxy queries loadCodeAssist with the same account identity before forwarding native generation. It restores the account’s production/daily endpoint choice without resending generation or changing account tier. A failed lookup is reported explicitly. Genuine provider quota limits still apply.

Model manager and credentials

proxy:start -- --open opens the browser manager. It has the same model editor, provider discovery, import/export, Google account controls and gateway connection as the desktop addon. Diagnostics shows measured recent requests; Test generation explicitly sends a small request that can consume provider quota. The ordinary Test connection continues to check connectivity/catalogs.

The manager URL includes an access token in its fragment. The page moves this token into tab session storage; it is not sent as a URL query or logged in HTTP paths. Management actions require the token and the exact loopback origin. Keep that URL private. Generation remains available to local IDE processes; the service rejects cross-origin browser requests and unrecognized Host headers. Use the separate authenticated gateway for remote access.

By default models use ~/.gemini/antigravity/custom_models.json. Node service credentials use AES-256-GCM with a local user key in that directory. Credentials encrypted by Electron’s OS safeStorage cannot be decrypted by plain Node: re-enter them in the manager, or use a separate --data-dir for the IDE. The manager’s Google account pool is separate from the IDE’s own login. It uses the explicit account setup described in the configuration guide.

Native model identities and capacity

IDE 2.5.5 builds its native picker from the Cloud Code model catalog and its sort/group entries. The proxy adds configured models to both and allocates a distinct native enum identity for each saved model, including effort variants. The browser manager and desktop preload receive those same authoritative IDs.

The inspected IDE schema has 651 placeholder values. Native-model reservations and retained assignments for deleted models consume part of that pool, so this is an upper bound rather than a promise of 651 extra entries. Models beyond the available native slots remain editable and accessible through their direct API aliases; the manager explains why native picker injection is unavailable. Provider discovery and saved configuration are not limited to this native picker capacity.

Assignments live in <data-dir>/custom_model_identities.json. They survive display-name changes, model reordering and service restarts. Deleted-model assignments remain reserved so a cached IDE selection cannot silently select a different provider. Back up this file with custom_models.json and the local credential key. Restoring only the model list can lose these stable identities.

Delegate to custom models with MCP

IDE 2.5.5 does not expose the native invoke_subagent tool in the tested sessions. Its supported MCP integration provides a separate path: a built-in or custom parent can call delegate_to_model, send a text task to one saved custom model, and receive its answer in the same chat.

Install dependencies/build, configure your custom model in the browser manager, and start the proxy with the same data directory used by the MCP server:

npm ci --ignore-scripts
npm run build
npm run proxy:start -- --data-dir "/path/to/model-data"
npm run ide:mcp -- apply --data-dir "/path/to/model-data"

The installer adds only the custom-models server to ~/.gemini/config/mcp_config.json, preserving other servers and JSONC comments. It writes absolute Node/script paths and stores no API key in the MCP config. Keep this repository and its dependencies at that path. It refuses an existing unmanaged server with the same name. Empty or comment-only starter files are supported and restored byte-for-byte when the managed configuration is removed. For a different configuration location, pass --config "/path/mcp_config.json" to apply/status/restore. Check View raw config in the IDE’s MCP manager for the active location: the tested IDE 2.5.5 loaded the global config above, but did not discover the workspace .agents/mcp_config.json during the live check.

In the IDE, open … → MCP Servers → Manage MCP Servers and refresh, or restart the IDE. The server provides two tools:

• list_custom_models: lists enabled saved names, with a nextCursor when more models are available. Pass that cursor to retrieve the next page.
• delegate_to_model: accepts the exact saved model, a prompt, and optional text context. Only the supplied task/context go to that provider. Results include completion/truncation metadata.

For example: “Use the custom-models tools to delegate a summary of this text to models/my-openrouter-model, then show me its answer.” The selected parent must support tool calling and have working provider access; a native parent’s quota error prevents it from invoking any tool.

Each delegation is an independent text-only worker. It does not open an IDE child window, inherit chat history, read files, execute commands, or call tools. The parent can explicitly supply relevant text as context. Calls use exactly the selected model without fallback to another model, allow four concurrent workers, and cap task/context at 64 KiB, output at 8,192 tokens and runtime at 120 seconds. Cancelling the MCP call cancels its provider request. Provider usage charges and saved account policies still apply.

The MCP process communicates over stdio and authenticates to the existing owned loopback proxy. It never starts a proxy automatically. For a manual MCP config, use Node directly with scripts/model-delegation-mcp.mjs --data-dir ...; do not use npm run as the stdio command because npm banners corrupt MCP output.

npm run ide:mcp -- status
npm run ide:mcp -- restore

Restore checks the managed entry and backup integrity, restores the original file when unchanged, and preserves unrelated later edits. Backups live in the adjacent mcp_config.json.antigravity-custom-models directory. A manual change to the managed entry is reported as a conflict rather than overwritten.

Status and recovery

npm run ide:status -- --resources "/path/to/Antigravity IDE/resources"
npm run proxy:status
npm run proxy:stop
npm run ide:restore -- --resources "/path/to/Antigravity IDE/resources"

Settings backups and a hash-checked manifest live beside the settings file in settings.json.antigravity-model-patch. Restore returns exact original bytes when unchanged, or restores only the managed property while preserving unrelated later edits. It refuses a conflicting manual endpoint change or damaged backup. Keep these backups until the adapter is removed. Comments and trailing commas are supported; duplicate keys and malformed JSONC are rejected.

Service state/logs live under <data-dir>/.ide-proxy/. Start is idempotent for the same directory and port. Stop authenticates the owned instance; it does not kill a process just because it uses that port or an old recorded PID.

Validation boundary

Installer fixtures cover Windows/macOS/Linux layouts, settings preservation, restore conflicts and startup ordering. HTTP fixtures test the real Node proxy, encrypted model persistence, browser management, local generation and lifecycle.

The extracted-function check uses captured message constructors. It verifies the vendor selection logic and enum values; it does not substitute for a complete protobuf decode or live IDE interaction.

The picker and custom-provider live checks ran on 2026-10-12; native-parent and MCP delegation checks ran on 2026-10-13, using an isolated Windows profile. Custom-provider checks include a local OpenAI-compatible fixture and the real OpenRouter free endpoint above. The remote run used the user’s API key entered in the local model manager and one short task; no credentials are committed or written to verification logs. Linux source inspection and macOS installer fixtures are separate checks; their desktop UI flows and paid custom-provider generation were not part of these live runs.

This release obtains its picker through fetchAvailableModels and native unified-state updates; it does not require a GetUserStatus RPC injection. Other IDE releases need their own compatibility evidence. If models are absent, include the IDE version, OS, ide:check output and request path without credentials. The standalone desktop binary patch is a different installer.