ag-relay

# ⚡ ag-relay — رله‌ی Antigravity ### استفاده از سهمیه‌ی Antigravity در همه‌ی برنامه‌ها — از داخل ایران، به‌صورت مستقیم **Gemini 3.8 Flash · Claude Sonnet 4.6 · Claude Opus 4.6 · GPT-OSS 120B**

Deploy on Vercel OpenAI Compatible Free MIT License

Setup page Telegram tutorials

🇮🇷 راهنمای فارسی · 🇬🇧 English guide

🇮🇷 راهنمای فارسی

Relay چیه؟ یه ابزار کوچیک و متن‌بازه که سهمیه‌ی Antigravity اکانت گوگلت (Gemini 3.8 Flash، ‏Claude Sonnet/Opus، ‏GPT-OSS) رو به یه آدرس استاندارد تبدیل می‌کنه تا هر برنامه‌ای که «OpenAI Compatible» قبول می‌کنه (مثل 9Router، ‏Claude Desktop، ‏zcode، ‏Cherry Studio و…) بتونه از داخل ایران به‌صورت مستقیم ازش استفاده کنه. هزینه‌ش صفره: روی سهمیه‌ی خودت و هاست رایگان کار می‌کنه.

نصب سریع (بدون ترمینال): ۱. صفحه‌ی ستاپ رو باز کن: eshghastast.github.io/ag-relay — اعتبارنامه‌ی اپ Antigravity رو وارد کن، با گوگل وارد شو و «پک نصب» (توکن + کلید Relay + پسورد داشبورد) رو تحویل بگیر. همه‌چیز توی مرورگر خودت انجام می‌شه.

صفحه‌ی ستاپ — راهنمای قدم‌به‌قدم نصب

۲. دکمه‌ی زیر رو بزن و مقادیر پک رو توی فرم Vercel وارد کن:

Deploy with Vercel

۳. داشبورد رو باز کن، پسورد رو بزن، کلید رو ثبت کن و یه مدل رو تست کن. تمام!

داشبورد این شکلیه — سهمیه‌ی هر دو استخر (Gemini و Claude + GPT) و چت داخلی برای تست مدل‌ها:

نمای کلی داشبورد — سهمیه‌ی هر دو استخر

چت داشبورد — تست مدل‌ها

شرط لازم: یه اکانت گوگلِ دارای مجوز Antigravity — اکانت Pro، یا اکانت رایگانی که ریجنش کشور پشتیبانی‌شده‌ست و تأیید گوگل رو رد کرده. آموزش ساخت اکانت Vercel و تغییر ریجن، قدم‌به‌قدم توی کانال ماست.

امنیت: همه‌ی رازها فقط توی متغیرهای محیطی (Environment Variables) پروژه‌ی خودت ذخیره می‌شن، هیچ‌چیز توی کد نیست. توصیه‌ی جدی: Relay رو با یه اکانت جدا راه بنداز، نه اکانت اصلیت. اگه اکانت اصلیت Pro داره، توی Google One یه گروه خانواده بساز، اکانت دوم رو اضافه کن و «Share Google One with family» رو روشن کن تا اکانت دوم هم به مزایای هوش مصنوعی پرو (از جمله Antigravity) دسترسی پیدا کنه؛ ولی سقف هفتگی Antigravity برای کل خانواده یکی و مشترکه، یعنی اکانت دوم سقف جداگانه نمی‌گیره. جزئیات توی SECURITY.md.

هدف سرویس: فقط برای دسترسی به سرویس‌هایی که ایران رو تحریم کردن؛ به هیچ وجه برای دور زدن اینترنت داخلی نیست.

📺 آموزش‌های کامل فارسی: کانال تلگرام KARA AI · اینستاگرام @kara_ai_offer

