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

Совместимость с E2B

Just Run предоставляет адаптер совместимости для приложений, использующих официальный SDK e2b. Он переводит управляющую часть E2B и часть для работы с данными по протоколу Connect в обычные песочницы Just Run. Это практический путь миграции, а не обещание полной идентичности всех возможностей E2B Cloud.

Опубликованный уровень совместимости

Набор тестов в репозитории зафиксирован на официальном пакете Python e2b==2.20.0. Начинайте именно с этой версии. Более новые выпуски Python и JavaScript/TypeScript SDK не входят в проверенный публичный контракт, пока не обновлен набор тестов.

Эта страница не вводит отдельный Python SDK Just Run.

Когда использовать адаптер​

Адаптер подходит существующим приложениям, которым в первую очередь нужны:

  • создание и поиск песочниц, подключение, пауза, возобновление, таймаут, метрики и удаление;
  • команды на переднем плане и в фоне, управление процессами, вывод и stdin;
  • основные операции с файлами и каталогами;
  • новая интерактивная PTY-сессия.

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

Перед началом​

Понадобятся:

  • инсталляция Just Run с включенным адаптером E2B;
  • публичный адрес шлюза и его имя хоста;
  • персональный токен с правами Полные для аккаунта, которому будут принадлежать песочницы;
  • существующий шаблон Just Run, например base.

API-ключ E2B Cloud не подходит для аутентификации в Just Run. Передайте персональный токен Just Run через E2B_API_KEY. Персональный токен с правами Только чтение позволяет получать списки и сведения, но шлюз отклоняет создание, паузу, возобновление, изменение таймаута и удаление.

Настройка Python SDK​

Установите версию, которую покрывает набор тестов репозитория:

python -m pip install "e2b==2.20.0"

Направьте обе части SDK на один адрес Just Run. Суффикс /e2b нужен только для URL управляющей части:

export E2B_API_URL="https://control.example.com/e2b"
export E2B_SANDBOX_URL="https://control.example.com"
export E2B_DOMAIN="control.example.com"
export E2B_API_KEY="pat_replace_me"
  • E2B_API_URL обслуживает создание, списки, подключение, жизненный цикл, таймаут и метрики.
  • E2B_SANDBOX_URL обслуживает команды, файлы, PTY и проверку работоспособности на корне шлюза. Не добавляйте /e2b.
  • E2B_DOMAIN служит подсказкой домена для SDK. Указанный E2B_SANDBOX_URL избавляет обычные запросы к части для работы с данными от зависимости от E2B-подобного DNS для каждой песочницы.
  • E2B_API_KEY передается в заголовке X-API-Key управляющей части.

Храните персональный токен в менеджере секретов или защищенном окружении. Не коммитьте его, не записывайте в логи и не помещайте в URL.

Проверенный сценарий​

Кратчайший полезный сценарий создает песочницу, проверяет команду и чтение-запись файла, а затем удаляет песочницу:

from e2b import Sandbox

sandbox = Sandbox.create("base", timeout=300)

try:
result = sandbox.commands.run("printf 'hello from just-run\\n'")
assert result.exit_code == 0
print(result.stdout, end="")

sandbox.files.write("/tmp/e2b-note.txt", "stored through E2B")
note = sandbox.files.read("/tmp/e2b-note.txt")
assert note == "stored through E2B"
print(note)
finally:
sandbox.kill()

Ожидаемый вывод:

hello from just-run
stored through E2B

Аргумент шаблона в Sandbox.create() соответствует имени шаблона Just Run. Доступные имена определяются каталогом конкретной инсталляции: совместимость со значением base по умолчанию не означает наличия всех шаблонов оригинального E2B.

Разделение аутентификации​

SDK использует два набора учетных данных, но приложению не нужно самостоятельно управлять вторым:

  1. Запросы к управляющей части под /e2b используют персональный токен Just Run в X-API-Key. Шлюз определяет контекст аккаунта и проверяет владение ресурсом и права персонального токена.
  2. Создание или подключение возвращает отдельный для песочницы envdAccessToken. SDK передает этот токен корневым эндпоинтам части для работы с данными. Шлюз и управляющий компонент проверяют токен и получают из него идентификатор песочницы.

Считайте envdAccessToken секретом. Не переносите его между песочницами и не вызывайте эндпоинт Connect с самостоятельно составленным заголовком E2b-Sandbox-Id: один этот заголовок не авторизует запрос.

Поддерживаемые возможности​

Жизненный цикл и поиск​

Адаптер реализует создание, получение, список, подключение, паузу, возобновление, удаление, is_running, set_timeout и метрики. Поддерживаются фильтры по метаданным и состояниям running/paused.

