Документация

Arcula — это служба arcula-host на вашем компьютере, которая держит агентов запущенными, и приложения (компьютер, телефон, терминал), которые с ней говорят.

Быстрый старт

Скачайте приложение для компьютера: Windows (x64). При первом запуске оно установит хост как фоновую службу.
Выберите режим — «Документы» или «Разработка» (что меняется).
Создайте бота: имя, папка проекта, агент. Если у вас нет своего агента, выберите Arcula AI — он работает сразу, на бесплатном тарифе.
Установите приложение для Android и отсканируйте QR-код из меню Arcula на компьютере.

Проверка. arcula-host status показывает, запущен ли хост, его версию и адрес.

Режимы: документы и разработка

Это одно приложение с двумя режимами. Режим выбирается при первом запуске и меняется в Настройках → Режим, на компьютере и на телефоне.

	Документы	Разработка
Обезличивание	Включено, вкладки «Обезличить» и «Вернуть данные»	Скрыто
Примеры ботов	Юрист, бухгалтер, врач, кадровик	Агенты кода в папках проектов
Агенты, рутины, экран, терминал	Есть	Есть, на первом плане

Данные и боты при переключении не меняются: режим влияет только на то, что показывает интерфейс.

Подключение телефона

Компьютер показывает одноразовый QR-код (меню Arcula или arcula-host pair). В нём ключи компьютера и адреса, по которым его искать. Телефон подключается:

напрямую — в одной сети или через Tailscale, порт 19222;
через облако — когда компьютер не виден напрямую; облако пересылает только зашифрованные кадры.

В обоих случаях канал шифруется сквозным ключом между телефоном и компьютером. Список устройств и отзыв доступа — arcula-host devices или в настройках.

Поддерживаемые агенты

Хост управляет агентами по Agent Client Protocol (JSON-RPC через stdio). Установленные CLI находятся сами, остальные скачиваются из реестра ACP.

Агент	Как войти
Arcula AI	Ничего не нужно — работает через облако Arcula
Claude Code	`claude auth login`
Codex	`codex login --device-auth`
Cursor	`cursor-agent login`
Gemini, Qwen, Copilot, OpenCode, Goose, Grok, Kimi, Droid, Amp, Kilo, Cline, Auggie, Kiro, Pi	Кнопка «Войти» в настройках бота открывает вход агента в терминале установки

Свой агент

Любая программа, которая говорит на ACP, подключается командой запуска в настройках бота, например npx my-agent --acp. Ключи, которые нужны агенту, сохраняются в хранилище хоста и передаются в окружение процесса, не в командную строку.

Боты, папки и разрешения

Бот — это постоянный агент с именем, аватаром, рабочей папкой, моделью и инструкциями. Его сессия переживает перезапуск хоста; «Новая сессия» начинает разговор заново.

Разрешения

Спрашивать — каждый запрос агента становится карточкой с вариантами ответа (на телефоне — прямо в уведомлении);
Автоматически — запросы одобряются сами; так начинают новые боты. Подходит для изолированных папок и доверенных задач.

Группы и треды

Групповой чат собирает нескольких ботов в одном разговоре; ответы в треде идут в отдельной ветке сессии.

Рутины

Рутина — это поручение боту по расписанию или по вебхуку. Проще всего попросить бота: «каждый будний день в 9:00 проверяй CI и пиши, если что-то упало». Вручную: Рутины → +.

Расписание — cron из пяти полей и часовой пояс IANA (0 9 * * 1-5, Europe/Moscow);
Вебхук — публичный адрес с ключом (Authorization: Bearer или подпись GitHub X-Hub-Signature-256); тело запроса передаётся боту вместе с поручением.

$ curl -X POST "https://api.arcula.club/v1/hooks/<компьютер>/<рутина>" \
    -H "Authorization: Bearer <ключ рутины>" \
    -d '{"event":"deploy","sha":"4f2a1c9"}'

Arcula AI

Встроенный агент на моделях Arcula: не нужно ставить CLI и оформлять отдельную подписку. Выберите агента Arcula AI в настройках бота.

Тариф	Модели	Лимиты	Цена
Бесплатный	Быстрая	базовые	0 ₽
Старт	Быстрая, Умная	×2,3	990 ₽ / мес — оплата скоро
Про	Быстрая, Умная, Глубокая	×6	2 490 ₽ / мес — оплата скоро
Макс	Быстрая, Умная, Глубокая	×19	7 900 ₽ / мес — оплата скоро

Лимиты и сбросы