✨ امکانات

   
🚀 سریع — مسیر کوتاه تا بک‌اند رسمی گوگل، با استریم زنده (SSE) 📊 داشبورد فارسی — سهمیه‌ی هر دو استخر، وضعیت و راهنمای قدم‌به‌قدم
🔒 امن — همه‌ی رازها فقط توی متغیرهای محیطی؛ هیچ‌چیز توی کد نیست 💬 چت داخلی — مکالمه‌ی چندنوبتی با ذخیره‌ی خودکار تا ۳۰ گفت‌وگو
🧪 تست مدل‌ها — تست تکی یا «تست همه» با زمان پاسخ و وضعیت هر مدل 📈 آمار مصرف — شمارنده‌ی دائمی درخواست‌ها به تفکیک مدل
🧰 نصب بدون ترمینال — صفحه‌ی ستاپ + دکمه‌ی دیپلوی یک‌کلیکه 🌗 دو تم — حالت روشن و تیره، کاملاً ریسپانسیو

🐳 Docker + VPS شخصی — سرور همیشه‌روشن خودت

اگه Vercel نمی‌خوای و یه VPS داری (یا همین روش رو روی کامپیوتر خودت می‌خوای)، با داکر بدون فایل کانفیگ بالا میاد — فقط متغیرهای محیطی:

git clone https://github.com/eshghastast/ag-relay.git && cd ag-relay
cp .env.example .env   # مقادیر پک ستاپ (توکن + کلید Relay) رو توش بنویس؛ هرگز کامیتش نکن
docker compose up -d --build

یا تک‌دستوری، بدون فایل:

docker build -t ag-relay .
docker run -d --name ag-relay --restart unless-stopped -p 8787:8787 \
  -e AG_REFRESH_TOKEN=... -e AG_CLIENT_ID=... -e AG_CLIENT_SECRET=... \
  -e RELAY_API_KEY=... ag-relay

بعد توی هر برنامه‌ی OpenAI-Compatible:

نکته‌ها: پورت 8787 رو توی فایروال VPS باز کن؛ AG_PROJECT_ID رو خالی بذار (خودکار پیدا می‌شه)؛ برای استفاده‌ی جدی، حتماً RELAY_API_KEY بذار — بدون کلید، رله روی پورت باز همه‌ی درخواست‌ها رو رد می‌کنه. لاگ: docker logs -f ag-relay.

☁️ Netlify — پورت دوم (Functions)

اگه Vercel نمی‌خوای ولی همچنان سرورلس می‌خوای، همون کد روی Netlify Functions هم اجرا می‌شه — بدون کپی منطق: هر فانکشن Netlify فقط یه wrapper نازک دور همون هندلرهای api/ـه (netlify/functions/ + آداپتور netlify/lib/adapter.mjs):

  1. ریپو رو توی Netlify ایمپورت کن (Import from Git). Netlify خودش netlify.toml رو می‌خونه: فانکشن‌ها از netlify/functions/ و مسیرهای /v1/... بهشون وصل می‌شن.
  2. توی Site settings → Environment variables همون متغیرها رو بذار:
    • AG_REFRESH_TOKEN — از ~/.ag-relay/config.json (بعد از npm run login)
    • AG_CLIENT_ID, AG_CLIENT_SECRET — (بخش Client credentials پایین)
    • RELAY_API_KEY — کلید خودت؛ بدون اون رله همه‌ی درخواست‌ها رو رد می‌کنه
    • DASH_PASSWORD — پسورد داشبورد (/)
    • AG_PROJECT_ID — خالی بذار (خودکار پیدا می‌شه؛ همون هشدار Vercel این‌جا هم برقراره)
  3. Deploy. آدرس: https://<your-site>.netlify.app/v1.

تفاوت‌ها با Vercel:

☁️ Cloudflare Workers — پورت سوم

اگه دنبال لبه‌ی جهانی و استریم واقعی هستی، همون کد روی Cloudflare Workers هم اجرا می‌شه — ورودی cloudflare/worker.mjs + آداپتور cloudflare/lib/adapter.mjs که هندلرهای api/ رو پشت fetch()‎ استاندارد Workers می‌نشونه (بدون کپی منطق):

  1. Wrangler رو نصب کن: npm install -g wrangler (یا npx wrangler).
  2. سکرت‌ها رو بذار — مقادیر واقعی هرگز توی فایل نمی‌رن: 
    wrangler secret put AG_REFRESH_TOKEN
