+ j,^RIt^RIt^RIt^RIt^RIt^RIt^RIHt^RIH t ^RI H t H t ^RI Ht^RIHt^RIHtHtHtHtHtHtHt^RIHt^RIt^R IHt^R IHtH t H!t!H"t"H#t#H$t$^R I%H&t&^R I'H(t(H)t)H*t*^R I+H,t,H-t-^RI.H/t/H0t0^RI1H2t2]0Pf!]44t5Rt6Rt7Rt8Rt9Rt:Rt;Rt<]=!]7]8];]<04t>Rt?Rt@RtA^tBRdtCRtD^2tERtFRetGRtHRtIRtJRtKRftL^tMR tNR!tOR"R#ltPR$R%ltQ] !R&R'44tR] !R(R)44tS] !R*R+44tT] R,R-l4tU!R.R/4tVR0R1ltWR2R3ltXR4R5ltYR6R7ltZ!R8R9]P4t\!R:R;4t]!R<R=4t^!R>R?4t_!R@RA4t`RBRCltaRDREltbRFRGltcRHRIltdRJRKlteRLRM/RNROlltfRPRQltgRRRSlthRTRUltiRVRWltjRRRX]H/RYRZlltkRR/R[R\lltlR]R^ltmR_R`ltnRRRa^/RbRclltoR#)gN)ThreadPoolExecutor)contextmanager) dataclassfield)Path) token_hex)AnyBinaryIOCallableIteratorListLiteraloverload)urlparse) constants)HOST_TRUST_TTL CacheContext CachedHostdelete_pool_cacheread_pool_cachesave_pool_cache)Volume)HfHubHTTPErrorSandboxCommandError SandboxError)HfApiJobInfo) get_tokenlogging)parse_durationi?z hf-sandboxzhf-sandbox-mode dedicatedpoolzhf-sandbox-poolzhf-sandbox-noncez python:3.12z0.6.0@bd08d60b3bdab4ddd4e81401b6dacc96e01bcee3a4753e258b99d40c07d81ee324hg>@own namespacenever.z/.hf-sbx-serveraset -e d=/tmp/.sbx-server if command -v wget >/dev/null 2>&1; then wget -q -O "$d" "$SBX_SERVER_URL" elif command -v curl >/dev/null 2>&1; then curl -fsSL -o "$d" "$SBX_SERVER_URL" else cp "$SBX_SERVER_MOUNT/sbx-server-$SBX_SERVER_SHA256" "$d"; fi if command -v sha256sum >/dev/null 2>&1; then actual=$(sha256sum "$d" | cut -d' ' -f1) elif command -v openssl >/dev/null 2>&1; then actual=$(openssl dgst -sha256 -r "$d" | cut -d' ' -f1) elif [ "${SBX_ALLOW_UNVERIFIED_SERVER:-}" = 1 ]; then echo "sbx: SBX_ALLOW_UNVERIFIED_SERVER=1: running the sandbox server unverified" >&2 actual=$SBX_SERVER_SHA256 # opted out, so there is nothing left to compare against else echo "sbx: cannot verify the sandbox server digest: this image has neither sha256sum nor" >&2 echo "sbx: openssl, so refusing to run it. Use an image with either hash tool installed." >&2 echo "sbx: Dedicated jobs may opt out with env={'SBX_ALLOW_UNVERIFIED_SERVER': '1'};" >&2 echo "sbx: pool hosts require setting it in the image environment instead." >&2 exit 1 fi if [ "$actual" != "$SBX_SERVER_SHA256" ]; then echo "sbx: sandbox server digest mismatch: got $actual," >&2 echo "sbx: expected $SBX_SERVER_SHA256." >&2 echo "sbx: refusing to run it. Upgrade huggingface_hub if this client is pinned to a" >&2 echo "sbx: digest that is no longer published." >&2 exit 1 fi chmod +x "$d" unset SBX_SERVER_URL SBX_SERVER_MOUNT SBX_SERVER_SHA256 SBX_ALLOW_UNVERIFIED_SERVER exec "$d" c<V^8dQhR\R\R\/#)hf_tokennoncereturnstr)formats"Y/home/luca/screen-checking/.venv/lib/python3.14/site-packages/huggingface_hub/_sandbox.py __annotate__r2s&ccCcccc\P!VP4RV 2P4\P4P 4#)aDerive the sandbox auth token from the user's HF token and the job's nonce. Stateless: any machine holding the same HF token can recompute it from the nonce stored in the job's labels, so `Sandbox.connect(job_id)` needs no local state. Only the derived token is passed to the sandbox server as a job secret; the HF token itself is not. Scope: one nonce is minted per *job*, not per sandbox. For a dedicated sandbox those are the same thing. In a pool this derives the *host* credential, which manages the pool and can recover per-sandbox tokens -- a leak there is host-wide. Each pooled sandbox also has its own random capability token, minted by the host server, which is what per-sandbox operations and `proxy_headers` use. This is not a hardened boundary in either direction. An untrusted image can own the sandbox port, so don't treat it as a guarantee that credentials stay out of the sandbox; and the token is derived for whichever job carries the matching nonce label, so don't treat holding it as proof of which job you are talking to. z hf-sandbox:)hmacnewencodehashlibsha256 hexdigest)r+r,s&&r1_derive_sandbox_tokenr;s;& 88HOO%UG'<'C'C'Ew~~ V ` ` bbr3c\V^8dQhR\\,\,R\/#)r*durationr-)intfloatr/)r0s"r1r2r2s#$$e c 1$c$r3cf\V\\34'd \V4#\V4#)zBParse a duration like 300, "300s", "10m", "2h", "1d" into seconds.) isinstancer>r?r )r=s&r1_duration_to_secsrBs((S%L))8} ( ##r3cja]tRt^toRtRtRt^t]V3RlRl4t V3RlRlt V3Rlt R t Vt R#) SandboxCommandResultz?Result of a command executed in a sandbox with [`Sandbox.run`].NFc <V^8dQhRS[/#r*r-bool)r0 __classdict__s"r1r2!SandboxCommandResult.__annotate__s##D#r3c VP^8H#r) exit_codeselfs&r1okSandboxCommandResult.oks~~""r3c <V^8dQhRS[/#rFr.)r0rIs"r1r2rJsss#sr3c\VP4^P8:d VPMVPR,R,pRVP RV: RVP R2#)P:NMNz...zSandboxCommandResult(exit_code=z , stdout=z, duration_ms=))lenstdoutrM duration_ms)rOouts& r1__repr__SandboxCommandResult.__repr__sU -3dkkS9IE9Q00@ #P^_c_o_o^ppqrrr3c~<V^8dQh/S[R,;R&S[;R&S[;R&S[R,;R&S[;R&S[;R&#)r*NrMrXstderrsignal timed_outrY)r>r/rH)r0rIs"r1r2rJsYTz  K  K  $Jr3)__name__ __module__ __qualname____firstlineno____doc__r_r`rYpropertyrPr[__annotate_func____static_attributes____classdictcell__rIs@r1rDrDs>I FIK ##ssr3rDcfa]tRt^toRt]!RRR7tRtRtRt Rt V3RlRlt V3Rlt R t VtR#) SandboxProcessaA background process started in a sandbox with [`Sandbox.run`]`(..., background=True)`. List a sandbox's processes with [`Sandbox.processes`] and stop one with [`SandboxProcess.kill`]. Recently completed processes stay in the listing (the server keeps a bounded number of them), so `running` and `exit_code` tell whether a process is still alive or already exited (as of when it was listed). F)reprcompareNTc <V^8dQhRS[/#rFrG)r0rIs"r1r2SandboxProcess.__annotate__s::d:r3c VPf \R4hVPPRRVP 24p\ VP 4P RR44#)a^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. zThis process cannot be stopped individually: its sandbox runs a sandbox server that predates opaque process ids, so the server never issued one. Recycle the pool's hosts, or delete the sandbox to stop everything it started.DELETEz /processes/killedF)idr_sandbox_requestrHjsonget)rOresponses& r1killSandboxProcess.killsa 77?U  ==))(k$''4KLHMMO''%899r3c<V^8dQh/S[R,;R&S[;R&S[S[S[,,;R&R;R&S[R,;R&S[R,;R&S[;R &S[R,;R &#) r*NrupidcmdSandboxrvtag started_at_msrunningrM)r/r>r rH)r0rIs"r1r2rqs d N H tCy!&:'( t)*:$+,-.Tz /r3ra)rbrcrdrerfrrvrrrrMr{rhrirjrks@r1rmrms=" UE:HC $MG I::3r3rmc8a]tRt^toRtRtRtV3RltRtVt R#) FileEntryz%A file or directory inside a sandbox.Nc~<V^8dQh/S[;R&S[;R&S[R,;R&S[;R&S[R,;R&S[;R&#) r*namepathtypesizeNmtime_msmode)filedirsymlink)r/rr>)r0rIs"r1r2FileEntry.__annotate__sY I  I  * ++  IDj Nr3ra) rbrcrdrerfrrrhrirjrks@r1rrs/  HDr3rcFV^8dQhR\R\\,/#)r* local_pathr-)rr r )r0s"r1r2r2 sdx/Ar3c#R"VPRVP R\^4 R2, p\P\P ,\P ,\\R^4,\\R^4,p\P!WR4p\P!VR4;_uu_4pVxRRR4\P!W4R# +'giL(;i \dTPRR 7hi;i5i) aYield a writer whose bytes only appear at `local_path` once the download completes. Writing straight to the destination has three problems: an interrupted transfer leaves a truncated file at the final name; `open(path, "wb")` follows a symlink sitting there, so the sandbox's output can be redirected into any file this process can write; and a predictable temp name is a race another local process can win. So the bytes go to a temp file in the destination directory, created `O_EXCL` (nobody else's file) and `O_NOFOLLOW` (not a symlink) with mode `0600` and an unguessable name, then `os.replace`d into place. `rename` does not follow symlinks either, so a symlinked destination is *replaced* rather than written through, and a failure leaves nothing behind. r(z.part O_NOFOLLOWO_BINARYiwbNT) missing_ok) parentrrosO_WRONLYO_CREATO_EXCLgetattropenfdopenreplace BaseExceptionunlink)rtmpflagsfdfs& r1_open_download_targetr s   *//!2!IaL>G GC KK"** $ryy 072|Q3O ORYZ\^hjkRl lE U #B YYr4 AG! 3#!   d # s6B+D'.D C2D0D'2 D =DD$$D'ca]tRtRtoRtR)tR*t^tR+tV3RlRlt V3RlRlt R,V3RlRllt R-V3R lR llt R-V3R lR llt V3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3R lR!ltV3R"lR#ltR.V3R$lR%lltV3R&lR'ltR(tVtR #)/ SandboxFilesi%uFilesystem operations inside a sandbox, available as [`Sandbox.files`]. In shared (pool) mode, paths are rooted at the sandbox's private home — the only place its code can write — so a leading `/` is taken relative to that home. In dedicated mode, paths are absolute on the container filesystem. Paths are normalized lexically, then resolved by the host server relative to an open home-directory descriptor. The file API refuses symlinks on every component, including links whose targets are inside the same home. c"<V^8dQhRRRR/#)r*sandboxrr-Nra)r0rIs"r1r2SandboxFiles.__annotate__?s   d r3cWnR#NrvrOrs&&r1__init__SandboxFiles.__init__?s r3c&<V^8dQhRS[RS[/#r*rr-r/bytes)r0rIs"r1r2rBs////r3c `VPV4PpW P8d\V RV RVP R24hW P8dD\ V4pVP W4FwrEWSWD\V4,%K \V4#VPV^V4#)zRead a file from the sandbox and return its content as bytes. Raises [`SandboxError`] above `MAX_READ_BYTES`; use [`download`] for anything that large, which streams to disk instead of buffering. z is z bytes, over the zc-byte limit for reading into memory. Use `files.download(path, local_path)`, which streams to disk.) statrMAX_READ_BYTESrPARALLEL_THRESHOLD bytearray _read_rangesrWr _read_range)rOrrbufferoffsetparts&& r1readSandboxFiles.readBs yy## %% %&TF"3D4G4G3HIYY  )) )t_F $ 1 1$ = 6:vT 23!>= a..r3c,<V^8dQhRS[RS[RS[/#)r*rencodingr-r.)r0rIs"r1r2rWs"00c0S0s0r3c BVPV4PV4#)z@Read a file from the sandbox and return its content as a string.)rdecode)rOrrs&&&r1 read_textSandboxFiles.read_textWsyy%%h//r3Nc^<V^8dQhRS[RS[S[,S[,RS[R,RR/#r*rdatarNr-)r/rr )r0rIs"r1r2r[s= S S# SS5[8%; S3: SY] Sr3c P\V\4'dVP4pM&\V\4'gVP 4p\ V4VP 8dVPWV4R#RV/pVeW4R&VPPRRWBR7R#)zHWrite content to a file in the sandbox (parent directories are created).NrrPUT /files/writeparamscontent) rAr/r7rrrWr _write_rangesrvrw)rOrrrrs&&&& r1writeSandboxFiles.write[s dC ;;=DD%((99;D t9t.. .   t4 0 $  !6N unVRr3cN<V^8dQhRS[S[,RS[RS[R,RR/#)r*rrrNr-r/r)r0rIs"r1r2ris2//t/3/cDj/TX/r3c 0\VR4;_uu_4p\P!VP44PpWPP 8dVP W$WS4MVPW$VR7RRR4R# +'giR#;i)zUpload a local file to the sandbox. The file is opened once and both sized (`fstat`) and read through that same descriptor, so what is uploaded is the file that was measured -- rather than whatever the path resolves to a moment later. rb)rN)rrfstatfilenost_sizer_write_ranges_from_filer)rOrrrrrs&&&& r1uploadSandboxFiles.uploadisj*d # #q88AHHJ'//D---,,TdA 4 .$ # # #s A%B B c:<V^8dQhRS[RS[S[,RR/#)r*rrr-Nr)r0rIs"r1r2rzs&##S#cDj#T#r3c  8VPV4Pp\\V44;_uu_4pW0P8dHVP W4F'wrVVP V4VPV4K) RRR4R#VPPRRRV/R7;_uu_4pVPRR7FpVPV4K RRR4RRR4R# +'giL;i +'giR#;i)aDownload a file from the sandbox. The bytes land in a private temp file next to the destination and are renamed over it at the end, so an interrupted download leaves no truncated file and a symlink sitting at `local_path` is replaced rather than followed. NGET /files/readrr chunk_size) rrrrrrseekrrv_stream iter_bytes) rOrrrrrrrzchunks &&& r1downloadSandboxFiles.downloadzsyy## "4 #3 4 4---%)$5$5d$ALFFF6NGGDM%B5 4&&umVTN&SSW_%00K0HEGGENIT5 4TS5 4 4s*AD(D8+C5 #D5 D D D cL<V^8dQhRS[RS[S[S[S[3,,/#)r*rr-)r>r tuple)r0rIs"r1r2rs,YYCYDsCx$9Yr3c ~VPp\^W4Uu.uFq3\W!V, 43NK up#uupirL)PARALLEL_CHUNK_SIZErangemin)rOrrrs&& r1_rangesSandboxFiles._rangess:((BG4BWXBWU6M23BWXXXs:cd<V^8dQhRS[S[,RS[S[.S[3,RS[S[,/#)r*itemsfnr-)r r r )r0rIs"r1r2rs511tCy1hucz.B1tCy1r3c \VP\V44p\V4;_uu_4p\ VP W!44uuRRR4# +'giR#;i)zRun `fn(item)` over items concurrently. All workers share the sandbox's `httpx.Client`, which is thread-safe and pools connections, so parallel transfers fan out over several streams at once. N)rPARALLEL_MAX_WORKERSrWrlistmap)rOrrworkersexecutors&&& r1 _parallelSandboxFiles._parallelsG d//U<  ( (H R/0) ( ( (s A A) c2<V^8dQhRS[RS[RS[RS[/#)r*rrlengthr-r/r>r)r0rIs"r1r2rs)   S # % r3c \4pVPPRRRVRVRV/R7;_uu_4pVPR R7F?p\ V4\ V4,V8d \ R4hVP V4KA RRR4\ V4V8wd \ R 4h\V4# +'giL6;i) rrrrrrrz+File response exceeded the requested range.Nz6File changed size during transfer; retry the download.r)rrvrrrWrextendr)rOrrrrrzrs&&&& r1rSandboxFiles._read_ranges{ ]] " " =&$&(TZ)[#  !,, ,Dt9s5z)F2&'TUU E"E  t9 WX XT{  s AB;; C c R<V^8dQhRS[RS[RS[S[S[S[3,,/#)r*rrr-)r/r>r rr)r0rIs"r1r2rs5PPPCPHU3:=N4OPr3c # haa"RVV3RllpSPV4p\SP\V44p\ V4;_uu_4p\ ^\V4V4F%pVP W4WwV,4RjxL K' RRR4R#L +'giR#;i5i)zFetch every range in parallel, yielding `(offset, bytes)` as they land. Yielding rather than returning a list is the point: the caller places each chunk and drops it, so peak memory is a few chunks instead of the whole file plus a copy. ctV^8dQhR\\\3,R\\\3,/#)r*rngr-)rr>r)r0s"r1r2/SandboxFiles._read_ranges..__annotate__s/ B BuS#X B5e+< Br3c4<VwrVSPSW43#r)r)r rrrrOs& r1fetch(SandboxFiles._read_ranges..fetchs" NF4++D&AA Ar3N)rrrrWrrr)rOrrr rangesrrstartsff& r1rSandboxFiles._read_rangess B Bd#d//V=  ( (Hq#f+w7#<<ego/NOOO8) (O) ( (s0AB27B B B B2B B/ ) B2c><V^8dQhRS[RS[RS[R,RR/#rr)r0rIs"r1r2rs-66#6U6#*66r3czaaaaRVVVV3RllpSPSP\S44V4R#)cJV^8dQhR\\\3,RR/#r*r r-Nrr>)r0s"r1r20SandboxFiles._write_ranges..__annotate__s& a aeCHo a$ ar3c `<VwrSPSVSWV,S\S4R7R#)totalN) _put_rangerW)r rrrrrrOs& r1push(SandboxFiles._write_ranges..pushs0 NF OOD&$v*H$VYZ^V_O `r3N)rrrW)rOrrrrsffff r1rSandboxFiles._write_rangess, a a t||CI.5r3c D<V^8dQhRS[RS[RS[RS[R,RR/#)r*rsourcerrNr-)r/r r>)r0rIs"r1r2rs811C111TWZ^T^1cg1r3c aaaaaa\P!4oRVVVVVV3RllpSPSPS4V4R#)zUpload `source` in parallel ranges, reading each range on demand. Serialize reads from the shared descriptor; network writes still overlap. cJV^8dQhR\\\3,RR/#rr)r0s"r1r2:SandboxFiles._write_ranges_from_file..__annotate__s& C CeCHo C$ Cr3c<VwrS;_uu_4S PV4S PV4pRRR4\X4V8wd \R4hSP SWSSR7R# +'giLB;i)Nz+Upload source changed size during transfer.r)rrrWrr) r rrrrr read_lockrOrr s & r1r2SandboxFiles._write_ranges_from_file..pushsd NF F# F+5zV#"#PQQ OOD&TO B s #A-- A= N) threadingLockrr)rOrr rrrr%sfffff @r1r$SandboxFiles._write_ranges_from_files6 NN$  C C t||D)40r3c J<V^8dQhRS[RS[RS[RS[R,RS[RR/#)r*rrrrNrr-r)r0rIs"r1r2rsE T Ts TC T TS4Z T[^ Tcg Tr3cRVRV/pVeWFR&V\V4,V8dWVR&VPPRRWcR7R#)rrNr truncate_torrr)rWrvrw)rOrrrrrrs&&&&&$ r1rSandboxFiles._put_rangesQ"($&!A  !6N CJ % '$)= ! unVSr3c6<V^8dQhRS[RS[S[,/#r)r/r r)r0rIs"r1r2rsir3c .pRpRV/pVeW4R&VPPRRVR7P4pVPRVR,44VP R 4pV'dKsV#) zList a directory in the sandbox. The server paginates, so this follows the cursor and returns everything -- a caller sees one list regardless of how the directory is chunked on the wire. Nrafterrz /files/listrc38"TFp\R/VBxK R#5i)Nra)r).0entrys& r1 $SandboxFiles.list..sN;M%9-u-;Mentriesnext)rvrwrxrry)rOrr7r0rpayloads&& r1rSandboxFiles.listsz$& &,d^F "'wmm,,UM&,QVVXG NNN79;MN NKK'E5r3c&<V^8dQhRS[RS[/#r)r/r)r0rIs"r1r2rs,,,,r3c tVPPRRRV/R7p\R/VP4B#)z3Get metadata of a file or directory in the sandbox.rz /files/statrrra)rvrwrrx)rOrrzs&& r1rSandboxFiles.stats6==))%PT~)V+8==?++r3c&<V^8dQhRS[RS[/#rr/rH)r0rIs"r1r2rs34r3c VPV4R# \dpTPR8XdRp?R#hRp?ii;i)z+Check whether a path exists in the sandbox.TNF)rr status_code)rOres&& r1existsSandboxFiles.existss7  IIdO }}#  s =88=c*<V^8dQhRS[RS[RR/#)r*r recursiver-Nr?)r0rIs"r1r2rs'II3I4IDIr3c dRV/pV'dRVR&VPPRRVR7R#)z*Delete a file or directory in the sandbox.r1rGrsz /files/deleterNrvrw)rOrrGrs&&& r1deleteSandboxFiles.deletes1$ "%F;  xHr3c$<V^8dQhRS[RR/#)r*rr-Nr.)r0rIs"r1r2rsNN#N$Nr3c FVPPRRRV/R7R#)z0Create a directory (and parents) in the sandbox.POSTz /files/mkdirrrNrJ)rOrs&&r1mkdirSandboxFiles.mkdirs v~vtnMr3ri ri )zutf-8r)F)rbrcrdrerfrrrrrrrrrrrrrrrrrrrrDrKrPrirjrks@r1rr%s ))'N  //*00 S S//"##(YY11  PP$6611$ T T&,, IINNr3rcV^8dQhR\\\,,R\R,R\\\3,/#)r*rshellNr-)r/r rHdictr )r0s"r1r2r2 s5  sT#Y td{ tCH~ r3cVRJd"\V\4'g \R4hVRJd"\V\4'd \R4hRV/pVeWR&V#)zQBuild the `cmd`/`shell` part of an `/exec` payload, validating their consistency.TzCshell=True requires `cmd` to be a shell command string, not a list.FzRshell=False requires `cmd` to be an argv list (e.g. ['echo', 'hi']), not a string.rrS)rAr/ ValueError)rrSr9s&& r1 _exec_payloadrW s\ }ZS11^__ ~*S#..mnn$clG   Nr3cZV^8dQhR\PR\\,/#)r*rzr-)httpxResponser rT)r0s"r1r2r2s"5>>htnr3c#"VP4F?pV'gK \P!V4pVPR4R8wgK;VxKA R#5i)zJIterate NDJSON events from a streaming response, skipping keepalive pings.eventpingN) iter_linesrxloadsry)rzliner\s& r1 _iter_eventsrasB##%  4  99W  'K &s AA Ac<V^8dQhR\PRR/#)r*rzr-N)rYrZ)r0s"r1r2r2#s"sss4sr3cVP4VP4R,p\ RVP RV 2VP R7h \dTPR,pLGi;i)zQRead the error body and raise a SandboxError (works for streaming responses too).error:NiNzSandbox API error (z): )rB)rrx ExceptiontextrrB)rzmessages& r1_raise_for_statusrh#sj MMO&--/'* ,X-A-A,B#gYO]e]q]q rr &--%&sAA10A1cHV^8dQhR\PR\RR/#)r*rzjob_idr-N)rYrZr/)r0s"r1r2r2-s%U^^STr3c VP4PR4p\V\4'd$\V\ 4'gV\ 8dR#VeTMRp\RV RV R\ R24h \dRpLii;i)aRefuse a server whose wire contract this client cannot drive. Permissive in one direction only. A *newer* server is accepted: it declares its own backwards compatibility by keeping the protocol integer it still supports. An *older* one is refused, because the mismatches are things like the per-sandbox capability token, which surfaces as a 403 on an unrelated route several calls later instead of here. `version` is no use for this: it moves for a doc fix as readily as for a protocol break. protocolNz1 (declares no protocol) Sandbox job z runs sbx-server protocol z5, but this version of huggingface_hub needs protocol z or newer. A pool host keeps the server binary it downloaded at boot for up to 24h, so recycle this pool's hosts (kill them, or let them idle-time-out) to pick up the current server.)rxryrerAr>rHSANDBOX_SERVER_PROTOCOLr)rzrjrlreporteds&& r1_check_server_protocolrp-s==?&&z2(C  Hd)C)CTkHk#/x5OH  vh8 C**A)BCD D  sA;; B  B c<a]tRtRtoRtV3RlRltRtRtVtR#) _SandboxAuthiGaAttach the *current* HF bearer to every request. The bearer used to be captured once when the transport was built. A sandbox host lives up to 24h, so an OIDC/OAuth credential can expire or rotate inside that window, after which every request to the Jobs proxy failed even though the handle was still perfectly good. Reading it per request fixes that. The `X-Sandbox-Token` is deliberately *not* re-derived: the server holds the value derived from the bearer that created the job, so re-deriving from a rotated bearer would produce a token the server has never seen. The two credentials answer different gates -- the proxy wants a live bearer, the server wants the original capability -- and only the first needs refreshing. c$<V^8dQhRS[RR/#)r*apir-N)r)r0rIs"r1r2_SandboxAuth.__annotate__VsEdr3cWnR#r_api)rOrts&&r1r_SandboxAuth.__init__Vs r3c#`"R\VP4 2VPR&VxR#5i)Bearer AuthorizationN)_effective_tokenrxheaders)rOrequests&&r1 auth_flow_SandboxAuth.auth_flowYs*-45Edii5P4Q+R( s,.rwN) rbrcrdrerfrrrirjrks@r1rrrrGs r3rrca]tRtRtoRtR^ R^/V3RlRllt]R^ R^/V3RlRll4t]V3R lR l4t V3R lR lt R R/V3RlRllt ] R R/V3RlRll4t V3RlRltV3RlRltV3RlRltV3RlRltRtVtR#)_SandboxServeri^u5HTTP transport to one `sbx-server` instance — a dedicated job or a shared host. Owns the `httpx.Client`, the base URL and the auth headers. In dedicated mode a server is paired 1:1 with its [`Sandbox` In pool mode one server (one host job) is shared by many sandboxes, and `live`/`capacity` track packing. max_connectionscapacitycb<V^8dQhRS[RS[RS[R,RS[RS[RS[RS[R S[R S[R R/ #) r*rjownerimageNbase_urlr, sandbox_tokenrtrrr-)r/rr>)r0rIs"r1r2_SandboxServer.__annotate__fsu- - -  - Tz -  - - - - - -  - r3c WnW nW0nW@nWPnWpnW`nWn^VnRVn RVn \P!RV/\V4\P!WR7RR7VnR#)rTFX-Sandbox-Token)rmax_keepalive_connections)r~authlimitsfollow_redirectsN)rjr_imagerr,rx_sandbox_tokenrliveverifiedownedrYClientrrLimits_client) rOrjrrrr,rrtrrs &$$$$$$$$$r1r_SandboxServer.__init__fs{      +    ||& 6c"<<k #   r3cB<V^8dQhRS[RS[RS[RS[RS[RS[RR/#) r*jobr,rrtrrr-r)rr/rr>)r0rIs"r1r2rsS             r3c  T!VPVPPVP;'g VP\ V4VVVVVR7 #)zIBuild a server from a freshly fetched job (reads its exposed server URL). rjrrrr,rrtrr)rurr docker_imagespace_id_find_server_url)clsrr,rrtrrs&$$$$$$r1from_job_SandboxServer.from_jobsO66))..""22cll%c*'+  r3c.<V^8dQhRS[R,/#r*r-Nr.)r0rIs"r1r2rssTzr3cVP#r)rrNs&r1r_SandboxServer.images {{r3c:<V^8dQhRS[RS[R,RS[/#)r*kwargsrNr-rTr/)r0rIs"r1r2rs&  $ sTz d r3c DVe/VPR/4CRV/CVR&V#)aOverride `X-Sandbox-Token` for one request. The client-level header carries the *host* credential, which manages the pool. A pooled sandbox's own operations should present that sandbox's capability token instead, so nothing wider than the sandbox is offered on a per-sandbox call. r~r)ry)rOrrs&&&r1 _with_token_SandboxServer._with_tokens2  $ _6::i#< _>OQ^ _F9  r3rNcT<V^8dQhRS[RS[RS[R,RS[P/#r*methodrrNr-r/rYrZ)r0rIs"r1r2rs4cd `e`n`nr3c VPR\P!RRR74pVPWC4pVPP !WP V,3RV/VBpVPR8d \V4V#)z@Request to the in-job server. Raises SandboxError on API errors.timeoutgN@$@connect) poprYTimeoutrrrrrBrhrOrrrrrrzs&&&$, r1r_SandboxServer.requestsp**Y dD(IJ!!&8<<'' 0D`g`Y_`   3 & h 'r3c d<V^8dQhRS[RS[RS[R,RS[S[P,/#rr/r rYrZ)r0rIs"r1r2rs:   !$ 8;d   %.. ! r3c+ j"VPR\P!RRR74pVPWC4pVPP !WP V,3RV/VB;_uu_4pVPR8d \V4VxRRR4R# +'giR#;i5i)zJStreaming request to the in-job server. Raises SandboxError on API errors.rgQ@rrrN) rrYrrrstreamrrBrhrs&&&$, r1r_SandboxServer.streams **Y dD(IJ!!&8 \\ )= Yw YRX Y Y]e##s*!(+NZ Y Y YsA2B34!B B3 B0 * B3c4<V^8dQhRS[RS[R,/#)r*local_idr-Nr.)r0rIs"r1r2rs  c cDj r3c VPRRV R24P4R,# \dpTPR8XdRp?R#hRp?ii;i)a)Recover a pooled sandbox's capability token, using the host credential. Keeps reconnection stateless: `Sandbox.connect` can reattach to a sandbox it never created. Returns `None` when the host runs a server that predates per-sandbox tokens, in which case the caller falls back to the host token. r/v1/sandboxes/z/tokentokenrAN)rrxrrB)rOrrCs&& r1r_SandboxServer.sandbox_tokensR <<z'HINNPQXY Y }}#  s*- AAAAc<V^8dQhRR/#rra)r0rIs"r1r2rstr3c:VPP4R#r)rcloserNs&r1r_SandboxServer.closes r3c<V^8dQhRR/#rra)r0rIs"r1r2rsGGDGr3chVPPVPVPR7R#)rjr&N)rx cancel_jobrjrrNs&r1r_SandboxServer.cancel_jobs! DKK4::Fr3c$<V^8dQhRS[RR/#)r* start_timeoutr-N)r?)r0rIs"r1r2rskkk$kr3c  \P!4V,pRp\P!4V8EdVPPVPR,\P !R4R7pVP ^8Xd\W@P4R#\P!4V, R8d\P!4pVPPVPVPR7pVPP\9dv\!VPVPVPR7p\#R VP R VPP R VPP$ R V 24h\P&!R 4EK\#R VP RVR R24h \PdELIi;i)zMPoll /health until the server answers; fail fast (with logs) if the job dies.gz/healthg@rNg@rr&rmz$ terminated during startup (status: z , message: ).g333333?z did not become ready within z.0fzs.)timerryrrYrrBrprj RequestErrorrx inspect_jobrstatusstage_TERMINAL_STAGES_tail_job_logsrrgsleep)rOrdeadlinelast_job_checkrzrlogss&& r1 wait_ready_SandboxServer.wait_readys99;.iikH$ <<++DMMI,Eu}}]`Oa+b''3.*8[[A/ yy{^+c1!%ii++4;;$**+U::##'77)$))T[[DJJWD&&t{{m4$$'JJ$4$4#5[ASAS@TTVW[V\^ JJt \$++6STabeSffhijj%%  sA(GG0/G0) rxrrrrrrjrr,rrr)rbrcrdrerfr classmethodrrgrrrrrrrrrrirjrks@r1rr^s-  "- - - ^  "    .  T EI     GGkkr3rcna]tRtRtoRt]V3RlRl4t]V3RlRl4tV3RlRltR tVtR #) _KillMethodiz>Lets `kill` work both as a classmethod and an instance method.c8<V^8dQhRRRS[RS[R,/#)r*instanceNrr-.Nrr )r0rIs"r1r2_KillMethod.__annotate__sNNNTNhy6INr3cR#rrarOrrs&&&r1__get___KillMethod.__get__sKNr3c<<V^8dQhRRRS[RS[.R3,/#)r*rrrr-Nr)r0rIs"r1r2rs!RR R$R8BH;MRr3cR#rrars&&&r1rrsORr3c8<V^8dQhRRRS[RS[R,/#)r*rSandbox | Nonerr-rr)r0rIs"r1r2rs( 0(9BUr3cFaVe VP#RRRR/RV3RlllpV#)Nr&rc\V^8dQhR\R\R,R\R,RR/#)r* sandbox_idr&Nrr-r.)r0s"r1r2)_KillMethod.__get__..__annotate__ s8 O OS Od  O#PT* O`d Or3cJ<SPWVR7P4R#))r&rN)rr{)rr&rrs&$$r1r{!_KillMethod.__get__..kill s MM*M G L L Nr3)_kill)rOrrr{s&&f r1rrs7  >> ! OT OW[ O O r3raN) rbrcrdrerfrrrirjrks@r1rrs.H NN RRr3rca]tRtRtoRtRR/V3RlRllt]]3RRR ]R RR RR RR RRRRRRRRR/ V3RlRlll4t ]R RRR/V3RlRll4t ] !4t V3RlRlt V3RlRltV3RlRltV3RlRlt]R R!R R!R"R!R#R!R$R!R%R!R&R!R'R!R(R!R)R!/ V3R*lR+ll4t]R R!R R!R"R!/V3R,lR-ll4tR RR RR"RR#RR$RR%RR&RR'R.R(R.R)R/ V3R/lR0lltV3R1lR2lt]V3R3lR4l4t]V3R5lR6l4tRDR7R8/V3R9lR:lllt]V3R;lR<l4tV3R=lR>ltV3R?lR@lt]V3RAlRBl4tRCtVtR#)Eria)An isolated cloud machine running on Hugging Face Jobs. > [!NOTE] > The Sandbox API is experimental. Its API and behavior may change without notice. Create a dedicated one with [`Sandbox.create`] (one job per sandbox), or get many cheap shared ones from a [`SandboxPool`]. Reattach to a running sandbox from anywhere with [`Sandbox.connect`]. Use as a context manager to terminate it on exit: ```python >>> from huggingface_hub import Sandbox >>> with Sandbox.create(image="python:3.12") as sbx: ... print(sbx.run("python --version").stdout) ``` rNc^<V^8dQhRS[RS[RS[R,RS[RS[RS[R,RR/#) r*ruserverrN owns_sandbox owns_serverrr-)r/rrH)r0rIs"r1r2Sandbox.__annotate__ s[!(!( !( !( * !(  !(!(Tz!( !(r3cWnW nW`nW0nVfRMRV 2VnW@nWPnRVnRVn\V4Vn R#)Nz/v1rF) ru_serverr _local_id _base_path _owns_sandbox _owns_server_on_kill_killedrfiles)rOrurrrrrs&$$$$$$r1rSandbox.__init__ s\ ,!$,#3%>(9T*(<@  !$' r3flavor cpu-basic idle_timeoutenvsecretsvolumesr&forward_hf_tokenFlabelsr^@rc4<V^8dQhRS[RS[RS[S[,S[,R,RS[S[S[3,R,RS[S[S[3,R,RS[S[,R,RS[R,R S[R S[S[S[3,R,R S[R S[R,R R/ #)r*rr r Nrrrr&rrrrr-r)r/r>r?rTr r rrH)r0rIs"r1r2rFsrarara ra EkC'$. ra #s(^d " rac3h$&raf$ra:raraS#X%raraTzra rar3c  XV e\V \4'g"\R\V 4P 24hV P 4FVwr\V \ 4'd\V \ 4'g \R4hV \9gKI\RV R24h \V R7p\V4p\^4p\VV4p\VVVVVVVVR7wppppTPTTTTT\/T ;'g/C\R\ \"\$V/CT;'gR\&.VR 7 pRp\(P+VVVV\,P.^,R 7pVP1V 4T!TP6TRRRR7# \2dTP5TP6TP8P:R 7M= \2d0p\<P?R TP6 R T 24Rp?MRp?ii;iTeTPA4hi;i)uCreate 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. Args: image (`str`, *optional*, defaults to `"python:3.12"`): Any Docker image with `/bin/sh` (Docker Hub or `hf.co/spaces/...`). flavor (`str`, *optional*, defaults to `"cpu-basic"`): Hardware flavor, e.g. `"cpu-basic"`, `"a10g-small"`. See `hf jobs hardware`. idle_timeout (`int` or `float` or `str`, *optional*, defaults to `600`): Auto-shutdown after this much inactivity (no API calls, no running processes). Defaults to 10 minutes; pass `None` to disable. Note that a *foreground* command is not currently counted as activity, so a single `run()` that takes longer than this without other API traffic can have its sandbox shut down under it — raise the timeout (or pass `None`) for long single commands. env (`dict[str, Any]`, *optional*): Environment variables available in the sandbox. secrets (`dict[str, Any]`, *optional*): Secret environment variables (encrypted server-side). volumes (`List[Volume]`, *optional*): HF repos/buckets to mount, see [`Volume`]. namespace (`str`, *optional*): User or org namespace to run under (defaults to current user). forward_hf_token (`bool`, *optional*, defaults to `False`): If True, your HF token is injected as `HF_TOKEN` (opt-in). labels (`dict[str, str]`, *optional*): Labels to attach to the underlying HF Job. start_timeout (`float`, *optional*, defaults to `120.0`): Max seconds to wait for the sandbox to become ready. token (`str`, *optional*): HF token override. 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). Nz'`labels` must be a dict[str, str], got z(`labels` keys and values must be stringszLabel 'zB' is reserved by huggingface_hub Sandbox and cannot be overridden.rrrrr rrrI rcommandrrr rrrexposer&rr,rrtrrzFailed to cancel sandbox job  after startup failure: Trurrrr)!rArTrVrrbrr/RESERVED_SANDBOX_LABELSrr}rr;_bootstrap_job_specrun_jobSANDBOX_MAX_LIFETIME SANDBOX_LABEL MODE_LABELMODE_DEDICATED NONCE_LABELSANDBOX_SERVER_PORTrrrrrrerrurrloggerwarningr)rrr r rrrr&rrrrkeyvaluertr+r,rrjob_env job_secrets job_volumesrrrCs&&$$$$$$$$$$ r1createSandbox.createEst  fd++ #J4PV 5H  %-' 6 2+{kk(iv||imS*nVachi''4'(  +/ #,,+ , A AA E -F   m ,cffVd[_``  dcff G d!>svvhF^_`^abcc d!   s7AF H)$1GH) H!%H H) HH)cL<V^8dQhRS[RS[R,RS[R,RR/#)r*rr&Nrr-rr.)r0rIs"r1r2rs9.b.b.bC$J.bcTXj.bdm.br3c  :\VR7p\W4wr\V9dVP\^4wrV\ WEVR7pVP RR4P 4Uu0uF qR,kK p pWi9d\RV RV R24hVPV4p T!TTTR R T R 7#VPWR 7p V P;'g/p V P\4p V P\4R 8wgV f\RV R\ R24hV P\ 4\"8Xd\RV R\ R24hV P$P&R8wd'\RV RV P$P& R24h\)\+V4V 4p \,P/V V V V\0P2^,R7pV!V P4VRR R R7#uupi \dTP4hi;i)z?Reattach to a running sandbox from anywhere, using only its id.rrr /v1/sandboxesruzSandbox z no longer exists on host r(FTrurrrrrrrINJob z is not a sandbox (missing 'z ' label).z` is a sandbox host, not a single sandbox. Connect to one of its sandboxes with id 'z '.RUNNING is not running (status: rrr)r_split_sandbox_id SHARED_ID_SEPsplit _connect_hostrrxrrrerrrryr%r"r# MODE_POOLrrr;r}rrrrru)rrr&rrt host_job_idrritemexistingrrrr,s&&$$ r1rSandbox.connects!%  1* H J &$.$4$4]A$F !K"3yIF 39>>%3Y3^3^3`a3`4JJ3`a+&*=WXcWdde'fgg!' 4 4X > !" +  ooZoE!!r ;' ::m $ +u}j\1Mm_\efg g ::j !Y .zl#33@/O  ::  y (*5NszzO_O_N``bcd d-.>s.CUK (('(==A ) cffVd\`aaMb    s "G=-G8>+G=8G==Hc<V^8dQhRR/#rra)r0rIs"r1r2rs!!t!r3c VP'dR#VPfVPP4M6VPP RRVP 2VP R7RVnVPeVPV4VP'dVPP4R#R# \ d1p\PRTP RT 24Rp?R#Rp?ii;i)zTerminate the sandbox. Idempotent. Dedicated sandboxes cancel their underlying job; shared sandboxes are removed from their host (freeing a slot) while the host keeps running. NrsrrzFailed to kill sandbox : T) rrrrrrrer'r(rurrrrOrCs& r1r Sandbox._kills <<<  ~~% '') $$X?O/P`d`s`s$t  == $ MM$      LL      NN4TWWIRsC D  s(C 5C D%DDc<V^8dQhRR/#rra)r0rIs"r1r2rs!!t!r3c bVP'dVPP4R#R#)zRelease the local HTTP client without terminating the sandbox. Idempotent. No-op for pool sandboxes (the client belongs to the pool's host). N)rrrrNs&r1r Sandbox.closes%     LL    r3c<V^8dQhRR/#)r*r-rra)r0rIs"r1r2rs9r3cV#rrarNs&r1 __enter__Sandbox.__enter__ r3c<V^8dQhRR/#rra)r0rIs"r1r2rsTr3cnVP'dVP4R#VP4R#r)rr{rrOexc_infos&*r1__exit__Sandbox.__exit__s     IIK JJLr3rS.cwdrstdin on_stdout on_stderrcheckcapture_output backgroundc4<V^8dQhRS[S[S[,,RS[R,RS[S[S[3,R,RS[R,RS[R,RS[R,RS[S[.R3,R,R S[S[.R3,R,R S[R S[R S[R ,RS[/ #)r*rrSNrrTrrUrVrWrXrYrZFr-) r/r rHrTr r?r rrD)r0rIs"r1r2rs## 49_#d{ # #s(^d " # 4Z ##Tz#SE4K(4/#SE4K(4/###EN# #r3c R#rra) rOrrSrrTrrUrVrWrXrYrZs &&$$$$$$$$$$r1run Sandbox.runs #r3c <V^8dQhRS[S[S[,,RS[R,RS[S[S[3,R,RS[R,RS[R,RS[/#) r*rrSNrrTrZTr-)r/r rHrTr rrm)r0rIs"r1r2r+sh 49_d{  #s(^d "  4Z DM r3cR#rra)rOrrSrrTrZs&&$$$$r1r]r^*sr3Tc6<V^8dQhRS[S[S[,,RS[R,RS[S[S[3,R,RS[R,RS[R,RS[R,RS[S[.R3,R,R S[S[.R3,R,R S[R S[R S[R S[S[,/ #)r*rrSNrrTrrUrVrWrXrYrZr-) r/r rHrTr r?r rDrm)r0rIs"r1r2r5s}} 49_}d{ } #s(^d " } 4Z }}Tz}SE4K(4/}SE4K(4/}}}}  .}r3c  2a a\W4p V'dW.__annotate__s%  S   r3c<S'gR#S\V4,\8d\R\ R24hS\V4, oVPV4R#)Nzcommand produced more than z characters of output. Pass `capture_output=False` with `on_stdout`/`on_stderr` to stream it instead, or redirect it to a file in the sandbox and download that.)rWMAX_CAPTURED_OUTPUT_CHARSrappend)rfrrYcaptureds&&r1keepSandbox.run..keepsZ!#d)#&??"12K1LMQQ D !H LL r3z/execr\rXrr^exitrMrr_r`FrY)rMrXr^r_r`rYz%connection lost while running command)rresult) rWrwrxrmryrrarDjoinrrMr`r)rOrrSrrTrrUrVrWrXrYrZr9r stdout_parts stderr_partsrprmrzr\rls&&$$$$$$$$d$ @r1r]r^5st +  EN  EN ==G=DIIKD!88D>KHHUO   !(I   $G  #% "$ .2  \\&'\ 8 8H%h/>X-uV}5 ,!%-0-7^x/uV}5 ,!%-0-7^v-1"' "4!ww|4!ww|4$yy2"'))K"?$)IImQ$? F'09* >FG G f&&!+v/?/?/?%#f= = 39 8sBH A)H H c0<V^8dQhRS[S[,/#rF)r rm)r0rIs"r1r2rs  4/ r3c 4VPRR4P4pVUu.uFgp\VPR4VR,VR,VPR4VPR4VR,VPR 4VR 7NKi up#uupi) asList 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. rrcrur~rrrrrM)rur~rrrrrMrv)rwrxrmry)rOrps& r1 processesSandbox.processess}}UL1668   55;eHeHEE%LeeO4) %% ,    sA-Bc.<V^8dQhRS[R,/#rr.)r0rIs"r1r2rs""sTz"r3c.VPP#r)rrrNs&r1r Sandbox.images||!!!r3c.<V^8dQhRS[R,/#rr.)r0rIs"r1r2rsKKtKr3c NVPeVPP#R#)zIFor a shared/pool sandbox, the job id of the host running it (else None).N)rrrjrNs&r1host_idSandbox.host_ids"'+nn&@t||""JdJr3schemezhttps://cB<V^8dQhRS[S[,RS[RS[RS[/#)r*portrrr-)r>r/)r0rIs"r1r2rs4(N(N#)(N3(N(N^a(Nr3c VPPPR^4R,pVPR4'dTMRV,pV V VP RV V 2#)aLPublic 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/.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:`. (You can also expose the port directly via the job proxy without going through here.) Args: port (`int` or `str`): The port (pool: the `` of the unix socket) the inner server listens on. path (`str`, *optional*, defaults to `"/"`): Path on the inner server to point at, e.g. `"/ws"`. scheme (`str`, *optional*, defaults to `"https://"`): URL scheme to build the link with. Defaults to `"https://"`; pass `"wss://"` for a WebSocket client (the proxy is protocol-agnostic, so only the client-side scheme changes). Returns: `str`: a URL like `https://--49983.hf.jobs/v1/.../proxy/8000/ws` (or `wss://...` with `scheme="wss://"`). Example: ```python >>> 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") ``` z:///z/proxy/)rrr9 startswithr)rOrrr host_and_rests&&&$ r1 proxy_url_forSandbox.proxy_url_forsaL --33E1=bA s++tt-(9tfMMr3c6<V^8dQhRS[S[S[3,/#rFr)r0rIs"r1r2rs  tCH~ r3c RR\VPP4 2RVP;'gVPP/#)aAuth headers to send with [`proxy_url_for`] requests (HF token + sandbox token). Read these at the moment you use them: the HF token is resolved on access, so a long-lived handle hands out a current bearer rather than one captured when the sandbox was created. For a pooled sandbox this is the sandbox's own capability token, not the pool host's: these headers typically end up in a browser or WebSocket client, so they should confer access to this sandbox and nothing else. r|r{r)r}rrxrrNs&r1 proxy_headersSandbox.proxy_headerssH w'7 8I8I'J&KL t22QQdll6Q6Q  r3c <V^8dQhRS[/#rFr.)r0rIs"r1r2rs@@#@r3c@RVP: RVP: R2#)z Sandbox(id=z, image=rV)rurrNs&r1r[Sandbox.__repr__sTWWKx ~Q??r3c@<V^8dQhRS[RS[RS[P/#r*rresourcer-r)r0rIs"r1r2rs+uusucuur3c vVPP!WPV,3RVP/VB#rB)rrrr)rOrrrs&&&,r1rwSandbox._requests2||##FOOh,FtVZViVitmsttr3cP<V^8dQhRS[RS[RS[S[P,/#rr)r0rIs"r1r2rs+cSx?Wr3c+"VPP!WPV,3RVP/VB;_uu_4pVxRRR4R# +'giR#;i5i)rN)rrrr)rOrrrrzs&&&, r1rSandbox._streamsZ \\ OOh. >B>Q>Q U[  N    sAA(A A( A%  A() rrrrrrrrr ru)r)rbrcrdrerfrr DEFAULT_IMAGEDEFAULT_IDLE_TIMEOUTr.rrr{rrrKrRrr]rwrgrr~rrr[rwrrrirjrks@r1rrs !(%)!(!(J#ra" ra 2F ra &* ra*.ra(,ra!%ra"'ra)-ra %ra!rararah.b.b[_.b.b.bd =D!!.!!#! # &) #  #!$# #36#36## ##&)### !  &)   }" } &* }  }!%}!}37}37}} $}!}}~  2""KK (Nz(N(NT  @@ uur3rca]tRtRtoRt]3RRR]R^RRR RR ]R RR R R]RRRR/ V3RlRlllt ] R RR]RR/V3RlRll4t RNV3RlRllt RRR ]RR/V3RlRllt V3RlRlt]V3RlRl4t]V3R lR!l4t]V3R"lR#l4tV3R$lR%ltV3R&lR'ltV3R(lR)ltV3R*lR+ltV3R,lR-ltV3R.lR/ltV3R0lR1ltV3R2lR3ltV3R4lR5ltV3R6lR7ltV3R8lR9ltV3R:lR;ltRlltV3R?lR@lt V3RAlRBlt!V3RClRDlt"V3RElRFlt#V3RGlRHlt$V3RIlRJlt%ROV3RKlRLllt&RMt'Vt(R#)P SandboxPooli#uA fleet of shared "host" jobs, each packing many landlock-isolated sandboxes. > [!WARNING] > The Sandbox API is experimental. Its API and behavior may change without notice. > > **Pooled sandboxes are for workloads inside one trust boundary.** A pooled sandbox is a uid plus a Landlock > ruleset inside a shared VM — not a VM of its own — and every sandbox on a host shares that host's auth token > and its privileged control plane. Use a pool to fan out *your own* code cheaply. For mutually distrusting > workloads, use [`Sandbox.create`], which gives each one its own VM. The specific gaps are listed under > "Known limitations" in the sandbox conceptual guide. One host is one billed HF Job (a VM); it runs the sandbox server and multiplexes up to `sandboxes_per_host` lightweight sandboxes, isolated from each other by uid + the Landlock LSM. This makes large fan-outs cheap (the VM cost is shared across all its sandboxes) and fast (creating a sandbox is ~one proxy round-trip once a host is warm). Best for many parallel CPU sandboxes such as RL rollouts; for GPU or strong VM-level isolation between mutually-distrusting workloads, use [`Sandbox.create`] instead. The constructor pre-provisions `warm_up` hosts (default 1) and blocks until they are ready; further hosts are then provisioned on demand as sandboxes are requested, and all are torn down on `close()` (or when idle, via `idle_timeout`). The user never manages jobs: ```python >>> from huggingface_hub import SandboxPool >>> with SandboxPool(image="python:3.12", flavor="cpu-basic", warm_up=2) as pool: ... boxes = [pool.create() for _ in range(100)] # packed across the warm hosts ... print(boxes[0].run("echo hi").stdout) hi ``` `create()` makes **one** sandbox at a time: it reuses a host that still has free capacity before booting a new one, so you grow on demand as work arrives. To avoid a cold start on the first few calls, pre-provision hosts with `warm_up` (or [`warm`]). Warm hosts are discovered via job labels, so reuse works **across processes** too (a fresh pool with the same `image`/`flavor`/`name` attaches to hosts an earlier run left behind): ```python >>> pool = SandboxPool(image="python:3.12") >>> sbx = pool.create() # finds a warm host (here or in another process), else boots one ``` r r sandboxes_per_hostwarm_up max_hostsNrr r&rr adopt_hostsr _connect_modeFc<V^8dQhRS[RS[RS[RS[RS[R,RS[R,RS[S[,S[,R,R S[R,R S[R S[R S[R,R S[RR/ #)r*rr rrrNrr r&rrrrr-)r/r>r?rH)r0rIs"r1r2SandboxPool.__annotate__PsD%D%D% D%  D%  D%:D%DjD%EkC'$.D%:D%D%D%TzD%D% D%r3c  pV \\\39d)\R\: R\: R\: RV : R2 4hV^8d \R4hV^8d \R4h\ V R7VnWnW nW0nW@n WPn VeTM R \^4 2Vn Wpn Wn\VP V4VnWnWnRVnR Vn.Vn\*P,!4Vn\*P,!4Vn\*P,!4VnR VnR VnWnV '*Vn^Vn\*P>!VP.4Vn \C4Vn"V 'gVPG4R#R#) u Configure a pool and pre-provision `warm_up` hosts (blocks until they are ready). Env/secrets are *not* set here: they belong to each sandbox and are passed to `create(env=...)`, so sandboxes in the same pool can have different environments. Args: image (`str`, *optional*, defaults to `"python:3.12"`): Docker image for the hosts (needs `/bin/sh`). All sandboxes in the pool share this image. flavor (`str`, *optional*, defaults to `"cpu-basic"`): Hardware flavor for the host jobs (e.g. `"cpu-basic"`). sandboxes_per_host (`int`, *optional*, defaults to `50`): How many sandboxes to pack per host (per VM density). warm_up (`int`, *optional*, defaults to `1`): How many hosts to pre-provision in the constructor (which blocks until they are ready), so an initial burst of `create()` calls doesn't pay a host cold start each. Existing warm hosts (from the cache / other processes) count towards it, so only the shortfall is booted; capped by `max_hosts`. Defaults to 1 (a single host). max_hosts (`int`, *optional*): Optional cap on the number of host jobs (a cost ceiling). When reached and all hosts are full, `create()` raises. The cap is enforced per-process against the hosts this handle knows about, so two processes using the same pool concurrently can exceed it. (Per-host density, `sandboxes_per_host`, *is* enforced by the host itself.) name (`str`, *optional*): Pool name, used as the `hf-sandbox-pool` job label so the pool is discoverable (e.g. `hf sandbox pool ls`, `connect()`). `create()` reuses running hosts carrying this label (including from other processes) before booting new ones, so distinct names keep separate pools from sharing hosts. A random name is generated when omitted. idle_timeout (`int` or `float` or `str`, *optional*, defaults to `600`): Host idle timeout — a host shuts down once it has had no sandboxes for this long (a billing backstop). Each sandbox also has its own idle timeout, set at `create()`. Pass `None` to disable. namespace (`str`, *optional*): User or org namespace to run hosts under. start_timeout (`float`, *optional*, defaults to `120.0`): Max seconds to wait for a host to become ready. adopt_hosts (`str`, *optional*, defaults to `"own"`): Which already-running hosts `create()` may pack onto. Hosts are found by filtering Jobs on labels, and labels are set by whoever creates the Job — so a label match is a claim, not proof. This decides how much more than the claim is required: - `"own"` (default): only Jobs this principal started, per the Jobs API's `initiator`. Safe in a shared namespace. - `"namespace"`: any Job in the namespace carrying the pool's labels, provided its image, flavor, command and exposed URL all match. Restores cross-user host sharing; only use it in a namespace whose members you trust, since any of them can publish a Job your client will then send a token to. - `"never"`: no adoption at all — this handle only uses hosts it booted itself. token (`str`, *optional*): HF token override. zadopt_hosts must be one of z, z; got r(z sandboxes_per_host must be >= 1.zwarm_up must be >= 1.rNzpool-F)$ ADOPT_OWNADOPT_NAMESPACE ADOPT_NEVERrVrrxrr r_warm_uprrr _idle_timeout _namespace_cache_context_start_timeout _adopt_hosts _principal_principal_resolved_hostsr'r(_lock _warmup_lock _boot_lock_closed _warmed_up_require_live_host _owns_hosts _in_flight Condition_drainedset_dead_host_ids_ensure_warmed_up) rOrr rrrrr r&rrrrs &&$$$$$$$$$$$r1rSandboxPool.__init__PsN y/;G G-i]"_DEFAULT_SANDBOXES_PER_HOST) rrr&rrrtcacherridle_raw max_hosts_raws &&$$$ r1rSandboxPool.connects!<%  )GH  kk||#(#;#;//"//#'"  "#)XI677-.0 ""CCcllCCm&)jj&<3szz?+"377>;U#VW,9,Ec-(4*2*>XD#  r3c6<V^8dQhRS[RS[S[,/#)r* num_hostsr-)r>r r/)r0rIs"r1r2rsc$s)r3c dVP'd \R4hVP4VP;_uu_4V\ VP 4, pRRR4X^8dLVP VRR7pVP;_uu_4VP PV4RRR4VP;_uu_4RVn RRR4VP4VP# +'giL;i +'giLc;i +'giLR;i)uZEnsure `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`. This SandboxPool is closed.NT allow_partial) rr_discover_hostsrrWr_provision_hostsrrr _save_cachehost_ids)rOr shortfallbooteds&& r1warmSandboxPool.warms <<<<= =  ZZZ!C $44I q=**9D*IF ""6*    "DO }}Z  s$C9D  D9 D D  D/ rrc<V^8dQhRS[S[S[3,R,RS[S[,S[,R,RS[RR/#r*rNr rr-rrTr/r r>r?rH)r0rIs"r1r2r9sP(+(+#s(^d "(+EkC'$. (+  (+  (+r3c  VP;_uu_4VP'd \R4hV;P^, unRRR4VP WV4VP;_uu_4V;P^,unVP P 4RRR4# +'giLs;i +'gi#;i TP;_uu_4T;P^,unTP P 4RRR4i +'gii;i;i)uCreate 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). Args: env (`dict[str, Any]`, *optional*): Environment variables for this sandbox (each sandbox gets its own). idle_timeout (`int` or `float` or `str`, *optional*, defaults to `600`): Per-sandbox idle timeout — a sandbox is evicted from its host after this much inactivity (no API calls, no running process). Distinct from the host idle timeout. Pass `None` to disable. forward_hf_token (`bool`, *optional*, defaults to `False`): If True, inject your HF token as `HF_TOKEN` in the sandbox (opt-in). Unlike a dedicated sandbox's `secrets`, a pooled sandbox's env is delivered to the host server at creation (never stored in the host job), so it doesn't appear in any job's metadata. rN)rrrr_create_lockedr notify_all)rOrr rs&$$$r1r.SandboxPool.create9s:ZZZ|||"#@AA OOq O   +&&s:JK1$ ((*Z1$ ((*s;7B7C:4C 7 C C E24D/ & E/ D? :Ec<V^8dQhRS[S[S[3,R,RS[S[,S[,R,RS[RR/#rr)r0rIs"r1r2rcsTLL #s(^d "LEkC'$.L L  Lr3cD\T;'g/4pV'd\VP4VR&Ve \V4MRp.pRp^pVP 4VP 4p V f+V'g#RpVP 4VP 4p V fwVP'dTV'dLVP'g:\VPVP4\RVP R24hVPV4p V eAVPWV4p T eTP'4T #Y9dTP)T 4RpV^, pV\*8gEK\R4h \dUTP ;_uu_4\#^T P$^, 4T nRRR4h +'gih;ii;i \dTP ;_uu_4TPU u.uF qT9gK T NK Muup iup TnRRR4M +'giM;iTFKp T P-4M \dMi;iT P/4K8 T P/4i;i hi;i)HF_TOKENNFT No running host found for pool 'X'. The pool has stopped (all its hosts were killed or idle-timed-out); create a new one.zZCould not place sandbox: hosts kept reporting full. Raise max_hosts or sandboxes_per_host.)rTr}rxrBr _reserve_onerrrrrrr_boot_one_host _create_onerermaxrrremove_MAX_PACK_ROUNDSrr) rOrr r sandbox_env idle_secs new_hosts discoveredroundshostrhs &&&& r1rSandboxPool._create_lockedcsE 399"o &6tyy&AK #8D7O%l3UY *,  <   " " $((*< !%J((*,,.D<...:dkkk*$))T5H5HI*>tyykJ__ ..y9D#"&"2"24i"P*((*& (!((." ! ,,&t%%"ZZZ(+Atyy1}(=DI((Z * *.++L+Q)9Kqq+L !!OO% JJLDJJL "  s,G!;7G!3G!;G! AG!E?.G!*G!4 G!?G#G  G G  GG!!JH9H# H# "H90 J9 I  JI#"J# I1.J0I11J4JJJc <V^8dQhRS[/#rFr>)r0rIs"r1r2rs$$3$r3c VP;_uu_4\VP4uuRRR4# +'giR#;i)z*Number of host jobs currently provisioned.N)rrWrrNs&r1rSandboxPool.num_hostss%ZZZt{{#ZZZs 5 A c <V^8dQhRS[/#rFr)r0rIs"r1r2rs::s:r3c VP;_uu_4\RVP44uuRRR4# +'giR#;i)z.s9[Tyy[r6N)rsumrrNs&r1 num_sandboxesSandboxPool.num_sandboxess+ZZZ9T[[99ZZZs < A c0<V^8dQhRS[S[,/#rF)r r/)r0rIs"r1r2rs99$s)9r3c VP;_uu_4VPUu.uFqPNK upuuRRR4#uupi +'giR#;i)z!Job ids of the provisioned hosts.N)rrrjrOrs& r1rSandboxPool.host_idss9ZZZ,0KK8KDKKK8Z8ZZsA AA A  A c<V^8dQhRR/#rra)r0rIs"r1r2rs==t=r3c  faSP;_uu_4SP'd RRR4R#RSnSP\,pSP'd[SP P V3RlVR7'g4\PRSP RSP RV R24SPp.Sn RRR4.p.pXF6pVP'dVP4TP!4K8 V'dSP#VR 7M2SP$'d!\'SPSP(4V'd,\+RSP RRP-V4 R24hR# +'giL;i \dcpTPT4TPTP R T R 24\PR TP R T 24Rp?ELRp?ii;i TP!4i;i)uRelease 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 `. 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. NTc"<SP^8H#rL)rrNsr1#SandboxPool.close..sdooYZFZr3rPool '': z$ operation(s) still in flight after z(s; any host they boot will keep running. (rVFailed to cancel sandbox host rC)hostsz#' could not terminate host job(s): ; zM. They are still running and billing; cancel them with `hf jobs cancel `.)rrr_CLOSE_DRAIN_TIMEOUTrrwait_forr'r(rrrrrerkrjrrrrrrrq)rO drain_timeoutr  survivorsfailuresrrCsf r1rSandboxPool.closes"ZZZ|||Z DL !//2FFMt}}'='=>Zdq'='r'rTYYKs4??*;;_$o%MOKKEDK"+-  D :::OO%     9  -     dii)<)< =  #FtyyQYGZF[\^^  QZ2 T  &4;;-r!A 67!? }BqcRSS  T sHF/F$&F AF#"F. F+ . H9AHHHHH0c<V^8dQhRR/#)r*r-rra)r0rIs"r1r2rs=r3cV#rrarNs&r1rKSandboxPool.__enter__rMr3c<V^8dQhRR/#rra)r0rIs"r1r2rsooTor3cVP4R# \d6T^,fh\PRTP R2RR7R#i;i)rNr z/' teardown failed while handling another error.T)rQ)rrr'r(rrPs&*r1rRSandboxPool.__exit__sP o JJL o{" NNVDII;.]^imN n  os"B"B4"H+/??$+F(t b!\]^\_`aa bsAA// B':B""B'c&<V^8dQhRS[RS[/#r*rr-rrH)r0rIs"r1r2rEs  g $ r3c  4\TVPVP\8XdVP4MRVPVP VP R7pVe6\PRVP RVP RV R24R#R#) z9Whether `job` may be adopted as one of this pool's hosts.Nr principal_idr&rr zNot adopting job  as a host for pool 'r r(FT _host_rejectionrrr%rrr r'debugrurrOrreasons&& r1 _adoptableSandboxPool._adoptableEs $$151B1Bi1O++-UYoo**;;     LL,SVVH4I$))TWX^W__`a br3c&<V^8dQhRS[RS[/#r(r))r0rIs"r1r2rTsg$r3c  6\TVPVP\8XdVP4MRVPVP VP RR7pVe6\PRVP RVP RV R24R#R#) zFLike `_adoptable`, minus the checks a not-yet-running job cannot pass.NF)rr,r&rr  check_urlzNot waiting for job r-r r(Tr.r1s&& r1_adoptable_pendingSandboxPool._adoptable_pendingTs $$151B1Bi1O++-UYoo**;;    LL/x7LTYYKWZ[aZbbcd er3c<V^8dQhRR/#)r*r-_SandboxServer | Nonera)r0rIs"r1r2rds5r3c VP;_uu_4VPFLpVPVP, ^8gK'V;P^, unVuuuRRR4# RRR4R# +'giR#;i)zNReserve one slot on the first host with free capacity (under lock), else None.N)rrrrrs& r1rSandboxPool._reserve_oneds\ ZZZ ==499,q0IINIK Z#  Z s/A< A<0A<< B c2<V^8dQhRS[R,RR/#)r*rrr-r;)r )r0rIs"r1r2rms"''-=(>'CZ'r3c  VP;_uu_4VP4pVe VuuRRR4#VP4'd!VP4pVe VuuRRR4#VP^4pVP V4VP ;_uu_4VP P V4RRR4VP4uuRRR4# +'giL*;i +'giR#;i)u0Provision (or adopt) one host and reserve a slot on it. Returns None to retry. Held under `_boot_lock` so that, within a process, only one host is booted at a time: a burst of create() calls that all found every host full queue here, and each new host frees `sandboxes_per_host` slots for the threads still waiting — so they reuse it instead of each booting their own. Before booting, we reuse a slot freed by a concurrent boot and, failing that, adopt a host already SCHEDULING for this pool (here or in another process) rather than piling on a duplicate. N)rr_adopt_pending_hostrrrr)rOrrrs&& r1rSandboxPool._boot_one_hostms___$$&D _''))((*#_**1-F   V $ ""6*$$&!___s4C3C3 C3,6C3"C >C3 C0 +C33 D c <V^8dQhRS[/#rFrG)r0rIs"r1r2rs''T'r3c  aaaSPUu0uFqPkK upo\VV3RlSPP R\ \ \SP/SPR74R4oSfR#\PRSP RSP R24\P!4SP,p\P!4V8dSPPSPSPR 7P P"pVR9dR#VR 8XdgSP%4\&;QJd)V3R lSP4F 'gK R M RM!V3R lSP44'dR #\P(!R 4KR#uupi)aWait for and adopt a host already SCHEDULING for this pool, if any. Avoids over-provisioning when a host is already on its way up for this pool (started by another process, or an earlier create() in this one): rather than booting a duplicate, wait for it to reach RUNNING and adopt it via discovery. Returns True if a pending host was found (whether or not it eventually came up), False if none is scheduling. c3<"TF3pVPS9gKSPV4'gK/VxK5 R#5ir)rur8)r2rknownrOs& r1r42SandboxPool._adopt_pending_host..sA C66&,0+B+B3+Gs >> > SCHEDULINGrrr&NFr z' host z: is already SCHEDULING; waiting for it instead of booting.rr5c3T<"TFqPSP8HxK R#5irrjru)r2rpendings& r1r4rFsI[T{{gjj0[%(Tg?)rGr5)rrjr8rx list_jobsr#r; POOL_LABELrrr'r0rurrrrrranyr)rOrrrrErKsf @@r1r@SandboxPool._adopt_pending_hostsI*.55 99..'& :tyyI"oo/    ? vdii[ |;uvw99;!4!44iikH$II))t)W^^ddE55 !$$&3IT[[I333IT[[III JJsO?6sG c<V^8dQhRR/#rra)r0rIs"r1r2rs*/*/*/r3c aVPUu0uFqPkK ppVPPR\\ \ VP/VPR7Uu.uF1pVPV9gKVPV4'gK/VNK3 ppVEFJoRp\VPSPVPR7p\VPSVPR7p\VPRVP44Vn\#VP%RR4P'44VnTP8;_uu_4\:;QJd)T3R lTP4F 'gK R M R M!T3R lTP44'dTP74MTPP=T4RRR4EKM R#uupiuupi \*\,P.\03dFp\2P5RSP R T 24TeTP74Rp?EKRp?ii;i +'giEK;i) aAttach to running host jobs carrying this pool's labels. Lets `create()` reuse a host warmed by an earlier call or another process instead of booting a new one. Hosts are found via job labels; each adopted host's free capacity is read from the server, so packing stays accurate. Labels select candidates; creator, job specification and proxy URL admission checks decide which candidates can receive credentials. Adopted hosts are released by close(), not cancelled, because another handle may still be using them. r5rHNrrrr2zSkipping host z during discovery: c3T<"TFqPSP8HxK R#5irrJ)r2rrs& r1r4.SandboxPool._discover_hosts..sE{{cff,rLTF)rrjrxrMr#r;rNrrrur3r:rr>ryrrrWrrxrrrY HTTPErrorrr'r0rrrOrk)rOrrErmatchesrrrCs& ` r1rSandboxPool._discover_hostss*.55yy** "Iz499E//+  vvU"  (,s'; C  CF &tyy#&&DOOT  3$//J"%cggnd>U>U&V"W!&.."H"M"M"OP 3EE333EEEELLNKK&&v. !6 &!%//>B  ~cffX5HLM%LLN  sHG6*G;G;G;,B&H&*I('I(;,I( I% 9I  I%( I: c <V^8dQhRS[/#rFr)r0rIs"r1r2rs#r3c VP;_uu_4VPUu0uFqPkK ppRRR4VPP R\ \ \VP/VPR7FpXPVP4K \X4#uupi +'giL;i \d0p\PRTP RT 24Rp?LXRp?ii;i)ahHow many hosts are running for this pool, not just the ones we track. `max_hosts` is documented as a cost ceiling, but it was compared against `len(self._hosts)` -- an in-process count. Two processes using the same pool each counted only their own hosts, so the number of billed host jobs could quietly exceed the cap by a factor of however many processes were involved. Counting via labels narrows that considerably. It does not close it: two processes can still list simultaneously and both decide there is room. A hard cap has to be enforced where the jobs are created, not by the clients racing to count them. Nr5rHz%Could not count live hosts for pool 'r )rrrjrxrMr#r;rNrraddrurer'r0rW)rOrtrackedrrCs& r1_live_host_countSandboxPool._live_host_countsZZZ/3{{;{t{{{G; Tyy** "Iz499E//+  CFF# 7|<Z T LL@ 3qcR S S Ts4B7B2B7A$C 2B77 C D%C??Drc<<V^8dQhRS[RS[RS[S[,/#)r*num_newrr-)r>rHr r)r0rIs"r1r2rs)$$$t$PTUcPd$r3c  |VPeVP4pV'd(\V\^VPV, 44pW1,VP8d@VPV, p\ RV RVP R\^V4 RV R2 4hV^8Xd.#\ \V^ 4R7;_uu_4p\ V4Uu.uFqePVP4NK ppRRR4.pRp XF#p VPV P44K% V e-VF$p V P4V P4K& V hV#uupi +'giLt;i \dp T p Rp ? KRp ? ii;i \dLXi;i T P4i;i)z=Boot `num_new` host jobs in parallel, respecting `max_hosts`.Nz Pool needs z more host(s) but max_hosts=z allows only z more (zH already running for this pool). Raise max_hosts or kill some sandboxes.) max_workers)rr\rrrrrsubmit _boot_hostrkrprerr) rOr_rcurrentallowedr_futuresrrdfuturerCrs &&$ r1rSandboxPool._provision_hostss >> %++-Ggs1dnnw.F'GH 4>>1..72"!'*Ft~~FVW##&q'?"377)D>> a<I C,< = =AFwPAt7GP>')"&F  fmmo.   #%%'LLN !K #Q> =   !LLNsZ E*#E%<E*E==F%E** E: = FFF F&#F)%F&&F))F;c <V^8dQhRS[/#rFr)r0rIs"r1r2r s@@N@r3c  `\VP4p\^4p\W4p\ VPVRRRVP RVR7wrErgRVR&\ VP4VR&VPe\ VP4VR&\R\\\VP\V/pVPPVP TTTVP"\$TT;'gR\&.VP(R7 p Rp \*P-V VVVP\/VP^,R 4VPR 7p V P1VP24TPBT n"T # \4dTPP7T P8T P:PR 7M= \4d0p \<P?R T P8 R T 24Rp ? MRp ? ii;iT eT PA4hi;i)z6Start one host job and wait until its server is ready.NFrrI SBX_HOST_MODErrr)rr,rrtrrrr r)#r}rxrr;rrr/rrr"r#r;rNrr%r rr r!r&rrrrrrrerrurr'r(rrr) rOr+r,rrr+r,r-rrrrCs & r1rcSandboxPool._boot_host s#DII." -h> 5H II ++"' 6 2+$' #&d&=&="> >> %'*4>>':GO $j)ZT_afgii**;;(''4'(oo  +/ $,,+II #D$;$;a$? E00 -F   d11 2''    e $$CFFciinn$M e!?xG_`a_bcdd e!   s7A%F H-;GH- H%%H H-HH-cR<V^8dQhRRRS[S[S[3,RS[R,RR/#)r*rrrrNr-r)rTr/r r>)r0rIs"r1r2rbs:'' 0'tCH~'RUX\R\'aq'r3c  6R^/pVeW4R&V'dW$R&VPRRVR7P4pR TnTPR 4;'g.p\TPR ^44'g T'g1TP;_uu_4TPTnRRR4R#T^,p\TP \ TR , 2TTR ,R RTPR4R7p TP"T nT # \\P3dUpTP 'dh\ PRTP R T 24TPT4Rp?R#Rp?ii;i +'giR#;i)uyCreate one sandbox on a reserved `host`. Returns the sandbox, or None to retry. None means either the host filled up between our reservation and the create (server-authoritative capacity — another client packed it, so we mark it full and place the sandbox elsewhere) or a host rebuilt from the cache is gone/unreachable (dropped and re-placed via discovery / a fresh boot). countNidle_timeout_secsrrOr2rdz!Dropping unreachable cached host rCT sandboxesrejectedruFrr3)rrxrrYrUrr'r0rj _drop_hostryr>rrrrr8_on_sandbox_killedr) rOrrrbodyrrCrtr=rs &&&& r1rSandboxPool._create_onebsX!(|  (1$ % K <<d<CHHJD HH[)//R txx A& ' 'y MM |++}od4j\:$Z((7+   221eoo. }}} LL*>*B#CGOO ZZZs 7A A' c$<V^8dQhRS[RR/#r*rr-Nrk)r0rIs"r1r2rs~$r3c *VP;_uu_4VPUu.uF q"VJgK VNK upVnVPPVP4RRR4VP 4R#uupi +'giL';i)zFForget a host found dead this session (and mark it for cache pruning).N)rrrrZrjr)rOrrs&& r1rvSandboxPool._drop_hostsa ZZZ&*kkCkd]11kCDK    # #DKK 0 DZs BA=A=-B=B B c<V^8dQhRR/#rra)r0rIs"r1r2rs1/1/1/r3c (a\VPVP4pVfR#\VP4p\ P !4pVP EFmoVP;_uu_4VPUu0uFqDPkK ppRRR4SPX9gSPSP8dKs\S4pVex\PRSP RVP RV R24VP;_uu_4VPP!SP4RRR4KVSP", \$8dVP'S4'gEK/\)SPSP*VP,SP.SP0\3VSP04VP\5VP6^,R4SPR7 pSPVn RVnVP;_uu_4\:;QJd)V3R lVP4F 'gK R M RM!V3R lVP44'dVP=4MVPP?V4RRR4EKp R#uupi +'giELE;i +'giEL;i +'giEK;i) uEAdopt the pool's cached hosts without any HTTP (rebuilt from cached URL + nonce). The first thing that happens to a seeded host is an authenticated `POST`, so what the file says about *where* it lives is not taken on trust: the URL must be one only this job can have (`_cached_host_rejection`), and an entry older than `HOST_TRUST_TTL` is re-checked against the Jobs API first (`_confirm_cached_host`). A fresh entry — the `pool create` → `create --pool` case the cache exists for — is used as is. Liveness stays best-effort: a seeded host is confirmed by its first successful request and dropped on the first failure (see `_create_one`). Hosts the cache believes are full are skipped — label discovery re-checks them with fresh counts if the seeded ones don't satisfy the request, so a stale-full entry never blocks a create. NzDropping cached host of pool 'z': it r(rnrFc3T<"TFqPSP8HxK R#5irrj)r2rchs& r1r45SandboxPool._seed_hosts_from_cache..sHKD{{bii/KrLT) rrrr}rxrr rrrjrr_cached_host_rejectionr'r0rrZ updated_atr_confirm_cached_hostrrrrr,r;rrrrOrrk) rOrr+nowrrEr2rrs & @r1r"SandboxPool._seed_hosts_from_caches  4+>+>? = #DII.iik++B15==yyE!RWW %;+B/F! 4RYYKz$))TZ[aZbbcdeZZZ''++BII6 R]]"^3D  $  r3c VP;_uu_4Vf VPMTpVUu.uFdp\VPVPVP VP VPVP\P!4R7NKf pp\VP4pRRR4\VPVPVPVP VP"VP$VP&e\)VP&4MRXXR7 R#uupi +'giL;i)aPersist the pool config + hosts (with their live counts) for next time. `hosts` overrides the tracked list, for the one case where they differ: `close()` persisting the hosts it could *not* cancel, since that record is the caller's only handle on a job that is still billing. N)rjrrr,rrr)contextrr rrr r  dead_host_ids)rrrrjrrr,rrrrrrrrrr rrrrB)rOr r rr7deads&& r1rSandboxPool._save_cachesZZZ$)MT[[uF# #D;;**!]]**!]]#yy{#  t**+D  II''**;;#66nnBFBTBTB`*4+=+=>fj  ZsD/A*D*D/*D// D? )rrxrrrrrrrrrrrrrrrrrrr rrrr)r))rbrcrdrerfrrrrrrrrr.rrgrrrrrKrRrr%r3r8rrr@rr\rrcrrwrvrrrrirjrks@r1rr#s5*\#D%" D% #= D%  D%!%D% D%2FD%!%D% %D%%D%!D%$D%D%PC !% C % C ! C C C J6(+&*(+2F (+ "' (+(+TLL\$$ :: 99 ==~oo''R     ''8''R*/*/X8$e$$L@@D''RDD 1/1/f((T    r3rcLV^8dQhR\R,R\R,/#)r*rNr-r.)r0s"r1r2r2 s"  C$J 3: r3cVfR#VP4P4pRF*pVPV4'gKV\V4RpK, V#)zCompare Docker images leniently: registries and tags get normalized server-side, and a mis-parse here must not stop a pool from working.N)z docker.io/zindex.docker.io/zlibrary/)striplowerrrW)rprefixs& r1_normalize_imager sS } KKM   !E@   F # ##f+-(EA Lr3cJV^8dQhR\R\R\R,/#)r*urlrjr-Nr.)r0s"r1r2r2% s%    d r3c\V4pVPR8wdRVP: R2#VP;'gRPV R\ R2P 44'gRV R\ R 2#R #) a3Why `url` is not a URL we should send a sandbox job's credentials to. The hostname must be derived from the job id we already hold, so nothing but the client's own knowledge of which job it is talking to can decide where the credentials go. The domain is not hard-coded, so staging endpoints keep working. httpsz uses scheme z , not httpsr--r(z is not job z's port-z URLN)rrhostnamerr&r)rrjparseds&$ r1_server_host_rejectionr% s|c]F }}fmm.k:: OO ! !r - -;N:Oq.Q.W.W.Y Z ZVHH-@,AFF r3c>V^8dQhR\R\R,/#)r*rr-Nrr/)r0s"r1r2r25 s"RRwR3:Rr3c&VPe*\VPP;'g.4M.p\V4^8wdR\V4 R\ 2#\ V^,VP R7pVeRV^,: RV 2#R#)zDWhy this Job's exposed URL is not one we should send credentials to.Nzexposes z' URL(s), expected exactly one for port r, which )rr expose_urlsrWr&rru)rurlsr2s& r1_server_url_rejectionr5 s141G4 &&,," -RD 4yA~#d)$KL_K`aa #DGCFF ;F5;5GXd1g[ 1QTQr3c>V^8dQhR\R\R,/#r~)rr/)r0s"r1r2r2> s" V V Vd Vr3cv\VPVPR7pVeRVP: RV 2#R#)aKWhy a cached host entry must not be rebuilt into a credentialed transport. Same reasoning as `_server_url_rejection`, for a URL that comes off the local disk instead of the Jobs API. Without this, the cache file gets to choose where the HF bearer and the derived host token are sent -- `http://127.0.0.1:1234` included -- and it gets to choose it *before* any API call could have contradicted it. Deriving the expected hostname from the entry's own `job_id` leaves it able to name only a job this client can independently identify, which is the same bar a discovered host has to clear. rNznames r)rrrj)rr2s& r1rr> s;$DMM$++ FF9?9KVDMM$HVH 5UQUUr3cJV^8dQhR\R\R,R\/#)r*rtr&Nr-)rr/r)r0s"r1r2r2L s*ppp#*ppr3cZ\P!VP\V4VR7#)zOThe local pool cache's security context for this endpoint/credential/namespace.)endpointrr&)rfor_credentialrr})rtr&s&&r1rrL s#  & & DTUXDYen oor3r7TcV^8dQhR\R\R\R,R\R,R\R,R\R,R\R \R,/#) r*rrr,Nr&rr r7r-)rr/rH)r0s"r1r2r2Q sn3=3= 3= 3=* 3= Tz 3= : 3= $J3=3= 4Z3=r3cV\8XdR#V\8Xd\VPpVeVPfR#VfR#VPV8wd%RVP;'g VP R2#VeHVP e:VP PV8wdRVP P: RV: 2#VP ;'g VPpVe$\V4\V48wd R V: RV: 2#Ve8\VP4V8wdR \VP4: RV: 2#VPe#\VP4\48wdR #V'd \V4#R#) aWhy this Job must not be adopted as one of our pool hosts, or `None`. Hosts are found by filtering Jobs on labels, and labels are set by whoever creates the Job -- so a label match says "this Job claims to be one of our hosts", not "this Job is one of our hosts". Anyone who can create a Job in the namespace can make that claim, copy the public nonce from a real host's labels, and receive the token derived for that host. Everything checked here is asserted by the backend rather than by the Job's creator: the initiator, the owner, the image, the flavor, the command, and the exposed URL. `initiator` is the load-bearing one -- there is no client-side way to set it -- and it is what makes `policy="own"` meaningful. z/host adoption is disabled (adopt_hosts='never')NzJthe Jobs API did not say who started it, so it cannot be confirmed as ourszHcould not resolve the current principal to compare against its initiatorz"started by a different principal (rVzruns under namespace z, not z runs image z runs flavor z*does not run the sandbox bootstrap command)rr initiatorrurrrrrr/r rr_bootstrap_commandr) rrr,r&rr r7r job_images &$$$$$$ r1r/r/Q sN.@ MM   4_  ] <<< '7 8V8V),,7WWXY Y!6399>>Y;V&syy~~&8ymLL  00CLLI -i8r?rHrr)r0s"r1r2r2 s(C(C (C(C c3h$  (C #s(^d " (C &\D (C+#d*(C(C(C 49d38nd38nd6l BC(Cr3c /T;'g/CR\\4/Cp/T;'g/CRV/Cp \T;'g.4p Ve\\V44VR&V'dWR&R\ 2p VP R\ P RV 2VR&\VR &\VR &V P\R \ P\R R 74\4WV 3#)aBuild the (command, env, secrets, volumes) to launch a job running sbx-server. Shared by dedicated sandboxes and shared hosts: both fetch and exec the same unified `sbx-server` binary at startup (via `/bin/sh`), downloading it with wget/curl, or reading it off the always-mounted server bucket when the image ships neither. Either way the download is pinned to `SANDBOX_SERVER_SHA256` and verified before it runs. SBX_PORT SBX_TOKENrrz sbx-server-z /buckets/z /resolve/SBX_SERVER_URLSBX_SERVER_SHA256SBX_SERVER_MOUNTbucketT)rr  mount_path read_only) r/r&rrBSANDBOX_SERVER_SHA256rrSANDBOX_SERVER_BUCKET_SERVER_MOUNT_PATHrkrr) rtr+rrrr rrr+r,r- server_objects &&$$$$$$ r1rr s(T#))Sj#>Q:RSG"Qgmm"Qk="QKw}}"%K&)*;L*I&J"#"*J ""7!89M#&<<. ):Y:Y9ZZcdqcr sG #8G  #5G HY%D%DQcost  { BBr3c:V^8dQhR\\,/#rFrg)r0s"r1r2r2 s22DI2r3cRR\.#)z>The Job command every sandbox host and dedicated sandbox runs.z/bin/shz-c)_BOOTSTRAP_DOWNLOADrar3r1rr s t0 11r3c xV^8dQhR\R\R\R,R\\\3,/#)r*rtrr&Nr-)rrr/rTr )r0s"r1r2r2 s45wcDjT#s(^r3c\VP\4'd VPM/pRV9dLVPVPVR7P;'g/p\V\4'dTM/pV#)z6Return a host job's env vars (where pool config lives)rr)rA environmentrTrru)rtrr&rs&&$ r1rr sb'>>#//BCS ooSVVyoAMMSSQST**c Jr3rc bV^8dQhR\R\R\R,R\R\/#)r*rtrr&Nrr-)rr/r)r0s"r1r2r2 s5""U"S"d "[^"ov"r3c RpV\8Xd#VPRR7PR4p.pVP R\\\V/VR7F;p\WsWBRRR7pVfVu#VPVP R V R 24K= V'd"\R V R R PV4 R24h\RV R24h \d#p\P RT 24Rp?LRp?ii;i)aReturn a running host job belonging to `pool_id`, found via the pool label. This one feeds `SandboxPool.connect`'s cold path, which rebuilds the pool's whole configuration (image, flavor, density, caps) from the job it returns -- so an unvalidated match would let a Job in the namespace choose the image that the pool's *next* hosts boot. Image and flavor are unknown here (they are what we are about to learn), so this checks ownership and shape. NTr"rur#r5rHr+r rVz%Found host job(s) labelled for pool 'z' but none usable: rzp. Pass adopt_hosts='namespace' to SandboxPool if you intend to share hosts with other members of this namespace.rr)rr$ryrer'r(rMr#r;rNr/rkrurrq) rtrr&r principalrCrurr2s &&$$ r1rr s*I  ^  .2248IH}}*iW!MYb! YSW`d  >J366("VHA./3G9)r0s"r1r2r2 s<WWWsW#*WTWWadWr3c\VPWR74V)RpT'd RRPRT44,#R# \dR#i;i)rNrz Last logs:  c3,"TF pRV 2xK R#5i)z Nra)r2r`s& r1r4!_tail_job_logs.. s&EutD6{us)rfetch_job_logsrerq)rtrjr&rliness&&$$ r1rr sbS''v'KLeVWUJO?TYY&Eu&EE EVTVV sA AAiXi) COMPLETEDERRORDELETEDCANCELED)pr8r5rxrr'rconcurrent.futuresr contextlibr dataclassesrrpathlibrrrtypingr r r r r rr urllib.parserrYrr_sandbox_cacherrrrrr _space_apirerrorsrrrhf_apirrutilsrrutils._parsingr get_loggerrbr'r&r"r#r$r;rNr% frozensetrrSANDBOX_SERVER_VERSIONrrnrr!rrrjrrrr8rrrrr;rBrDrmrrrrWrarhrpAuthrrrrrrrrrrrr/r}rrrrr:r7rrrar3r1rs  1%(MMM! EE"%*   H %     ! #]J K$XY !Z   -    A'Bc,$ ss s& ):): ):X  2eNeNP s45::.^k^kB"PPfs s l   R Vp 3=3=l(CV2 "T"aj"J44 *gWtWZ\WWr3