Обзор автоматизации

Santiago превращает каждый профиль браузера в программируемый, полностью замаскированный браузер, которым можно управлять из собственного кода или передать AI-агенту. Вы обращаетесь к единому локальному HTTP API на http://localhost:7891; демон запускает браузер Camoufox (на базе Firefox) для профиля и применяет за вас всю подмену отпечатка, прокси, таймзоны и WebRTC. Вам не нужно собирать отпечаток или подключать прокси в коде автоматизации — вы ссылаетесь на профиль по ID и действуете внутри него.

Что можно автоматизировать

Всё, что вы можете сделать вручную в окне профиля, можно заскриптовать — на одном профиле или на сотнях, параллельно.

Сценарий	Как это выглядит
Заполнение форм	Перейдите к форме, заполните каждое поле, разберитесь с выпадающими списками, отправьте — всё через доверенные, гуманизированные события. См. Заполнение форм.
Извлечение данных	Запустите профиль, читайте DOM через evaluate и доставайте нужный текст или значения. Куки и вкладки синхронизируются обратно при остановке.
Управление несколькими профилями	Запускайте множество изолированных профилей одновременно — каждый со своим отпечатком, прокси и хранилищем кук — чтобы выполнять одну задачу параллельно. См. Несколько профилей.
Долгие задачи	Передайте агенту длительность и дайте ему работать автономно со случайным, человекоподобным темпом. См. Автономные задачи.

Подмена работает автоматически

Canvas, WebGL, аудио, шрифты, голоса, WebRTC, таймзона, геолокация и user agent — всё это берётся из профиля и применяется при запуске. Ваша автоматизация никогда не задаёт эти значения — она просто действует внутри уже замаскированного браузера. См. Как работает фингерпринтинг.

Как устроены компоненты

Santiago — это одно настольное приложение с многоуровневой иерархией процессов:

Process hierarchy

Electron tray app
  └─ local daemon  (Fastify HTTP server on http://localhost:7891)
       └─ Camoufox browser  (one process per running profile)

• Трей Electron — настольное приложение, которое вы устанавливаете и в которое входите. Оно владеет вашей лицензией и запускает демон.
• Локальный демон — HTTP-сервер на Fastify, слушающий http://localhost:7891. Это единственный публичный API Santiago. Он управляет профилями, запускает браузеры и предоставляет эндпоинты автоматизации.
• Camoufox — усиленный браузер на базе Firefox, запускаемый для каждого профиля, со встроенным отпечатком профиля. Когда включена humanize, демон автоматически добавляет ко всем действиям движение курсора по кривой Безье.

Ваш код или AI-агент находится вне этого стека и вызывает демон по обычному HTTP:

Who calls what

your code / AI agent  ──HTTP──▶  daemon :7891  ──▶  Camoufox profile

Только локально

Демон привязан к localhost. Удалённого API Santiago для автоматизации не существует — облачный аккаунт, биллинг и управление командой живут за интерфейсом приложения. Всё, что вы скриптуете, выполняется на той же машине, что и запущенный браузер.

Поверхность API

На :7891 есть две HTTP-поверхности, обе под /api:

Поверхность	Базовый путь	Назначение
Profile API	http://localhost:7891/api/profiles	Список, создание, обновление, запуск, остановка профилей; чтение статуса; импорт/экспорт кук.
Automation API	http://localhost:7891/api/automation/:profileId/<action>	Управление запущенным профилем: переход, снимок, клик, ввод, заполнение форм, скриншот, evaluate.

Каждый ответ использует один и тот же конверт:

Success

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

Error

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

Минимальный поток

Выберите профиль, запустите его и начните им управлять. Всё, что нужно, — это ID профиля.

Find a profile

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

Launch it (async, returns 202)

PROFILE=<profile-id>
curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

Navigate inside the running profile

curl -s localhost:7891/api/automation/$PROFILE/navigate -X POST \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'

Snapshot the page to find your targets

curl -s localhost:7891/api/automation/$PROFILE/snapshot -X POST | jq -r .data.snapshot

Stop it — cookies and tabs sync before closing

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

Полный набор действий (click, type, fill-page, select-combobox, screenshot, evaluate, wait, batch и другие) описан в руководстве по HTTP API и справочнике API.

Два способа управления

Вы можете вызывать демон как угодно — curl, fetch, Python-клиент, что угодно, что говорит по HTTP. Есть два распространённых подхода:

• Собственный код — отправляйте HTTP-вызовы напрямую. Эндпоинты, тела запросов и форматы ответов описаны в HTTP API и справочнике API.
• AI-агент — установите agent skill для Santiago и дайте модели решать конкретные действия (какой элемент кликнуть, что ввести, когда подождать). Skill обучает агента эндпоинтам и правилам незаметности. См. Установка agent skill.

Download the agent skill

curl -fsSL https://downloads.santiago-browser.com/skill/latest/santiago-browser-skill.tar.gz \
  -o santiago-browser-skill.tar.gz

Правила незаметности, важные для автоматизации

Маскировка хороша ровно настолько, насколько хороши генерируемые вами события. Два правила переносятся на всё, что вы скриптуете:

evaluate работает только на чтение

evaluate выполняет JavaScript страницы и идеально подходит для чтения DOM — заголовков, текста, координат элементов. Никогда не используйте его для взаимодействия со страницей. Синтетический element.click() порождает событие с isTrusted: false без предшествующего движения мыши, что антибот-системы помечают напрямую. Для любого взаимодействия используйте click / type / press-key / mouse/click — они генерируют доверенные, гуманизированные события.

Сложные, анимированные формы

Некоторые формы используют тяжёлые CSS-переходы или рендерят выпадающие списки в отдельных оверлеях, что ломает наивные локаторы. Эндпоинт fill-page, работающий по координатам, и клавиатурные запасные варианты надёжно справляются с этим. См. Лучшие практики.

Статус профиля и параллелизм

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

Статус	Значение
idle	Не запущен. Вызовы автоматизации возвращают PROFILE_NOT_RUNNING.
launching	Браузер запускается.
running	Готов к управлению через automation API.
stopping	Браузер завершает работу (синхронизирует куки и вкладки).
locked	Профиль используется на другом устройстве — его нельзя запустить здесь, пока он не освобождён.

Сколько профилей можно запустить параллельно, определяется вашим тарифом, и демон следит за соблюдением этого лимита.

Тариф	Цена	Профили
Starter	$9/мес	3
Pro (самый популярный)	$59/мес	40
Agency	$149/мес	300 + команда до 10 участников

Santiago работает только по платной подписке — бесплатного пробного периода нет. Для запуска профиля нужна активная лицензия и свободный параллельный слот; превышение количества слотов возвращает CONCURRENT_LIMIT_REACHED. Подробнее см. Тарифы.

Что дальше

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