Release the local HTTP client without terminating the sandbox. Idempotent.

No-op for pool sandboxes (the client belongs to the pool’s host).

Reattach to a running sandbox from anywhere, using only its id.

Create a dedicated sandbox (one HF Job) and block until it is ready (~7s on cpu-basic).

Each sandbox is a full isolated VM, so this is the right choice for GPU workloads or untrusted code. To fan out many cheap CPU sandboxes instead, use SandboxPool.

The job runs with a fixed 24h maximum lifetime; idle_timeout is the real keeper — an idle sandbox shuts itself down well before that.

The image only needs /bin/sh. The sandbox server is downloaded at startup with wget/curl if available, otherwise read off an always-mounted server bucket (which adds ~2-3s to cold start, so shipping wget/curl keeps it fast).

List the background processes of this sandbox.

Returns the processes started with Sandbox.run()(..., background=True); stop one with SandboxProcess.kill(). Recently completed processes stay listed (with running=False and their exit_code); the server keeps a bounded number of them, so a sandbox that has run thousands of short commands will not list them all.

Public URL that proxies through to a server running inside this sandbox.

Requests to the returned URL are forwarded by the in-job sandbox server to a server you started in the sandbox on port, including WebSocket (ws(s)://) upgrades and streamed responses. Pair it with proxy_headers for auth.

How the sandbox must listen on port:

• Pool / shared sandbox: it cannot bind a TCP port (Landlock), so bind a unix socket at $SBX_PROXY_DIR/<port>.sock (the SBX_PROXY_DIR env var is set in every sandbox). E.g. uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• Dedicated sandbox: bind a normal TCP port on 127.0.0.1:<port>. (You can also expose the port directly via the job proxy without going through here.)

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

Run a command in the sandbox and wait for it, streaming output live.

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.

Returns: a SandboxCommandResult (with exit_code, stdout, stderr, duration_ms), or a SandboxProcess when background=True.

Release the pool. Idempotent.

For a pool we created, this terminates all host jobs (and therefore all their sandboxes). For a connect()‘d handle it only releases the local HTTP clients: the shared hosts may be serving other clients, so — like Sandbox.connect() — leaving a with block must not tear them down. Terminate a connected pool’s hosts explicitly with hf sandbox pool delete <id>.

Only hosts this handle started are cancelled. A host discovered via labels may be serving another process’ sandboxes, so it is released rather than terminated.

Raises SandboxError if a host job could not be cancelled, naming the jobs that are still running — they keep billing, and their cache entries are kept so they stay discoverable. When close() is reached through __exit__ with an exception already in flight, the failure is logged instead, so it cannot mask the original error.

Reattach to a running pool by id, from any machine — no local state needed.

Finds a running host labelled with pool_id and rebuilds the pool’s config (image/flavor/density/host-idle) from that host job’s spec and env vars, returning a SandboxPool ready to create() more sandboxes — packing onto the running hosts, or booting a duplicate (same config) when they are full.

Raises SandboxError if no running host is found (a pool stops existing once all of its hosts are gone — idle-timed-out or killed).

Create one sandbox, provisioning a host if needed.

Reuses a host with free capacity (this pool’s, or a warm host found via job labels / the local cache) before booting a new one, so a create() against a warm host costs ~one round-trip. Call it repeatedly to fan out; use warm_up (or warm) to pre-provision hosts and avoid a cold start on the first calls. If a host fills up under us (another process packed it) or a cached host is gone, the sandbox is re-placed on another host (or a fresh one).

Ensure num_hosts empty host(s) are running and leave them running. Returns the pool’s host job ids.

Used to “create” a pool up front: the hosts carry the pool label and config (in their env vars), so a later SandboxPool.connect(pool_id) (even from another machine) finds them and spawns sandboxes without a cold start. The hosts keep billing until killed or idle.

Adopts hosts already running for this pool (found via job labels) before booting, so a warm() after connect() — or a repeated warm() — tops up to num_hosts instead of duplicating live hosts and blowing past max_hosts.

Terminate the background process. Idempotent.

Returns whether this call is what stopped it: False means it had already exited or been terminated, which is not an error.

Note that a descendant which detaches with setsid() leaves the signalled process group and outlives this call. Delete the sandbox to be certain everything it started is gone.