Отпустите локальный HTTP-клиент, не завершая песочницу. Идемпотентно.

Не выполняет действий для песочниц пула (клиент принадлежит хосту пула).

Переподключитесь к запущенному песочному окружению из любого места, используя только его id.

Создайте отдельную песочницу (один HF Job) и блокируйте выполнение, пока она не будет готова (~7 с на cpu-basic).

Каждый песочница представляет собой полностью изолированную виртуальную машину, поэтому это правильный выбор для GPU-нагрузок или недоверенного кода. Чтобы развернуть множество недорогих CPU-песочниц, используйте SandboxPool.

Задача выполняется с фиксированным максимальным временем жизни 24 часа; idle_timeout — это настоящий «страж»: бездействующий песочный контейнер завершает работу задолго до этого срока.

Для изображения достаточно /bin/sh. Сервер песочницы загружается при запуске с помощью wget/curl, если они доступны, в противном случае он считывается из постоянно смонтированного серверного бакета (что добавляет ~2-3 секунды к холодному запуску, поэтому наличие wget/curl позволяет сохранить скорость).

Перечислите фоновые процессы этой песочницы.

Возвращает процессы, запущенные с помощью Sandbox.run()(..., background=True); остановить один из них можно с помощью SandboxProcess.kill(). Недавно завершённые процессы остаются в списке (с running=False и их exit_code); сервер хранит ограниченное количество таких процессов, поэтому песочница, в которой было выполнено тысячи коротких команд, не будет перечислять их все.

Публичный URL, который проксирует запросы на сервер, работающий внутри этой песочницы.

Запросы к возвращённому URL пересылаются песочным сервером внутри задания на сервер, запущенный вами в песочнице на port, включая апгрейды WebSocket (ws(s)://) и потоковые ответы. Используйте вместе с proxy_headers для аутентификации.

Как песочница должна слушать port:

• Пул / общая песочница: она не может привязать TCP-порт (Landlock), поэтому привяжите unix-сокет к $SBX_PROXY_DIR/<port>.sock (переменная окружения SBX_PROXY_DIR задана в каждой песочнице). Например, uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• Выделенная песочница: привяжите обычный TCP-порт к 127.0.0.1:<port>. (Вы также можете напрямую открыть порт через прокси задачи, минуя этот шаг.)

>>> url = sandbox.proxy_url_for(8000, "/ws", scheme="wss://")
>>> import websockets
>>> async with websockets.connect(url, additional_headers=sandbox.proxy_headers) as ws:
...     await ws.send("hello")

Выполните команду в песочнице и дождитесь её завершения, получая вывод в реальном времени.

При background=True команда запускается в фоновом режиме, а run сразу возвращает объект SandboxProcess, не дожидаясь завершения процесса, — это удобно для серверов и других долгоживущих процессов. Позже их можно получить списком с помощью Sandbox.processes() и остановить один из них с помощью SandboxProcess.kill(). Опции потоковой передачи и ожидания (timeout, stdin, on_stdout, on_stderr, check) в этом режиме не применяются.

Возвращает: SandboxCommandResult (с exit_code, stdout, stderr, duration_ms) или SandboxProcess, если background=True.

Освободить пул. Идемпотентно.

Для созданного пула это завершает все хостовые задания (а следовательно, и все их песочницы). Для обработчика, подключённого через connect(), освобождаются только локальные HTTP-клиенты: общие хосты могут обслуживать других клиентов, поэтому — как и в случае с Sandbox.connect() — выход из блока with не должен их останавливать. Хосты подключённого пула следует завершать явно с помощью hf sandbox pool delete <id>.

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

Вызывает SandboxError, если хостовую задачу не удалось отменить, указывая задачи, которые всё ещё выполняются — они продолжают тарифицироваться, а их записи в кэше сохраняются, чтобы они оставались доступными для поиска. Если close() вызывается через __exit__ при уже возникшем исключении, ошибка логируется, чтобы не маскировать исходную ошибку.

Переподключитесь к работающему пулу по идентификатору с любого компьютера — локальное состояние не требуется.

Находит работающий хост с меткой pool_id и пересобирает конфигурацию пула (image/flavor/density/host-idle) из спецификации и переменных окружения задания этого хоста, возвращая SandboxPool, готовый к create() для создания дополнительных песочниц — с размещением на работающих хостах или запуском дубликата (с той же конфигурацией), если они заполнены.

Вызывает SandboxError, если не найден ни один работающий хост (пул перестаёт существовать, когда все его хосты исчезают — по истечении времени простоя или принудительно завершены).

Создайте один песочный контейнер, при необходимости развернув хост.

Повторно использует хост со свободной ёмкостью (из этого пула или «тёплый» хост, найденный по меткам задания / в локальном кэше) перед запуском нового, поэтому вызов create() для «тёплого» хоста занимает примерно один round-trip. Вызывайте его многократно для распределения нагрузки; используйте warm_up (или warm), чтобы заранее подготовить хосты и избежать холодного запуска при первых вызовах. Если хост заполняется под нами (другой процесс занял его) или кэшированный хост исчезает, песочница перемещается на другой хост (или на новый).

Убедитесь, что запущены num_hosts пустых хостов, и оставьте их запущенными. Возвращает идентификаторы задач хостов пула.

Используется для предварительного «создания» пула: хосты несут метку и конфигурацию пула (в переменных окружения), поэтому последующий вызов SandboxPool.connect(pool_id) (даже с другой машины) находит их и запускает песочницы без холодного старта. Хосты продолжают тарифицироваться, пока не будут остановлены или не окажутся в режиме простоя.

Перед запуском новых узлов принимает уже работающие хосты для этого пула (находятся по меткам задач), поэтому вызов warm() после connect() — или повторный вызов warm() — доводит количество узлов до num_hosts, а не дублирует активные хосты и не превышает max_hosts.

Завершить фоновый процесс. Идемпотентно.

Возвращает, является ли этот вызов причиной остановки: False означает, что процесс уже завершился или был принудительно остановлен, что не является ошибкой.

Обратите внимание, что потомок, отключающий себя с помощью setsid(), покидает сигнальную группу процессов и переживает этот вызов. Удалите песочницу, чтобы убедиться, что всё, что она запустила, было завершено.