زاد · Zad

One OpenAI-compatible endpoint over the free tiers of 17+ AI providers — self-hosted, Arabic-first.

موجّه واحد متوافق مع OpenAI يجمع نماذج الذكاء الاصطناعي المجانية من 17+ مزوّداً.

🌐 zad.tools · 🧪 Live demo · demo.zad.tools · ⭐ GitHub

🌙 زاد · العربية

عشرات النماذج المجانية الممتازة موجودة فعلاً — بس مبعثرة عبر 17+ مزوّداً، كل واحد بحدوده وصيغته ومفتاحه. زاد بيجمعهم كلهم خلف نقطة واحدة متوافقة مع OpenAI (/v1/chat/completions)، بيختار النموذج المناسب لكل طلب، ويحوّل احتياطياً للي بعده لو مزوّد وقع أو تجاوز حدّه — وأنت بتستخدم مفتاحاً واحداً.

مستضاف ذاتياً بالكامل: مفاتيحك مشفّرة على سيرفرك، بياناتك ما بتطلعش برّه، وبدون أي فاتورة شهرية.

💰 ليه يهمّك — أرقام حقيقية

لحجم عمل ~50,000 طلب شات شهرياً (~2k توكن للطلب):

المزوّد	التكلفة الشهرية
Claude Sonnet 4.5	$1,100
GPT-4o	$1,167
Gemini 2.5 Pro	$708
زاد (free tiers + استضافة ذاتية)	$0

نفس النماذج. نفس الجودة. اللي بيتغيّر هو السباكة. الـ free tiers اللي بتحمل الـ $0 ده مش لعبة — Cerebras (ألف طلب/يوم، أقل من ثانية)، Groq (ألف/يوم)، Gemini (سياق مليون توكن)، NVIDIA، Mistral، Cohere، SambaNova. مجموعهم بيستوعب أغلب التطبيقات براحة.

✨ المميزات

🔌 متوافق مع OpenAI — بدّل base_url بس، أي SDK أو أداة بتشتغل على طول.
🧭 140 مزوّد · 5,140 نموذج جاهز للاكتشاف عبر /api/registry (مبني على models.dev، نفس مصدر opencode).
🌊 17+ مزوّد · 100+ نموذج مجاني مفعّل افتراضياً (Groq · Cerebras · SambaNova · NVIDIA · Mistral · OpenRouter · GitHub Models · Cohere · Cloudflare · Google · Zhipu · Ollama Cloud وغيرهم).
🔁 تحويل احتياطي تلقائي — يرتّب النماذج بالذكاء/السرعة/الميزانية ويقفز للي بعده عند الفشل أو تجاوز الحد.
💸 تسعير حقيقي + حساب التوفير — من جدول LiteLLM، يوريك كام كنت هتدفع لو مدفوع.
📊 تحديثات حيّة (SSE) — الطلبات، زمن الاستجابة، التوكنز، الأخطاء — تتحدّث لحظياً.
🔔 إشعارات تليجرام — مفتاح جديد/غير صالح · مزوّد وقع/رجع · ملخص يومي · طفرة أخطاء (تُضبط من الواجهة).
➕ مزوّدون مخصّصون من الواجهة — أضف أي خدمة متوافقة مع OpenAI وعدّل رابطها live (Ollama محلي · vLLM · LM Studio…).
🔐 مفاتيح مشفّرة at-rest + فحص صحة دوري + تعطيل تلقائي للمفاتيح الفاشلة.
🔑 لوحة تحكم و/api محميّان بمفتاح — شاشة دخول، ومافيش أي شيء مكشوف غير فحص الحياة.
🟢 واجهة عربية كاملة RTL بهوية حديثة، فاتح/داكن، بدون build step معقّد.

🚀 التشغيل السريع (Self-host)

المتطلبات: Node.js ≥ 20 + git. الخطوة الوحيدة المختلفة بين الأنظمة هي تثبيتهما:

النظام	تثبيت المتطلبات
🍎 macOS	`brew install node git`
🐧 Linux (Debian/Ubuntu)	`curl -fsSL https://deb.nodesource.com/setup_20.x \| sudo -E bash -` ثم `sudo apt install -y nodejs git`
🪟 Windows (PowerShell)	`winget install OpenJS.NodeJS.LTS Git.Git`

