richlegrand/bitbang-cliأنشئ وصولاً آمناً عن بُعد إلى جهاز يتضمن قشرة تفاعلية (shell)، ونقل ملفات، ووكيل ويب عبر WebRTC من نظير إلى نظير بتشفير من الطرف إلى الطرف، باستخدام متصفح أو واجهة سطر أوامر (CLI) دون الحاجة إلى إعادة توجيه المنافذ أو إنشاء حسابات.
# BitBang CLI
[](https://github.com/richlegrand/bitbang-cli/actions/workflows/tests.yml)
`bitbang` هي أداة متعددة الاستخدامات للوصول عن بُعد في صورة ملف تنفيذي ثابت واحد. من أي متصفح: وصول إلى صدفة تفاعلية ومتصفح ملفات على الجهاز البعيد. يمكنك أيضًا الوصول إلى تطبيقات الويب على شبكة ذلك الجهاز. وإلى جانب المتصفح، تقوم الأداة بإعادة توجيه منافذ TCP، ونسخ الملفات، ومشاركة الطرفية. لا تتطلب أي حساب أو إعدادات -- إنها تعمل مباشرة.
على الجهاز الذي تريد الوصول إليه:
```
curl -sSfL bitba.ng/install | sh
bitbang serve
```
`serve` يطبع عنوان URL. افتحه في أي متصفح فتحصل على طرفية، ومتصفح ملفات، ووكيل (proxy) إلى شبكة ذلك الجهاز -- أو يمكنك الوصول إلى الجهاز نفسه من طرفية أخرى باستخدام `bitbang connect <url>`، الذي يضيف إعادة توجيه المنافذ (`-L`) ونسخ الملفات (`bitbang cp`). الاتصال مشفّر من طرف إلى طرف ومباشر بين الطرفين (peer-to-peer)؛ خادم `bitba.ng` يعرّف الطرفين ببعضهما ثم ينسحب جانبًا.
`bitbang` هو ملف Go ثنائي ثابت واحد. وهو جزء من [مشروع BitBang](https://github.com/richlegrand/bitbang)؛ وتغطي [هذه الورقة البيضاء](https://github.com/richlegrand/bitbang/blob/main/whitepaper.md) التصميم بعمق.
## كيف يقارَن
| | ngrok | Tailscale | `bitbang` |
| ------------------------------ | ---------------------- | ------------------------------ | ------------------- |
| الإعداد قبل الاستخدام الأول | حساب + authtoken | حساب + تسجيل الدخول على كل جهاز | **تشغيل أمر واحد** |
| لمشاركة شيء ما، تشغّل | خادم ويب، بالإضافة إلى ngrok | عميلهم على كلا الجهازين | **`bitbang serve`** |
| ما يحصل عليه متصفح على الطرف البعيد | خادم الويب الذي كنت تشغّله بالفعل | لا شيء -- فهو يحتاج عميلهم | **طرفية، ومتصفح ملفات، وتطبيقات ويب على الشبكة البعيدة** |
| مسار البيانات | خوادمهم | P2P (مع تراجع إلى relay) | **P2P (مع تراجع إلى relay)** |
| مشفّر من طرف إلى طرف | ليس افتراضيًا | نعم | **نعم** |
## وصفات سريعة
**الوصول إلى خدمة في المنزل**
- [اربط NAS المنزلي من أي مكان (SMB)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#mount-your-home-nas-from-anywhere-smb)
- [شاهد مكتبة الوسائط من أي مكان (Jellyfin)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-your-media-library-from-anywhere-jellyfin)
- [استخدم نموذجك اللغوي الخاص من أي مكان (Ollama, Open WebUI)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#use-your-own-llm-from-anywhere-ollama-open-webui)
- [تحقق من كاميرات المراقبة (Frigate)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-security-cameras-frigate)
- [الوصول إلى أتمتة منزلك دون كشفها (Home Assistant)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-your-home-automation-without-exposing-it-home-assistant)
- [اطبع على طابعة منزلك (IPP, CUPS)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#print-to-your-home-printer-ipp-cups)
**الدخول إلى جهاز**
- [احصل على shell على جهاز خلف NAT](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-on-a-machine-behind-nat)
- [احصل على shell من هاتفك](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-from-your-phone)
- [سطح مكتب عن بُعد إلى جهاز Windows (RDP)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#remote-desktop-into-a-windows-machine-rdp)
- [الوصول إلى سطح مكتب Linux أو Mac (VNC)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-linux-or-mac-desktop-vnc)
- [SSH إلى جهاز بلا منفذ مفتوح (OpenSSH)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#ssh-to-a-machine-with-no-open-port-openssh)
- [إعداد Raspberry Pi بلا شاشة (headless)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#set-up-a-headless-raspberry-pi)
**المشاركة مع شخص آخر**
تتضمن المشاركة ببساطة إعطاء شخص ما عنوان URL فريدًا أو رمز QR يمنحه الوصول. يمكن تخصيص الأذونات وضبطها لتنتهي صلاحيتها خلال دقائق أو ساعات، إلخ.
- [شارك الملفات دون رفعها إلى أي مكان](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#share-files-without-uploading-them-anywhere)
- [اعرض مشروعك على شخص ما](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-your-project)
- [اعرض على شخص ما الخطأ الذي علقت عنده](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-the-error-you-are-stuck-on)
- [امنح شخصًا ما وصولًا ينتهي صلاحيته](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#give-someone-access-that-expires)
- [تحقق من جلسة الوكيل الخاص بك من هاتفك (Claude Code، tmux)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-agent-session-from-your-phone-claude-code-tmux)
- [أصلح موجّه شخص آخر](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#fix-someone-elses-router)
**التطوير والأجهزة**
- [الوصول إلى قاعدة بيانات من جهاز التطوير الخاص بك (Postgres، MySQL)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-database-from-your-dev-machine-postgres-mysql)
- [زامن الأجهزة التي لا تستطيع العثور على بعضها البعض (Syncthing)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#sync-devices-that-cannot-find-each-other-syncthing)
- [راقب روبوتًا من متصفح (ROS، Foxglove)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-a-robot-from-a-browser-ros-foxglove)
**التقنيات**
- [ما الذي يكشفه مستمع إعادة التوجيه](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#what-a-forwarding-listener-exposes)
- [اسمح لأجهزة أخرى على شبكتك المحلية باستخدام إعادة توجيه](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#let-other-machines-on-your-lan-use-a-forward)
- [المعروف أنه لا يعمل](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#known-not-to-work)
## استخدام `bitbang`
كل اتصال له طرفان: **مستمع** (`bitbang serve`، يعمل على الجهاز الذي يتم الوصول إليه) و**موصّل** (متصفح، أو أداة `bitbang` CLI، على الجهاز الذي يقوم بالوصول). عنوان URL واحد للمستمع يخدم كلا نوعي الموصّلات.
### المستمع: `bitbang serve`
```
bitbang serve # everything: shell + proxy + files + forward
bitbang serve shell # just a terminal
bitbang serve files ~/share # just a directory (-files-upload to allow uploads)
bitbang serve proxy localhost:8080 # just one web app, straight at the URL
bitbang serve proxy a.lan:80,b.lan:80 # ...or several, chosen in the browser
bitbang serve forward 127.0.0.1:22 # just TCP, for `connect -L`
bitbang serve shell files ~/share proxy nas.lan:8096 # any combination
```
كل منهما يطبع رمز QR وعنوان URL ورمز اقتران. يحدد الوضع ما يمكن للمستمع فعله على الإطلاق: `serve shell` لا يملك أي إعادة توجيه لمنحه، والمستمع المخصص لإعادة التوجيه فقط لا يبدأ صدفة أبدًا، لذا لا يوجد شيء للتصعيد إليه.
هناك إعداد افتراضي يستحق المعرفة: **إعادة التوجيه والوكيل يصلان إلى أي host:port يمكن للمستمع الوصول إليه**، وليس فقط الهدف الذي كان في ذهنك، لذا فإن رابطًا يُمنح لقاعدة بيانات يصل أيضًا إلى بقية تلك الشبكة. تسمية الأهداف بالكلمة تضيّق ذلك -- `forward db.internal:5432` يصل إلى ذلك الهدف ولا شيء غيره.
### مشاركة جلسة قيد التشغيل: `bitbang share`
`serve shell` يبدأ صدفة جديدة. أما `share` فينشر جلسة tmux قيد التشغيل بالفعل:
```
bitbang share # publish the current tmux session
bitbang share --read-only # publish without a control URL
bitbang share status|stop|rotate
```
يعود الأمر بعد النشر، لذا يعمل `Ctrl-Z` و`bitbang share` و`fg`
لمهمة قيد التنفيذ بالفعل. تتطلب الاستضافة tmux 3.2+ على Unix أو
WSL. يمكن لعملاء Windows الأصليين فتح عناوين URL لكن لا يمكنهم استضافة مشاركة.
بشكل افتراضي، يطبع الأمر عنوانَي URL حاملين:
- يمكن لـ **Control URL** الكتابة بنفس الصلاحية التي يتمتع بها لوحة المفاتيح المحلية.
يمكن لجهاز تحكم واحد الاتصال في كل مرة.
- **View URL** للمشاهدة فقط. يتم إسقاط الإدخال قبل وصوله إلى tmux، و
يمكن لما يصل إلى `--max-viewers` مشاهد الاتصال في وقت واحد (الافتراضي 16).
يحذف `--read-only` بيانات اعتماد التحكم بالكامل. يتم الاحتفاظ بحدود المشاهد
وجهاز التحكم طوال عمر كل اتصال، حتى قبل أن يفتح صدفة.
تستمر المشاركات حتى يتم إيقافها بشكل افتراضي؛ يضبط `--ttl` مدة صلاحية (مثل `--ttl 1h`).
عناوين URL للمشاركة مؤقتة ولا يتم حفظها أبدًا في `devices.json`. يؤدي `share stop`
أو انتهاء صلاحية TTL أو إزالة الجلسة المصدر إلى قطع اتصال الأقران البعيدين دون
إيقاف الجلسة المصدر.
إعادة تشغيل `bitbang share` تعيد طباعة عناوين URL للمشاركة قيد التشغيل. إذا مررت
علامة تتعارض مع ما هو قيد التشغيل (قل `--read-only`
مقابل مشاركة لديها Control URL)، فإنه يذكر ذلك بدلاً من
إعادة عناوين URL القديمة؛ يستبدل `bitbang share rotate` المشاركة
بأخرى تستخدم العلامات الجديدة.
يعمل عامل خلفي في جلسة إدارة tmux منفصلة `_bbshare_*`،
لذا لا يوجد خادم خفي أو ملف PID لإدارته.
لا تغيّر المشاركة أي خيارات في tmux. مع الإعداد الافتراضي `window-size latest` في tmux، تتبع
النافذة العميل النشط للقراءة والكتابة؛ لا يزال المشاهد الوحيد يوفر
الحجم الوحيد المتاح. إذا تم تجاوز `window-size`، فإن `share` يبلّغ عنه
لكنه لا يغيّر إعدادات المستخدم.
### منح وصول محدود: `bitbang link`
مستمع واحد، وعنوان URL واحد، وأي عدد تحتاجه من **روابط الوصول**. كل منها
رمز منفصل على نفس عنوان URL، يمنح مجموعة فرعية مما يقدمه المستمع
وينتهي اختياريًا في وقت محدد:
```
bitbang link edit # add entries in $EDITOR
bitbang link ls # what you have handed out
bitbang link rm <label> # revoke one
bitbang link qr <label> # its URL and QR code
```
المُدخل هو سطر JSON في `~/.bitbang/bitbang/links.json`. اكتب واحدًا بدون
كود، وأعد تحميل المستمع من وحدته الطرفية، وسيقوم بإنشاء واحد:
```json
[
{"label": "ana", "grant": "files", "expires": "2026-09-01T00:00:00Z"},
{"label": "ben", "grant": "files /srv/photos"},
{"label": "dev", "grant": "shell forward 127.0.0.1:5432"}
]
```
```
0) owner files forward proxy shell
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#_vtQ0JCPe7s
1) ana files expires in 6d
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#T-Ty_HhvLfY
2) ben files /srv/photos
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#L6La8OzBO74
3) dev forward 127.0.0.1:5432 shell
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#8kmI3LYzB7E
```
`owner` هو رمز الهوية نفسه ويمنح كل ما يقدّمه المستمع؛ أرسل
أحد الرموز الأخرى بدلاً منه. تقبل الطرفية إما التسمية أو الرقم المجاور
لها، لذا فإن `rm 2` و`rm ben` تفعلان الشيء نفسه.
يُكتب `grant` بالكلمات التي يقبلها `serve`، ولا يمكنه إلا أن يضيّق ما
يقدّمه المستمع بالفعل. وهذا يعني أن الرابط ليس مقيدًا باختيار القدرات:
فيمكنه تسمية دليل فرعي من المجلد المشترك، أو مجموعة فرعية من أهداف التمرير، أو
أمر واحد لـ `shell`. احذف `grant` وسيمنح الرابط كل ما يفعله المستمع.
اطلب شيئًا خارج نطاق المستمع وسترفضه الطرفية بالرسالة نفسها التي
سيعطيك إياها `serve`.
التسمية هي ما يحدد الرابط، وليس شروطه، لذا يمكن لشخصين أن يحملا روابط
بمنح وانتهاء صلاحية متطابقين، ويمكنك مع ذلك إبطال أحدهما دون المساس
بالآخر.
الإبطال وانتهاء الصلاحية يطالان الجلسات المفتوحة بالفعل: يُغلق الاتصال
ويُخبر حامله بالسبب، بدلاً من أن يصمت. والرمز المنتهي الصلاحية
يُسحب بدلاً من تعليقه -- تجديد إدخال يولّد رمزًا جديدًا، لذا يبقى عنوان URL الذي
أرسلته بالفعل ميتًا.
### الاقتران برمز مكوّن من 6 أرقام
عندما لا تستطيع لصق عنوان URL أو مسح رمز QR، كما هو الحال عندما تكون على الهاتف، أو على مسافة صياح، يطبع `bitbang serve` أيضًا **رمز اقتران** قصيرًا. يفتح الطرف الآخر `bitba.ng/<code>` (أو يشغّل `bitbang connect <code>`)، وتعرض شاشته رقمًا آخر مكوّنًا من 6 أرقام، ويقرأ لك *ذلك* الرقم. تكتبه للموافقة. لا يستطيع رجل في المنتصف جعل الرقمين متطابقين، ويحفظ الاقتران بيانات اعتماد اتصال الجهاز للمرة القادمة، مثل `bitbang connect nas1`. إذا كنت تعرف [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole)، فالشكل مشابه -- رمز منطوق يقدّم جهازين بأمان.
### أحضر TURN الخاص بك
معظم الاتصالات تذهب مباشرة من نظير إلى نظير. عندما يكون كلا الطرفين خلف NAT
لا يسمح بثقب الفتح، يحتاج المرور إلى مُرحّل، وهو افتراضيًا خاص بنا. يوجّه `-ice-servers`
المستمع إلى خادمك الخاص بدلاً من ذلك:
```
bitbang serve -ice-servers ~/turn.json
```
يُسلّم المستمع الإعدادات إلى خادم الإشارات عند التسجيل، ويُعطيها الخادم لمن يتصل -- لذا يستخدم الطرفان مرحّل الرسائل الخاص بك ولا يكون مرحّلنا متورطًا أبدًا. أي خادم coturn، أو مزوّد مستضاف مثل Cloudflare أو Twilio، يعمل.
الملف بصيغة JSON، بأي من هذه الأشكال الثلاثة التي سلّمك إياها مزوّدك:
```json
[{"urls": ["turn:turn.example.net:3478"], "username": "user", "credential": "pass"}]
```
```json
{"ice_servers": [{"urls": "stun:stun.example.net:3478"}]}
```
```json
{"iceServers": [{"urls": ["turn:turn.example.net:3478"], "username": "u", "credential": "p"}]}
```
`urls` يقبل سلسلة نصية أو قائمة؛ و`username` و`credential` مخصّصان لـ TURN ويمكن تركهما خارج مدخل STUN فقط. قد يكون المسار مطلقًا أو نسبيًا أو جذريًا بـ `~`. الملف الذي لا يُحلَّل يوقف المستمع عند بدء التشغيل بدلًا من التراجع بصمت.
إذا انتهت جلسة إلى التمرير عبر relay دون طلب ذلك، فإن `bitbang connect` يصرّح بذلك بدلًا من تركك تتساءل عن سبب بطئه. يسجّل المستمع ذلك في كلتا الحالتين (`via RELAY`)، ويفرض `-relay` / `-norelay` السؤال في أحد الاتجاهين عندما تشخّص مسارًا ما.
يجدر القول: هذا يتعلق بمن يحمل البايتات، لا بمن يمكنه قراءتها. لا يرى الـ relay سوى نص DTLS المشفّر، بما في ذلك نصّنا. شغّل relay خاصًا بك عندما تحتاج إلى TURN أكثر مما نستطيع توفيره (نحدّد الوقت حاليًا).
### الاتصال من متصفح
افتح عنوان URL. بناءً على ما يتم تقديمه، ستحصل على:
- **Shell** -- طرفية كاملة في الصفحة (ألوان، تغيير الحجم، نسخ/لصق).
- **Files** -- تصفّح، معاينة، تنزيل، ورفع.
- **Proxy** -- اكتب عنوان LAN (`nas.local`، `192.168.1.10:8080`، `localhost:3000/admin`) واستخدم التطبيق كما لو كنت محليًا. تعمل عمليات تسجيل الدخول وملفات تعريف الارتباط والرفع والبث جميعها.
<!-- TODO: per-feature demos -->
<!-- Remote shell in a browser tab -->
<!-- Streaming Jellyfin through the proxy -->
### الاتصال من CLI
```
bitbang connect <url> # interactive shell
bitbang connect <url> -- tail -f /var/log/syslog # one-shot command
bitbang connect <url> -L 15432:db.internal:5432 # local TCP forwarding
bitbang connect <url> -L 14450:nas.local:445 -L 15900:[fd00::20]:5900
bitbang cp <url>:/var/log/app.log ./app.log # copy files, scp-style
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin # stdin/stdout work too
```
`-L` يمرر **TCP فقط**، مثل `ssh -L`. يربط `-L` على `127.0.0.1` ما لم تمرر
`-g`، الذي يجعل المنفذ المُمرَّر قابلاً للوصول من شبكتك المحلية -- وأي شخص
يصل إليه يحصل على ما يصل إليه النفق، دون أي
بيانات اعتماد BitBang أمامه.
يحتاج المستمع إلى `bitbang serve forward` أو `bitbang serve`. افتراضيًا،
يصل رابط `forward` إلى **أي host:port يمكن للمستمع الوصول إليه**، وليس فقط
الذي كان في ذهنك، لذا فإن رابطًا مُمنوحًا لقاعدة بيانات يصل أيضًا إلى بقية
تلك الشبكة. ضيّقه بتسمية ما يجوز له الوصول إليه:
```
bitbang serve forward db.internal:5432 # this link reaches one service
```
كل اتصال أو اقتران ناجح يُحفظ في `~/.bitbang/devices.json`، لذا يكفي من ذلك الحين اسم قصير: `bitbang connect nas1`.
## دعم المنصات
ملف تنفيذي واحد لكل منصة، بلا اعتماديات وقت التشغيل. كل شيء يعمل
في كل مكان باستثناء الصفين المذكورين أدناه.
| | Linux | macOS | Windows |
| ---------------------------------------- | :---: | :---: | :-----: |
| Shell, files, proxy (`bitbang serve`) | yes | yes | yes |
| TCP forwarding (`-L`) | yes | yes | yes |
| Access links -- grant, expiry, revocation | yes | yes | yes |
| Bring your own TURN | yes | yes | yes |
| Pairing with a 6-digit code | yes | yes | yes |
| The listener console (Enter) | yes | yes | yes |
| `bitbang connect`, `bitbang cp` | yes | yes | yes |
| Viewing a shared session | yes | yes | yes |
| **Hosting a share** (`bitbang share`) | yes | yes | no * |
| **Terminal resize while connected** | yes | yes | no ** |
\* ينشر `bitbang share` جلسة tmux، لذا تتطلب استضافتها وجود tmux --
Linux أو macOS أو WSL. لا يزال بإمكان Windows الأصلي فتح روابط المشاركة باستخدام
`bitbang connect`.
\*\* لا يلاحظ موصل Windows تغيير حجم طرفيته، لذا تحتفظ
الصدفة البعيدة بالحجم الذي بدأت به حتى تعيد الاتصال. تحصل Unix
على ذلك من `SIGWINCH`، الذي لا يوجد له مكافئ في Windows.
## الأمان
- **هوية ذاتية التصديق.** عند التشغيل الأول، يولّد `bitbang` زوج مفاتيح RSA تحت `~/.bitbang/<program>/`؛ يُشتق معرّف الجهاز UID من المفتاح العام، لذا يعني انتحال هوية جهاز إيجاد صورة سابقة ثانية لمعرّفه UID.
- **لا يلمس السر الخادم أبدًا.** يعيش رمز الوصول في جزء الرابط (`#…`)، الذي لا ترسله المتصفحات أبدًا -- يتوسط `bitba.ng` في الاتصال دون أن يرى قط بيانات الاعتماد التي تجيزه.
- **تشفير من طرف إلى طرف.** تمر كل حركة المرور عبر DTLS الخاص بـ WebRTC. لا يرى خادم الإشارات سوى المفتاح العام، ومعرّف UID المشتق، وبيانات وصفية للاتصال -- ولا يرى بياناتك أبدًا. أما مرحّل TURN، إن لزم أحده، فلا يرى سوى النص المشفّر.
- **اقتران موثّق.** الرقم المقروء بصوت عالٍ في الاقتران بالرمز هو سلسلة مصادقة قصيرة (SAS)، تُحسب بشكل مستقل على الطرفين من بصمات DTLS المتفاوض عليها ومن nonce ملتزم بهما -- لا يستطيع رجل في المنتصف، الذي تختلف بصماته بالضرورة، جعل الرقمين متطابقين.
- **الرابط بيانات اعتماد حاملة.** من يملكه يحصل على ما اخترت تقديمه -- صدفة، إن شغّلت `serve shell`. شاركه وفقًا لذلك.
- **رمز PIN اختياري** (`--pin`) للإعدادات الدائمة أو بلا واجهة، و**وضع الاستخدام لمرة واحدة** (`-ephemeral`) لهوية جديدة في كل تشغيل.
- **ما لا يزال الخادم يراه.** ليس لا شيء. فهو يتوسط في التعريف، لذا
يلاحظ عناوين IP للطرفين، ومتى يتصلان، ومقدار ما
يتبادلانه. يُبقيه التشفير من طرف إلى طرف خارج بياناتك، لا خارج
البيانات الوصفية المحيطة بها -- *الثقة الدنيا* وصف أعدل من
*بلا ثقة*.
- **المتصفح يثق بالصفحة التي حمّلها.** عميل المتصفح هو JavaScript
يقدمه خادم الإشارات، لذا يعني فتح رابط الثقة بذلك الخادم
في تقديم شيفرة صادقة. لا يعتمد `bitbang connect` على ذلك: فهو
ملف تنفيذي قمت بتثبيته والتحقق من بصمته. إن كان هذا التمييز مهمًا لك،
فاتصل عبر CLI.
كيف يصادق الطرفان بعضهما بعضًا، بحيث لا يستطيع خادم الإشارات
إدخال نفسه في الاتصال، مشروح بالتفصيل هنا: [*Trustless Signaling: Authentication Without a Central Authority*](https://github.com/richlegrand/bitbang/blob/main/trustless-signaling.md).
## لماذا؟
- **لا شيء لفتحه أو تكوينه.** يعمل من خلف NAT أو CGNAT أو شبكة مقيدة -- لا تغييرات في الراوتر، لا VPN، لا برنامج خفي للنفق.
- **لا شيء لتثبيته على جانب الاتصال.** يكفي متصفح. تتوفر واجهة سطر أوامر عندما تريد البرمجة النصية والأنابيب ونسخ الملفات.
- **خاص بالتصميم.** حركة المرور هي WebRTC/DTLS، من نظير إلى نظير. لا يراها خادم الإشارات أبدًا؛ إذا لم يكن المسار المباشر ممكنًا، فإن مرحّل TURN ينقل النص المشفر فقط.
- **لا حساب، لا قياس عن بُعد.**
### لماذا لا تستخدم SSH فقط؟ أو Tailscale؟
الإجابة المختصرة: بالنسبة لجهاز يمكنك بالفعل الدخول إليه عبر SSH، أو مجموعة من أجهزتك
الخاصة التي يمكنك التثبيت عليها، استمر في استخدام ما لديك. `bitbang` مخصص للحالات التي يكون فيها
الطرف البعيد شخصًا وليس جهازًا، أو عندما لا يمكنك تثبيت أي شيء
حيث تجلس. تتم الإجابة على كلا السؤالين بالتفصيل في
**[الأسئلة الشائعة](https://github.com/richlegrand/bitbang-cli/blob/main/FAQ.md)**.
## التثبيت
```
curl -sSfL bitba.ng/install | sh
```
لينكس وmacOS. يكتشف نظام التشغيل لديك والمعمارية (`amd64`، `arm64`، و`armv7` على لينكس)، ويُنزّل الملف التنفيذي من أحدث [إصدار على GitHub](https://github.com/richlegrand/bitbang-cli/releases)، ويتحقق من SHA-256 الخاص به مقابل ملف `checksums.txt` المرفق بالإصدار، ويثبّته في `~/.local/bin/bitbang`.
تُنشر إصدارات Windows بصيغة `bitbang-windows-amd64.exe` و
`bitbang-windows-arm64.exe`. نزّل الملف التنفيذي المناسب من صفحة Releases،
وأعد تسميته إلى `bitbang.exe`، وضعه على `PATH` الخاص بك.
**البناء من المصدر:** راجع [أدناه](#building-from-source).
**macOS وGatekeeper.** لا يتأثر أمر التثبيت أحادي السطر أعلاه: فـ `curl` لا
يضبط سمة `com.apple.quarantine`، لذا يعمل الملف التنفيذي الذي يجلبه
بشكل طبيعي. أما إذا نزّلت `bitbang-darwin-arm64` من صفحة Releases
عبر متصفح بدلاً من ذلك، فإن macOS يضعه في الحجر الصحي ويرفض فتحه، لأن الملفات
التنفيذية للإصدارات غير موثّقة (notarized). أزل الحجر الصحي بأي من الأمرين التاليين:
```
xattr -d com.apple.quarantine ./bitbang-darwin-arm64
```
أو انقر بزر الفأرة الأيمن على الملف في Finder واختر Open، مما يتيح تجاوزًا لمرة واحدة. بدلاً من ذلك، ابنِ من المصدر، وهو لا يضع علامة حجر أبدًا.
**Windows وSmartScreen.** يحدث الشيء نفسه على Windows، وللسبب ذاته. تنزيل المتصفح يُرفق Mark-of-the-Web، لذا يُظهر التشغيل الأول *"Windows protected your PC"* -- اختر **More info**، ثم **Run anyway**. ملفات التوزيع الثنائية ليست موقّعة برمجيًا، لذا هذا أمر متوقع وليس علامة على وجود خطأ ما. جلب ملف `.exe` باستخدام `curl` أو `Invoke-WebRequest` في PowerShell لا يُرفقه، وكذلك البناء من المصدر.
### خيارات التثبيت
ثبّت إصدارًا محددًا، أو غيّر الموقع، أو اقرأ السكربت قبل تشغيله:
```
curl -sSfL bitba.ng/install | sh -s -- --version 0.5.0
curl -sSfL bitba.ng/install | sh -s -- --prefix /usr/local/bin
curl -sSfL bitba.ng/install -o install.sh && less install.sh && sh install.sh
```
لا تحتوي وسوم الإصدار على بادئة `v` (`0.5.0`، وليس `v0.5.0`).
### كيف يعمل رابط التثبيت
`bitba.ng/install` هو إعادة توجيه، وليس نصًا برمجيًا مستضافًا. السلسلة:
1. يصل `curl` إلى `https://bitba.ng/install`، الذي يعيد توجيه 302 إلى [`install.sh`](https://github.com/richlegrand/bitbang-cli/blob/main/install.sh) في هذا المستودع (على `main`).
2. يعمل النص البرمجي في shell الخاص بك، ويكتشف نظام التشغيل والمعمارية، وينزّل ملفًا ثنائيًا من `https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>`.
3. يجلب `checksums.txt` من الإصدار نفسه ويتحقق من SHA-256 للملف الثنائي.
4. يثبّت في `~/.local/bin` (قابل للتجاوز).
يعيش نص التثبيت البرمجي في هذا المستودع، بجوار الكود الذي يثبّته -- لذا يمكنك مراجعته إلى جانب الملف الثنائي، ومضيف bitba.ng الأساسي يملك فقط الرابط القصير. يمكن للمستضيفين الذاتيين توجيه `/install` الخاص بمضيفهم إلى أي نص برمجي يشحنونه: متغير البيئة `INSTALL_URL` في خادم الإشارات يتحكم في هدف إعادة التوجيه (فارغ → 404).
## مرجع الأوامر
كل أمر فرعي وعلم موجود في **[CLI.md](https://github.com/richlegrand/bitbang-cli/blob/main/CLI.md)**، و`bitbang <command>
--help` يطبع الشيء نفسه في الطرفية.
## البناء من المصدر
يتطلب Go 1.25+. Go خالص، مرتبط بشكل ثابت (`CGO_ENABLED=0`) -- ترجمة متقاطعة بسيطة، بلا تبعيات وقت التشغيل.
```
go build ./cmd/bitbang/
# cross-compile:
GOOS=linux GOARCH=arm64 go build -o bitbang-arm64 ./cmd/bitbang/
GOOS=linux GOARCH=arm GOARM=7 go build -o bitbang-armv7 ./cmd/bitbang/
```
---
[Read more](https://github.com/richlegrand/bitbang-cli)