Перейти к основному содержимому
Открыть Markdown

Разработчикам

Just Run предоставляет несколько интеграционных контрактов вокруг одной платформы, в которой все ресурсы принадлежат аккаунтам. Этот раздел помогает выбрать между ними и правильно обработать аутентификацию, асинхронное состояние, вывод в реальном времени, ошибки, повторные попытки и изменения контрактов. Точные пути, поля, ответы, инструменты и фреймы протоколов находятся в Справочнике API.

Собственный REST API — основной выбор для новой интеграции. MCP, работа в реальном времени, совместимость с E2B и входящие вебхуки решают более узкие задачи и не являются взаимозаменяемыми псевдонимами REST.

Выбор способа интеграции​

СпособЛучший сценарийЧего не следует предполагать
Собственный REST API под /v1Сервисы, скрипты, CLI, управление жизненным циклом и точный контроль запросов и ответовЧто каждая операция синхронна или допускает безопасный повтор
MCP управления платформой на /mcpAI-агенты и MCP-клиенты, которые обнаруживают и вызывают инструменты платформы уровня аккаунтаЧто это Hosted MCP, туннель REST или API стриминга команд
Эндпоинты песочницы на SSE и WebSocketПостепенный вывод команд, переподключение к фоновому процессу и интерактивные терминалыЧто у всех способов передачи одинаковая модель переподключения
Адаптер совместимости с E2BСуществующие приложения, проверенные с закрепленным оригинальным Python SDK e2bПолный паритет с E2B Cloud или собственный Python SDK Just Run
Получатель вебхука автоматизацииСобытия провайдера, которые должны поставить запуск автоматизации в очередьЧто входящее событие аутентифицируется персональным токеном Just Run
Публичный артефакт OpenAPIГенерация проверяемых типов для операций собственного REST API из публичного списка разрешенныхЧто он покрывает инструменты MCP, семантику вебхуков, фреймы протоколов реального времени или каждый маршрут, реализованный в продукте

Одна интеграция может сочетать несколько способов. Например, создать и проверить песочницу через REST, запустить фоновый процесс через REST и следить за ним через WebSocket. Назначьте одного канонического владельца каждой операции, чтобы резервная логика случайно не отправила одно изменение дважды.

Одна инсталляция, несколько контрактов​

integration
│
├── REST /v1 ───────── resources, lifecycle, files, Storage, configuration
├── MCP /mcp ───────── discoverable control-plane tools for an agent
├── SSE / WebSocket ── command output, process attach, terminal
├── E2B adapter ────── translated control and sandbox data planes
└── webhook receiver ─ verified external event → queued Automation run

all account-scoped control paths converge on the same deployment,
but each surface keeps its own authentication and completion contract

Используйте публичный адрес, предоставленный инсталляцией, например https://your-just-run-host. Собственный REST API, часть платформы для работы с данными песочницы, /mcp и адаптер E2B размещены по этому адресу шлюза. Приложения превью используют сгенерированные URL превью и имеют отдельную границу публикации и аутентификации.

Аутентификация для нужного аккаунта​

Для интеграции с собственным REST API, работающей без участия человека, создайте персональный токен, пока дашборд находится в личном контексте или контексте организации, которая должна владеть ресурсами. Персональный токен остается привязан к этому аккаунту; клиент не выбирает другой аккаунт, добавляя заголовок с ID аккаунта.

КонтрактСпособ передачи учетных данных
Защищенный собственный REST APIAuthorization: Bearer <PAT> или поддерживаемый токен пользовательской сессии
MCP управления платформойСтатический Authorization: Bearer <PAT> в запросах Streamable HTTP или вход через браузер по OAuth: MCP-клиент сам получает и обновляет токен доступа
SSE и WebSocket песочницыАутентификация bearer; у handshake из браузера есть отдельный путь с короткоживущей сессией
Управляющая часть E2BПерсональный токен Just Run в X-API-Key; возвращенный токен доступа песочницы — для преобразованной части платформы для работы с данными
Вебхук автоматизацииПроверка подписи провайдера или общий токен, настроенные в автоматизации

Используйте персональный токен read_only для клиентов, которые только читают состояние. Основные изменяющие операции REST блокируются по методу HTTP, а MCP одновременно скрывает и отклоняет инструменты записи для такого токена. Выбирайте full только когда интеграция должна создавать, выполнять, изменять или удалять ресурсы.

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