wrangler secret put AG_CLIENT_ID
wrangler secret put AG_CLIENT_SECRET
wrangler secret put RELAY_API_KEY
wrangler secret put DASH_PASSWORD

    (AG_PROJECT_ID رو خالی بذار — خودکار پیدا می‌شه؛ همون هشدار Vercel.)

  3. npm install (برای باندل‌شدن وابستگی‌ها) بعد wrangler deploy. آدرس: https://ag-relay.<subdomain-شما>.workers.dev/v1.

تفاوت‌ها با Vercel و Netlify:

🔄 به‌روزرسانی (بدون حذف و نصب دوباره)

برای به‌روز کردن یه دیپلوی موجود، هرگز پروژه رو پاک و دوباره نصب نکن.

اول، مدل ذهنی درست: هر دیپلوی یه کپی جدا از ریپو داره. کامیت‌های جدید upstream خودبه‌خود وارد کپی هیچ‌کس نمی‌شن — نه با Deploy Button (که یه اسنپ‌شات می‌سازه، نه یه فورک متصل)، نه با هیچ تنظیم ورسل. و دکمه‌ی Redeploy هاست هم فقط همون کامیت قبلی رو دوباره دیپلوی می‌کنه؛ کد جدید upstream رو نمی‌گیره. تنها چیزی که نسخه‌ی جدید رو بالا می‌آره، رسیدن کد جدید به ریپوی متصل به پروژه‌ست (پوش به اون ریپو → هاست خودکار دیپلوی می‌کنه، اگه پروژه به گیت وصله).

آپدیتر یک‌کلیکه (روش پیشنهادی): داشبورد دکمه‌ی «به‌روزرسانی» داره که master upstream رو با GitHub API توی ریپوی خودت پوش می‌کنه. یه‌بار تنظیمش کن:

۱. یه توکن گیت‌هاب بساز: github.com/settings/tokens → Generate new token (classic) با دسترسی repo (یا fine-grained با Contents read+write روی همون یه ریپو). ۲. توی داشبورد هاست، دو متغیر محیطی بذار و یه ریدیپلوی بزن تا اعمال بشن:

چی می‌شه: آپدیتر درخت کامل master رو پوش می‌کنه (فایل‌های جدید/تغییرکرده میان، حذف‌شده‌ها حذف می‌شن؛ .github/ هیچ‌وقت سینک نمی‌شه). اگه وسط کار خطایی بشه، هیچ‌چیز پوش نمی‌شه (تا آپدیت ref آخر، هیچ‌چیز توی ریپو نمی‌ره) و می‌تونی دوباره بزنی. بعد از پوش موفق، اگه پروژه به گیت وصله هاست خودکار دیپلوی می‌کنه؛ اگه وصل نیست، ریپوت به‌روز شده ولی باید خودت ازش دیپلوی بگیری (یا گیت رو از تنظیمات هاست وصل کنی). توجه: تغییرهای خودت توی اون ریپو با سینک از دست می‌ره.

بدون آپدیتر: ریپوی متصل به پروژه رو دستی با master سینک کن (اگه فورکه: Sync fork؛ اگه کپی Deploy Buttonـه: کد جدید رو خودت بریز توش) و بذار هاست روی پوش دیپلوی کنه. تغییر متغیرهای محیطی (env) هم برای اعمال شدن یه ریدیپلوی می‌خواد.

داشبورد نسخه‌ی نصب‌شده رو توی فوتر نشون می‌ده و با دکمه‌ی «بررسی به‌روزرسانی» می‌تونی ببینی نسخه‌ی جدید در ریپو هست یا نه (مقایسه با آخرین کامیت master در گیت‌هاب).

🇬🇧 English guide

Use your Antigravity model quota (Gemini 3.8 Flash, Claude Sonnet/Opus 4.6, GPT-OSS 120B) from any OpenAI-compatible app — your own code, chat UIs, agent frameworks, anything that accepts a custom base_url + API key.

