Skip to main content
Glama

A subscription is not an API key, and taking its token is the fast way to lose the account. Third-party tools that reused the Antigravity login token were cut off with a 403 TOS_VIOLATION, and accounts were banned.

antigravity-connector does the one thing that keeps traffic coming from the official client: it runs the agy binary as a subprocess for every call. The server never reads, copies, logs or forwards the token, and never calls Google directly. The rules that keep it that way are lint rules and tests, not comments (ADR 0003).

The risk is lower, not zero. Google's terms treat access through third-party software as a breach. This server is built for low, personal use: one user, one machine, one call at a time.


Status

The server is built: the OpenAI-compatible API, the MCP endpoint with web_search, generate_image, research and browse, the Docker image, the end-to-end tests and the call log. What is still missing is in Limits. The execution order is in #29 and the project brief is #1.

Related MCP server: antigravity

What you get

Two doors, one process

An OpenAI-compatible API under /v1 (chat with and without streaming, models, images) and an MCP server under /mcp over Streamable HTTP. Works from any OpenAI-compatible client or SDK and from any MCP client.

A shared queue

Both doors share one global queue, which runs up to QUEUE_CONCURRENCY agy calls at once (4 by default; ADR 0013), plus a daily limit per kind of run. The daily limits are the cost control for a subscription. MCP over stdio is out of scope (ADR 0006).

Local by default

Listens on 127.0.0.1 by default and refuses to start on any other address unless you allow it. The image listens on all interfaces so the published port works, and the install publishes it on 127.0.0.1 only, behind the HTTPS proxy. Every route but /health and the one-time upload links needs the bearer API_KEY.

No web page, almost no state

The login is done over HTTP: GET /v1/auth returns a link and POST /v1/auth takes the code (ADR 0012). The only stored data is a small SQLite call log with metadata, so the daily limits survive a restart (ADR 0010).

What it can do

Capability

Door

How it runs

Chat

/v1/chat/completions, with and without streaming

agy -p, plan mode, no file edits

Web search

MCP tool web_search

agy with its search tool, answer with source URLs

Image generation

MCP tool generate_image, and /v1/images/generations

The native image subagent, in a fresh temporary directory

Research

MCP tool research

A longer report with links; takes minutes

Browsing

MCP tool browse

The /browser command with a throwaway browser profile

Video, Google Flow, Deep Research from the Gemini app, workflows, swarms, MCP over stdio, any web page, several users and exposing the server to a network are out of scope (ADR 0004).

Risk note

Running a subscription through a server you expose to the internet is not something Google documents for the CLI. Its terms, its limits and the CLI itself can change at any time, and a call can fail or be refused. Use it for yourself, on your own machine, at a low volume. Keep the API key secret: anyone who has it can spend your daily limits.

Requirements

  • Docker with Compose.

  • A Google account with an AI Pro subscription.

Quick start

Three steps, on any VPS that runs Docker: run the server, log in once, connect your AI. Replace connector.your-domain.com with your own host name, and your-api-key with a random secret of at least 24 characters (for example openssl rand -hex 24).

1. Run the server on your VPS

The image is ghcr.io/guilhermebkel/antigravity-connector, public on GitHub Container Registry. No clone and no files are needed.

docker run -d --name antigravity-connector --restart unless-stopped \
  -p 127.0.0.1:8787:8787 \
  -e API_KEY='your-api-key' \
  -v agy-gemini:/home/agy/.gemini -v agy-data:/data \
  ghcr.io/guilhermebkel/antigravity-connector:latest

The port is published on 127.0.0.1 only. The internet reaches it through an HTTPS reverse proxy that you already run (Caddy, nginx, Traefik or a platform proxy), pointed at 127.0.0.1:8787, with a host name (an A record) for the VPS. The two volumes keep the login and the call log: keep them, or you log in again after every update.

Check it: curl https://connector.your-domain.com/health answers {"status":"ok","agy":"login_required"} until you log in.

