Phóng thích client HTTP cục bộ mà không kết thúc sandbox. Idempotent.

Không thực hiện thao tác nào với các sandbox pool (client thuộc về host của pool).

Kết nối lại với một sandbox đang chạy từ bất kỳ đâu, chỉ cần sử dụng id của nó.

Tạo một sandbox riêng (một HF Job) và chặn cho đến khi nó sẵn sàng (~7s trên cpu-basic).

Mỗi sandbox là một VM cách ly hoàn toàn, vì vậy đây là lựa chọn phù hợp cho các tác vụ GPU hoặc mã không đáng tin cậy. Để triển khai nhiều sandbox CPU giá rẻ hơn, hãy sử dụng SandboxPool.

Công việc chạy với thời gian tồn tại tối đa cố định là 24 giờ; idle_timeout mới là yếu tố thực sự quyết định — một sandbox ở trạng thái nhàn rỗi sẽ tự động tắt trước thời điểm đó rất lâu.

Hình ảnh chỉ cần /bin/sh. Máy chủ sandbox sẽ được tải xuống khi khởi động bằng wget/curl nếu có sẵn, nếu không sẽ được đọc từ một server bucket luôn được gắn (điều này thêm ~2-3s vào thời gian khởi động lạnh, vì vậy việc cung cấp wget/curl giúp giữ tốc độ nhanh).

Liệt kê các tiến trình nền của sandbox này.

Trả về các tiến trình được khởi chạy bằng Sandbox.run()(..., background=True); dừng một tiến trình bằng SandboxProcess.kill(). Các tiến trình vừa hoàn thành vẫn được liệt kê (với running=False và exit_code của chúng); máy chủ chỉ giữ một số lượng có giới hạn các tiến trình này, nên một sandbox đã chạy hàng nghìn lệnh ngắn sẽ không liệt kê tất cả chúng.

URL công khai được proxy đến một máy chủ chạy bên trong sandbox này.

