Запуск и работа с профилями

Прежде чем агент сможет автоматизировать страницу, нужный профиль должен быть запущен. На этой странице разобран весь жизненный цикл через API локального демона — список профилей, создание профиля (с отпечатком и прокси), его запуск, опрос статуса и остановка — а также объясняется ошибка PROFILE_NOT_RUNNING, с которой вы столкнётесь, если пропустите шаг запуска.

Все запросы идут к локальному демону. API управления профилями находится по адресу http://localhost:7891/api; API автоматизации (навигация, клики, ввод текста, снимки) находится по адресу http://localhost:7891/api/automation/:profileId/<action> и описан в разделах HTTP API и Справочник API.

Формат ответа

Каждый эндпоинт демона возвращает один и тот же JSON-конверт, чтобы ваш код мог ветвиться по ok до чтения data:

Success

{ "ok": true, "data": { } }

Failure

{ "ok": false, "error": { "code": "PROFILE_NOT_RUNNING", "message": "..." } }

Некоторые эндпоинты возвращают "data": null при успехе (launch, stop, unlock). Проверяйте ok, а не структуру data.

Значения статуса профиля

Профиль сообщает один статус выполнения. Автоматизация работает только пока профиль находится в статусе running.

Статус	Значение
idle	Создан, но не запущен. Процесс браузера не работает.
launching	Запуск принят; браузер стартует и синхронизирует удалённое состояние сессии.
running	Браузер работает. Эндпоинты автоматизации доступны.
stopping	Остановка принята; куки и вкладки синхронизируются перед закрытием браузера.
locked	Профиль открыт на другом устройстве. Запустить его здесь нельзя, пока блокировка не снята.

Заметка

launch асинхронен. Успешный запуск сразу возвращает 202 Accepted, ещё до того, как браузер закончит старт. Опрашивайте эндпоинт статуса, пока он не вернёт running, прежде чем отправлять действия автоматизации — см. Дождитесь, пока профиль запустится.

Список профилей

Возвращает все профили с их текущим статусом выполнения. Для чтения списка лицензия не требуется.

List profiles with status

curl -s localhost:7891/api/profiles | jq '.data[] | {id, name, status}'

Если вы внешний агент, которому не передали конкретный ID профиля, запросите список профилей и дайте оператору выбрать один. Получив ID, сохраните его в переменной окружения на весь остальной процесс:

Pin the profile ID

PROFILE=<profile-id>

Создание профиля

Создание профиля требует активной лицензии. В теле запроса передаются имя профиля, прокси, отпечаток и геолокация. При успехе демон возвращает 201 с новым профилем и status: "idle".

Create a profile (fingerprint + proxy)

curl -s localhost:7891/api/profiles -X POST \
  -H 'Content-Type: application/json' -d '{
    "name": "My Profile",
    "proxy": {"type": "none"},
    "fingerprint": {
      "os": "windows",
      "userAgent": "Mozilla/5.0 ...",
      "screenWidth": 1920, "screenHeight": 1080,
      "language": "en-US", "timezone": "America/New_York",
      "webrtc": "fake"
    },
    "geolocation": {"enabled": false}
  }'

Поле webrtc принимает значения real, fake или disabled. Чтобы подключить прокси вместо {"type": "none"}, укажите параметры подключения в объекте proxy — см. Настройка прокси. Полный список полей отпечатка и их соответствие настройкам браузера приведён в разделе Параметры отпечатка.

Пусть сервер сам соберёт отпечаток

Вместо того чтобы вручную прописывать поля отпечатка, попросите демон сгенерировать статистически реалистичный и подставьте результат прямо в тело запроса на создание. Генератор работает на стороне сервера и требует активной лицензии.

Generate a realistic fingerprint

curl -s localhost:7891/api/generate-fingerprint -X POST \
  -H 'Content-Type: application/json' -d '{"os": "windows"}' | jq .data

Подробности — в разделе Генерация отпечатка.

Обновление профиля

При обновлении все поля необязательны — отправляйте только то, что хотите изменить. Демон возвращает обновлённый профиль с его текущим статусом.

Rename and tag a profile

curl -s localhost:7891/api/profiles/$PROFILE -X PATCH \
  -H 'Content-Type: application/json' -d '{"name": "New Name", "tags": ["work"]}'

Запуск профиля

Запуск стартует процесс браузера для профиля. Он асинхронен: при успехе вы получаете 202 Accepted с "data": null, а статус переходит в launching.

Launch a profile

curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

Перед тем как принять запуск, проверяются два условия:

1. Активная лицензия. Нет активной подписки → 403 с NO_SUBSCRIPTION (аккаунт никогда не платил) или LICENSE_EXPIRED (подписка истекла). Тарифы только платные — см. Тарифы и цены.
2. Свободный одновременный слот. Ваш тариф ограничивает, сколько профилей может работать одновременно — Starter 3, Pro 40, Agency 300. Если вы уже достигли лимита, запуск вернёт 403 CONCURRENT_LIMIT_REACHED; сначала остановите работающий профиль или повысьте тариф.