Основы собственного REST API​

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

export JUSTRUN_API="https://your-just-run-host"

curl --fail-with-body \
"$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT"

Большинство тел запросов и ответов управляющей части платформы используют JSON, а передача файлов, операции хранилища по presigned URL, ответы SSE и переключения на WebSocket — документированные для них типы содержимого. Публичная ошибка HTTP содержит код статуса и небольшое тело JSON:

{
"error": "human-readable message"
}

Каждый ответ шлюза содержит x-request-id. Записывайте его вместе с временной меткой, методом, путем, статусом и ID ресурса. Валидное переданное клиентом значение распространяется дальше, иначе шлюз генерирует новое.

Коды статуса определяют способ восстановления:

СтатусРеакция интеграции
400 или 422Исправить запрос; повтор того же тела бесполезен
401Обновить или заменить учетные данные, не запускать цикл
403Проверить права персонального токена или разрешения
404Считать ресурс недоступным текущему аккаунту
409Прочитать текущее состояние жизненного цикла до выбора следующей операции
413Уменьшить или перенести передаваемые данные согласно правилам соответствующей функции
429Отличить исчерпание квоты от ограничения частоты запросов и отступить
502 или 503Считать потенциально временным сбоем, но повторять только безопасную операцию
500Сохранить x-request-id; внутренние подробности намеренно скрыты

Ограничения частоты запросов зависят от конфигурации инсталляции и неодинаково охватывают маршруты. Ответ 429 не задает универсальное время сброса, а текущий общий контракт ошибок не обещает заголовок Retry-After. Используйте ограниченную экспоненциальную задержку со случайным разбросом и прекращайте попытки после заданного лимита.

Явные повторные попытки для изменяющих операций​

Классифицируйте каждую операцию до ее повтора:

  • операции чтения обычно можно повторять в пределах ограниченной политики;
  • удаление часто естественно сходится к одному состоянию, но проверяйте конкретный эндпоинт;
  • создание, выполнение, повторная доставка и другие вызовы с побочными эффектами нельзя повторять только потому, что клиент потерял ответ;
  • один метод HTTP не доказывает идемпотентность на уровне приложения.

POST /v1/sandboxes поддерживает Idempotency-Key. Повторно используйте один ключ для повторных попыток одного логического создания; новый ключ означает новую песочницу. Это контракт конкретной операции, а не общий заголовок идемпотентности шлюза.

Выполнение команды со стримингом не имеет ключа идемпотентности или курсора возобновления. Если его SSE-соединение закрылось без события exit, проверьте внешнее состояние до повторной отправки команды. Для работы, которая должна пережить отключение клиента, запустите фоновый процесс и подключайтесь к нему.

Обработка асинхронной работы по наблюдаемому состоянию​

Разные операции завершаются на разных границах:

  • ответ команды с буферизацией завершается после выхода команды и возврата собранного вывода;
  • создание песочницы может вернуться после запуска VM, пока настройка репозитория или другая подготовка еще выполняется;
  • ответ с фоновой задачей определяет долговременную фоновую работу, состояние которой можно читать отдельно;
  • принятый вебхук автоматизации подтверждает постановку в очередь, а не успех действия;
  • завершающие сообщения SSE и WebSocket, а не само закрытие соединения, подтверждают завершение команды или процесса.

API фоновых задач уровня аккаунта предоставляет получение списка, чтение и отмену:

GET    /v1/jobs
GET /v1/jobs/{id}
DELETE /v1/jobs/{id}

Задача сообщает status, progress_pct, опциональные result или error и временные метки. Выполняйте опрос с ограниченным интервалом до done, failed или cancelled. Отмена принимается только пока задача находится в pending или running; не считайте ее откатом эффектов, которые обработчик задачи уже успел зафиксировать.

Предпочитайте состояние конкретной функции, когда оно точнее записи задачи. Например, дождитесь provisioning.status песочницы, прежде чем считать настройку репозитория готовой, и проверяйте запуск автоматизации, чтобы узнать результат действия.

Выбор контракта обмена данными в реальном времени по поведению при разрыве соединения​

