Libere o cliente HTTP local sem encerrar o sandbox. Idempotente.

Sem efeito para sandboxes de pool (o cliente pertence ao host da pool).

Reconecte-se a um sandbox em execução de qualquer lugar, usando apenas seu id.

Crie um sandbox dedicado (um HF Job) e bloqueie até que ele esteja pronto (~7s em cpu-basic).

Cada sandbox é uma VM isolada completa, portanto, esta é a escolha correta para cargas de trabalho de GPU ou código não confiável. Para distribuir muitos sandboxes de CPU de baixo custo, use SandboxPool.

O job é executado com uma vida útil máxima fixa de 24h; idle_timeout é o verdadeiro responsável — um sandbox ocioso se desliga muito antes disso.

A imagem precisa apenas de /bin/sh. O servidor sandbox é baixado na inicialização com wget/curl, se disponível; caso contrário, é lido de um bucket de servidor sempre montado (o que adiciona ~2-3s ao cold start, então incluir wget/curl mantém o processo rápido).

Liste os processos em segundo plano deste sandbox.

Retorna os processos iniciados com Sandbox.run()(..., background=True); encerre um deles com SandboxProcess.kill(). Processos concluídos recentemente permanecem listados (com running=False e seu exit_code); o servidor mantém um número limitado deles, de modo que um sandbox que executou milhares de comandos curtos não os listará todos.

URL pública que faz proxy para um servidor executado dentro deste sandbox.

As solicitações à URL retornada são encaminhadas pelo servidor de sandbox do job para um servidor que você iniciou na sandbox na port, incluindo upgrades de WebSocket (ws(s)://) e respostas em streaming. Combine-o com proxy_headers para autenticação.

Como o sandbox deve escutar na port:

• Pool / sandbox compartilhado: não é possível vincular uma porta TCP (Landlock), portanto vincule um socket unix em $SBX_PROXY_DIR/<port>.sock (a variável de ambiente SBX_PROXY_DIR é definida em todos os sandboxes). Por exemplo, uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• Sandbox dedicado: vincule uma porta TCP normal em 127.0.0.1:<port>. (Você também pode expor a porta diretamente via o proxy do job, sem passar por aqui.)

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

Execute um comando no sandbox e aguarde por ele, transmitindo a saída ao vivo.

Com background=True, o comando é iniciado de forma destacada e run retorna um SandboxProcess imediatamente, sem aguardar a conclusão — útil para servidores e outros processos de longa duração. Liste-os posteriormente com Sandbox.processes() e encerre um deles com SandboxProcess.kill(). As opções de streaming/apenas espera (timeout, stdin, on_stdout, on_stderr, check) não se aplicam nesse modo.

Retorna: um SandboxCommandResult (com exit_code, stdout, stderr, duration_ms), ou um SandboxProcess quando background=True.

Libere o pool. Idempotente.

Para um pool que criamos, isso encerra todos os jobs do host (e, portanto, todos os seus sandboxes). Para um handle conectado via connect(), ele apenas libera os clientes HTTP locais: os hosts compartilhados podem estar atendendo a outros clientes, então — assim como Sandbox.connect() — sair de um bloco with não deve encerrá-los. Encerre explicitamente os hosts de um pool conectado com hf sandbox pool delete <id>.

Apenas hosts que iniciaram este handle são cancelados. Um host descoberto por meio de rótulos pode estar servindo sandboxes de outro processo, portanto, ele é liberado em vez de ser encerrado.

Gera SandboxError se um job do host não puder ser cancelado, indicando os jobs que ainda estão em execução — eles continuam gerando cobrança e suas entradas de cache são mantidas para que permaneçam descobertas. Quando close() é alcançado por meio de __exit__ com uma exceção já em andamento, a falha é registrada em log, para que não possa mascarar o erro original.

Reconecte-se a um pool em execução pelo id, de qualquer máquina — sem necessidade de estado local.

Encontra um host em execução rotulado com pool_id e reconstrói a configuração do pool (image/flavor/density/host-idle) a partir da especificação e das variáveis de ambiente do job desse host, retornando um SandboxPool pronto para create() mais sandboxes — empacotando nos hosts em execução ou iniciando um duplicado (mesma configuração) quando eles estiverem cheios.

Gera SandboxError se nenhum host em execução for encontrado (um pool deixa de existir quando todos os seus hosts são removidos — por tempo limite de inatividade ou por serem encerrados).

Crie um sandbox, provisionando um host, se necessário.

Reutiliza um host com capacidade livre (deste pool, ou um host quente encontrado via rótulos de job / o cache local) antes de iniciar um novo, de modo que um create() em um host quente custa ~uma ida e volta. Chame-o repetidamente para distribuir as chamadas; use warm_up (ou warm) para provisionar hosts antecipadamente e evitar um início frio nas primeiras chamadas. Se um host encher sob nós (outro processo o ocupou) ou um host em cache desaparecer, o sandbox é realocado em outro host (ou em um novo).

Garanta que num_hosts host(s) vazio(s) estejam em execução e mantenha-os em execução. Retorna os ids dos jobs dos hosts do pool.

Usado para “criar” um pool antecipadamente: os hosts carregam o rótulo e a configuração do pool (em suas variáveis de ambiente), de modo que uma chamada posterior a SandboxPool.connect(pool_id) (mesmo de outra máquina) os encontra e inicia sandboxes sem um cold start. Os hosts continuam sendo cobrados até serem encerrados ou ficarem ociosos.

Adota hosts já em execução para este pool (encontrados via rótulos de job) antes de iniciar novos, de modo que um warm() após connect() — ou um warm() repetido — complete até num_hosts em vez de duplicar hosts ativos e ultrapassar max_hosts.

Encerre o processo em segundo plano. Idempotente.

Indica se esta chamada é o que a interrompeu: False significa que ela já havia saído ou sido encerrada, o que não é um erro.

Observe que um descendente que se desconecta com setsid() deixa o grupo de processos sinalizado e sobrevive a esta chamada. Exclua o sandbox para ter certeza de que tudo o que ele iniciou foi removido.