clawk

<div align="center">

<img src="https://assets.kitploit.com/production/public/readmes/7237/193b3f67135a6e0f90c36ec914e8c5fd73a4d6181ea56b6ba75e042e6335dc72.png" alt="clawk" width="400">

*امنح وكيل البرمجة آلة Linux خاصة به قابلة للتخلص منها، لا آلتك.*

[![CI](https://github.com/clawkwork/clawk/actions/workflows/ci.yml/badge.svg)](https://github.com/clawkwork/clawk/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Go 1.26+](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go&logoColor=white)](go.mod)
![Platform: macOS · Linux (experimental)](https://img.shields.io/badge/platform-macOS%20%C2%B7%20Linux%20(experimental)-lightgrey)

**[التثبيت](#install)** · **[البدء السريع](#quickstart)** ·
**[لماذا آلة افتراضية؟](#why-a-vm)** · **[كيف يعمل](#how-it-works)** ·
**[مقارنة بـ](#compared-to)** · **[الأسئلة الشائعة](#faq)** · **[التوثيق](https://github.com/clawkwork/clawk/blob/main/docs)**

</div>

لا يكون وكيل البرمجة مفيدًا إلا عندما تتيح له أن *يفعل* الأشياء فعليًا: تثبيت
الحزم، وتشغيل الكود الذي يكتبه، وتشغيل الخوادم، واستخدام الشبكة. على آلتك
الخاصة، يتركك ذلك أمام خيارين سيئين. إما أن توافق على كل أمر (وتظل تراقب
نافذة موافقة كل بضع ثوانٍ)، أو تشغّل `--dangerously-skip-permissions` وتأمل
ألا يكون أي شيء مهم على بُعد أمر `rm -rf` واحد أو رمز مميز مسرّب واحد.

clawk هو الخيار الثالث. انتقل بـ `cd` إلى مستودع، واكتب `clawk`، وسيعمل Claude Code (أو
Codex، أو pi، أو صدفة) داخل آلة Linux افتراضية قابلة للتخلص منها (كودك مُثبَّت
بالداخل، وصلاحيات الجذر في الضيف، دون مطالبات أذونات) بينما تبقى ملفاتك وسلسلة مفاتيحك
وبقية آلتك بعيدة عن المتناول. **يحصل الوكيل على آلة
خاصة به بدلًا من آلتك.**

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7237/56b97e90b5af190abc2e1de5cc7b8ad4e835a05dd6e7a1e2f3416d78021a6a8b.gif" alt="عرض توضيحي لـ clawk: يشغّل clawk آلة افتراضية ويُرفق claude؛ تظهر محاولة محظورة لإرسال بيانات إلى خادم غير معروف في رفض الشبكة الخاص بـ clawk؛ ويستأنف clawk attach البيئة المعزولة لاحقًا" width="760">
  <br>
  <sub><i>أمر واحد للوصول إلى وكيل عامل؛ محاولة لإرسال بيانات إلى
  خادم غير معروف، حظرتها قائمة السماح الشبكية؛ ويستأنف <code>clawk attach</code>
  الجلسة لاحقًا.</i></sub>
</p>

الحد الفاصل ليس قاعدة في توجيه يمكن إقناع الوكيل بتجاوزها. إنه
آلة منفصلة، والمنافذ الوحيدة هي تلك التي ثبّتّها أنت. من صدفة
داخل بيئة معزولة:

```console
$ curl https://tracker.evil.example   # not on the allow-list: blocked
curl: (7) Failed to connect to tracker.evil.example port 443 after 2 ms: Connection refused

$ cat ~/.ssh/id_rsa                   # your keys never entered the VM
cat: /home/agent/.ssh/id_rsa: No such file or directory

$ git push                            # ...yet this works: ssh-agent is forwarded
Enumerating objects: 5, done.
```

للإنصاف بشأن القيود، تمنع قائمة السماح الاتصالات بخوادم *غير معروفة*، وليس
تلك التي سمحت بها: github.com مسموح به مسبقًا ويمكن لـ ssh-agent المُمرَّر أن
يدفع، لذا تعامل مع أي شيء يستطيع الوكيل قراءته على أنه شيء يمكنه نشره.
يوضح [نموذج الأمان](#security-model-and-its-limits) هذا بالتفصيل.

وإذا أفسد الوكيل الآلة الافتراضية، فشغّل `clawk destroy && clawk`: آلة افتراضية
جديدة، نفس المستودع، و`--resume` يستعيد المحادثة.

> [!IMPORTANT]
> **قبل الإصدار 1.0 وبوتيرة سريعة.** توقّع تغييرات كاسرة بين الإصدارات
> وحوافّ خشنة أحيانًا؛ يمكن أن تنكسر الأمور وستنكسر. يُرجى فتح issues؛
> تلك الملاحظات تُشكّل الإصدار 1.0.

## أبرز الميزات

- **دع الوكيل يفعل أي شيء.** يعمل في آلة افتراضية قابلة للتخلص منها مع شبكة
  مقيّدة، لذا لا يمكن لـ `rm -rf` أو تثبيت الحزم أو الشيفرة غير الموثوقة الوصول
  إلى مضيفك أو ملفاتك أو أي شيء لم تشاركه صراحةً.
- **العمل بأمر واحد.** انتقل بـ `cd` إلى مستودع وشغّل `clawk`. لا حاجة إلى
  Dockerfile أو devcontainer أو ملف إعداد. أول إقلاع يبني rootfs من
  صورتك؛ وكل إقلاع بعده يستغرق ثوانٍ.
- **اكسره دون فقدان أي شيء.** دمّر وأعد الإنشاء بحرية؛ شيفرتك ومحادثات
  الوكيل تعيش على المضيف. يُفقد فقط قرص الآلة الافتراضية القابل للتخلص منه.
- **صندوق Linux حقيقي، وسلسلة أدواتك.** أي صورة OCI هي الـ rootfs: نظام
  تشغيل كامل بالأدوات التي يحتاجها مشروعك بالضبط. لا حاجة إلى Docker daemon.
- **الأسرار تبقى على جهازك.** حركة المرور الصادرة مسموح بها عبر قائمة، ويُمرَّر
  ssh-agent الخاص بك، لذا يعمل `git push` دون دخول المفاتيح إلى الآلة الافتراضية.
- **صندوق رمل لكل مشروع أو تذكرة.** شغّل عدة صناديق في آنٍ واحد؛ التذاكر
  متعددة المستودعات تحصل على git worktree لكل مستودع مع PRs منسّقة. الآلات
  الافتراضية الخاملة تحرّر الذاكرة تلقائيًا وتُعلَّق إلى القرص، لذا لا يكلّف
  صندوق رمل منسيّ (تقريبًا) شيئًا.

## لماذا آلة افتراضية؟

clawk بيئة محلية عامة الغرض لوكلاء البرمجة المستقلين.
الآلة الافتراضية هي المقصد: إنها آلة كاملة يمكن للوكيل امتلاكها، وليست عملية
مغلّفة بسياسة على الآلة التي تستخدمها.

- **نواة منفصلة.** يعمل الضيف بنواة Linux خاصة به، لذا نظام ملفات المضيف
  ليس مخفيًا خلف قواعد منع؛ لم يُوصَّل أصلًا.
- **بيئة Linux تقليدية.** نواة قياسية، userland قياسي، توقعات على شكل
  `/dev/kvm`، لذا تتصرف الأدوات كما تقول وثائقها، دون مفاجأة من
  مرشّح syscall.
- **صلاحية root في الضيف.** ثبّت حزم النظام، حرّر `/etc`، حمّل وحدة،
  اربط منفذًا ذا امتياز. إنه صندوق الوكيل لإعادة تهيئته.
- **دورة حياة قابلة للتخلص منها.** رخيصة الكسر وسريعة إعادة الإنشاء؛ آلة
  افتراضية محطّمة تبعد أمرًا واحدًا `clawk destroy && clawk`، مع بقاء مستودعك
  ومحادثاتك دون مساس على المضيف.
- **فصل أقوى عن المضيف.** يستند العزل إلى حدود الـ hypervisor
  بدلًا من إتقان سياسة صندوق رمل للعمليات بدقة.

هذا المزيج يشغّل أحمال عمل تميل صناديق رمل العمليات المقيّدة إلى معارضتك فيها:

- تثبيت الحزم والاعتماديات الأصلية؛
- تشغيل خدمات خلفية (قواعد بيانات، طوابير، خوادم تطوير)؛
- تنفيذ عمليات بناء واختبارات غير موثوقة بالسرعة الكاملة؛
- استخدام أدوات Linux على مستوى النظام التي تتوقع آلة حقيقية؛
- ومع نواة ضيف ممكّنة بـ KVM على عتاد مدعوم، سير عمل تطوير الحاويات و
  Kubernetes مثل تشغيل Docker أو Kind *داخل* صندوق الرمل. هذا اختياري
  ومشروط بالعتاد؛ راجع [Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override)
  للمتطلبات الدقيقة.

لا شيء من هذا هو *المنتج*؛ clawk مخصص لعمل الوكلاء المحلي عمومًا.
Docker وKubernetes مجرد أوضح مثال على "يحتاج آلة حقيقية،
لا عملية داخل صندوق رمل."

## التثبيت

يتطلب macOS 14+ على Apple silicon. (Linux مدعوم عبر firecracker وهو
تجريبي حاليًا — ابدأ بـ
**[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**، الذي يغطي الإعداد
وسير العمل والثغرات. هذا README يركّز على macOS أولًا.)

```sh
brew install clawkwork/tap/clawk
```

**من المصدر** (المساهمون، أو إذا كنت لا تستخدم Homebrew)، يتطلب Go 1.26+:

```sh
git clone https://github.com/clawkwork/clawk && cd clawk
make install
```

في كلتا الحالتين لا توجد أدوات إضافية مطلوبة على المضيف: لا Docker، ولا qemu، ولا sudo. الـ hypervisor هو Virtualization.framework من Apple، مرتبط داخل الملف التنفيذي، والملفات التنفيذية للإصدارات تحمل الوكيل داخل الضيف (in-guest agent) مبنيًا مسبقًا — لذا لا تحتاج إلى سلسلة أدوات Go إلا إذا بنيت من المصدر، وفي هذه الحالة ستكون لديك بالفعل. عند التشغيل الأول يتم فحص أي شيء مفقود وعرض إصلاحه.

**إلغاء التثبيت:** نفّذ `clawk destroy` على صناديقك الرملية (sandboxes)، ثم `rm -rf ~/.clawk`، ثم أزل الملف التنفيذي باستخدام `brew uninstall clawk` (أو احذفه من `$GOBIN` إذا كان التثبيت من المصدر). لم يتم تثبيت أي شيء آخر: لا توجد مهام launchd؛ فخدمات daemon الخاصة بكل صندوق رملي هي عمليات عادية تنتهي مع أجهزتها الافتراضية.

## البدء السريع

الحالة اليومية، صندوق رملي للدليل الذي أنت فيه:

```sh
cd ~/code/my-project
clawk                      # boot a sandbox for this dir + attach claude
clawk run shell            # drop into a shell in the same sandbox
clawk run codex            # or another agent: codex, pi, opencode, shell
clawk down                 # stop the VM (repo + agent state persist)
clawk attach               # come back later — boots if stopped, reattaches claude
clawk destroy              # remove the VM (conversation history is kept)
```

خيارات شائعة:

```sh
clawk run claude -- --resume            # pass args through to the agent
clawk forward add my-project 3000       # expose a guest dev server on localhost:3000
clawk network allow my-project api.example.com
```

هل تعمل على تذكرة تمتد عبر عدة مستودعات؟ أمر واحد ينشئ
بيئة معزولة (sandbox) مع git worktree لكل مستودع على فرع جديد، ولاحقًا يفتح `clawk pr`
طلبات سحب (PRs) مترابطة لكل ما تغيّر:

```sh
cd ~/code/my-workspace     # contains a clawk.mod listing the repos
clawk work INFRA-123       # one sandbox, a worktree per repo, claude attached
clawk pr INFRA-123         # push branches + open one PR per repo
```

دورة حياة التذكرة الكاملة (الحالة، وفروع المتابعة بعد عمليات الدمج وإعادة الأساس) موجودة في **[docs/ticket-mode.md](https://github.com/clawkwork/clawk/blob/main/docs/ticket-mode.md)**.

> **نصيحة:** هل تستخدم Claude Code؟ شغّل `claude setup-token` ثم
> `clawk auth set-token` مرة واحدة، وستُفتح كل بيئة معزولة (sandbox) وهي مسجّلة الدخول مسبقًا،
> دون `/login` ودون تعارضات تسجيل الدخول بين البيئات المعزولة المتوازية. راجع
> **[docs/claude-auth.md](https://github.com/clawkwork/clawk/blob/main/docs/claude-auth.md)**.

## ما الذي يبقى بعد ماذا

تحكم قاعدة واحدة الاستمرارية: *الجهاز الافتراضي قابل للتخلص منه؛ وكل ما ستفتقده
يعيش على المضيف.*

| | `clawk down` | `clawk destroy` |
| --- | :---: | :---: |
| مستودعك (worktree مُثبّت؛ الـ commits، الفروع) | ✅ | ✅ |
| حالة الوكيل (محادثات Claude/Codex/pi/opencode، الذاكرة) | ✅ | ✅ |
| قرص الجهاز الافتراضي (تثبيتات apt، ذاكرات التخزين المؤقت، `$HOME`) | ❌ (يُعاد بناؤه من جديد عند كل إقلاع*) | ❌ (هذا هو المقصود) |

\* استثناءان: استئناف `clawk snapshot` يستعيد القرص والذاكرة
تمامًا كما كانتا معلّقتين، ومزوّد Linux/firecracker يحتفظ
بقرصه حتى تنفيذ destroy. الأدوات التي يحتاجها كل إقلاع يجب أن تكون في الصورة
(`vm ( image … )`)؛ أما الإعداد الخاص بكل إقلاع فيجب أن يكون في خطافات `on up`.

حالة الوكيل مُثبّتة من المضيف لكل بيئة معزولة: دليل home الخاص بكل مشغّل —
`~/.claude/` الخاص بـ claude، و`~/.codex/` الخاص بـ codex، و`~/.pi/` الخاص بـ pi، ودليلا XDG الخاصان بـ opencode —
تقع تحت
`~/.clawk/namespaces/default/state/<name>/` على المضيف، لذا تلتقط البيئة المعزولة المُعاد إنشاؤها
محادثاتها القديمة باستخدام `--resume`. هذا التثبيت هو ما يجعل الوعد حقيقيًا: إذ يُعاد استنساخ قرص الجهاز الافتراضي نفسه من الصورة عند
كل إقلاع، لذا فإن أي شيء يكتبه مشغّل خارج تلك الأدلة يزول
عند تنفيذ `clawk up` التالي.

## استقلالية كاملة افتراضيًا (وخيار الانسحاب `--safe`)

تُطلق المشغّلات في أوضاعها "المعزولة خارجيًا": يحصل claude على
`--dangerously-skip-permissions`، ويحصل codex على
`--dangerously-bypass-approvals-and-sandbox`، ويحصل pi على `--approve` (فليس لديه
مطالبات موافقة لتجاوزها — فهو لا يشحن أي بيئة معزولة على الإطلاق — لكنه يقيّد
إعدادات `.pi/` المحلية للمشروع والإضافات خلف مطالبة ثقة)، ويحصل
opencode على `--auto`. على جهازك الخاص ستكون هذه الأعلام
متهورة؛ أما هنا فهي المقصود: فحدود الجهاز الافتراضي وقائمة السماح الشبكية
توفّران الاحتواء، لذا يعمل الوكيل بأقصى سرعة دون
مطالبات لكل إجراء. لا يمكن للوكيل التأثير إلا على ما ثبّتته و
أضفته إلى قائمة السماح، ولا شيء أكثر (راجع [SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md)).

هل تفضّل مطالبات التأكيد على أي حال؟ أضف `--safe` إلى أي attach
(`clawk --safe`، `clawk run claude --safe`) ليبدأ المشغّل دون
أعلام التجاوز لتلك الجلسة.

## الشبكات

حركة المرور الصادرة مرفوضة افتراضيًا؛ ولكل بيئة معزولة قائمة السماح الخاصة بها.
يحل DNS كل شيء؛ أما TCP وUDP (بما في ذلك QUIC) وICMP echo إلى مضيفات غير مدرجة
فترفض. السجلات الشائعة (npm، PyPI، crates.io، GitHub،
Anthropic، …) مسموح بها مسبقًا، والمرشّح واعٍ بـ DNS، لذا يظل السماح لـ
`example.com` يعمل مع تغيّر عناوين IP الخاصة به.

```sh
clawk network allow my-project api.stripe.com '*.internal.mycorp.com' 10.0.0.5
clawk network denials my-project     # what the agent tried that got blocked
clawk forward add my-project 3000    # localhost:3000 → the guest's dev server
clawk forward add-reverse my-project 63342   # and the other way: a service on YOUR
                                             # localhost, reachable inside the guest
```

تُسجَّل عمليات الرفض باسم *اسم المضيف الذي حلّه الضيف*، لذا تُقرأ `clawk network
denials` كسجل لما حاول الوكيل الوصول إليه. توجد السياسات المسماة القابلة لإعادة الاستخدام (بما في ذلك الاشتراك في قوائم الحظر الخارجية مثل oisd) وسلسلة
`use` التي تُرتّبها في
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**.

## التهيئة: `clawk.mod`

لا يلزم وجود ملف تهيئة؛ فالقيم الافتراضية مناسبة. وعندما يحتاج المشروع إلى
المزيد، يصفه ملف `clawk.mod`، بصياغة على نمط go.mod:

```text
sandbox my-project (
    vm (
        cpu    4
        memory 8GiB
        image  golang:1.25          # any OCI image is the rootfs
    )
    network ( allow api.example.com )
    forwards ( 3000 )
    env ( DATABASE_URL )            # forward a host var; values come from your shell
    # also: GH=${OTHER_NAME}, LOG=${LOG:-info} defaults, API=${API:?required}
    mcp (                           # MCP servers, ready on first boot
        linear https://mcp.linear.app/mcp header "Authorization: Bearer ${LINEAR_TOKEN}"
    )
    on create ( "go mod download" )
    agent (
        instructions "Ask before running destructive commands."
    )
)
```

هذه الكتلة عبارة عن *قالب*: تُلتقط عند إنشاء الصندوق الرملي، لذا لا يتغيّر صندوق رملي قيد التشغيل بشكل غير متوقع. المرجع الكامل (المشاركات، وملفات الأسرار، والمهارات، وتهيئة ذاكرة الوكيل، وجذور مساحات العمل متعددة المستودعات) موجود في **[docs/configuration.md](https://github.com/clawkwork/clawk/blob/main/docs/configuration.md)**؛ وخوادم MCP وكيفية إبقاء بيانات اعتمادها بعيدًا عن القرص موجودة في **[docs/mcp.md](https://github.com/clawkwork/clawk/blob/main/docs/mcp.md)**؛ وإدخال لوحة USB-serial من جهاز Mac الخاص بك إلى الصندوق الرملي للعمل على المتحكمات الدقيقة موجود في **[docs/serial.md](https://github.com/clawkwork/clawk/blob/main/docs/serial.md)**؛ والصور ونوى الضيف المخصصة (بما في ذلك النواة المفعّلة بـ KVM المستخدمة للافتراضية المتداخلة) موجودة في **[docs/images.md](https://github.com/clawkwork/clawk/blob/main/docs/images.md)**.

## دورة الحياة

```sh
clawk list                  # all sandboxes
clawk status [<name>]       # state, forwards, blocked hosts; --json for scripts
clawk up / down             # boot / stop
clawk pause / resume        # suspend / resume the running VM in memory
clawk snapshot              # save to disk: RAM freed, guest intact; resume restores it
clawk destroy               # remove the VM; host-side state persists
```

`clawk snapshot` هو سبات للصناديق الرملية: تُحفظ ذاكرة الضيف
بجانب قرصه، ويستعيد الإقلاع التالي الضيف تمامًا حيث كان.
تستمر العمليات الخلفية وخوادم التطوير كما لو لم يحدث شيء،
و`clawk attach` يعيدك إلى أمام الوكيل. سطح الأوامر الكامل،
وتوزيع المشغّل، وآلية إدارة الخمول (ballooning،
التحكم في القبول، الإيقاف التلقائي) موجودة في **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**.

## كيف يعمل

```text
you ──▶ clawk CLI ──▶ per-sandbox daemon (detached; owns the VM)
                        ├─ gvproxy: in-process userspace TCP/IP stack —
                        │  the DNS-aware outbound filter the guest can't reconfigure
                        ├─ vsock bridge to the in-guest pty-agent (no sshd)
                        ├─ ssh-agent proxy, macOS (signing stays on the host)
                        └─ VM: Virtualization.framework (macOS) / firecracker (Linux)
                             ├─ clawk-init, PID 1 (no systemd, no cloud-init)
                             ├─ your repo, live-mounted over virtio-fs
                             └─ claude / codex / pi / shell on a PTY
```

بعض الخيارات المتعمدة، باختصار:

- **نظام ملفات الجذر (rootfs) هو صورة OCI عادية.** يقوم clawk بسحبها (بدون Docker daemon)،
  ويسطّح الطبقات، ويكتب قرص ext4 مباشرةً، دون صلاحيات جذر ودون
  أجهزة loop. كل صندوق رمل من الصورة نفسها هو نسخة استنساخ عند الكتابة
  (APFS `clonefile` / `FICLONE`)، لذا فإن تكلفة القرص لكل صندوق رمل هي ما يكتبه
  الضيف.
- **تُصفّى الشبكة أسفل الضيف.** الطبقة الثالثة (L3) بالكامل للجهاز الافتراضي (البوابة،
  DHCP، DNS، NAT) هي مكدّس في مساحة المستخدم داخل عملية الخدمة (daemon). كل
  اتصال صادر وكل إجابة DNS يستشيران قائمة السماح هناك، حيث
  لا يستطيع حتى الجذر داخل الضيف تغييرها. لا iptables على المضيف، ولا sudo.
- **مدخل واحد فقط.** لا sshd، ولا cloud-init: وكيل vsock واحد هو مسار
  التحكم الوحيد إلى الضيف، وكل اتصال بأسلوب container-exec: عملية
  جديدة، تُنهى عند قطع الاتصال.

الصورة الكاملة (مكدّس الضيف، والمزوّدان، والشبكات على مستوى الإطار)
موجودة في **[ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md)**، والمنطق
وراء كل قرار في **[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md)**.

## مقارنةً بـ

- **الحاويات وdevcontainers.** تتشارك نواتك (kernel) وترى نظام
  ملفاتك ناقصًا قواعد الرفض؛ خلل واحد في النواة أو تركيب خاطئ يمكن أن
  يكشف المضيف. غالبًا ما تقوم إعدادات devcontainer بربط مقبس Docker الخاص بالمضيف
  لبناء الصور، مما يمنح الحاوية التحكم في خدمة المضيف؛
  بينما يُبقي clawk Docker *داخل* الجهاز الافتراضي بدلًا من ذلك. ولا يوجد
  `Dockerfile`/`devcontainer.json` لكتابته: أي صورة OCI هي نظام ملفات الجذر.
- **صناديق رمل الوكلاء على مستوى نظام التشغيل.** أدوات مثل sandbox-runtime من Anthropic تطبّق
  حواجز حماية على مستوى العملية على جهازك الحقيقي: رائعة للقواعد
  الخفيفة، لكن خطأ سياسة واحد يكشف كل شيء (بما في ذلك سلسلة المفاتيح)، و
  عمليات التثبيت، أو الخدمات الخلفية، أو برنامج مراقبة افتراضية متداخل يصعب السماح بها
  بأمان. ينقل clawk عبء العمل بالكامل إلى جهاز مختلف.
- **مديرو الأجهزة الافتراضية للأغراض العامة (مثل Lima).** يمنحك Lima جهازًا افتراضيًا Linux؛
  بينما clawk هو *سير عمل* فوقه: جهاز افتراضي لكل مشروع مع تركيب المستودع،
  ووكيل متصل ومُصادَق، وخروج مسموح به افتراضيًا مع تسجيل حالات الرفض،
  ومحادثات الوكيل محفوظة عبر عمليات الإتلاف،
  ووضع تذاكر يدير worktrees وطلبات السحب (PRs). (تحت الغطاء يستخدم كلاهما
  Virtualization.framework.)
- **صناديق الرمل السحابية.** محلية أولًا: لا يغادر كودك الجهاز أبدًا،
  ولا يُحتسب شيء بالساعة، وworktree التي يعدّلها الوكيل هي نفسها
  الموجودة في محرّرك، ومركّبة حيًّا على macOS (مزوّد Linux حاليًا يدمجها
  عند الإنشاء؛ انظر [خارطة الطريق](#roadmap)). تناسب صناديق الرمل السحابية الأساطيل؛
  بينما clawk مخصّص للجهاز على مكتبك.

## نموذج الأمان (وحدوده)

حدّان يقومان بالعمل: الجهاز الافتراضي (نظام ملفات المضيف غير مرئي إلا
لما تركّبه) وقائمة السماح الصادرة (المفروضة في مساحة المستخدم أسفل
الضيف، لكل بروتوكول يمكنه مغادرته). ما **لا** يحمي منه clawk:

- **كل ما تركّبه أو تسمح به مكشوف.** الـ worktrees قابلة للكتابة، لذا يمكن
  للوكيل إيداع كود سيئ أو الدفع إلى أي مستودع يمكن لـ ssh-agent المُمرَّر الوصول إليه. راجع ما يخرج
  من صندوق الرمل كما تراجع طلب سحب (PR) من شخص غريب.
- **الأسرار التي تدفعها بها مرئية.** محتويات `files ( … )` و`shares ( … )`،
  ومتغيرات البيئة المُمرَّرة، ورمز Claude متاحة للوكيل ليقرأها
  (وإن كانت وجهة ما مسموحًا بها، لإرسالها إليها). شارك الحد الأدنى.
- **الهروب من برنامج المراقبة الافتراضية.** يعتمد clawk على عزل
  Virtualization.framework/KVM؛ ولا يضيف دفاعات تتجاوزها.

إذا وجدت طريقة لكسر حدّ ما (الهروب من الضيف إلى المضيف، تجاوز
تصفية الشبكة، تسريب بيانات الاعتماد)، فيرجى الإبلاغ عنه بشكل خاص عبر
[SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md).

## الأسئلة الشائعة

**ما مقدار الحمل الإضافي؟**
يدفع الإقلاع الأول من صورة بناءً لمرة واحدة لنظام ملفات الجذر (سحب → تسطيح →
ext4). بعد ذلك، تكون الأقراص نسخًا استنساخية عند الكتابة وتُقلع النواة مباشرةً،
دون برنامج ثابت (firmware) ودون مثبّت. تُحرّر الأجهزة الافتراضية الخاملة الذاكرة حتى ~1 GiB، وتتوقف
تلقائيًا بعد 30 دقيقة خمول، ويمكن أخذ لقطة لها إلى القرص بحيث لا تكلّف سوى
التخزين.

**هل يعمل على أجهزة Intel Mac؟ Windows؟**
لا. يتطلب macOS شريحة Apple silicon (macOS 14+). على Linux، يعمل مزوّد firecracker
لكنه تجريبي (انظر
[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md#vm-providers)). لا يوجد دعم لـ Windows.

**هل أحتاج إلى تثبيت Docker؟**
لا. يقوم clawk بسحب صور OCI وبناء أقراص قابلة للإقلاع بنفسه. *صور* Docker
هي صيغة الإدخال؛ محرك Docker ليس طرفًا في ذلك. (تشغيل خادم Docker
*داخل* بيئة معزولة هو ميزة منفصلة اختيارية؛ انظر
[Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) لمتطلبات العتاد والنواة.)

**لماذا "clawk"؟**
الشعار هو مخلب؛ و*clawkwork* تلاعب لفظي على *A Clockwork Orange*. آلة افتراضية
تشغّلها، وتطلقها، ويمكنك دائمًا إعادة ضبطها.

## خارطة الطريق

التالي: تشغيل عدد أكبر من البيئات المعزولة مما يمكن لذاكرتك استيعابه في وقت واحد.

- **إيقاف الخمول مع أخذ لقطة.** تم إصدار التعليق اليدوي إلى القرص باسم
  `clawk snapshot` / `clawk resume`؛ وبعد ذلك، سيستخدم إيقاف الخمول *التلقائي* ذلك أيضًا،
  حتى تنجو خوادم التطوير من الإيقاف، ولا تكلّف البيئة المعزولة المعلّقة سوى
  مساحة القرص.
- **حد أقصى للأجهزة الافتراضية العاملة.** بدلًا من رفض جهاز افتراضي جديد عند استنفاد الذاكرة،
  علّق البيئة المعزولة الأقل استخدامًا مؤخرًا إلى القرص وابدأ
  الجديدة.
- **تكافؤ Firecracker.** نشر شجرة العمل الحية ودفع ملفات المضيف على
  Linux.

## الحالة

ما قبل الإصدار 1.0 وقيد التطوير النشط، ويتطور بسرعة: توقّع تغييرات
كاسرة بين الإصدارات. واجهة سطر الأوامر تتغير أقل من غيرها والبنى الداخلية أكثر من غيرها،
لكن لا شيء مجمّد حتى الإصدار 1.0.

## المساهمة

المشكلات وطلبات السحب مرحّب بها. انظر [CONTRIBUTING.md](https://github.com/clawkwork/clawk/blob/main/CONTRIBUTING.md) للبناء
والاختبار، و[ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md) لكيفية بنائه، و
[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md) إلى أين يتجه.

## الترخيص

[Apache License 2.0](https://github.com/clawkwork/clawk/blob/main/LICENSE). يضمّن clawk مكوّنين من طرفين خارجيين بموجب
تراخيصهما الخاصة (gvisor-tap-vsock، Apache-2.0؛ كاتب ext4 من hcsshim، MIT)؛
انظر [NOTICE](https://github.com/clawkwork/clawk/blob/main/NOTICE).