بعدها الأوامر واحدة على كل الأنظمة (Terminal أو PowerShell):

git clone https://github.com/ahmedvnabil/zad.git && cd zad
npm install

# جهّز الإعدادات
cp .env.example .env
# ولّد مفتاح التشفير وحطّه في .env تحت ENCRYPTION_KEY:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# ابنِ وشغّل
npm run build
node server/dist/index.js

افتح http://localhost:3001. أول مرة هيطلب منك المفتاح الموحّد — الخادم بيطبعه في اللوج عند أول تشغيل. بعد الدخول، روح صفحة المفاتيح، الصق مفتاح أي مزوّد مجاني (تسجيل مجاني بدون بطاقة) — وابدأ.

🔐 نموذج الأمان

مفتاح واحد يحمي كل شيء — نفس المفتاح الموحّد اللي بتبعته لـ /v1.

المسار	الحماية
`/api/*`	يتطلب المفتاح — المفاتيح، الإعدادات، التحليلات، الطلبات، السجل، التحديثات الحيّة
`/v1/*`	يتطلب المفتاح
`/api/ping`	عام — فحص حياة فقط (الحالة + علم الديمو). لا يكشف أي شيء آخر

المفتاح يُولَّد عند أول تشغيل ويُطبع في اللوج مرة واحدة. بعدها تقراه من صفحة المفاتيح أو تولّد غيره منها.
مفاتيح المزوّدين مشفّرة at-rest بـ ENCRYPTION_KEY. لا تُعاد أبداً كنص صريح — الواجهة تعرض قناعاً فقط.
المقارنة بالمفتاح ثابتة الزمن، والمفتاح لا يُوضع في أي رابط (localStorage في المتصفح، وهيدر Authorization على السلك).
CSP مفعّلة: default-src 'self' — لا سكربتات inline ولا eval. المسموح من الخارج ثلاثة فقط: ستايل خطوط Google، وملفات الخطوط، وسكربت Umami — وهي بالضبط ما يحمّله index.html.
HSTS يُرسَل فقط إذا وصل الطلب فعلاً عبر TLS (req.secure أو X-Forwarded-Proto: https). على http://localhost لا يُرسَل — لأن إرساله هناك يثبّت المتصفح على https://localhost ويكسر كل خوادم التطوير المحلية عندك، لا هذا فقط.

لو ضاع منك المفتاح:

sqlite3 server/data/freeapi.db "select value from settings where key='unified_api_key'"

⚠️ زاد مصمَّم لمشغّل واحد. مفتاح واحد، ومجموعة واحدة من مفاتيح المزوّدين يتشاركها كل من يملك المفتاح. مافيش حسابات ولا أدوار ولا عزل بين مستخدمين. تمام تماماً على شبكتك أو سيرفرك الخاص — بس ما تعرضهوش على الإنترنت وتوزّع المفتاح على ناس وأنت متوقّع إن كل واحد يستهلك حصّته لوحده؛ مش ده الغرض.

وضع التطوير: npm run dev (يشغّل الخادم + Vite معاً).

Docker: فيه Dockerfile جاهز. docker build -t zad . && docker run -p 3001:3001 -e ENCRYPTION_KEY=$(openssl rand -hex 32) zad

🔧 الإعدادات (env)

المتغيّر	الغرض
`ENCRYPTION_KEY`	مطلوب — مفتاح 64-hex لتشفير المفاتيح المخزّنة.
`PORT`	منفذ الخادم (افتراضي 3001).
`DASHBOARD_ORIGINS`	أصول إضافية مسموح لها بنداء الـAPI من المتصفح (لو الواجهة على مضيف مختلف).
`DEMO_MODE`	`true` يفعّل حماية الديمو العام (حارس SSRF على روابط المزوّدين، يقفل إعدادات تليجرام). مُستخدم على `demo.zad.tools`.
`INGEST_TOKEN`	يحمي endpoints الإضافة السريعة وإدارة المزوّدين (اختياري على شبكة موثوقة).
`TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID`	إشعارات تليجرام (أو اضبطها من صفحة التنبيهات).
`MERIDIAN_BASE_URL` / `CLIPROXY_BASE_URL`	تفعيل مزوّدات محلية اختيارية متوافقة مع OpenAI.

