{"title":"Computer Control API","slug":"computers","category":"api","summary":"تحكم بعيد بالأجهزة المسجّلة — إدراج الأوامر في الطابور، التقاط لقطات الشاشة، تشغيل سكربتات على الأجهزة البعيدة.","audience":["human","llm"],"tags":["api","computers","remote-control","automation"],"difficulty":"advanced","updated":"2026-06-27","word_count":318,"read_minutes":2,"llm_context":"Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)\nRegister agent: POST /computers/register { install_code } → returns computer_token\nList: GET /computers/list (Mind Key or JWT)\nQueue command: POST /computers/:id/commands { type, payload }\nCommand types: screenshot, click, move, type, key, scroll, drag\nAgent poll: GET /computers/me/poll?wait=5 (Computer Token)\nAgent result: POST /computers/me/commands/:cid/result (Computer Token)\nOne-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)\nPattern: register agent on remote machine → user queues commands → agent polls and executes\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# Computer Control API\n\nتتيح لك Computer Control API التحكم عن بُعد بالأجهزة المسجّلة. يعمل وكيل\nصغير (`screen-remote-agent`) على الجهاز الهدف، يستطلع للأوامر، ينفّذها،\nويُعيد نشر النتائج. هذا يُمكّن أتمتة الواجهة الرسومية المدفوعة بنماذج LLM.\n\n## البنية\n\n```\n┌─────────────┐ queue cmd ┌──────────┐ poll ┌─────────────────┐\n│ LLM Agent │ ───────────▶ │ Synapse │ ◀───── │ screen-remote │\n│ (user-side) │ │ Server │ ──────▶│ (on target PC) │\n└─────────────┘ └──────────┘ result └─────────────────┘\n ▲\n │\n ┌─────────────┐\n │ Human UI │\n │ (browser) │\n └─────────────┘\n```\n\n## نقاط نهاية المستخدم (Mind Key أو JWT)\n\n### GET /computers/list\n\nقائمة بجميع الأجهزة المسجّلة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/list\n```\n\n### GET /computers/:id\n\nالحصول على تفاصيل جهاز واحد.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001\n```\n\n### POST /computers/install-code\n\nتوليد رمز تثبيت لتسجيل جهاز جديد.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/install-code \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"computer_name\": \"office-mac\"}'\n```\n\nالاستجابة: `{ \"install_code\": \"ic_xyz789\", \"expires_at\": \"...\" }`\n\n### POST /computers/:id/commands\n\nإدراج أمر في الطابور لينفّذه الوكيل البعيد.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"screenshot\",\n \"payload\": {}\n }'\n```\n\nالاستجابة: `{ \"command_id\": \"cmd_001\", \"status\": \"queued\" }`\n\n### GET /computers/:id/command (عبر الاستعلام)\n\nإدراج أمر عبر GET (للحالات البسيطة).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot\"\n```\n\n### GET /computers/:id/commands\n\nقائمة الأوامر الأخيرة لجهاز.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/computers/comp_001/commands?limit=50\"\n```\n\n### GET /computers/:id/commands/:cid\n\nالحصول على الحالة + النتيجة لأمر محدد.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001\n```\n\n### GET /computers/:id/screenshot\n\nأحادي الخطوة: إدراج أمر لقطة شاشة والانتظار حتى 30 ثانية للنتيجة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png\n```\n\n### POST /computers/:id/disable\n\nتعطيل جهاز (يُبطل رمزه، ويُبقي السجل للتدقيق).\n\n```bash\ncurl -X POST -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001/disable\n```\n\n### DELETE /computers/:id\n\nحذف جهاز نهائيًا.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001\n```\n\n## نقاط نهاية الوكيل (Computer Token)\n\nتُستخدم هذه النقاط من قبل `screen-remote-agent` الذي يعمل على الجهاز الهدف.\nتستخدم Computer Token (يُرجعها `/computers/register`)، وليس Mind Key.\n\n### POST /computers/register\n\nاسترداد رمز تثبيت والحصول على Computer Token.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"code\": \"ic_xyz789\",\n \"computer_name\": \"office-mac\",\n \"platform\": \"darwin\",\n \"platform_release\": \"14.5.0\",\n \"python\": \"3.12.4\"\n }'\n```\n\nالاستجابة: `{ \"computer_id\": \"comp_001\", \"computer_token\": \"ct_...\" }`\n\n> [!CRITICAL]\n> احفظ `computer_token` — يُعرض مرة واحدة فقط ومطلوب لجميع نقاط نهاية\n> الوكيل.\n\n### GET /computers/me/poll\n\nاستطلاع طويل للأوامر الجديدة. يستدعي الوكيل هذا في حلقة.\n\n```bash\ncurl -H \"Authorization: Bearer ct_YOUR_COMPUTER_TOKEN\" \\\n \"https://synapse.schaefer.zone/computers/me/poll?wait=30\"\n```\n\nيُرجع فورًا إذا كانت هناك أوامر معلّقة، أو بعد `wait` ثانية إن لم تكن.\n\n### POST /computers/me/commands/:cid/result\n\nنشر نتيجة تنفيذ أمر.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \\\n -H \"Authorization: Bearer ct_YOUR_COMPUTER_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"status\": \"done\",\n \"result\": { \"screenshot_b64\": \"iVBORw0KG...\" }\n }'\n```\n\n## أنواع الأوامر\n\n| النوع | الحمولة | الوصف |\n|------|---------|-------------|\n| `screenshot` | `{}` | التقاط الشاشة كـ PNG (base64) |\n| `click` | `{x, y}` | النقر عند الإحداثيات |\n| `move` | `{x, y}` | تحريك الماوس إلى الإحداثيات |\n| `type` | `{text}` | كتابة نص عند المؤشر |\n| `key` | `{keys: [\"Ctrl\",\"c\"]}` | ضغط مجموعة مفاتيح |\n| `scroll` | `{deltaX, deltaY}` | تمرير العجلة |\n| `drag` | `{fromX, fromY, toX, toY}` | سحب وإفلات |\n\n## النمط الشائع: أتمتة الواجهة الرسومية المدفوعة بـ LLM\n\n```python\n# سير عمل وكيل LLM\n1. List computers: GET /computers/list\n2. Take screenshot: GET /computers/:id/screenshot\n3. Analyze screenshot (vision model)\n4. Queue click: POST /computers/:id/commands {type:\"click\", payload:{x,y}}\n5. Wait for result: GET /computers/:id/commands/:cid\n6. Take new screenshot to verify\n7. Repeat until task done\n```\n\n## الخطوات التالية\n\n- [وكيل المتصفح](/docs/api/browser) — خدمة منفصلة لأتمتة المتصفح\n- [دليل الوكلاء المستضافين ذاتيًا](/docs/guides/self-hosted-agents)\n","content_html":"

Computer Control API

\n

تتيح لك Computer Control API التحكم عن بُعد بالأجهزة المسجّلة. يعمل وكيل\nصغير (screen-remote-agent) على الجهاز الهدف، يستطلع للأوامر، ينفّذها،\nويُعيد نشر النتائج. هذا يُمكّن أتمتة الواجهة الرسومية المدفوعة بنماذج LLM.

\n

البنية

\n

┌─────────────┐  queue cmd   ┌──────────┐  poll   ┌─────────────────┐\n│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │\n│ (user-side) │              │  Server  │ ──────▶│ (on target PC)  │\n└─────────────┘              └──────────┘ result  └─────────────────┘\n                                     ▲\n                                     │\n                              ┌─────────────┐\n                              │  Human UI   │\n                              │ (browser)   │\n                              └─────────────┘

نقاط نهاية المستخدم (Mind Key أو JWT)

\n

GET /computers/list

\n

قائمة بجميع الأجهزة المسجّلة.

\n

curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/list

GET /computers/:id

\n

الحصول على تفاصيل جهاز واحد.

\n

curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001

POST /computers/install-code

\n

توليد رمز تثبيت لتسجيل جهاز جديد.

\n

curl -X POST https://synapse.schaefer.zone/computers/install-code \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"computer_name": "office-mac"}'

الاستجابة: { "install_code": "ic_xyz789", "expires_at": "..." }

\n

POST /computers/:id/commands

\n

إدراج أمر في الطابور لينفّذه الوكيل البعيد.

\n

curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "type": "screenshot",\n    "payload": {}\n  }'

