Liberar el cliente HTTP local sin terminar el sandbox. Idempotente.

Sin efecto para los sandbox de pool (el cliente pertenece al host del pool).

Vuelve a conectar a un sandbox en ejecución desde cualquier lugar, usando solo su id.

Cree un sandbox dedicado (un solo HF Job) y bloquee hasta que esté listo (~7 s en cpu-basic).

Cada sandbox es una VM aislada completa, por lo que esta es la opción adecuada para cargas de trabajo de GPU o código no confiable. Para desplegar muchos sandboxes de CPU de bajo costo, use SandboxPool.

El trabajo se ejecuta con una vida máxima fija de 24 h; idle_timeout es el verdadero responsable: un sandbox inactivo se apaga mucho antes de ese límite.

La imagen solo necesita /bin/sh. El servidor de sandbox se descarga al inicio con wget/curl si está disponible; de lo contrario, se lee desde un bucket de servidor siempre montado (lo que añade ~2-3 s al arranque en frío, por lo que incluir wget/curl mantiene la velocidad).

Liste los procesos en segundo plano de este sandbox.

Devuelve los procesos iniciados con Sandbox.run()(..., background=True); detenga uno con SandboxProcess.kill(). Los procesos finalizados recientemente permanecen en la lista (con running=False y su exit_code); el servidor mantiene un número limitado de ellos, por lo que un sandbox que haya ejecutado miles de comandos cortos no los enumerará todos.

URL pública que hace de proxy hacia un servidor que se ejecuta dentro de este sandbox.

Las solicitudes a la URL devuelta son reenviadas por el servidor de sandbox del trabajo a un servidor que iniciaste en el sandbox en el port, incluidas las actualizaciones de WebSocket (ws(s)://) y las respuestas transmitidas. Combínalo con proxy_headers para la autenticación.

Cómo debe escuchar el sandbox en el port:

• Pool / sandbox compartido: no puede enlazar un puerto TCP (Landlock), por lo que debe enlazar un socket unix en $SBX_PROXY_DIR/<port>.sock (la variable de entorno SBX_PROXY_DIR se establece en cada sandbox). Por ejemplo, uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• Sandbox dedicado: enlaza un puerto TCP normal en 127.0.0.1:<port>. (También puedes exponer el puerto directamente a través del proxy del trabajo sin pasar por aquí.)

>>> 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")

Ejecuta un comando en el sandbox y espera a que termine, transmitiendo la salida en vivo.

Con background=True, el comando se inicia de forma desacoplada y run devuelve un SandboxProcess de inmediato, sin esperar a que termine; esto resulta útil para servidores y otros procesos de larga duración. Más adelante, puede listarlos con Sandbox.processes() y detener uno con SandboxProcess.kill(). Las opciones de solo streaming/espera (timeout, stdin, on_stdout, on_stderr, check) no se aplican en ese modo.

Devuelve: un SandboxCommandResult (con exit_code, stdout, stderr, duration_ms), o un SandboxProcess cuando background=True.

Liberar el pool. Idempotente.

Para un pool que creamos, esto termina todos los trabajos del host (y, por lo tanto, todos sus sandboxes). Para un handle conectado con connect(), solo libera los clientes HTTP locales: los hosts compartidos pueden estar sirviendo a otros clientes, por lo que — al igual que Sandbox.connect() — salir de un bloque with no debe desmontarlos. Termina los hosts de un pool conectado explícitamente con hf sandbox pool delete <id>.

Solo se cancelan los hosts que gestionan procesos iniciados. Un host descubierto mediante etiquetas puede estar sirviendo los sandbox de otro proceso, por lo que se libera en lugar de terminarse.

Lanza SandboxError si no se pudo cancelar un trabajo del host, indicando los trabajos que siguen en ejecución: siguen generando cargos y se conservan sus entradas de caché para que permanezcan accesibles. Cuando se llega a close() a través de __exit__ con una excepción ya en curso, el fallo se registra en el registro en su lugar, para que no enmascare el error original.

Vincúlate a un pool en ejecución por id, desde cualquier máquina: no se necesita estado local.

Busca un host en ejecución etiquetado con pool_id y reconstruye la configuración del pool (imagen/sabor/densidad/host-idle) a partir de la especificación y las variables de entorno del trabajo de ese host, devolviendo un SandboxPool listo para create() más sandboxes, ya sea agrupándolos en los hosts en ejecución o iniciando un duplicado (misma configuración) cuando estén llenos.

Lanza SandboxError si no se encuentra ningún host en ejecución (un pool deja de existir cuando todos sus hosts desaparecen, ya sea por tiempo de espera inactivo o por haber sido eliminados).

Cree un solo sandbox, aprovisionando un host si es necesario.

Reutiliza un host con capacidad libre (de este pool, o un host cálido encontrado mediante las etiquetas del trabajo / la caché local) antes de iniciar uno nuevo, de modo que una llamada a create() contra un host cálido cuesta aproximadamente un solo viaje de ida y vuelta. Llámalo repetidamente para distribuir la carga; usa warm_up (o warm) para aprovisionar hosts de antemano y evitar un arranque en frío en las primeras llamadas. Si un host se llena bajo nosotros (otro proceso lo llenó) o un host en caché ya no existe, el sandbox se reubica en otro host (o en uno nuevo).

Asegúrese de que num_hosts host(s) vacíos estén en ejecución y déjelos en ejecución. Devuelve los ids de trabajo de los hosts del pool.

Se utiliza para “crear” un pool de antemano: los hosts llevan la etiqueta y la configuración del pool (en sus variables de entorno), por lo que una posterior llamada a SandboxPool.connect(pool_id) (incluso desde otra máquina) los encuentra y genera sandboxes sin un arranque en frío. Los hosts siguen facturando hasta que se terminan o quedan inactivos.

Adopta los hosts que ya están en ejecución para este pool (detectados mediante las etiquetas del trabajo) antes de iniciarlos, de modo que una llamada a warm() después de connect() —o una llamada repetida a warm()— complete hasta num_hosts en lugar de duplicar los hosts activos y superar max_hosts.

Termina el proceso en segundo plano. Idempotente.

Indica si esta llamada es la que lo detuvo: False significa que ya se había cerrado o terminado, lo cual no es un error.

Tenga en cuenta que un descendiente que se desconecta con setsid() abandona el grupo de procesos señalados y sobrevive a esta llamada. Elimine el sandbox para asegurarse de que todo lo que inició ha desaparecido.