Совместимость с 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 использует два набора учетных данных, но приложению не нужно самостоятельно управлять вторым:
- Запросы к управляющей части под
/e2bиспользуют персональный токен Just Run вX-API-Key. Шлюз определяет контекст аккаунта и проверяет владение ресурсом и права персонального токена. - Создание или подключение возвращает отдельный для песочницы
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(код E2Bconflict), пока песочницей владеет другая операция: идущая остановка или гибернация, сохранение как шаблон, перенос.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.