الاستجابة: { "command_id": "cmd_001", "status": "queued" }

\n

GET /computers/:id/command (عبر الاستعلام)

\n

إدراج أمر عبر GET (للحالات البسيطة).

\n

curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"

GET /computers/:id/commands

\n

قائمة الأوامر الأخيرة لجهاز.

\n

curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"

GET /computers/:id/commands/:cid

\n

الحصول على الحالة + النتيجة لأمر محدد.

\n

curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001

GET /computers/:id/screenshot

\n

أحادي الخطوة: إدراج أمر لقطة شاشة والانتظار حتى 30 ثانية للنتيجة.

\n

curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png

POST /computers/:id/disable

\n

تعطيل جهاز (يُبطل رمزه، ويُبقي السجل للتدقيق).

\n

curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001/disable

DELETE /computers/:id

\n

حذف جهاز نهائيًا.

\n

curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001

نقاط نهاية الوكيل (Computer Token)

\n

تُستخدم هذه النقاط من قبل screen-remote-agent الذي يعمل على الجهاز الهدف.\nتستخدم Computer Token (يُرجعها /computers/register)، وليس Mind Key.

\n

POST /computers/register

\n

استرداد رمز تثبيت والحصول على Computer Token.

\n

curl -X POST https://synapse.schaefer.zone/computers/register \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "code": "ic_xyz789",\n    "computer_name": "office-mac",\n    "platform": "darwin",\n    "platform_release": "14.5.0",\n    "python": "3.12.4"\n  }'