Важные границы:

  • Sandbox.pause() выполняет сохраняющую файловую систему остановку Just Run. Последующий Sandbox.connect() восстанавливает файловую систему, но запущенные процессы и память VM не сохраняются. Поэтому поведение паузы в оригинальном E2B и в Just Run не взаимозаменяемо.
  • pause(), connect() (когда требуется возобновление) и kill() отвечают 409 (код E2B conflict), пока песочницей владеет другая операция: идущая остановка или гибернация, сохранение как шаблон, перенос. kill() во время гибернации отклоняется так же. Заголовок Retry-After сохраняется в ответе и равен 1, пока владелец еще останавливает песочницу. Оригинальный SDK не повторяет запрос сам, поэтому подождите и повторите вызов.
  • connect() к песочнице, которая еще останавливается, возобновляет ее из локальной копии этой остановки, а не опрашивает ее завершение. Если копия не подготовлена примерно за 10 секунд, вызов отвечает 409 с Retry-After.
  • По истечении таймаута используется тот же путь остановки с сохранением файловой системы. E2B-настройки жизненного цикла вроде auto_resume не входят в контракт совместимости: явно вызывайте Sandbox.connect() перед следующей операцией.
  • Подключение к уже работающей песочнице может продлить срок ее работы, но более короткий таймаут при подключении не сокращает существующий срок. Для намеренного сброса используйте set_timeout().
  • Пагинация списков не реализована. limit может ограничить коллекцию, но nextToken не действует, а ответ всегда сообщает об отсутствии следующей страницы.
  • get_metrics() возвращает текущий преобразованный замер. Параметры start и end не дают исторический временной ряд через адаптер.

Собственная модель состояний описана в разделе «Жизненный цикл песочницы».

Команды и процессы​

Проверенное ядро включает:

  • commands.run() на переднем плане и в фоне;
  • стриминг stdout и stderr;
  • просмотр, подключение и завершение фоновых процессов;
  • синхронную отправку stdin работающему процессу;
  • переменные окружения и абсолютные или относительные от домашнего каталога рабочие директории.

Слой совместимости преобразует только сигналы завершения и принудительного завершения. Очень короткий клиентский таймаут может вернуть HTTP-таймаут оригинального SDK вместо TimeoutException E2B. Асинхронный stdin не является проверенным сценарием.

Файлы и каталоги​

Адаптер поддерживает основные операции files:

  • чтение и запись текста или бинарных данных;
  • запись нескольких файлов;
  • exists, info и просмотр каталога;
  • создание каталогов, переименование или перемещение и удаление.

Относительные пути разрешаются под /home/user; для переносимости приложения лучше использовать абсолютные пути. Содержимое файлов проходит через ограниченные по размеру HTTP- и gRPC-пути, поэтому лимиты загрузки конкретной инсталляции продолжают действовать.

PTY-сессии​

Поддерживаются создание PTY, получение вывода, отправка ввода и изменение размера активного PTY. Повторное подключение к тому же PTY после отключения не поддерживается: после разрыва клиента запускайте новый PTY.

Намеренные пробелы совместимости​

В контракт адаптера не входят следующие возможности оригинального E2B:

  • снимки E2B и создание из снимка;
  • Volumes E2B;
  • API сборки шаблонов — адаптер создает песочницы только из уже существующих шаблонов Just Run;
  • SDK e2b-code-interpreter и @e2b/code-interpreter;
  • стриминг watch_dir и надежный паритет наблюдения за каталогами;
  • подписанные E2B URL файлов;
  • get_host() и хост превью вида {port}-{sandbox}.{domain} — используйте сетевые возможности и открытие портов Just Run;
  • allow_internet_access, сетевые ACL E2B, маскирование хоста и токены доступа к трафику;
  • автоматическое возобновление по файловой, командной или HTTP-активности;
  • подключение к PTY после отключения;
  • совместимость с JavaScript/TypeScript SDK и версиями Python кроме зафиксированной.

Неизвестные поля запроса могут быть проигнорированы слоем совместимости. Успешный вызов не означает, что применена каждая опция оригинального E2B. Не переносите E2B-специфичные настройки жизненного цикла и сети, если они прямо не перечислены на этой странице.

Диагностика типичных ошибок​

Запрос к управляющей части возвращает 401. Убедитесь, что E2B_API_URL заканчивается на /e2b, а E2B_API_KEY содержит действующий персональный токен Just Run, а не ключ E2B Cloud.

Изменяющая операция возвращает 403. Вероятно, у персонального токена права Только чтение. Для интеграции, управляющей жизненным циклом песочниц, создайте персональный токен с правами Полные.

Создание работает, но команды или файлы возвращают 401. Оставьте E2B_SANDBOX_URL равным адресу без /e2b и позвольте SDK передавать возвращенный envdAccessToken. Пересоздайте SDK-объект или подключитесь заново вместо ручного составления запросов к части для работы с данными.

Проверка работоспособности возвращает 502 или is_running() равен false. У песочницы нет активного управляющего компонента-владельца, обычно потому что она приостановлена или остановлена. Вызовите Sandbox.connect(sandbox_id), чтобы восстановить возобновляемую песочницу.

pause(), connect() или kill() возвращает 409. Песочницей владеет другая операция жизненного цикла. Подождите интервал Retry-After (или несколько секунд, если заголовка нет) и повторите вызов.

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