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

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

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

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

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

## Когда использовать адаптер[​](#when-to-use-the-adapter "Прямая ссылка на Когда использовать адаптер")

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

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

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

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

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

* инсталляция Just Run с включенным адаптером E2B;
* публичный адрес шлюза и его имя хоста;
* [персональный токен](/accounts/personal-access-tokens.md) с правами *Полные* для аккаунта, которому будут принадлежать песочницы;
* существующий [шаблон Just Run](/templates/choose-a-template), например `base`.

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

## Настройка Python SDK[​](#configure-the-python-sdk "Прямая ссылка на Настройка 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.

## Проверенный сценарий[​](#run-a-verified-workflow "Прямая ссылка на Проверенный сценарий")

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

```
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.

## Разделение аутентификации[​](#how-authentication-is-split "Прямая ссылка на Разделение аутентификации")

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

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

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

## Поддерживаемые возможности[​](#supported-surface "Прямая ссылка на Поддерживаемые возможности")

### Жизненный цикл и поиск[​](#lifecycle-and-discovery "Прямая ссылка на Жизненный цикл и поиск")

Адаптер реализует создание, получение, список, подключение, паузу, возобновление, удаление, `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` не дают исторический временной ряд через адаптер.

Собственная модель состояний описана в разделе [«Жизненный цикл песочницы»](/sandboxes/lifecycle.md).

### Команды и процессы[​](#commands-and-processes "Прямая ссылка на Команды и процессы")

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

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

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

### Файлы и каталоги[​](#files-and-directories "Прямая ссылка на Файлы и каталоги")

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

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

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

### PTY-сессии[​](#pty-sessions "Прямая ссылка на PTY-сессии")

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

## Намеренные пробелы совместимости[​](#deliberate-compatibility-gaps "Прямая ссылка на Намеренные пробелы совместимости")

В контракт адаптера не входят следующие возможности оригинального 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](/sandboxes/networking-and-previews.md);
* `allow_internet_access`, сетевые ACL E2B, маскирование хоста и токены доступа к трафику;
* автоматическое возобновление по файловой, командной или HTTP-активности;
* подключение к PTY после отключения;
* совместимость с JavaScript/TypeScript SDK и версиями Python кроме зафиксированной.

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

## Диагностика типичных ошибок[​](#diagnose-common-failures "Прямая ссылка на Диагностика типичных ошибок")

**Запрос к управляющей части возвращает `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.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Персональные токены](/accounts/personal-access-tokens.md)
* [Основы работы с API](/developers/api-fundamentals.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Файлы и Git](/sandboxes/files-and-git.md)
* [Справочник REST API](/api-reference/rest.md)
* [Документация оригинального E2B](https://e2b.dev/docs/)