Код ошибки	HTTP	Значение
NO_SUBSCRIPTION	403	У аккаунта никогда не было платного тарифа.
LICENSE_EXPIRED	403	Подписка истекла.
CONCURRENT_LIMIT_REACHED	403	Все одновременные слоты вашего тарифа заняты.
PROFILE_NOT_FOUND	404	Профиля с таким ID нет.
PROFILE_LOCKED	409	Профиль открыт на другом устройстве.
UNAUTHORIZED	401	Сессионные токены демона отсутствуют или истекли; войдите через приложение.

Лимит на одновременные, а не на все профили

Лимит запуска считает профили, которые работают прямо сейчас, а не сколько вы создали. На тарифе Pro можно владеть 40 профилями и запускать лишь несколько одновременно — но превысить лимит тарифа на количество одновременно живых браузеров нельзя. См. Состояния лицензии.

Дождитесь, пока профиль запустится

Поскольку запуск возвращается до того, как браузер готов, опрашивайте эндпоинт статуса, пока он не вернёт running. Не отправляйте действия автоматизации во время launching.

Poll status after launch

curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status

Простой цикл ожидания:

Launch, then wait for running

curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

until [ "$(curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status)" = "running" ]; do
  sleep 1
done

Проверка статуса

Эндпоинт статуса — единственный источник истины о том, можно ли автоматизировать профиль. Лицензия для него не нужна, ответ мгновенный.

Check a single profile's status

curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status

Response

{ "ok": true, "data": { "status": "running" } }

Остановка профиля

Остановка закрывает браузер. Перед завершением процесса демон синхронизирует сессию — открытые вкладки и любые изменённые куки выгружаются, чтобы следующий запуск продолжил с того места, где вы остановились. При успехе вы получаете "data": null, а статус переходит в stopping, затем обратно в idle.

Stop a profile

curl -s localhost:7891/api/profiles/$PROFILE/stop -X POST

Остановка синхронизирует вашу сессию

Куки и открытые вкладки сохраняются между циклами остановки и запуска — именно это делает профиль устойчивой личностью, а не одноразовой сессией. Чтобы начать прогон с чистой сессии без перезапуска, очистите куки на работающем профиле (см. Куки). Подробнее о том, что сохраняется, — в разделе Синхронизация сессий.

PROFILE_NOT_RUNNING

Если вы вызываете эндпоинт автоматизации (/api/automation/$PROFILE/navigate, /snapshot, /click, …) для профиля, который не находится в статусе running, демон отвечает 404 с кодом ошибки PROFILE_NOT_RUNNING.

Automating a non-launched profile

{ "ok": false, "error": { "code": "PROFILE_NOT_RUNNING", "message": "..." } }

Это самая частая ошибка при первом запуске: профиль существует, но его браузер так и не был запущен (или уже остановлен). Эндпоинты кук ведут себя так же — GET/POST/DELETE /api/profiles/$PROFILE/cookies работают только пока профиль запущен.

Как этого избежать:

• Запускайте профиль (POST /api/profiles/$PROFILE/launch) до любого вызова автоматизации.
• Воспринимайте 202 от запуска как «принято, но не готово». Опрашивайте GET /api/profiles/$PROFILE/status, пока он не вернёт running — автоматизация во время launching всё ещё может завершиться неудачей.
• Перепроверяйте статус, если долгий процесс застопорился: сбой браузера или остановка с другого устройства выводят профиль из статуса running.
• Работайте строго внутри профиля, который дал вам оператор. Не запускайте, не останавливайте и не переключайтесь на другой профиль, чтобы «исправить» несоответствие — если указанный профиль не запущен или не подходит для задачи, остановитесь и спросите оператора.

Сквозной жизненный цикл

Полный процесс создание → запуск → автоматизация → остановка:

Full lifecycle

# 0. Pin the profile ID (or create one first)
PROFILE=<profile-id>

# 1. Launch (async — returns 202)
curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

# 2. Wait until the browser is up
until [ "$(curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status)" = "running" ]; do
  sleep 1
done

# 3. Automate (now safe — no PROFILE_NOT_RUNNING)
curl -s localhost:7891/api/automation/$PROFILE/navigate -X POST \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'

# 4. Stop — syncs cookies & tabs before closing
curl -s localhost:7891/api/profiles/$PROFILE/stop -X POST

Дальнейшие шаги

• HTTP API — эндпоинты действий автоматизации, когда профиль запущен.
• Справочник API — полный каталог эндпоинтов и действий.
• Лучшие практики — пакетная обработка, снимки и правила скрытности.
• Установка агентского скилла — готовые инструкции для AI-агента.