Companion Remote ru

Удалённое управление и Companion

🌐 English · Русский · 中文

Управляй прокси-клиентом на другом устройстве — обычно это ClashFest на Android TV или SlothClash на headless-боксе — прямо со своего десктопа по локальной сети. Включай/выключай VPN, отправляй подписку, смотри статус, переименовывай. Без аккаунтов, облака и релеев — всё остаётся в твоём Wi-Fi.

Здесь SlothClash — контроллер (пульт); другое устройство работает как агент.

---

Что можно делать

• Находить агентов в LAN по понятному имени (Гостиная, Спальня, …).
• Спаривать безопасно по PIN (у десктопа нет камеры, поэтому используется код, который показывает агент — или вставляешь строку паринга агента).
• Переключать VPN на агенте вкл/выкл.
• Отправлять одну из своих подписок на агента одним действием.
• Видеть статус (запущен / активный профиль / трафик) и переименовывать устройство.
• Отвязывать для мгновенного отзыва доступа.

Настройка

На агенте (например, на телевизоре)

1. Открой его приложение → пункт Удалённое управление.
2. Включи Разрешить удалённое управление. По умолчанию выключено — как включение отладки, ты соглашаешься осознанно.
3. Выбери Показать PIN для паринга — 6-значный код, действителен короткое время. (Также показывается QR и его ip:port.)

На десктопе (контроллер)

1. Открой SlothClash → Companion.
2. Введи PIN агента (или вставь его строку clashctl-pair://…).
3. Спарено! Устройство появляется в списке, и можно сразу отправить активную подписку на него.

Оба устройства должны быть в одной локальной сети. Паринг требует физически видеть экран агента (PIN/QR) — это и есть доказательство присутствия.

Диагностика

• «Недоступен» сразу после паринга — убедись, что оба устройства в одном Wi-Fi (без гостевой изоляции / разных VLAN).
• Ничего не находится — некоторые роутеры блокируют mDNS/multicast; спарь напрямую по PIN или вставленной строке паринга.
• Агент переехал / переустановлен — открой у него экран удалённого управления заново для свежего PIN и спарь снова.

Модель безопасности

Механизм	Зачем
По умолчанию ВЫКЛ — явное согласие на агенте	Никакого тихого сетевого доступа
Паринг по PIN / QR несёт ip:port + токен + отпечаток TLS	Требует физически видеть агента = доказательство присутствия
TLS (самоподписанный, pinned) по отпечатку из паринга	Трафик (включая отправляемые подписки) шифруется; MITM невозможен
Токен на устройство, отзывается отвязкой	Один скомпрометированный контроллер ≠ все; лёгкий отзыв
REST API ядра остаётся привязан к 127.0.0.1	Шлюз — единственная аудируемая точка входа в LAN

---

Для разработчиков — протокол (v1)

Companion — это тонкий безопасный LAN-шлюз перед управлением агента (переключение VPN, импорт подписки).

• Discovery: mDNS-сервис _clashctl._tcp. TXT-ключи: app (clashfest|slothclash), id, name, ver, fp (отпечаток TLS).
• Строка паринга: clashctl-pair://<ip>:<port>?id=<deviceId>&name=<name>&app=<app>&fp=<sha256>&token=<token>
• Транспорт: HTTPS (самоподписанный, pinned). Authorization: Bearer <token> в каждом запросе.
• Эндпоинты (v1):
  • GET /v1/status → { running, activeProfile, uploadTotal, downloadTotal, mode }
  • POST /v1/power { "action": "on" | "off" | "toggle" }
  • POST /v1/subscription { "url", "name" } или { "payload": "<yaml>" }
  • POST /v1/rename { "name" }
  • POST /v1/pair { "pin" } → выдаёт bearer-токен

Общий контракт протокола живёт в репозитории clash-companion, так что ClashFest, SlothClash и любой будущий контроллер говорят на одном протоколе байт-в-байт.