كل التفاصيل في .env.example.

🧪 الاستخدام (OpenAI-compatible)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="<مفتاح-زاد-الموحّد>",   # من صفحة المفاتيح
)

resp = client.chat.completions.create(
    model="auto",                      # خلّي زاد يختار + يحوّل احتياطياً
    messages=[{"role": "user", "content": "أهلاً!"}],
)
print(resp.choices[0].message.content)

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer <مفتاح-زاد-الموحّد>" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"أهلاً!"}]}'

model: "auto" = زاد يقرّر (مع التحويل الاحتياطي)، أو حدّد معرّف نموذج بعينه. الاستجابة بترجع هيدر X-Routed-Via يوضّح أي مزوّد/نموذج خدم الطلب.

🏗️ المعمارية

الخادم: Express + better-sqlite3 (المفاتيح مشفّرة، فحص صحة، توجيه + تحويل احتياطي، بروكسي متوافق مع OpenAI).
الواجهة: React + Vite + Tailwind + shadcn/ui (RTL).
التخزين: SQLite محلي — مفيش خدمة خارجية، مفيش تتبّع، بياناتك عندك.
التحديثات الحيّة: SSE (توزيع داخل العملية).
~7,000 سطر TypeScript إجمالاً، رخصة MIT، يقرأ في ساعة.

🙏 البناء على (Attribution)

زاد مبني على ومشتقّ من مشروع freellmapi (رخصة MIT) لـ Tashfeen Ahmed — شكراً للعمل الأصلي الممتاز.

أضافت نسخة زاد فوقه: تعريب كامل RTL + هوية بصرية جديدة، تسعير LiteLLM حقيقي وحساب التوفير، تحديثات حيّة عبر SSE، إشعارات تليجرام بصفحة إعدادات، إضافة/تعديل مزوّدين ديناميكياً من الواجهة، تجربة فورية من لوحة المعلومات، مزوّدين إضافيين، Dockerfile + وضع الديمو العام (DEMO_MODE)، ولاندنج بيج مصمّمة بـ Hallmark.

🤝 المساهمة

المساهمات مرحَّب بها — افتح issue أو PR. شغّل الاختبارات بـ npm test -w server. شوف CONTRIBUTING.md.

📄 الترخيص

MIT — انظر `LICENSE`. يحتفظ بحقوق المؤلف الأصلي ويضيف تعديلات زاد.

🌍 Zad · English

Dozens of excellent free AI models exist — but they're scattered across 17+ providers, each with its own limits, error semantics, and API key. Zad unifies them all behind a single OpenAI-compatible endpoint (/v1/chat/completions), picks the right model for each request, and automatically falls back when a provider rate-limits or goes down — all behind one key.

Fully self-hosted: keys encrypted on your server, data never leaves the building, no monthly bill.

🎬 Watch the full walkthrough (MP4)

💰 Why it matters — real numbers

For a workload of ~50,000 chat requests/month (~2k tokens each):

Provider	Monthly cost
Claude Sonnet 4.5	$1,100
GPT-4o	$1,167
Gemini 2.5 Pro	$708
Zad (free tiers + self-hosted)	$0

Same models. Same quality. Different plumbing. The free tiers carrying that $0 are not toys — Cerebras (1k req/day, sub-second), Groq (1k/day), Gemini (1M-token context), NVIDIA, Mistral, Cohere, SambaNova. Together they comfortably absorb most apps.

✨ Features