ag-relay is a tiny, dependency-free translator: it takes OpenAI-style requests, refreshes a Google OAuth access token for your own account, and calls the same Code Assist backend the official Antigravity clients use, then translates the answers back to OpenAI format.

Built and maintained by KARA AI — Telegram channel: t.me/kara_ai_offer · Instagram: @kara_ai_offer. Step-by-step Persian tutorials live in the channel.

⚡ Fastest setup — no terminal

  1. Open the setup page (setup.html in this repo — serve it via GitHub Pages or just open the file): enter the Antigravity client credentials, click “Sign in with Google”, paste the callback URL back, and the page hands you a ready pack: your refresh token plus an auto-generated RELAY_API_KEY and DASH_PASSWORD. Everything runs locally in your browser; nothing is stored or sent anywhere except Google.
  2. Click the deploy button and paste the values into Vercel’s env form:

Deploy with Vercel

  1. Open your deployment, unlock the dashboard with DASH_PASSWORD, save the relay key once — done.

Vercel deploy tips (from a real first run):

🖥️ Quickstart — local

git clone <this repo> ag-relay && cd ag-relay   # Node 18+, no dependencies
AG_CLIENT_SECRET=... npm run login             # sign in with your Google account, paste the callback URL
npm run serve                                  # http://localhost:8787/v1

Then in your app:

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.8-flash-medium","messages":[{"role":"user","content":"Hello!"}]}'

Streaming ("stream": true) is supported.

☁️ Quickstart — Vercel relay

  1. Fork/clone this repo and import it into Vercel (it’s a plain functions project — api/, lib/, vercel.json).
  2. Run npm run login locally once to get your refresh token.
  3. Set these project environment variables in Vercel:
    • AG_REFRESH_TOKEN — from ~/.ag-relay/config.json
    • AG_CLIENT_ID, AG_CLIENT_SECRET — the client credentials (see below)
    • RELAY_API_KEY — invent a long random string; your apps must send it as Authorization: Bearer <key>. Required: without it the relay refuses all /v1 requests (fail closed); RELAY_OPEN=1 only for an intentionally open local dev relay.
    • AG_PROJECT_ID — optional; speeds up cold starts. Leave it unset (recommended) — the relay auto-resolves your account’s managed Code Assist project (e.g. aicode-consumers). ⚠️ Never set it to the Google Cloud project that hosts your OAuth client: the private Cloud Code API can never be enabled on a personal project (Google returns PERMISSION_DENIED), so the relay dies with a misleading “Cloud Code Private API is not enabled in your project” error. Only set this if you know your managed project ID for sure.
  4. Deploy. Your endpoint is https://<your-project>.vercel.app/v1.

Keep the refresh token secret: whoever has it can spend your quota.

🔑 Client credentials

The relay logs in through the public Antigravity desktop OAuth client (client_id is the same one shipped in the official app and in open-source routers). Desktop OAuth clients cannot keep a secret; the matching client_secret is distributed with those clients. Provide it via the AG_CLIENT_SECRET environment variable — this repo does not hardcode it. You can also register your own OAuth client in Google Cloud Console (Desktop type, enable the Cloud Code API) and use its id/secret instead — the full step-by-step walkthrough is in the setup page (step 1, method 2).

🤖 Models

Whatever your account’s Antigravity plan exposes. Typical set:

Model ID Notes
gemini-3.8-flash-high / -medium / -low Native, fastest, huge context; higher = more thinking
gemini-3.1-pro-high / -low, gemini-pro-agent Gemini Pro tiers
claude-sonnet-4-6 Best balance for coding
claude-opus-4-6-thinking Strongest; burns the Claude pool fastest
gpt-oss-120b-medium Open-weight fallback

Quota is percentage-based and shared per model group (Gemini pool vs Claude+GPT pool), with a short-window refresh and a weekly cap on paid plans; free plans refresh weekly. There is no official token counter — heavy agent loops can drain a free account quickly.

⚠️ Honest warnings

🔐 Security

🗂️ Layout

📄 License

MIT

This site is open source. Improve this page.