샌드박스를 종료하지 않고 로컬 HTTP 클라이언트를 해제합니다. 멱등적입니다.

풀 샌드박스에 대해서는 아무 동작도 수행하지 않습니다(클라이언트가 풀의 호스트에 속해 있음).

id만 사용하여 어디서든 실행 중인 샌드박스에 다시 연결합니다.

전용 샌드박스(하나의 HF Job)를 생성하고 준비가 될 때까지 차단합니다(cpu-basic에서 약 7초 소요).

각 샌드박스는 완전히 격리된 VM이므로 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에서 리스닝해야 하는 방법:

• Pool / 공유 샌드박스: TCP 포트 바인딩이 불가능합니다(Landlock). 따라서 $SBX_PROXY_DIR/<port>.sock 위치에 unix socket을 바인딩해야 합니다(SBX_PROXY_DIR 환경 변수는 모든 샌드박스에 설정되어 있습니다). 예: uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• 전용 샌드박스: 127.0.0.1:<port>에 일반 TCP 포트를 바인딩합니다. (여기를 거치지 않고 job proxy를 통해 포트를 직접 노출할 수도 있습니다.)

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

샌드박스에서 명령을 실행하고 완료까지 대기하며, 출력을 실시간으로 스트리밍합니다.

With background=True the command is started detached and run returns a SandboxProcess immediately, without waiting for it to finish — handy for servers and other long-running processes. List them later with Sandbox.processes() and stop one with SandboxProcess.kill(). The streaming/wait-only options (timeout, stdin, on_stdout, on_stderr, check) don’t apply in that mode.

SandboxCommandResult(exit_code, stdout, stderr, duration_ms 포함)를 반환하거나, background=True인 경우 SandboxProcess를 반환합니다.

풀을 해제합니다. 멱등적입니다.

생성된 풀의 경우, 이 작업은 모든 호스트 작업(따라서 모든 샌드박스)을 종료합니다. connect()된 핸들의 경우, 로컬 HTTP 클라이언트만 해제합니다. 공유 호스트는 다른 클라이언트를 서비스 중일 수 있으므로, Sandbox.connect()와 마찬가지로 with 블록을 벗어나도 호스트를 종료하지 않아야 합니다. 연결된 풀의 호스트는 hf sandbox pool delete <id>를 사용하여 명시적으로 종료하십시오.

이 핸들에서 시작된 호스트만 취소됩니다. 레이블을 통해 발견된 호스트는 다른 프로세스의 샌드박스를 서비스 중일 수 있으므로 종료되지 않고 해제됩니다.

호스트 작업을 취소할 수 없는 경우 SandboxError를 발생시키며, 여전히 실행 중인 작업 이름을 명시합니다. 해당 작업은 계속 과금되며, 캐시 항목이 유지되어 검색 가능 상태로 남습니다. 예외가 이미 발생 중인 상태에서 __exit__를 통해 close()에 도달하면, 원래 오류를 가리지 않도록 실패가 기록됩니다.

id를 사용하여 로컬 상태 없이 어떤 머신에서든 실행 중인 풀에 다시 연결합니다.

pool_id 레이블이 지정된 실행 중인 호스트를 찾아 해당 호스트 작업의 스펙과 환경 변수에서 풀 구성(이미지/플래버/밀도/호스트-유휴)을 재구성하고, create()를 통해 추가 샌드박스를 생성할 준비가 된 SandboxPool을 반환합니다. 실행 중인 호스트에 패킹하거나, 호스트가 가득 차면 동일한 구성으로 복제 호스트를 부팅합니다.

실행 중인 호스트를 찾을 수 없으면 SandboxError를 발생시킵니다. (풀은 모든 호스트가 사라지면 더 이상 존재하지 않습니다 — 유휴 타임아웃 또는 종료된 경우).

필요한 경우 호스트를 프로비저닝하여 샌드박스를 하나 생성합니다.

여유 용량이 있는 호스트(해당 풀의 호스트 또는 job labels / 로컬 캐시를 통해 찾은 warm host)를 재사용한 후 새 호스트를 부팅하므로, warm host에 대한 create() 호출 비용은 약 1회 왕복 통신 수준입니다. 반복 호출하여 fan out을 수행하고, warm_up(또는 warm)을 호출하여 호스트를 사전 프로비저닝함으로써 초기 호출 시 cold start를 방지합니다. 호스트가 다른 프로세스에 의해 가득 차거나 캐시된 호스트가 사라진 경우, 샌드박스는 다른 호스트(또는 새 호스트)에 다시 배치됩니다.

num_hosts개의 빈 호스트가 실행 중인지 확인하고 실행 상태를 유지합니다. 풀의 호스트 작업 ID를 반환합니다.

풀을 사전에 “생성”하는 데 사용됩니다. 호스트는 풀 라벨과 구성(환경 변수에 포함)을 보유하므로, 이후 SandboxPool.connect(pool_id) 호출(다른 머신에서 실행하더라도) 시 해당 호스트를 찾아 콜드 스타트 없이 샌드박스를 생성합니다. 호스트는 종료되거나 유휴 상태가 될 때까지 계속 과금됩니다.

이 풀에서 이미 실행 중인 호스트를(잡 라벨을 통해 발견) 부팅 전에 채택하므로, connect() 이후의 warm() — 또는 반복된 warm() — 은 실행 중인 호스트를 중복하여 max_hosts를 초과하는 대신 num_hosts까지 채웁니다.

백그라운드 프로세스를 종료합니다. 멱등적입니다.

이 호출이 프로세스를 종료했는지 여부를 반환합니다: False는 프로세스가 이미 종료되었거나 종료 처리되었음을 의미하며, 이는 오류가 아닙니다.

setsid()을 호출하여 분리되는 자손 프로세스는 시그널이 전송된 프로세스 그룹을 떠나 이 호출보다 오래 생존합니다. 샌드박스가 시작한 모든 프로세스가 종료되었는지 확인하려면 샌드박스를 삭제하세요.