2. Log in once

Use the Google account that has the AI Pro plan. Ask for the link, open it, sign in, copy the code, and send it back within 60 seconds (Logging in):

curl -H "Authorization: Bearer your-api-key" https://connector.your-domain.com/v1/auth

curl -X POST -H "Authorization: Bearer your-api-key" -H "Content-Type: application/json" \
  -d '{"code":"the code from the login page"}' https://connector.your-domain.com/v1/auth

/health now answers {"status":"ok","agy":"connected"}.

3. Connect your AI

Any client that speaks one of two standards works. Pick the one your tool supports.

An MCP client (Claude, Cursor, Codex and others): add the server to its MCP settings. It uses the Streamable HTTP transport.

{
  "mcpServers": {
    "antigravity": {
      "url": "https://connector.your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

The file name and the exact key names differ between clients, so check the MCP page of yours: it needs the URL and one Authorization header. Some clients have a command for it; for example, Claude Code: claude mcp add --transport http antigravity https://connector.your-domain.com/mcp --header "Authorization: Bearer your-api-key".

An OpenAI-compatible client (a script, the OpenAI SDKs, the Vercel AI SDK, or any app with a "custom OpenAI endpoint" setting):

Setting

Value

Base URL

https://connector.your-domain.com/v1

API key

your API_KEY

Model

gemini-3.8-flash (list them with GET /v1/models)

Ask

Search the web for the latest stable Node.js version and give me the links.
Generate an image of a lighthouse at dusk, flat illustration.
Research the trade-offs between SQLite and Postgres for a small app, with sources.

Every tool call is a full agent run: a search takes tens of seconds and research takes minutes, so a call may come back as "running" first (details).

Run it locally with Docker Compose

To try it on your own computer instead:

cp .env.example .env                 # then set API_KEY to a random value of at least 24 characters
docker compose up -d --build
curl -H "Authorization: Bearer $API_KEY" http://127.0.0.1:8787/v1/auth    # login link, if agy is not logged in yet
curl -s http://127.0.0.1:8787/health

To update the VPS install, pull the new image, remove the old container (docker rm -f antigravity-connector) and run the docker run command again; the login and the call log stay in their volumes.

The API key is the only access control: anyone who has it can spend your daily limits. docker inspect shows the value of -e API_KEY, so keep the VPS to yourself.

Persistent storage on any platform

Whatever runs the container (a PaaS dashboard, Kubernetes, Compose, Nomad), it must keep two directories across redeploys:

Directory in the container

What it keeps

/home/agy/.gemini

The agy login

/data

The call log and the daily counters

Other settings the platform needs: the image ghcr.io/guilhermebkel/antigravity-connector:<version> (a release, or a branch image such as :<branch>), the environment variable API_KEY, the container HTTP port 8787, and HTTPS on the domain.

Without the two directories, every redeploy recreates the container and the login is lost: GET /v1/auth starts answering login_required again. A platform flag that says "has persistent data" does not always mount anything; mount the directories explicitly as volumes or bind mounts. At startup the server logs storage.checked with isLoginDirMounted and isDataDirMounted; a warn line means one of the directories is not mounted. After you add them, log in once more: the directories start empty.

Logging in

The first start has no session. The login is done over HTTP with the API key, so no shell into the container is needed:

  1. Ask for the link: GET /v1/auth returns {"status":"login_required","login_url":"https://accounts.google.com/...","expires_in_seconds":60}. The MCP tool is check_auth.

  2. Open login_url in a browser, sign in with the Google account that has the AI Pro plan, and copy the code the page shows.

  3. Send the code within 60 seconds: POST /v1/auth with {"code":"..."} returns {"status":"connected"}. The MCP tool is set_auth. A wrong or expired code is refused; ask for a new link and try again.

  4. Check: GET /v1/auth returns {"status":"connected"}, and /health returns {"status":"ok","agy":"connected"}.

The login is kept in the named volume agy-gemini. docker compose down keeps it; docker compose down -v removes it, and you must log in again.

Using the API

With curl:

curl https://connector.your-domain.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.8-flash","reasoning_effort":"low","messages":[{"role":"user","content":"Say hello in one word."}]}'

With the Vercel AI SDK (@ai-sdk/openai-compatible):

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const provider = createOpenAICompatible({
  name: "antigravity",
  baseURL: "https://connector.your-domain.com/v1",
  apiKey: process.env.API_KEY,
});
const { text } = await generateText({ model: provider("gemini-3.8-flash"), prompt: "Say hello in one word." });

More endpoints and options:

  • POST /v1/images/generations returns one PNG as data[0].b64_json. n other than 1 and response_format other than b64_json return 400.

  • response_format with {"type":"json_schema","json_schema":{"name":"x","schema":{...}}} returns the JSON as the message content. json_object returns any JSON object. A streamed structured answer is sent once, at the end.

  • An image_url part with a base64 data: URL (PNG, JPEG or WebP, up to 4 MiB each, four per request) is saved for the run. Remote URLs are refused, and nothing is fetched.

  • conversation_id from a previous response continues that conversation: send the new message only. The id is kept for 24 hours, in memory; after a restart, or once it expires, send the full history without it.

Connect your AI in detail

The setup is in Quick start. This section says what each door gives your AI.

MCP tools (/mcp)

Any MCP client that supports Streamable HTTP can use them: it sends the URL and the Authorization: Bearer <API_KEY> header. The tools are web_search, generate_image, create_upload_link, research, browse, get_result, check_auth and set_auth.

The web_search tool returns a short answer with links. A search takes about 20 to 45 seconds and counts against DAILY_LIMIT_SEARCH.

The generate_image tool returns one PNG image. A call takes about a minute and counts against DAILY_LIMIT_IMAGE. It can take up to four reference images in images, each a base64 data: URL, an https:// URL or an upload: value from create_upload_link, of a PNG, JPEG or WebP file of up to 4 MiB. The server downloads an https:// URL itself (ADR 0014): it follows at most 3 redirects (https only), gives up after 15 seconds and refuses, on every hop, a host that resolves to a private, loopback or link-local address. The chat API still takes data: URLs only.

A photo that sits on your own machine has no public URL, and a long base64 string is easy to corrupt when a model copies it. The create_upload_link tool returns a one-time path, /upload/<token>, an upload:<id> value and, when PUBLIC_URL is set, the full uploadUrl. Send the file as the raw body of a POST to that path on your server, with no key, because the link is the credential (curl --data-binary @photo.jpg https://connector.your-domain.com/upload/<token>), then put the upload:<id> value in images. A link works once and lasts 5 minutes, the picture is kept in memory for 15 minutes, and at most 8 links and pictures wait at a time (ADR 0015).

The long MCP tools (web_search, generate_image, research and browse) wait about 20 seconds for their result. If it is not ready, they return status running and a job_id; call get_result with that job_id after retry_after_seconds until it returns the result. A client that cancels during the first 20 seconds stops the run; after that the run goes on without the client, and the result is kept for 10 minutes. The OpenAI-compatible API does not use jobs.

The research tool writes a Markdown report with a source link for each claim. A call takes several minutes (up to 10), spends tens of thousands of tokens, and counts against DAILY_LIMIT_RESEARCH. The report is capped at 20000 characters, and truncated says when it was cut.

The browse tool opens a public page in headless Chrome, reads it or does a simple task, and can return a screenshot. It has no logins and no saved cookies. Loopback and private addresses, and URLs with a user name or password, are refused. A call counts against DAILY_LIMIT_BROWSE. Pages may contain instructions; the tool treats them as data.

When the client sends a progress token, the server reports progress while a call waits in the queue and runs. A client that cancels a call stops the agy process.

Configuration

Variable

Default

What it does

API_KEY

none (required, at least 24 characters)

The bearer token every route except /health and the upload links requires.

HOST

127.0.0.1 (0.0.0.0 in the image)

The address the server listens on.

ALLOW_NON_LOOPBACK_BIND

false (true in the image)

Allows a non-loopback HOST. The image sets it so the port can be published on the host. Publish it on 127.0.0.1 only and put an HTTPS proxy in front.

PORT

8787

The port.

AGY_BIN

agy

The agy binary.

AGY_TIMEOUT_MS

300000

A call that runs longer is stopped.

QUEUE_MAX_WAIT_MS

120000

A call that waits longer in the queue is refused.

QUEUE_CONCURRENCY

4

Agy runs in flight at once, from 1 to 8. Calls past this wait in the queue.

DAILY_LIMIT_CHAT / _SEARCH / _IMAGE / _RESEARCH / _BROWSE

200 / 50 / 20 / 5 / 20

Calls per UTC day, per kind. 0 refuses that kind.

HTTP_MAX_REQUESTS_PER_MINUTE

120

Requests per minute, counted separately for failed and valid authentications.

DATA_DIR

data (/data in the image)

Where the SQLite call log (calls.sqlite) is kept. It holds metadata only: no prompts, responses, queries, URLs or images. Rows older than 90 days are deleted at startup.

PUBLIC_URL

none

The public origin of the server, such as https://connector.your-domain.com. When it is set, create_upload_link also returns the full uploadUrl; without it, the client joins uploadPath to the host it already uses.

MCP_MAX_SESSIONS

8

MCP sessions open at once.

MCP_SESSION_TTL_MS

1800000

An MCP session idle for longer expires.

How it works

  client ──▶ 1. AUTH ──▶ 2. VALIDATE ──▶ 3. LIMIT + QUEUE ──▶ 4. RUN agy ──▶ 5. REPLY
  (/v1, /mcp)  bearer key   strict Zod      daily limit, then    fresh empty    OpenAI shape
               SHA-256      schemas         the one global       temp dir,      or MCP result,
                                            queue                timeout        logs: metadata only

The work is split into packages on purpose, and the direction of the imports is a lint rule:

Package

Does

Why

apps/server

Fastify; mounts the API, the MCP endpoint and /health

It only mounts; no rule lives here

packages/api

The OpenAI-compatible routes

Nothing outside the OpenAI format; never imports agy

packages/mcp

The tool manifest, input and output schemas

Never imports agy or api

packages/core

The queue, the daily limits, the session state, the environment, the logging

One place enforces the limits for both doors

packages/agy

The only place that spawns the binary, and the fake agy for tests

The only package that may import child_process

packages/protocol

Shared types and Zod schemas

Imports no other package

Decisions are in docs/adr/, vocabulary in GLOSSARY.md.

Limits and what is not supported yet

  • Up to QUEUE_CONCURRENCY agy calls run at once (4 by default). Calls from the API and from MCP share one queue, and the rest wait.

  • Calls are slow: a chat answer takes seconds, a search takes tens of seconds.

  • Streaming works with stream: true (Server-Sent Events, OpenAI chunk format). Set stream_options.include_usage to get the usage in the last chunk.

  • Not available yet: tool calling (tools returns 400, because agy runs its own tools), PDF and other file input, audio and video, and a browser profile with your own logins.

  • browse runs Chrome through agy's /browser command. The temporary directory of each run is removed after it; agy chooses where its Chrome profile lives, and no flag sets that, so the profile is not confined to the run directory yet.

  • Sampling parameters (temperature, top_p, max_tokens, max_completion_tokens) are accepted and ignored. The response header x-antigravity-connector-ignored-params lists the ones you sent.

  • The agy binary is pinned to version 1.5.9 in the image. It cannot update itself, because it is installed read-only for the server user.

Troubleshooting

  • /health says login_required after a restart. The login is gone: the volume was removed or the image was rebuilt without it. Log in again (see above). A restart or a recreate with the same volume keeps the login.

  • 503 with queue_timeout. Another call held the queue longer than QUEUE_MAX_WAIT_MS. Retry in a moment.

  • 429 with daily_limit_reached. The limit for that kind is used up. It resets at the next UTC midnight, and the message says when.

  • 504 with agy_timeout. The call ran longer than AGY_TIMEOUT_MS and was stopped. Ask a shorter question.

  • 502 with agy_failed. agy failed. The container logs show the cause without the prompt or the answer.

  • The container stops at once with a message about API_KEY. .env is missing the key, or the key is shorter than 24 characters.

Privacy and safety

  • The login token stays with agy. No source file names its credentials folder (lint rule), and the app never reads, copies, logs or forwards it.

  • Logs carry metadata only: door, route or tool, model, duration and token counts. Never a message, a search query, a prompt, image bytes or the API_KEY. Every output path is tested with a fake secret.

  • Every run is boxed: a fresh empty temporary directory, a timeout that kills the process, and plan mode for chat, search and research. Browsing always uses a throwaway profile.

  • The only network exit is the agy binary. No telemetry, no analytics.

Found a way around any of this? Open an issue without secrets in it.

How it compares

  • Using the token directly (a proxy that calls Google's internal API) is what got accounts banned. Here the token never leaves the CLI.

  • A generic OpenAI proxy gives every client the whole subscription with no queue and no limits. Here there is one queue, a daily limit per kind of run, an API key and HTTPS in front.

FAQ

No. It is a single-user server, reachable over HTTPS with an API key, and the subscription is yours. The bind guard refuses another address unless ALLOW_NON_LOOPBACK_BIND=true, which only the Docker image sets; the install and an HTTPS proxy is the public entry.

There is no web page on purpose. When there is no session, GET /v1/auth (or the check_auth tool) returns a login link; you open it, sign in, and send the code to POST /v1/auth (or set_auth). /health says whether the session is connected, as seen by a real agy check, never by configuration (ADR 0009). The landing page is a separate static folder, site/ (ADR 0011).

Yes, as long as the named volume agy-gemini is kept. docker compose down keeps it and docker compose down -v removes it, so you would log in again. Details are in docs/spike-results.md.

Roadmap

The full order, in groups, is in #29.

  • Harness and structure: monorepo, lint rules, architecture tests, CI and docs.

  • Spike: agy inside Docker, login and session persistence.

  • Chat over /v1, with streaming, structured output, conversations and image input.

  • MCP with web_search, generate_image, research and browse.

  • Docker image, end-to-end tests and the real acceptance run (docs/acceptance-2026-11.md).

  • Not available yet: tool calling, PDF and other file input, audio and video, a browser profile with your own logins.

Contributing

Issues and pull requests are welcome. Start with AGENTS.md, which says what to read for each kind of task.

Development

Needs the Node version in .nvmrc and pnpm.

nvm use
pnpm install
pnpm dev     # the server with the fake agy on 127.0.0.1:8787
pnpm check   # typecheck, lint, quality, tests and build

The image smoke test is scripts/image-smoke.sh (it needs Docker).

A release is started by hand: run the Release workflow on master and pick patch, minor or major (none releases the current version). It checks everything, tags the commit, publishes the GitHub Release and the image to ghcr.io/guilhermebkel/antigravity-connector.


Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables local AI agents to generate code and interact with Google Antigravity (Gemini Pro) via MCP, consuming zero API tokens.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP-compatible AI clients like Claude Code, Cursor, and Codex to invoke Google Antigravity's Gemini coding agent for repository-aware file operations, command execution, code review, test generation, and quota checks, while also providing a standalone dual-mode CLI.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Bridges a locally installed and signed-in Google Antigravity subscription to MCP coding agents such as Cursor, Claude Code, and Codex, so prompts are answered through the existing Antigravity session without a separate API key or token cost. Supports multi-turn conversations via session ids and lets agents on remote machines reach the Mac-hosted server over an SSH reverse forward.
      MIT