Các yêu cầu đến URL được trả về sẽ được chuyển tiếp bởi máy chủ sandbox trong job đến máy chủ mà bạn đã khởi chạy trong sandbox trên port, bao gồm cả nâng cấp WebSocket (ws(s)://) và các phản hồi dạng luồng. Kết hợp với proxy_headers để xác thực.

Cách sandbox phải lắng nghe trên port:

• Pool / sandbox dùng chung: không thể bind cổng TCP (Landlock), do đó hãy bind một unix socket tại $SBX_PROXY_DIR/<port>.sock (biến môi trường SBX_PROXY_DIR được đặt trong mọi sandbox). Ví dụ: uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• Không gian riêng biệt: gắn một cổng TCP thông thường vào 127.0.0.1:<port>. (Bạn cũng có thể phơi bày trực tiếp cổng này qua proxy của job mà không cần đi qua đây.)

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

Chạy một lệnh trong sandbox và chờ nó, đồng thời phát trực tiếp đầu ra.

Với background=True, lệnh được khởi chạy ở chế độ tách rời và run trả về một SandboxProcess ngay lập tức, không chờ nó hoàn tất — rất tiện cho các server và các tiến trình chạy dài khác. Bạn có thể liệt kê chúng sau đó bằng Sandbox.processes() và dừng một tiến trình bằng SandboxProcess.kill(). Các tùy chọn chỉ dành cho streaming/chờ (timeout, stdin, on_stdout, on_stderr, check) không áp dụng trong chế độ đó.

Trả về: một SandboxCommandResult (với exit_code, stdout, stderr, duration_ms), hoặc một SandboxProcess khi background=True.

Giải phóng pool. Idempotent.

Đối với pool do chúng ta tạo, thao tác này sẽ kết thúc tất cả các tác vụ host (và do đó là tất cả các sandbox của chúng). Đối với handle đã được connect(), nó chỉ giải phóng các client HTTP cục bộ: các host dùng chung có thể đang phục vụ các client khác, nên — giống như Sandbox.connect() — việc rời khỏi khối with không được phép hủy chúng. Hãy kết thúc các host của pool đã kết nối một cách tường minh bằng hf sandbox pool delete <id>.

Chỉ các host mà chúng ta đã khởi động mới bị hủy. Một host được phát hiện thông qua nhãn có thể đang phục vụ các sandbox của một tiến trình khác, do đó nó được giải phóng thay vì bị kết thúc.

Ném SandboxError nếu một tác vụ trên host không thể bị hủy, kèm theo tên của các tác vụ vẫn đang chạy — chúng tiếp tục bị tính phí và các mục cache của chúng được giữ lại để vẫn có thể tìm thấy. Khi close() được gọi thông qua __exit__ trong khi một ngoại lệ đã đang diễn ra, lỗi sẽ được ghi log thay vì được ném ra, để không che lấp lỗi gốc.

Gắn lại vào một pool đang chạy theo id, từ bất kỳ máy nào — không cần trạng thái cục bộ.

Tìm một host đang chạy được gắn nhãn pool_id và xây dựng lại cấu hình của pool (image/flavor/density/host-idle) từ spec và các biến môi trường của job host đó, trả về một SandboxPool sẵn sàng để create() thêm các sandbox — đóng gói lên các host đang chạy, hoặc khởi động một bản sao (cùng cấu hình) khi chúng đã đầy.

Ném SandboxError nếu không tìm thấy host nào đang chạy (một pool sẽ ngừng tồn tại khi tất cả các host của nó biến mất — do hết thời gian chờ nhàn rỗi hoặc bị kết thúc).

Tạo một sandbox, cấp phát một host nếu cần.

Tái sử dụng một host có dung lượng trống (của pool này, hoặc một host ấm được tìm thấy qua nhãn job / bộ nhớ đệm cục bộ) trước khi khởi động một host mới, do đó một lệnh create() trên một host ấm chỉ tốn khoảng một lượt đi-về. Gọi lệnh này nhiều lần để phân tán; sử dụng warm_up (hoặc warm) để cung cấp sẵn các host và tránh khởi động lạnh ở các lần gọi đầu tiên. Nếu một host bị đầy dưới chân chúng ta (một tiến trình khác đã lấp đầy nó) hoặc một host trong bộ nhớ đệm đã biến mất, sandbox sẽ được đặt lại trên một host khác (hoặc một host mới).

Đảm bảo num_hosts host trống đang chạy và giữ cho chúng tiếp tục chạy. Trả về các id job của host trong pool.

Được dùng để “tạo” sẵn một pool: các host mang nhãn và cấu hình của pool (trong các biến môi trường của chúng), do đó một lệnh SandboxPool.connect(pool_id) sau đó (ngay cả từ một máy khác) sẽ tìm thấy chúng và khởi tạo các sandbox mà không cần khởi động lạnh. Các host tiếp tục tính phí cho đến khi bị kết thúc hoặc ở trạng thái nhàn rỗi.

Nhận các host đã đang chạy cho pool này (tìm thấy qua nhãn của job) trước khi khởi động, do đó một warm() sau connect() — hoặc một warm() lặp lại — sẽ bổ sung lên đến num_hosts thay vì nhân bản các host đang hoạt động và vượt quá max_hosts.

Kết thúc tiến trình nền. Idempotent.

Trả về việc cuộc gọi này có phải là nguyên nhân khiến nó dừng lại hay không: False có nghĩa là nó đã thoát hoặc bị kết thúc trước đó, điều này không phải là lỗi.

Lưu ý rằng một tiến trình con tách ra bằng setsid() sẽ rời khỏi nhóm tiến trình được gửi tín hiệu và tồn tại lâu hơn lệnh gọi này. Hãy xóa sandbox để chắc chắn rằng mọi thứ nó khởi động đã bị xóa sạch.