ЗадачаКонтрактГраница завершения и переподключения
Постепенный вывод одной командыSSE exec-streamexit подтверждает завершение; повторный POST запускает еще одну команду
Следить за фоновым процессомWebSocket подключения к процессуПроцесс переживает разрыв соединения; переподключение включает ограниченное воспроизведение, способное повторить фрагменты
Интерактивная оболочкаWebSocket терминалаexited завершает один PTY; переподключение создает новый PTY без воспроизведения платформой
Один детерминированный ответREST exec с буферизациейHTTP-ответ приходит после завершения; вывод может быть ограничен по размеру

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

Паттерны восстановления описаны на странице Стриминг и обмен данными в реальном времени, точные фреймы приведены на странице Протоколы песочницы для обмена данными в реальном времени.

Использование MCP для управления платформой​

Эндпоинт шлюза /mcp — MCP-сервер с сохранением состояния на Streamable HTTP. MCP-клиент выполняет обычный handshake initialize, вызывает tools/list и использует возвращенные схемы для tools/call. Инструменты чтения и записи работают с аутентифицированным аккаунтом.

Этот эндпоинт подходит, когда агент должен обнаруживать действия платформы. Он отличается от MCP-хостинга, где Just Run запускает выбранный или предоставленный вами сервер. MCP управления платформой может содержать инструменты hosted_mcp_*, управляющие такими инстансами Hosted MCP.

Предпочитайте актуальный tools/list жестко заданному каталогу. Некоторые инструменты зависят от функций инсталляции — хранилища, доступа к каталогу навыков или Hosted MCP; наличие в списке не гарантирует, что соответствующая функция включена. Обрабатывайте ошибки инструментов MCP по контракту MCP, а не как тела ошибок REST.

Выполнение команд через MCP происходит с буферизацией. Если нужны постепенный вывод, подключение к процессу или терминал, используйте собственный REST API вместе с контрактами для работы в реальном времени.

Сгенерированные клиенты как артефакты сборки​

Загружаемый документ OpenAPI 3.1 генерируется из текущих схем Rust и точного публичного списка разрешенных операций. Он намеренно неполон и исключает эндпоинты администратора, оператора, проверки состояния, метрик и внутренней передачи данных. Генерируйте и проверяйте из него типы, но не приписывайте сгенерированному типу поведение повторных попыток, пагинации, ожидания или управления учетными данными.

Сообщения MCP, проверка вебхуков, фреймы протоколов реального времени и адаптер E2B описаны в отдельных справочниках, написанных вручную. Они не являются операциями OpenAPI собственного REST API.

Сейчас Just Run не публикует поддерживаемый собственный Python SDK. Путь через совместимость с E2B использует официальный пакет Python точной версии, покрытой набором тестов репозитория. Новые интеграции обычно следует начинать с собственного REST API.

Планирование изменений контракта​

Префикс /v1 обозначает текущее пространство имен собственного REST API; сам по себе он не обещает семантического версионирования или графика устаревания. Пока отдельная политика не опубликует явный срок поддержки:

  1. Закрепляйте или архивируйте входной документ OpenAPI, использованный для генерации клиентских типов.
  2. Проверяйте различия в сгенерированных файлах до их принятия.
  3. Допускайте появление новых полей в ответах и не обрабатывайте недокументированные значения перечислений исчерпывающим образом без запасного варианта.
  4. Проверяйте важные сценарии на целевой инсталляции до внедрения.
  5. Читайте Историю изменений и заметки о миграции при изменениях поведения.

Не предполагайте постоянство маршрута, поля, цели совместимости или срока устаревания только потому, что они есть в текущей реализации.

Контрольный список интеграции для рабочей среды​

Перед включением операций записи в рабочей среде:

  1. Запишите целевой адрес и владельца аккаунта.
  2. Выдайте клиенту минимальные права персонального токена и срок действия.
  3. Перечислите каждую изменяющую операцию и определите, можно ли и как ее повторять.
  4. Определите конечные состояния для используемых фоновых задач, подготовки, запусков автоматизаций и потоков в реальном времени.
  5. Ограничьте опрос, задержки между повторами, таймауты, конкурентность и сохраняемый вывод.
  6. Логируйте x-request-id, но не учетные данные, значения секретов или подписанные URL.
  7. Закрепите сгенерированные контракты и протестируйте поведение при обновлении.
  8. Определите очистку для каждого созданного интеграцией ресурса.

Подробнее об интеграции​