🔌 OpenAI-compatible — swap base_url, any SDK or tool works immediately.
🧭 140 providers · 5,140 models ready to discover via /api/registry (powered by models.dev, the same source that backs opencode).
🌊 17+ providers · 100+ free models enabled by default (Groq · Cerebras · SambaNova · NVIDIA · Mistral · OpenRouter · GitHub Models · Cohere · Cloudflare · Google · Zhipu · Ollama Cloud and more).
🔁 Automatic fallback — ranks models by intelligence/speed/budget, falls over on failure or rate-limit.
💸 Real pricing + savings analytics — from LiteLLM, shows what you'd have paid on a paid API.
📊 Live updates (SSE) — requests, latency, tokens, errors — all in real time.
🔔 Telegram alerts — new/invalid key · provider down/recovered · daily digest · error spikes (configured from the UI).
➕ Custom providers from the UI — add any OpenAI-compatible endpoint and edit its URL live (local Ollama · vLLM · LM Studio…).
🔐 Encrypted keys at rest + periodic health checks + automatic disable of failing keys.
🔑 Key-gated dashboard and /api — sign-in screen, and nothing exposed but a liveness probe.
🟢 Full Arabic RTL UI with a modern identity, light/dark, no complex build step.

🚀 Quick start (self-host)

Requirements: Node.js ≥ 20 + git.

OS	Install requirements
🍎 macOS	`brew install node git`
🐧 Linux (Debian/Ubuntu)	`curl -fsSL https://deb.nodesource.com/setup_20.x \| sudo -E bash -` then `sudo apt install -y nodejs git`
🪟 Windows (PowerShell)	`winget install OpenJS.NodeJS.LTS Git.Git`

git clone https://github.com/ahmedvnabil/zad.git && cd zad
npm install

# prepare config
cp .env.example .env
# generate the encryption key and put it in .env under ENCRYPTION_KEY:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# build & run
npm run build
node server/dist/index.js

Open http://localhost:3001. On first visit it asks for the unified API key — the server prints it to the log on first boot. Once you're in, go to the Keys page, paste any free-provider key (free sign-up, no card) — and you're running.

🔐 Security model

One key protects everything — the same unified key you send to /v1.

Path	Protection
`/api/*`	Key required — keys, settings, analytics, requests, registry, live updates
`/v1/*`	Key required
`/api/ping`	Public — liveness only (status + demo flag). Exposes nothing else

The key is generated on first boot and printed to the log once. After that, read or regenerate it from the Keys page.
Provider keys are encrypted at rest with ENCRYPTION_KEY and are never returned in plaintext — the UI only ever shows a mask.
Key comparison is constant-time, and the key never goes in a URL (localStorage in the browser, Authorization header on the wire).
CSP is on: default-src 'self' — no inline scripts, no eval. Exactly three third parties are allowed: the Google Fonts stylesheet, the font files, and the Umami script — precisely what index.html loads.
HSTS is sent only when the request actually arrived over TLS (req.secure or X-Forwarded-Proto: https). Never on http://localhost, where it would pin the browser to https://localhost and break every local dev server on the machine, not just this one.

Lost the key?

sqlite3 server/data/freeapi.db "select value from settings where key='unified_api_key'"

⚠️ Zad is built for a single operator. One key, and one pool of provider keys shared by everyone who holds it. There are no accounts, no roles, and no per-user isolation. That's fine on your own network or server — but don't expose it to the internet and hand the key to several people expecting each to draw on their own quota. That isn't what it does.

Dev mode: npm run dev (runs server + Vite together).

Docker: A Dockerfile is included. docker build -t zad . && docker run -p 3001:3001 -e ENCRYPTION_KEY=$(openssl rand -hex 32) zad

🔧 Configuration (env)

Variable	Purpose
`ENCRYPTION_KEY`	Required — 64-hex key for at-rest encryption of stored API keys.
`PORT`	Server port (default 3001).
`DASHBOARD_ORIGINS`	Extra browser origins allowed to call the API (if you serve the dashboard from a different host).
`DEMO_MODE`	`true` enables public-demo guards (SSRF protection on custom-provider URLs, blocks Telegram config). Used for `demo.zad.tools`.
`INGEST_TOKEN`	Protects quick-ingest + provider management endpoints (optional on trusted networks).
`TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID`	Telegram alerts (or set them from the Notifications page).
`MERIDIAN_BASE_URL` / `CLIPROXY_BASE_URL`	Optional local OpenAI-compatible providers.

All details in .env.example.