Окно 5 часов открывается первым запросом и закрывается ровно через 5 часов; время сброса видно в разделе «Расход».
Недельное окно устроено так же, на 7 дней. Глубокая модель может занять не больше 40 % недели.
Когда окно 5 часов исчерпано, платные тарифы продолжают работать на Быстрой модели до сброса.
Начатый ответ всегда дописывается до конца. Ошибки модели не списываются.

Как это устроено

Агент Arcula AI — это Claude Code через адаптер ACP. Хост даёт ему локальный адрес http://127.0.0.1:19222/ai и одноразовый ключ, подписывает каждый запрос ключом компьютера и передаёт в облако. Ключ агента работает только на этом компьютере. Облако хранит счётчики, а не тексты.

Команды arcula-host

Команда	Что делает
`install` / `uninstall`	Ставит или убирает фоновую службу (launchd, systemd --user, Windows)
`status`	Установлен ли хост, запущен ли, версия
`serve --port 19222`	Запуск на переднем плане (то, что запускает служба)
`pair`	Одноразовый QR-код для телефона; `--json` — ссылка для скриптов
`tui`	Боты и чаты в терминале; `--url` — другой компьютер через SSH-туннель
`devices`	Список устройств; `devices revoke <ключ>` — отозвать
`access`	Запросы устройств аккаунта: `approve` по коду, `deny`
`cloud --enable` / `--disable`	Доступ через облако Arcula
`info`	Идентификатор компьютера и адрес API (для SSH)
`reset-token`	Новый токен локального API

Локальный API

Приложения на компьютере и ваши скрипты говорят с хостом по HTTP. API отвечает только с этого компьютера (loopback); телефоны ходят через зашифрованный канал. Токен — в ~/.arcula/token.

$ TOKEN=$(cat ~/.arcula/token)
$ curl -s -X POST http://127.0.0.1:19222/api/sync \
    -H "Authorization: Bearer $TOKEN" -d '{"since":0}'

Основные методы

Метод	Тело	Ответ
`sync`	`{"since": rev}`	Боты, записи чатов и расход после ревизии
`createBot`	`{"name", "backend", "cwd"}`	Новый бот
`send`	`{"botId", "text"}`	Сообщение боту; ответ придёт событиями
`stop`	`{"botId"}`	Остановить текущий ход
`respondPermission`	`{"entryId", "optionId"}`	Ответ на запрос разрешения
`refreshBackends`	—	Найденные агенты и их вход
`aiPlan`	—	Тариф Arcula AI и окна лимитов

События

GET /events?since=<rev> — поток SSE: сначала всё пропущенное по порядку ревизий, затем новое вживую. Каждое изменение несёт глобальный rev; клиенты обновляют записи по id.

Удалённый доступ

Облако Arcula (по умолчанию): хост держит исходящее соединение с ретранслятором, телефон подключается к нему же. Ретранслятор видит только шифротекст и адресацию.
Напрямую: LAN или Tailscale, /channel на порту 19222.
SSH: ssh -L 19222:127.0.0.1:19222 компьютер, затем arcula-host tui --url http://127.0.0.1:19222 --token ….

Новое устройство аккаунта получает доступ только после сверки 6-значного кода на компьютере (arcula-host access approve <код>).

Своё облако

Облако (вход устройств, ретранслятор, панель администратора) поднимается на своём сервере в Docker, с HTTPS от Let's Encrypt. Нужны Linux, 1 ГБ памяти, порты 80 и 443 и DNS-записи A для сайта и api..

$ cd arcula/deploy/server
$ cp .env.example .env && nano .env   # DOMAIN, API_DOMAIN, ADMIN_TOKEN
$ docker compose up -d --build

Проверка: https://api.ваш-домен/v1/health. Хост направляется на своё облако переменной ARCULA_CLOUD_URL или при сборке ARCULA_BUILD_CLOUD_URL; телефон получает адрес из QR-кода.

Безопасность

Чаты, файлы и память ботов хранятся на компьютере. Облако не хранит переписку. С Arcula AI текст задачи проходит через сервер к модели и не сохраняется: хранятся только счётчики лимитов.
Канал телефон ↔ компьютер шифруется сквозным ключом (X25519, ChaCha20-Poly1305); каждое устройство подписывает запросы своим ключом Ed25519.
Локальный API доступен только с самого компьютера; ключи агентов и коннекторов лежат в системном хранилище ключей.
Уведомления шифруются ключом устройства: сервер уведомлений видит общий текст.
В режиме «Документы» имена, паспорта, ИНН и счета заменяются метками на устройстве до того, как текст попадёт к модели.