Разработчикам
Just Run предоставляет несколько интеграционных контрактов вокруг одной платформы, в которой все ресурсы принадлежат аккаунтам. Этот раздел помогает выбрать между ними и правильно обработать аутентификацию, асинхронное состояние, вывод в реальном времени, ошибки, повторные попытки и изменения контрактов. Точные пути, поля, ответы, инструменты и фреймы протоколов находятся в Справочнике API.
Собственный REST API — основной выбор для новой интеграции. MCP, работа в реальном времени, совместимость с E2B и входящие вебхуки решают более узкие задачи и не являются взаимозаменяемыми псевдонимами REST.
Выбор способа интеграции
| Способ | Лучший сценарий | Чего не следует предполагать |
|---|---|---|
Собственный REST API под /v1 | Сервисы, скрипты, CLI, управление жизненным циклом и точный контроль запросов и ответов | Что каждая операция синхронна или допускает безопасный повтор |
MCP управления платформой на /mcp | AI-агенты и 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 API | Authorization: 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-stream | exit подтверждает завершение; повторный 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; сам
по себе он не обещает семантического версионирования или графика устаревания.
Пока отдельная политика не опубликует явный срок поддержки:
- Закрепляйте или архивируйте входной документ OpenAPI, использованный для генерации клиентских типов.
- Проверяйте различия в сгенерированных файлах до их принятия.
- Допускайте появление новых полей в ответах и не обрабатывайте недокументированные значения перечислений исчерпывающим образом без запасного варианта.
- Проверяйте важные сценарии на целевой инсталляции до внедрения.
- Читайте Историю изменений и заметки о миграции при изменениях поведения.
Не предполагайте постоянство маршрута, поля, цели совместимости или срока устаревания только потому, что они есть в текущей реализации.
Контрольный список интеграции для рабочей среды
Перед включением операций записи в рабочей среде:
- Запишите целевой адрес и владельца аккаунта.
- Выдайте клиенту минимальные права персонального токена и срок действия.
- Перечислите каждую изменяющую операцию и определите, можно ли и как ее повторять.
- Определите конечные состояния для используемых фоновых задач, подготовки, запусков автоматизаций и потоков в реальном времени.
- Ограничьте опрос, задержки между повторами, таймауты, конкурентность и сохраняемый вывод.
- Логируйте
x-request-id, но не учетные данные, значения секретов или подписанные URL. - Закрепите сгенерированные контракты и протестируйте поведение при обновлении.
- Определите очистку для каждого созданного интеграцией ресурса.
Подробнее об интеграции
- Основы работы с API — адрес, заголовки, контекст аккаунта, ошибки, ID запросов и идемпотентность создания песочницы.
- Стриминг и обмен данными в реальном времени — выбор способа передачи, завершение, воспроизведение и поведение при переподключении.
- Длительные операции — фоновые задачи, опрос, прогресс, отмена и готовность конкретных функций.
- Генерация типов OpenAPI — загрузка, проверка, генерация и контроль объявлений типов TypeScript.
- Совместимость с E2B — закрепленная целевая версия SDK, преобразованное поведение и намеренные пробелы.
- MCP управления платформой — безопасное подключение агентов и выбор инструментов MCP.
- Ошибки и ограничения частоты запросов — классификация сбоев и ограниченное восстановление.
- Версионирование и устаревание API — политика изменения контракта по мере ее формализации.
- Справочник API — точные контракты REST, вебхуков, MCP и протоколов реального времени.
- Персональные токены — привязка к аккаунту, права, срок действия и отзыв.
- Быстрый старт с API — создание песочницы, выполнение команды и удаление через cURL.