🧪 Usage (OpenAI-compatible)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="<your-zad-unified-key>",   # from the Keys page
)

resp = client.chat.completions.create(
    model="auto",                       # let Zad pick + auto-fallback
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer <your-zad-unified-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

model: "auto" = Zad picks (with automatic fallback), or specify a model ID directly. The response includes an X-Routed-Via header showing which provider/model served the request.

🏗️ Architecture

Server: Express + better-sqlite3 (encrypted keys, health checks, routing + fallback, OpenAI-compatible proxy).
Client: React + Vite + Tailwind + shadcn/ui (RTL).
Storage: local SQLite — no external services, no tracking, your data stays with you.
Live updates: SSE (in-process fan-out).
~7,000 lines of TypeScript total, MIT-licensed, readable in an hour.

📸 Screenshots

Playground	Fallback chain

Analytics	Notifications (Telegram)

Keys & providers	Request log

🙏 Attribution

Zad is built on and derived from freellmapi (MIT) by Tashfeen Ahmed — thanks for the original excellent work.

Zad adds on top: full Arabic RTL localization + new brand identity, real LiteLLM pricing & savings calculation, live updates via SSE, in-app Telegram notifications, dynamic provider add/edit from the UI, inline quick-try from the dashboard, additional providers, Dockerfile + public-demo (DEMO_MODE) hardening, and Hallmark-designed landing page.

🤝 Contributing

Contributions welcome — open an issue or PR. Run tests with npm test -w server. See CONTRIBUTING.md.

📄 License

MIT — see `LICENSE`. Retains the original author's copyright and adds Zad's modifications.

🌐 zad.tools · 🧪 demo.zad.tools · ⭐ Star on GitHub

Name		Name	Last commit message	Last commit date
.githooks		.githooks
.github/workflows		.github/workflows
client		client
docs		docs
repo-assets		repo-assets
scripts		scripts
server		server
shared		shared
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
free-ai-apis.pdf		free-ai-apis.pdf
free-ai-apis.typ		free-ai-apis.typ
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository files navigation

زاد · Zad

🌙 زاد · العربية

💰 ليه يهمّك — أرقام حقيقية

✨ المميزات

🚀 التشغيل السريع (Self-host)

🔐 نموذج الأمان

🔧 الإعدادات (env)

🧪 الاستخدام (OpenAI-compatible)

🏗️ المعمارية

🙏 البناء على (Attribution)

🤝 المساهمة

📄 الترخيص

MIT — انظر `LICENSE`. يحتفظ بحقوق المؤلف الأصلي ويضيف تعديلات زاد.

🌍 Zad · English

💰 Why it matters — real numbers

✨ Features

🚀 Quick start (self-host)

🔐 Security model

🔧 Configuration (env)

🧪 Usage (OpenAI-compatible)

🏗️ Architecture

📸 Screenshots

🙏 Attribution

🤝 Contributing

📄 License

MIT — see `LICENSE`. Retains the original author's copyright and adds Zad's modifications.

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

زاد · Zad

🌙 زاد · العربية

💰 ليه يهمّك — أرقام حقيقية

✨ المميزات

🚀 التشغيل السريع (Self-host)

🔐 نموذج الأمان

🔧 الإعدادات (env)

🧪 الاستخدام (OpenAI-compatible)

🏗️ المعمارية

🙏 البناء على (Attribution)

🤝 المساهمة

📄 الترخيص

MIT — انظر LICENSE. يحتفظ بحقوق المؤلف الأصلي ويضيف تعديلات زاد.

🌍 Zad · English

💰 Why it matters — real numbers

✨ Features

🚀 Quick start (self-host)

🔐 Security model

🔧 Configuration (env)

🧪 Usage (OpenAI-compatible)

🏗️ Architecture

📸 Screenshots

🙏 Attribution

🤝 Contributing

📄 License

MIT — see LICENSE. Retains the original author's copyright and adds Zad's modifications.

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

MIT — انظر `LICENSE`. يحتفظ بحقوق المؤلف الأصلي ويضيف تعديلات زاد.

MIT — see `LICENSE`. Retains the original author's copyright and adds Zad's modifications.