@boymep/cremote
v0.1.4
Published
Remote control for Claude Code sessions from a phone
Readme
cremote
cremote — веб-приложение (PWA) для телефона, которое управляет Claude Code. Оно показывает сессии на вашем компьютере (CLI и расширение VS Code): можно отвечать на запросы разрешений и вопросы, отправлять сообщения, останавливать запуск и начинать новые сессии. Работает на macOS (launchd) и Linux (systemd --user). Лицензия MIT.
Содержание
- Что это
- Безопасность
- Требования
- Быстрый старт
- Способы доступа с телефона
- Установка из исходников
- Использование с телефона
- Несколько аккаунтов (cswap)
- Обновление
- Конфигурация
- Команды CLI
- Диагностика и частые проблемы
- Удаление
- Разработка и лицензия
Что это
cremote — это маленький сервер на вашем компьютере и веб-приложение для телефона. Сервер читает сессии Claude Code с диска, получает события через хуки и показывает их в браузере. Ответ с телефона сервер отдаёт обратно в Claude Code.
Телефон (PWA)
│ HTTPS
▼
Tailscale / Cloudflare / ваш VPS ← способ доступа (на выбор)
│
▼
cremote server 127.0.0.1:7878 ← на вашем компьютере
│
├── хуки в ~/.claude/settings.json (события Claude Code)
├── чтение ~/.claude/projects (история сессий)
└── Claude Agent SDK (новые сессии с телефона)Подробное техническое описание — в docs/SPEC.md.
Безопасность: прочитайте до установки
Тот, кто вошёл в cremote, может выполнять команды на вашем компьютере через Claude. Он видит ваши проекты, отвечает на запросы разрешений и запускает новые сессии. Относитесь к паролю как к SSH-ключу.
- Задайте длинный пароль. Минимум 8 символов, лучше фраза из 4–5 слов или пароль из менеджера. Не используйте пароль от других сервисов.
- Секрет хуков.
hookSecretв~/.cremote/config.jsonзащищает локальные эндпоинты/hook/*. Файл создаётся с правами 600. Не публикуйте его и не коммитьте. - Что наружу не выходит. Эндпоинты
/hook/*нужны только локальному Claude Code. Шаблон nginx закрывает их (404). Сервер по умолчанию слушает только127.0.0.1. - Файлы. Просмотрщик отдаёт файлы только из разрешённых корней (папка проекта сессии, Загрузки, каталоги из
fileRoots). HTML открывается как предпросмотр в изолированном iframe, файл — отдельным экраном с кнопкой «Назад». Секреты (.env, ключи,~/.sshи подобное) закрыты чёрным списком. - Одобрения. Карточка «Разрешить» на телефоне равна нажатию Enter в терминале. Если Claude Code вызвал инструмент, который классификатор заблокировал, вы можете разрешить его один раз. Читайте, что именно вы разрешаете.
- Самый безопасный способ — Tailscale. Порт не открыт в интернет, сервис доступен только вашим устройствам в tailnet. Cloudflare Tunnel и VPS открывают адрес в интернет: защитой остаётся только пароль.
Требования
- macOS (launchd) или Linux (systemd --user).
- Node.js 20 или новее.
- Claude Code (
claudeвPATH) с выполненным входом:claude→/login. КлючANTHROPIC_API_KEYне нужен. - Для способа доступа: Tailscale, либо cloudflared и аккаунт Cloudflare с доменом, либо свой VPS с доменом.
- Для push-уведомлений на iPhone: iOS 16.4 или новее, HTTPS и установка на экран «Домой».
Быстрый старт
Установите пакет:
npm i -g @boymep/cremoteЗапустите мастер настройки:
cremote setupМастер проверит Node.js и
claude, спросит пароль и способ доступа, установит хуки и сервисы автозапуска. В конце он напечатает адрес. Мастер можно запускать повторно: он покажет текущие значения как значения по умолчанию.Откройте напечатанный адрес на телефоне и войдите с паролем.
Добавьте приложение на экран «Домой»: в Safari «Поделиться» → «На экран “Домой”», в Chrome «Установить приложение». Для push на iPhone этот шаг обязателен.
Перезагрузите окна VS Code (
Developer: Reload Window). Расширение Claude читает хуки при старте.Проверьте установку:
cremote doctor.
Способы доступа с телефона
Способ выбирается в cremote setup и хранится в поле access файла ~/.cremote/config.json. Сменить его можно повторным запуском мастера.
Tailscale (рекомендуется)
Домен и открытые порты не нужны. Адрес вида https://<машина>.<tailnet>.ts.net работает только внутри вашего tailnet и сразу с HTTPS.
- Установите Tailscale на компьютер и на телефон, войдите в один аккаунт.
- В админке Tailscale включите MagicDNS и HTTPS-сертификаты.
- В
cremote setupвыберите пункт 1. Мастер предложит выполнитьtailscale serve --bg http://127.0.0.1:7878. Согласитесь. - Откройте на телефоне адрес
https://<машина>.<tailnet>.ts.net, который напечатает мастер.
Телефон должен быть в сети Tailscale (приложение включено).
Cloudflare Tunnel
Подходит, если у вас есть домен в Cloudflare и вы хотите доступ без VPN.
- Установите
cloudflared(brew install cloudflaredна macOS). - В Cloudflare Zero Trust откройте Networks → Tunnels → Create a tunnel → Cloudflared.
- Скопируйте токен туннеля.
- На вкладке Public Hostname добавьте адрес, например
cremote.example.com, с сервисомhttp://localhost:7878. - В
cremote setupвыберите пункт 2, вставьте токен и публичный адрес.
Токен хранится в ~/.cremote/config.json (права 600) и в файле сервиса с правами 600. В логи он не попадает. Мастер установит сервис cloudflared tunnel run.
Свой VPS: SSH-туннель + nginx
Схема: компьютер держит обратный SSH-туннель до VPS. nginx на VPS отдаёт статику и проксирует /api и /ws в туннель. Плюс схемы: страница открывается, даже когда компьютер спит.
Домен. Создайте A-запись (и AAAA, если есть IPv6)
cremote.example.com→ IP вашего VPS. Дождитесь, пока DNS обновится.SSH-ключ. Создайте ключ без пароля для туннеля и положите его на VPS:
ssh-keygen -t ed25519 -f ~/.ssh/cremote_tunnel -N "" ssh-copy-id -i ~/.ssh/cremote_tunnel.pub [email protected] ssh -i ~/.ssh/cremote_tunnel [email protected] trueПоследняя команда должна выполниться без вопросов. Иначе сервис туннеля не подключится.
nginx и certbot на VPS (Debian/Ubuntu):
sudo apt install nginx certbot python3-certbot-nginxКаталог для статики без sudo. Дайте своему пользователю владение каталогом, чтобы выкладывать файлы без sudo:
sudo mkdir -p /var/www/cremote sudo chown user:user /var/www/cremoteКонфиг nginx. Скопируйте deploy/nginx-cremote.conf на VPS в
/etc/nginx/sites-available/cremote, заменитеexample.comна ваш домен. Порт3010вproxy_passдолжен совпадать сaccess.ssh.remotePort. Затем:sudo ln -s /etc/nginx/sites-available/cremote /etc/nginx/sites-enabled/cremote sudo certbot --nginx -d cremote.example.com sudo nginx -t && sudo systemctl reload nginxВ шаблоне блоки
listen 443 sslи пути к сертификатам помечены как управляемые certbot. Если certbot не выпустил сертификат, сначала оставьте только блокlisten 80, выпустите сертификат, затем верните полный конфиг.Статика на VPS. С вашего компьютера, из репозитория (нужны исходники, см. следующий раздел):
[email protected]:/var/www/cremote/ npm run deploy:webКоманда собирает
web/distи выкладывает его черезrsync. Без переменнойCREMOTE_DEPLOYскрипт остановится с ошибкой. Если вы ставили cremote черезnpm i -g, соберите статику из клона репозитория той же версии.cremote setup. Выберите пункт 3. Укажите
[email protected], порт на VPS (по умолчанию 3010), файл ключа~/.ssh/cremote_tunnelи публичный адресhttps://cremote.example.com. Мастер проверит вход по SSH и установит сервис туннеля:ssh -N -R 127.0.0.1:3010:127.0.0.1:7878 -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes -i <ключ> [email protected]
Статику на VPS выкладывать необязательно. Сервер cremote сам отдаёт web/dist. Но тогда страница не откроется, пока компьютер спит.
Только локально
В cremote setup выберите пункт 4. cremote слушает 127.0.0.1:7878 и открывается на этом же компьютере: http://127.0.0.1:7878. С телефона доступа нет. Подходит для проверки установки.
Установка из исходников
git clone https://github.com/boymep/cremote.git
cd cremote
npm ci
npm --prefix web ci
npm run build
./bin/cremote setupДальше всё как в быстром старте. Чтобы команда cremote была в PATH, выполните npm link в корне репозитория.
Использование с телефона
- Список сессий. Видны сессии из вкладок VS Code и из терминала (CLI), а также сессии, запущенные из cremote.
- Чат. История сообщений и ответов Claude, ответ обновляется по мере работы.
- Отправка текста и картинок. Прикрепляйте фото из галереи или камеры.
- Карточки разрешений. Когда Claude просит разрешение на инструмент, на телефоне появляется карточка. Вызовы, которые заблокировал классификатор (событие
PermissionDenied), тоже показываются, с кнопкой «Разрешить» на один раз. - Вопросы. Если Claude задаёт вопрос с вариантами, выберите ответ на телефоне.
- Кнопка «Стоп». Останавливает текущий запуск.
- Новые сессии. Запускаются через Claude Agent SDK в выбранной папке.
- Просмотр файлов. Пути в сообщениях открываются как файлы. Доступны разрешённые корни и
fileRootsиз конфига, секреты закрыты чёрным списком. - PWA и push. Приложение ставится на экран «Домой» и присылает уведомления (Web Push), когда нужен ваш ответ. На iPhone push работает только после установки на экран «Домой», на iOS 16.4+ и по HTTPS.
Несколько аккаунтов (cswap)
Необязательная возможность. cremote умеет переключать аккаунты Claude через сторонний инструмент claude-swap (команда cswap). Он не связан с cremote и Anthropic.
pipx install claude-swap # или: uv tool install claude-swapМастер cremote setup спросит путь к cswap, если команды нет в ~/.local/bin. Путь хранится в поле cswapPath.
Осторожно: условия использования Claude могут ограничивать совместное использование и обход лимитов через несколько аккаунтов. Проверьте условия сами и используйте только свои аккаунты. Вы отвечаете за это сами.
Обновление
cremote update # проверить и установить новую версию
cremote update --check # только проверитьКоманда ставит новую версию пакета глобально, заново ставит хуки (путь к Node мог измениться) и перезапускает сервис. Установка из клона репозитория обновляется командами git pull && npm ci && npm run build.
В интерфейсе при выходе новой версии появляется баннер «Доступна версия X» с кнопкой «Обновить». Версия показана в настройках.
Поведение задаёт поле autoUpdate в конфиге:
| Значение | Что происходит |
| --- | --- |
| notify (по умолчанию) | Только баннер в интерфейсе. Обновляете вы сами. |
| auto | Сервер обновляется сам ночью, с 03:00 до 05:00 по местному времени, когда нет занятых сессий. |
| off | Проверки и баннер выключены. |
Сервер проверяет реестр npm раз в сутки и при старте. Лог обновления: ~/.cremote/logs/update.log.
Конфигурация
Файл ~/.cremote/config.json (права 600). Большинство полей задаёт мастер.
| Поле | По умолчанию | Назначение |
| --- | --- | --- |
| host | 127.0.0.1 | Адрес, на котором слушает сервер. |
| port | 7878 | Порт сервера. |
| passwordHash | — | Хеш пароля. Задаётся cremote passwd. |
| hookSecret | генерируется | Секрет локальных хуков. |
| access.mode | none | tailscale, cloudflare, ssh или none. |
| access.ssh | — | target (user@host), remotePort (по умолчанию 3010), identityFile. |
| access.cloudflare.token | — | Токен Cloudflare Tunnel. |
| access.publicUrl | — | Публичный адрес. Нужен только для подсказок в setup и doctor. |
| tunnel | — | Устаревшее поле, user@host. Читается как access.mode = ssh. |
| vapidSubject | mailto:[email protected] | Контакт для Web Push. Лучше указать свой адрес. |
| autoUpdate | notify | notify, auto или off. |
| cswapPath | ~/.local/bin/cswap | Путь к cswap. |
| phonePresenceMs | 1800000 (30 минут) | Сколько телефон считается «на связи» после закрытия соединения. |
| fileRoots | [] | Дополнительные абсолютные каталоги для просмотрщика файлов. |
Переменные окружения:
| Переменная | Назначение |
| --- | --- |
| CREMOTE_PORT | Порт сервера (приоритетнее конфига). |
| CREMOTE_HOST | Адрес прослушивания (приоритетнее конфига). |
| CREMOTE_HOME | Каталог данных вместо ~/.cremote. |
| CLAUDE_CONFIG_DIR | Каталог конфигурации Claude Code вместо ~/.claude. |
| CREMOTE_CLAUDE_SETTINGS | Путь к settings.json, куда ставятся хуки. |
| CREMOTE_HOOK_DISABLE=1 | Хук ничего не делает. cremote ставит её сам для сессий, которые запускает через SDK. |
| CREMOTE_DEBUG_HOOKS=1 | Подробный лог хуков. |
| CREMOTE_LAUNCH_AGENTS, CREMOTE_SYSTEMD_DIR | Каталоги сервисов вместо стандартных (нужны в основном тестам). |
| CREMOTE_DEPLOY | Назначение rsync для npm run deploy:web, например [email protected]:/var/www/cremote/. |
Данные и логи лежат в ~/.cremote: config.json, state.json, uploads/, logs/.
Команды CLI
| Команда | Что делает |
| --- | --- |
| cremote setup | Мастер настройки: пароль, доступ, хуки, сервисы. |
| cremote start | Запускает сервер в этом терминале. |
| cremote passwd | Задаёт новый пароль. |
| cremote hooks install | Добавляет хуки в ~/.claude/settings.json (с резервной копией). |
| cremote hooks uninstall | Убирает хуки cremote. |
| cremote service install | Ставит автозапуск (launchd или systemd --user). Флаг --no-load только пишет файлы. |
| cremote service uninstall | Удаляет автозапуск. |
| cremote service restart | Перезапускает сервисы. |
| cremote service status | Показывает, какие сервисы работают. |
| cremote update [--check] | Обновляет cremote или только проверяет версию. |
| cremote doctor | Проверяет установку. |
| cremote version | Печатает версию (также --version, -v). |
| cremote help | Справка (также --help, -h). |
Старые команды cremote install и cremote uninstall работают как hooks install и hooks uninstall.
Сервисы: на macOS это dev.cremote.server и dev.cremote.tunnel в ~/Library/LaunchAgents, на Linux — cremote.service и cremote-tunnel.service в ~/.config/systemd/user. Логи: ~/.cremote/logs.
Диагностика и частые проблемы
Начните с cremote doctor. Команда проверяет версию Node, claude, хуки, сервис, ответ сервера на 127.0.0.1 и подсказывает по способу доступа.
| Симптом | Причина и решение |
| --- | --- |
| Телефон не подключается, когда компьютер ушёл в сон | Mac в сне не отвечает. Отключите сон при питании от сети (Системные настройки → Аккумулятор) или используйте VPS со статикой: страница откроется, но данные появятся после пробуждения. |
| После обновления Node всё перестало работать | В сервисах и хуках записан абсолютный путь к Node. Выполните cremote hooks install и cremote service install. |
| Сессии VS Code не появляются, нет карточек | Хуки читаются при старте. Выполните Developer: Reload Window в VS Code. Проверьте cremote doctor. |
| Сессия, начатая с телефона, пропала после перезапуска | Сессии через Agent SDK живут в процессе сервера и умирают при его перезапуске. Историю можно открыть и продолжить заново. Не перезапускайте сервис во время работы. |
| В сообщении Claude видит текст «NOT USER INPUT» | Это служебное сообщение пробуждения (rewake) от cremote, а не ваш ввод. Его можно игнорировать. |
| На Linux сервисы останавливаются после выхода из системы | Выполните loginctl enable-linger $USER. |
| Туннель не поднимается | Проверьте cremote service status и ~/.cremote/logs/tunnel.log. Для SSH проверьте, что ssh -i <ключ> [email protected] true работает без вопросов. |
| На iPhone нет push | Нужны iOS 16.4+, HTTPS и установка на экран «Домой». Откройте приложение с иконки и разрешите уведомления. |
| Порт занят | Смените port в конфиге или CREMOTE_PORT, затем cremote service restart. |
Удаление
cremote service uninstall
cremote hooks uninstall
npm rm -g @boymep/cremote
rm -rf ~/.cremoteЕсли вы использовали Tailscale, выключите публикацию: tailscale serve reset.
Разработка и лицензия
npm ci && npm --prefix web ci
npm run dev # tsc --watch для сервера
npm --prefix web run dev # Vite для интерфейса
npm --prefix web run dev:mock # интерфейс с тестовыми данными
npm --prefix web run check # svelte-check
npm run build # полная сборкаВыпуск версий описан в docs/RELEASING.md.
Лицензия: MIT.