الاستجابة: { "computer_id": "comp_001", "computer_token": "ct_..." }

\n

احفظ `computer_token` — يُعرض مرة واحدة فقط ومطلوب لجميع نقاط نهاية\nالوكيل.

GET /computers/me/poll

\n

استطلاع طويل للأوامر الجديدة. يستدعي الوكيل هذا في حلقة.

\n

curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \\\n     "https://synapse.schaefer.zone/computers/me/poll?wait=30"

يُرجع فورًا إذا كانت هناك أوامر معلّقة، أو بعد wait ثانية إن لم تكن.

\n

POST /computers/me/commands/:cid/result

\n

نشر نتيجة تنفيذ أمر.

\n

curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \\\n  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "status": "done",\n    "result": { "screenshot_b64": "iVBORw0KG..." }\n  }'

أنواع الأوامر

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

النوع	الحمولة	الوصف
`screenshot`	`{}`	التقاط الشاشة كـ PNG (base64)
`click`	`{x, y}`	النقر عند الإحداثيات
`move`	`{x, y}`	تحريك الماوس إلى الإحداثيات
`type`	`{text}`	كتابة نص عند المؤشر
`key`	`{keys: ["Ctrl","c"]}`	ضغط مجموعة مفاتيح
`scroll`	`{deltaX, deltaY}`	تمرير العجلة
`drag`	`{fromX, fromY, toX, toY}`	سحب وإفلات

\n

النمط الشائع: أتمتة الواجهة الرسومية المدفوعة بـ LLM

\n

# سير عمل وكيل LLM\n1. List computers: GET /computers/list\n2. Take screenshot: GET /computers/:id/screenshot\n3. Analyze screenshot (vision model)\n4. Queue click: POST /computers/:id/commands {type:"click", payload:{x,y}}\n5. Wait for result: GET /computers/:id/commands/:cid\n6. Take new screenshot to verify\n7. Repeat until task done

الخطوات التالية

\n

وكيل المتصفح — خدمة منفصلة لأتمتة المتصفح
دليل الوكلاء المستضافين ذاتيًا

\n","urls":{"html":"/docs/api/computers","text":"/docs/api/computers?format=text","json":"/docs/api/computers?format=json","llm":"/docs/api/computers?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}