+ Pj 9^RIt^RIt^RIt^RIt^RIt^RIHt^RIHt^RI H t H t ^RI H t ^RIHt^RIHtHtHtHtHtHtHt^RIt^RIHt^R IHtHtHtHt^R I H!t!^R I"H#t#H$t$H%t%^R I&H't'H(t(^R I)H*t*H+t+^RI,H-t-]+P\!]/4t0Rt1Rt2Rt3Rt4Rt5Rt6Rt7Rt8RGt9Rt:^2t;RtRt?Rt@RRltARRltB] !RR 44tC] !R!R"44tD] !R#R$44tE!R%R&4tFR'R(ltGR)R*ltHR+R,ltI!R-R.4tJ!R/R04tK!R1R24tL!R3R44tMR5R6ltNR7R8ltOR9R:ltPR;R/R<R=lltQR;R/R>R?lltRR@RAltSRBRCltTR;RRD^/RERFlltUR#)IN)ThreadPoolExecutor)contextmanager) dataclassfield)Path) token_hex)AnyBinaryIOCallableIteratorListLiteraloverload) constants) 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.1224h.z/.hf-sbx-serveraset -e d=/tmp/.sbx-server if command -v wget >/dev/null 2>&1; then wget -q --header "Authorization: Bearer $SBX_DL_TOKEN" -O "$d" "$SBX_SERVER_URL" elif command -v curl >/dev/null 2>&1; then curl -fsSL -H "Authorization: Bearer $SBX_DL_TOKEN" -o "$d" "$SBX_SERVER_URL" else cp "$SBX_SERVER_MOUNT/sbx-server" "$d"; fi chmod +x "$d" unset SBX_DL_TOKEN SBX_SERVER_URL SBX_SERVER_MOUNT exec "$d" c<V^8dQhR\R\R\/#)hf_tokennoncereturnstr)formats"q/Users/ahmed/devFolder/Ultron/claude-voice/gateway/.venv/lib/python3.14/site-packages/huggingface_hub/_sandbox.py __annotate__r+]s&ccCcccc\P!VP4RV 2P4\P4P 4#)a%Derive the per-sandbox auth token from the user's HF token and the sandbox 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. The HF token itself is never sent to the sandbox. z hf-sandbox:)hmacnewencodehashlibsha256 hexdigest)r$r%s&&r*_derive_sandbox_tokenr4]s; 88HOO%UG'<'C'C'Ew~~ V ` ` bbr,c\V^8dQhR\\,\,R\/#)r#durationr&)intfloatr()r)s"r*r+r+gs#$$e c 1$c$r,cf\V\\34'd \V4#\V4#)zBParse a duration like 300, "300s", "10m", "2h", "1d" into seconds.) isinstancer7r8r)r6s&r*_duration_to_secsr;gs((S%L))8} ( ##r,cja]tRt^ntoRtRtRt^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)r) __classdict__s"r*r+!SandboxCommandResult.__annotate__zs##D#r,c VP^8H#r) exit_codeselfs&r*okSandboxCommandResult.okys~~""r,c <V^8dQhRS[/#r?r')r)rBs"r*r+rC}sss#sr,c\VP4^P8:d VPMVPR,R,pRVP RV: RVP R2#)P:NMNz...zSandboxCommandResult(exit_code=z , stdout=z, duration_ms=))lenstdoutrF duration_ms)rHouts& r*__repr__SandboxCommandResult.__repr__}sU -3dkkS9IE9Q00@ #P^_c_o_o^ppqrrr,c~<V^8dQh/S[R,;R&S[;R&S[;R&S[R,;R&S[;R&S[;R&#)r#NrFrQstderrsignal timed_outrR)r7r(rA)r)rBs"r*r+rCnsYTz  K  K  $Jr,)__name__ __module__ __qualname____firstlineno____doc__rXrYrRpropertyrIrT__annotate_func____static_attributes____classdictcell__rBs@r*r=r=ns>I FIK ##ssr,r=cfa]tRt^toRt]!RRR7tRtRtRt Rt V3RlRlt V3Rlt R t VtR#) SandboxProcessaqA 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`]. Completed processes stay in the listing until the sandbox is deleted, so `running` and `exit_code` tell whether a process is still alive or already exited (as of when it was listed). F)reprcompareNTc<V^8dQhRR/#r#r&NrZ)r)rBs"r*r+SandboxProcess.__annotate__sCCdCr,c XVPPRRVP 24R#)z:Terminate the background process (idempotent server-side).DELETEz /processes/N)_sandbox_requestpidrGs&r*killSandboxProcess.kills! x;txxj)ABr,c<V^8dQh/S[;R&S[S[S[,,;R&R;R&S[R,;R&S[R,;R&S[;R&S[R,;R &#) r#rpcmdSandboxrnNtag started_at_msrunningrF)r7r(r rA)r)rBs"r*r+rkss H tCy: t:$ !"Tz #r,rZ)r[r\r]r^r_rrnrvrwrxrFrqrarbrcrds@r*rfrfs? UE:HC $MG ICC'r,rfc8a]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(rr7)r)rBs"r*r+FileEntry.__annotate__sY I  I  * ++  IDj Nr,rZ) r[r\r]r^r_rrrarbrcrds@r*rzrzs/  HDr,rzcNa]tRt^toRtR"tR#t^tV3RlRltV3RlRlt R$V3RlRllt R%V3R lR llt R%V3R lR llt V3R lRlt V3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3RlRltV3RlRltR&V3RlRlltV3RlR ltR!tVtR#)' SandboxFilesu-Filesystem 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. c"<V^8dQhRRRR/#)r#sandboxrur&NrZ)r)rBs"r*r+SandboxFiles.__annotate__s   d r,cWnR#NrnrHrs&&r*__init__SandboxFiles.__init__s r,c&<V^8dQhRS[RS[/#r#r~r&r(bytes)r)rBs"r*r+rs    r,c VPV4PpW P8d!RPVP W44#VP P RRRV/R7pVP#)z=Read a file from the sandbox and return its content as bytes.r,GET /files/readr~params)statrPARALLEL_THRESHOLDjoin _read_rangesrnrocontent)rHr~rresponses&& r*readSandboxFiles.readsgyy## )) )88D--d9: :==))%PT~)Vr,c,<V^8dQhRS[RS[RS[/#)r#r~encodingr&r')r)rBs"r*r+rs"00c0S0s0r,c BVPV4PV4#)z@Read a file from the sandbox and return its content as a string.)rdecode)rHr~rs&&&r* read_textSandboxFiles.read_textsyy%%h//r,Nc^<V^8dQhRS[RS[S[,S[,RS[R,RR/#r#r~datarNr&)r(rr )r)rBs"r*r+rs= S S# SS5[8%; S3: SY] Sr,c 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).Nr~rPUT /files/writerr) r:r(r0rrrPr _write_rangesrnro)rHr~rrrs&&&& r*writeSandboxFiles.writes dC ;;=DD%((99;D t9t.. .   t4 0 $  !6N unVRr,cN<V^8dQhRS[S[,RS[RS[R,RR/#)r# local_pathr~rNr&r(r)r)rBs"r*r+rs2++t+3+cDj+TX+r,c L\V4P4PpW@P8d-VP V\V4P 4V4R#\ VR4;_uu_4pVPW%VR7RRR4R# +'giR#;i)z#Upload a local file to the sandbox.Nrb)r)rrst_sizerr read_bytesopenr)rHrr~rrfs&&&& r*uploadSandboxFiles.uploadsxJ$$&.. )) )   tT*%5%@%@%BD I  *d # #q JJtTJ *$ # # #s 4B B# c:<V^8dQhRS[RS[S[,RR/#)r#r~rr&Nr)r)rBs"r*r+rs& # #S #cDj #T #r,c  RVPV4PpW0P8dI\VR4;_uu_4pVP W4FpVP V4K RRR4R#VP PRRRV/R7;_uu_4p\VR4;_uu_4pVPRR7FpVP V4K RRR4RRR4R# +'giR#;i +'giL.;i +'giR#;i) z!Download a file from the sandbox.wbNrrr~r) chunk_size) rrrrrrrn_stream iter_bytes)rHr~rrrpartrchunks&&& r*downloadSandboxFiles.downloadsyy## )) )j$''1 --d9DGGDM:(  ]] " "5- " O OS[j$''1%00K0HEGGENI(P O (' ''P O Os0*C.D1+D D. C?  D D D& cL<V^8dQhRS[RS[S[S[S[3,,/#)r#rr&)r7r tuple)r)rBs"r*r+rs,YYCYDsCx$9Yr,c ~VPp\^W4Uu.uFq3\W!V, 43NK up#uupirE)PARALLEL_CHUNK_SIZErangemin)rHrroffsets&& r*_rangesSandboxFiles._rangess:((BG4BWXBWU6M23BWXXXs:cd<V^8dQhRS[S[,RS[S[.S[3,RS[S[,/#)r#itemsfnr&)r r r )r)rBs"r*r+rs511tCy1hucz.B1tCy1r,c \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_WORKERSrPrlistmap)rHrrworkersexecutors&&& r* _parallelSandboxFiles._parallelsG d//U<  ( (H R/0) ( ( (s A A) c<<V^8dQhRS[RS[RS[S[,/#)r#r~rr&)r(r7r r)r)rBs"r*r+rs&999C9DK9r,c\aaRVV3RllpSPSPV4V4#)cRV^8dQhR\\\3,R\/#)r#rngr&)rr7r)r)s"r*r+/SandboxFiles._read_ranges..__annotate__s" $ $uS#X $5 $r,c l<VwrSPPRRRSRVRV/R7pVP#)rrr~rlengthr)rnror)rrrrr~rHs& r*fetch(SandboxFiles._read_ranges..fetchsF NF}}--}fdHfhX^-_.H## #r,)rr)rHr~rrsff& r*rSandboxFiles._read_rangess) $ $~~dll40%88r,c><V^8dQhRS[RS[RS[R,RR/#rr)r)rBs"r*r+rs-66#6U6#*66r,czaaaaRVVVV3RllpSPSP\S44V4R#)cJV^8dQhR\\\3,RR/#)r#rr&N)rr7)r)s"r*r+0SandboxFiles._write_ranges..__annotate__s& q qeCHo q$ qr,c ~<VwrRSRV/pSeSVR&SPPRRVSWV,R7R#)r~rNrrrrrnro)rrrrrrr~rHs& r*push(SandboxFiles._write_ranges..pushsO NF&,dHf%EF!%v MM " "5.QUV\hn_nQo " pr,N)rrrP)rHr~rrrsffff r*rSandboxFiles._write_rangess, q q t||CI.5r,c6<V^8dQhRS[RS[S[,/#r)r(r rz)r)rBs"r*r+r s#LLLiLr,c VPPRRRV/R7pVP4R,Uu.uFp\R/VBNK up#uupi)z List a directory in the sandbox.rz /files/listr~rentriesrZ)rnrojsonrz)rHr~rentrys&& r*rSandboxFiles.list sO==))%PT~)V08  0JK0Ju "E"0JKKKsAc&<V^8dQhRS[RS[/#r)r(rz)r)rBs"r*r+rs,,,,r,c tVPPRRRV/R7p\R/VP4B#)z3Get metadata of a file or directory in the sandbox.rz /files/statr~rrZ)rnrorzr)rHr~rs&& r*rSandboxFiles.stats6==))%PT~)V+8==?++r,c&<V^8dQhRS[RS[/#rr(rA)r)rBs"r*r+rs34r,c VPV4R# \dpTPR8XdRp?R#hRp?ii;i)z+Check whether a path exists in the sandbox.TiNF)rr status_code)rHr~es&& r*existsSandboxFiles.existss7  IIdO }}#  s =88=c*<V^8dQhRS[RS[RR/#)r#r~ recursiver&Nr)r)rBs"r*r+rs'II3I4IDIr,c dRV/pV'dRVR&VPPRRVR7R#)z*Delete a file or directory in the sandbox.r~1rrmz /files/deleterNr)rHr~rrs&&& r*deleteSandboxFiles.deletes1$ "%F;  xHr,c$<V^8dQhRS[RR/#)r#r~r&Nr')r)rBs"r*r+r%sNN#N$Nr,c FVPPRRRV/R7R#)z0Create a directory (and parents) in the sandbox.POSTz /files/mkdirr~rNr)rHr~s&&r*mkdirSandboxFiles.mkdir%s v~vtnMr,ri r)zutf-8r)F)r[r\r]r^r_rrrrrrrrrrrrrrrrrr rbrcrds@r*rrs))    00 S S++ # #YY119966LL ,, IINNr,rcV^8dQhR\\\,,R\R,R\\\3,/#)r#rtshellNr&)r(r rAdictr )r)s"r*r+r+*s5  sT#Y td{ tCH~ r,cVRJd"\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.rtr )r:r( ValueError)rtr payloads&& r* _exec_payloadr*s\ }ZS11^__ ~*S#..mnn$clG   Nr,cZV^8dQhR\PR\\,/#)r#rr&)httpxResponser r )r)s"r*r+r+6s"5>>htnr,c#"VP4F?pV'gK \P!V4pVPR4R8wgK;VxKA R#5i)zJIterate NDJSON events from a streaming response, skipping keepalive pings.eventpingN) iter_linesrloadsget)rliners& r* _iter_eventsr6sB##%  4  99W  'K &s AA Ac<V^8dQhR\PRR/#)r#rr&N)rr)r)s"r*r+r+@s"sss4sr,cVP4VP4R,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): )r)rr Exceptiontextrr)rmessages& r*_raise_for_statusr#@sj MMO&--/'* ,X-A-A,B#gYO]e]q]q rr &--%&sAA10A1ca]tRtRtoRtR^ R^/V3RlRllt]R^ R^/V3RlRll4t]V3R lR l4t V3R lR lt ] V3R lRl4t V3RlRlt V3RlRltV3RlRltRtVtR#)_SandboxServeriJu5HTTP 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#job_idownerimageNbase_urlr% sandbox_tokenapir&r'r&)r(rr7)r)rBs"r*r+_SandboxServer.__annotate__Rsu& & &  & Tz &  & & & & & &  & r,c *WnW nW0nW@nWPnWpn\ V4VnW`nWn ^Vn RVn \P!RRVP 2RV/\P!WR7RR7VnR#)rT AuthorizationBearer X-Sandbox-Token)r&max_keepalive_connections)headerslimitsfollow_redirectsN)r)r*_imager,r%_api_effective_token _auth_token_sandbox_tokenr'liveverifiedrClientLimits_client) rHr)r*r+r,r%r-r.r&r's &$$$$$$$$$r*r_SandboxServer.__init__Rs      +C0+   ||74+;+;*>r,c VPR\P!RRR74pVPP!WP V,3RV/VBpVP R8d \V4V#)z@Request to the in-job server. Raises SandboxError on API errors.timeoutgN@$@connect)poprTimeoutrArequestr,rr#rHrSr~kwargsrVrs&&&, r*r]_SandboxServer.requests`**Y dD(IJ<<'' 0D`g`Y_`   3 & h 'r,cP<V^8dQhRS[RS[RS[S[P,/#rRr(r rr)r)rBs"r*r+r/s+S(5>>:Rr,c+ H"VPR\P!RRR74pVPP!WP V,3RV/VB;_uu_4pVP R8d \V4VxRRR4R# +'giR#;i5i)zJStreaming request to the in-job server. Raises SandboxError on API errors.rVgQ@rWrXrZN)r[rr\rAstreamr,rr#r^s&&&, r*rd_SandboxServer.streamsx**Y dD(IJ \\ )= Yw YRX Y Y]e##s*!(+NZ Y Y YsA!B"#!B B" B  B"c<V^8dQhRR/#rjrZ)r)rBs"r*r+r/str,c:VPP4R#r)rAcloserGs&r*rh_SandboxServer.closes r,c<V^8dQhRR/#rjrZ)r)rBs"r*r+r/sGGDGr,chVPPVPVPR7R#)r) namespaceN)r9 cancel_jobr)r*rGs&r*rn_SandboxServer.cancel_jobs! DKK4::Fr,c$<V^8dQhRS[RR/#)r# start_timeoutr&N)r8)r)rBs"r*r+r/skkk$kr,c  \P!4V,pRp\P!4V8EdlVPPVPR,\P !R4R7pVP ^8XdR#\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@)rVNg@rlrmz Sandbox job z$ terminated during startup (status: z , message: ).g333333?z did not become ready within z.0fzs.)timerArr,rr\r RequestErrorr9 inspect_jobr)r*statusstage_TERMINAL_STAGES_tail_job_logsrr"sleep)rHrqdeadlinelast_job_checkrrDlogss&& r* wait_ready_SandboxServer.wait_readyst99;.iikH$ <<++DMMI,Eu}}]`Oa+b''3./yy{^+c1!%ii++4;;$**+U::##'77)$))T[[DJJWD&&t{{m4$$'JJ$4$4#5[ASAS@TTVW[V\^ JJt \$++6STabeSffhijj%%  sAGGG) r9r;rAr8r<r,r'r)r=r%r*r>N)r[r\r]r^r_r classmethodrLr`r+r]rrdrhrnrrbrcrds@r*r%r%Js&  "& & & P  "    .GGkkr,r%cna]tRtRtoRt]V3RlRl4t]V3RlRl4tV3RlRltR tVtR #) _KillMethodiz>Lets `kill` work both as a classmethod and an instance method.c8<V^8dQhRRRS[RS[R,/#)r#instanceNr*r&.Nrr )r)rBs"r*r+_KillMethod.__annotate__sNNNTNhy6INr,cR#rrZrHrr*s&&&r*__get___KillMethod.__get__sKNr,c<<V^8dQhRRRS[RS[.R3,/#)r#rrur*r&Nr)r)rBs"r*r+rs!RR R$R8BH;MRr,cR#rrZrs&&&r*rrsORr,c8<V^8dQhRRRS[RS[R,/#)r#rSandbox | Noner*r&rr)r)rBs"r*r+rs( 0(9BUr,cFaVe VP#RRRR/RV3RlllpV#)Nrmtokenc\V^8dQhR\R\R,R\R,RR/#)r# sandbox_idrmNrr&r')r)s"r*r+)_KillMethod.__get__..__annotate__s8 O OS Od  O#PT* O`d Or,cJ<SPWVR7P4R#))rmrN)rYrq)rrmrr*s&$$r*rq!_KillMethod.__get__..kills MM*M G L L Nr,)_kill)rHrr*rqs&&f r*rrs7  >> ! OT OW[ O O r,rZN) r[r\r]r^r_rrrbrcrds@r*rrs.H NN RRr,rcla]tRtRtoRtV3RlRlt]]3RRR]RR R R R R R R R RRRRR / V3RlRlll4t ]R R RR /V3RlRll4t ] !4t V3RlRlt V3RlRltV3RlRltV3RlRlt]RRRRR RR!RR"RR#RR$RR%RR&R/ V3R'lR(ll4t]RRRRR R/V3R)lR*ll4tRR RR R R R!R R"R R#R R$R R%R+R&R/ V3R,lR-lltV3R.lR/lt]V3R0lR1l4t]V3R2lR3l4tRAR4R5/V3R6lR7lllt]V3R8lR9l4tV3R:lR;ltV3R<lR=lt]V3R>lR?l4tR@tVtR #)BruiaAn isolated cloud machine running on Hugging Face Jobs. 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) ``` c J<V^8dQhRS[RS[RS[R,RS[RS[RR/#)r#rGserverlocal_idN owns_sandbox owns_serverr&)r(r%rA)r)rBs"r*r+Sandbox.__annotate__sM(( ( ( * (  (( (r,cWnW nW0nVfRMRV 2VnW@nWPnRVnRVn\V4Vn R#)Nz/v1/v1/sandboxes/F) rG_server _local_id _base_path _owns_sandbox _owns_server_on_kill_killedrfiles)rHrGrrrrs&$$$$$r*rSandbox.__init__sT !$,#3%>(9T*(<@  !$' r,flavor cpu-basic idle_timeoutenvNsecretsvolumesrmforward_hf_tokenFrq^@rc <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[R S[R,R R / #)r#r+rrNrrrrmrrqrr&ru)r(r7r8r r r rrA)r)rBs"r*r+rsbababa ba EkC'$. ba #s(^d " bac3h$&baf$ba:bababaTzba bar,c  \V R7p \V 4p \^4p \W4p\ V V VVVVVVR7wppppT P TTTTT\ \R\\\V /T;'gR\.VR7 pRp\PVV VV \P^,R7pVP!V 4T!TP&TRR R R 7# \"dT P%TP&TP(P*R7M= \"d0p\,P/RTP& R T 24Rp?MRp?ii;iTeTP14hi;i) u;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. 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. 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). 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). rrrrrrr-rN r+commandrrrrVlabelsrexposermrDr%r-r.r&rlzFailed to cancel sandbox job  after startup failure: TrGrrrr)rr:rr4_bootstrap_job_specrun_jobSANDBOX_MAX_LIFETIME SANDBOX_LABEL MODE_LABELMODE_DEDICATED NONCE_LABELSANDBOX_SERVER_PORTr%rLrrrr rnrGr*r}loggerwarningrh)rKr+rrrrrrmrrqrr.r$r%r-rjob_env job_secrets job_volumesrDrrs&&$$$$$$$$$ r*createSandbox.createsf% #C(" -h> 5H  %-' 6 2+{kk(!3 NKQVW''4'(  +/ #,,+ , A AA E -F   m ,cffVd[_``  dcff G d!>svvhF^_`^abcc d!   s7 AC$$ E501D"!E5" E-%EE5EE5cL<V^8dQhRS[RS[R,RS[R,RR/#)r#rrmNrr&rur')r)rBs"r*r+rfs9$b$b$bC$J$bcTXj$bdm$br,c \VR7p\W4wr\V9dVP\^4wrV\ WEVR7pVP RR4P 4Uu0uF qR,kK p pWi9d\RV RV R24hT!YTR R 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\.P0^,R7pV!V P2VRR R R 7#uupi \dTP4hi;i)z?Reattach to a running sandbox from anywhere, using only its id.rrsr /v1/sandboxesrGzSandbox z no longer exists on host r!FTrrlrNJob 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: rtr)r_split_sandbox_id SHARED_ID_SEPsplit _connect_hostr]rrr rhrwrrrrr MODE_POOLrxryr4r:r%rLrrrG)rKrrmrr. host_job_idrritemexistingrDrr%r-s&&$$ r*rYSandbox.connectes%  1* H J &$.$4$4]A$F !K"3yIF 39>>%3Y3^3^3`a3`4JJ3`a+&*=WXcWdde'fgg, *hUZhlm mooZoE!!r ;' ::m $ +u}j\1Mm_\efg g ::j !Y .zl#33@/O  ::  y (*5NszzO_O_N``bcd d-.>s.CUK (('(==A ) cffVd\`aa9b   s "G+-G&>G+&G++Hc<V^8dQhRR/#rjrZ)r)rBs"r*r+rs!!t!r,c VP'dR#VPfVPP4M*VPP RRVP 24RVnVPeVPV4VP'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. NrmrzFailed to kill sandbox : T) rrrrnr]r rrrGrrrh)rHrs& r*r Sandbox._kills <<<  ~~% '') $$X?O/PQ  == $ MM$      LL      NN4TWWIRsC D  s(B?)B?? C: %C55C:c<V^8dQhRR/#rjrZ)r)rBs"r*r+rs!!t!r,c 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)rrrhrGs&r*rh Sandbox.closes%     LL    r,c<V^8dQhRR/#)r#r&rurZ)r)rBs"r*r+rs9r,cV#rrZrGs&r* __enter__Sandbox.__enter__ r,c<V^8dQhRR/#rjrZ)r)rBs"r*r+rsTr,cnVP'dVP4R#VP4R#r)rrqrhrHexc_infos&*r*__exit__Sandbox.__exit__s     IIK JJLr,r .cwdrVstdin on_stdout on_stderrcheck backgroundc.<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 ,R S[/ #)r#rtr NrrrVrrrrrFr&) r(r rAr r r8r rr=)r)rBs"r*r+rs # # 49_ #d{ # #s(^d " # 4Z # #Tz #SE4K(4/ #SE4K(4/ # #EN #  #r,c R#rrZ) rHrtr rrrVrrrrrs &&$$$$$$$$$r*run Sandbox.runs #r,c <V^8dQhRS[S[S[,,RS[R,RS[S[S[3,R,RS[R,RS[R,RS[/#) r#rtr NrrrTr&)r(r rAr r rrf)r)rBs"r*r+rsh 49_d{  #s(^d "  4Z DM r,cR#rrZ)rHrtr rrrs&&$$$$r*rrsr,Tc0<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[S[,/ #) r#rtr NrrrVrrrrrr&) r(r rAr r r8r r=rf)r)rBs"r*r+rs[[ 49_[d{ [ #s(^d " [ 4Z [[Tz[SE4K(4/[SE4K(4/[[[  .[r,c  \W4p V'dW;R&V'dWKR&V 'dGVPRRV R7P4p \V R,WP R4VR7#VeW[R &VeWkR &.p .pR pVP RR V R7;_uu_4p\ V4FpVR ,R8Xd0V PVR,4VeV!VR,4K>K@VR ,R8Xd0VPVR,4VeV!VR,4K{K}VR ,R8XgK\VR,RPV 4RPV4VP R4VP RR4VP R^4R7pK R R R 4Vf \R4hV 'd0VP^8wgVP'd \WR7hV# +'giLX;i)uRun 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. Args: cmd (`str` or `List[str]`): A shell command string (run with `/bin/sh -c`) or an argv list (exec'd directly). shell (`bool`, *optional*): Force the execution mode instead of inferring it from the type of `cmd`. `True` runs through `/bin/sh -c` and requires `cmd` to be a string; `False` exec's `cmd` directly and requires it to be an argv list. `None` (default) infers from the type. Set it explicitly to avoid the type-driven footgun (e.g. `["echo hi"]` being exec'd as a single program named `"echo hi"`). env (`dict[str, Any]`, *optional*): Extra environment variables for this command. cwd (`str`, *optional*): Working directory. timeout (`float`, *optional*): Kill the command (whole process group) after this many seconds. stdin (`str`, *optional*): Data to write to the command's stdin. on_stdout (`Callable[[str], None]`, *optional*): Callback invoked with stdout chunks as they arrive. on_stderr (`Callable[[str], None]`, *optional*): Callback invoked with stderr chunks as they arrive. check (`bool`, *optional*, defaults to `True`): If True, raise [`SandboxCommandError`] on non-zero exit. background (`bool`, *optional*, defaults to `False`): If True, start the command detached and return a [`SandboxProcess`] right away instead of waiting for it and returning a [`SandboxCommandResult`]. Returns: a [`SandboxCommandResult`] (with `exit_code`, `stdout`, `stderr`, `duration_ms`), or a [`SandboxProcess`] when `background=True`. rrr /processesrrprv)rprtrvrnNrVrz/execrrQrrWexitrFr{rXrYFrR)rFrQrWrXrYrRz%connection lost while running command)rtresult)rrorrfrrrappendr=rrrFrYr)rHrtr rrrVrrrrrrr stdout_parts stderr_partsrrrs&&$$$$$$$$$ r*rrsh +  EN  EN ==G=DIIKD!d5ksZ^_ _  !(I   $G "$ "$ .2 \\&'\ 8 8H%h/>X- ''f 6 ,!%-0-7^x/ ''f 6 ,!%-0-7^v-1"' "4!ww|4!ww|4$yy2"'))K"?$)IImQ$? F09& >FG G f&&!+v/?/?/?%#= = /9 8s$BG6=A)G66 H c0<V^8dQhRS[S[,/#r?)r rf)r)rBs"r*r+r2s  4/ r,c  VPRR4P4pVUu.uFWp\VR,VR,VPR4VPR4VR,VPR4VR 7NKY up#uupi) aList the background processes of this sandbox. Returns the processes started with [`Sandbox.run`]`(..., background=True)`; stop one with [`SandboxProcess.kill`]. Completed processes stay listed (with `running=False` and their `exit_code`) until the sandbox is deleted. rrrprtrvrwrxrF)rprtrvrwrxrFrn)rorrfr)rHrps& r* processesSandbox.processes2s}}UL1668   eHeHEE%LeeO4) %% ,    sABc.<V^8dQhRS[R,/#rjr')r)rBs"r*r+rJs""sTz"r,c.VPP#r)rr+rGs&r*r+ Sandbox.imageIs||!!!r,c.<V^8dQhRS[R,/#rjr')r)rBs"r*r+rNsKKtKr,c NVPeVPP#R#)zIFor a shared/pool sandbox, the job id of the host running it (else None).N)rrr)rGs&r*host_idSandbox.host_idMs"'+nn&@t||""JdJr,schemezhttps://cB<V^8dQhRS[S[,RS[RS[RS[/#)r#portr~rr&)r7r()r)rBs"r*r+rTs4(N(N#)(N3(N(N^a(Nr,c 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/)rr,r startswithr)rHrr~r host_and_rests&&&$ r* proxy_url_forSandbox.proxy_url_forTsaL --33E1=bA s++tt-(9tfMMr,c6<V^8dQhRS[S[S[3,/#r?)r r()r)rBs"r*r+rs  tCH~ r,c dRRVPP 2RVPP/#)zPAuth headers to send with [`proxy_url_for`] requests (HF token + sandbox token).r1r2r3)rr;r<rGs&r* proxy_headersSandbox.proxy_headers~s4 wt||'?'?&@A t||::  r,c <V^8dQhRS[/#r?r')r)rBs"r*r+rs@@#@r,c@RVP: RVP: R2#)z Sandbox(id=z, image=rO)rGr+rGs&r*rTSandbox.__repr__sTWWKx ~Q??r,c@<V^8dQhRS[RS[RS[P/#r#rSresourcer&rT)r)rBs"r*r+rs+RRsRcRRr,c ^VPP!WPV,3/VB#r)rr]r)rHrSr#r_s&&&,r*roSandbox._requests%||##FOOh,FQ&QQr,cP<V^8dQhRS[RS[RS[S[P,/#r"rb)r)rBs"r*r+rs+cSx?Wr,c+"VPP!WPV,3/VB;_uu_4pVxRRR4R# +'giR#;i5ir)rrdr)rHrSr#r_rs&&&, r*rSandbox._streams? \\ 8)C Nv N NRZNO N N Ns7AA A A  A) rrrrrrrrrG)r)r[r\r]r^r_rr DEFAULT_IMAGEDEFAULT_IDLE_TIMEOUTrrYrrqrrhrrrrrr`r+rrrrTrorrrbrcrds@r*rurus ((:#ba" ba 2F ba &* ba*.ba(,ba!%ba"'ba %ba!bababaH$b$b[_$b$b$bP =D!!.!! #! # &) #  #!$ #  #36 #36 # #&) # # #!  &)   [" [ &* [  [!%[![37[37[[![[z  .""KK (Nz(N(NT  @@ RRr,ruc*a]tRtRtoRt]3RRR]R^RRR RR ]R RR R RRRR/ V3RlRlllt] R RRR/V3RlRll4t R@V3RlRllt RRR ]RR/V3RlRllt ] V3RlRl4t] V3RlRl4t] V3RlR l4tV3R!lR"ltV3R#lR$ltV3R%lR&ltV3R'lR(ltV3R)lR*ltV3R+lR,ltV3R-lR.ltV3R/lR0ltV3R1lR2ltV3R3lR4ltV3R5lR6ltV3R7lR8ltV3R9lR:ltV3R;lR<ltV3R=lR>ltR?t Vt!R#)A SandboxPooliaA fleet of shared "host" jobs, each packing many landlock-isolated sandboxes. 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 ``` rrsandboxes_per_hostwarm_up max_hostsNr}rrmrqrr _connect_modeFc<V^8dQhRS[RS[RS[RS[RS[R,RS[R,RS[S[,S[,R,R S[R,R S[R S[R,R S[R R/ #)r#r+rr-r.r/Nr}rrmrqrr0r&)r(r7r8rA)r)rBs"r*r+SandboxPool.__annotate__s`%`%`% `%  `%  `%:`%Dj`%EkC'$.`%:`%`%Tz`%`% `%r,c  >V^8d \R4hV^8d \R4h\V R7VnWnW nW0nW@nWPnVeTM R\^4 2Vn Wpn Wn Wn .Vn \P!4Vn\P!4Vn\P!4VnRVnRVnWnV '*Vn\/4VnV 'gVP34R#R#)uConfigure 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. 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. token (`str`, *optional*): HF token override. z sandboxes_per_host must be >= 1.zwarm_up must be >= 1.rNzpool-F)rrr9r+rr-_warm_upr/rr} _idle_timeout _namespace_start_timeout_hosts threadingLock_lock _warmup_lock _boot_lock_closed _warmed_up_require_live_host _owns_hostsset_dead_host_ids_ensure_warmed_up) rHr+rr-r.r/r}rrmrqrr0s &&$$$$$$$$$$r*rSandboxPool.__init__sl  !?@ @ Q;45 5&   "4 " ,DE)A,2H )#+,. ^^% &NN, $..* #0 -,(+   " " $r,cL<V^8dQhRS[RS[R,RS[R,RR/#)r#pool_idrmNrr&r,r')r)rBs"r*r+r2s34 4 c4 t4 3QU:4 an4 r,c  \V4pVeTT!VPVPVPVPTVP Vf VP MTVRR7 #\VR7p\WQVR7p\WVVR7pVPR4pVPR4p T!VP;'gVP;'g\VPe\VP4MR\VPR \ 44V e \V 4MRTVe \V4MRVVRR7 #) uReattach 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). Args: pool_id (`str`): The id returned when the pool was first created. namespace (`str`, *optional*): Namespace to search for the pool's hosts (defaults to yours). token (`str`, *optional*): HF token override. NT) r+rr-r/r}rrmrr0rrsSBX_IDLE_TIMEOUT SBX_MAX_HOSTSr SBX_CAPACITY)rr+rr-r/rrmr_find_pool_host_job _host_envrrHrIr)r(r7DEFAULT_SANDBOXES_PER_HOST) rKrGrmrcacher.rDridle_raw max_hosts_raws &&$$ r*rYSandboxPool.connects. (  kk||#(#;#;//"//-6->%//I"  % !#)DI677-.0 ""CCcllCCm&)jj&<3szz?+"377>;U#VW,9,Ec-(4*2*>XD  r,c6<V^8dQhRS[RS[S[,/#)r# num_hostsr&)r7r r()r)rBs"r*r+r2Ssc$s)r,c `VP'd \R4hVP4VP;_uu_4V\ VP 4, pRRR4X^8dJVP V4pVP;_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) r>r_discover_hostsr;rPr8_provision_hostsextendr<r? _save_cachehost_ids)rHrT shortfallbooteds&& r*warmSandboxPool.warmSs <<<<= =  ZZZ!C $44I q=**95F ""6*    "DO }}Z  s$C7D  D7 D D  D- rrc<V^8dQhRS[S[S[3,R,RS[S[,S[,R,RS[RR/#)r#rNrrr&ru)r r(r r7r8rA)r)rBs"r*r+r2nsVee#s(^d "eEkC'$. e  e  er,c hVP'd \R4h\T;'g/4pV'd\VP4VR&Ve \ V4MRp.pRp^pVP 4VP4p V f+V'g#RpVP4VP4p V flVP'dIV'dAVP'g/\VP4\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 Tn RRR4M +'giM;iTFKp T P-4M \dMi;iT P/4K8 T P/4i;i hi;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. rVHF_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.)r>rr r:r9r;rD _reserve_onerWr@r8rr}_boot_one_host _create_oner r;maxr=rZremove_MAX_PACK_ROUNDSrnrh) rHrrr sandbox_env idle_secs new_hosts discoveredroundshostrhs &$$$ r*rSandboxPool.creatensR: <<<<= =399"o &6tyy&AK #8D7O%l3UY *,  <   " " $((*< !%J((*,,.D<...:dkkk*$))4*>tyykJ__ ..y9D#"&"2"24i"P*((*& (!((." ! ,,&t%%"ZZZ(+Atyy1}(=DI((Z * *.++L+Q)9Kqq+L !!OO% JJLDJJL "  s+,G37G3G3G3*AG3.FG3*G3 G3G00#G G0 G, ' G00G33J1I !H5 .H5 4I  J1 I  J1$I54J5 JJJJJ1J**J1c <V^8dQhRS[/#r?r7)r)rBs"r*r+r2s$$3$r,c VP;_uu_4\VP4uuRRR4# +'giR#;i)z*Number of host jobs currently provisioned.N)r;rPr8rGs&r*rTSandboxPool.num_hostss%ZZZt{{#ZZZs 5 A c <V^8dQhRS[/#r?rt)r)rBs"r*r+r2s::s:r,c VP;_uu_4\RVP44uuRRR4# +'giR#;i)z,SandboxPool.num_sandboxes..s9[Tyy[sN)r;sumr8rGs&r* num_sandboxesSandboxPool.num_sandboxess+ZZZ9T[[99ZZZs < A c0<V^8dQhRS[S[,/#r?)r r()r)rBs"r*r+r2s99$s)9r,c VP;_uu_4VPUu.uFqPNK upuuRRR4#uupi +'giR#;i)z!Job ids of the provisioned hosts.N)r;r8r)rHrps& r*r[SandboxPool.host_idss9ZZZ,0KK8KDKKK8Z8ZZsA AA A  A c<V^8dQhRR/#rjrZ)r)rBs"r*r+r2s))t)r,c VP;_uu_4VPp.VnRVnRRR4XF6pVP'dVP 4TP4K8 VP'd\VP4R#R# +'giLw;i \ d0p\ PRTP RT 24Rp?LRp?ii;i TP4i;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 `. TNFailed to cancel sandbox host r) r;r8r>rArnr rrr)rhrr})rHhostsrprs& r*rhSandboxPool.closesZZZKKEDKDLD ###OO%      dii ( Z T!? }BqcRSS T s4B"B2 B/ 2 C,=%C'"C/'C,,C//Dc<V^8dQhRR/#)r#r&r,rZ)r)rBs"r*r+r2s=r,cV#rrZrGs&r*rSandboxPool.__enter__rr,c<V^8dQhRR/#rjrZ)r)rBs"r*r+r2sTr,c&VP4R#r)rhrs&*r*rSandboxPool.__exit__s  r,c<V^8dQhRR/#rjrZ)r)rBs"r*r+r2s''4'r,c  VP;_uu_4VP'd RRR4R#VP4VPf VPM\ VPVP4pVP ;_uu_4V\VP4, pRRR4X^8dVP4VP'gVP ;_uu_4V\VP4, pRRR4V^8dJVPV4pVP ;_uu_4VPPV4RRR4RVnRRR4VP'dVP4R#R# +'giL;i +'giL;i +'giLk;i +'giLo;i)uQOne-time: seed from the cache and pre-provision up to `warm_up` hosts. Cheap by default: seeding is local (no HTTP), and if the cache already gives at least `warm_up` hosts we trust them and skip discovery/booting (dead ones are pruned lazily by `create()`). Only when short do we list_jobs and boot the shortfall in parallel, capped by `max_hosts`. Runs at most once per pool, under `_warmup_lock`: concurrent first `create()` calls block here until the warm-up completes — and see its hosts — rather than racing past a half-set flag and each booting their own. `_warmed_up` is only set once the work succeeds, so a failed warm-up is retried (seeding/discovery dedupe by job id). Warm-up hosts are pool-level (like [`warm`]): they are not torn down if the triggering `create()` later fails — `close()` (or the `with` block) reclaims them. NT)r<r?_seed_hosts_from_cacher/r4rr;rPr8rWr@rXrYrZ)rHtargetr\r]s& r*rDSandboxPool._ensure_warmed_ups;       ' ' )&*nn&'CZ'r,c  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)r=re_adopt_pending_hostrXrYr;r8)rHrmrpr]s&& r*rfSandboxPool._boot_one_host9s___$$&D _''))((*#_**1-F   V $ ""6*$$&!___s4C3C3 C3,6C3"C >C3 C0 +C33 D c <V^8dQhRS[/#r?r@)r)rBs"r*r+r2Us$$T$r,c  aaVPUu0uFqPkK upo\V3RlVPP R\ \ \VP/VPR74R4oSfR#\PRVP RSP R24\P!4VP,p\P!4V8dVPPSPVPR 7P P"pVR9dR#VR 8XdgVP%4\&;QJd)V3R lVP4F 'gK R M RM!V3R lVP44'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. c3N<"TFpVPS9gKVxK R#5ir)rG)rzrDknowns& r*r{2SandboxPool._adopt_pending_host.._s, C 66& s% % SCHEDULINGrxrrmNFzPool 'z' host z: is already SCHEDULING; waiting for it instead of booting.rlrc3T<"TFqPSP8HxK R#5irr)rG)rzrppendings& r*r{rvsI[T{{gjj0[%(Tg?)rr)r8r)nextr9 list_jobsrr POOL_LABELr}r6rdebugrGrur7rwrxryrWanyr|)rHrpr}ryrrs& @@r*rSandboxPool._adopt_pending_hostUsI*.55 99..'& :tyyI"oo/     ? vdii[ |;uvw99;!4!44iikH$II))t)W^^ddE55 !$$&3IT[[I333IT[[III JJsO96sG c<V^8dQhRR/#rjrZ)r)rBs"r*r+r2{s&/&/&/r,c aVPUu0uFqPkK ppVPPR\\ \ VP/VPR7Uu.uFpVPV9gKVNK ppVEFJoRp\VPSPVPR7p\VPSVPR7p\VPRVP44Vn\!VP#RR4P%44VnTP6;_uu_4\8;QJd)T3R lTP4F 'gK R M R M!T3R lTP44'dTP54MTPP;T4RRR4EKM R#uupiuupi \(\*P,\.3dFp\0P3RSP R T 24TeTP54Rp?EKRp?ii;i +'giEK;i) a%Attach to running host jobs that match this pool (image/flavor/name). 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. rrNrsrKrrzSkipping host z during discovery: c3T<"TFqPSP8HxK R#5irr)rzrprDs& r*r{.SandboxPool._discover_hosts..sE{{cff,rTF)r8r)r9rrrrr}r6rGrrMr7rr-r'rPr]rr=rr HTTPErrorrrrrhr;rr)rHrprrDmatchesrrrs& ` r*rWSandboxPool._discover_hosts{s*.55yy** "Iz499E//+  vvU" C  CF &tyy#&&DOOT  3$//J"%cggnd>U>U&V"W!&.."H"M"M"OP 3EE333EEEELLNKK&&v. !6 &!%//>B  ~cffX5HLM%LLN  sBG*G"G"B&G' *I:'I",I' I 9II  I! c6<V^8dQhRS[RS[S[,/#)r#num_newr&)r7r r%)r)rBs"r*r+r2s ^0Dr,c  tVP;_uu_4\VP4pRRR4VPeUXV,VP8d=VPV, p\ RV RVP R\ ^V4 R24h\ \V^ 4R7;_uu_4p\V4Uu.uFqTPVP4NK ppRRR4.pRpXF#p VPV P44K% Ve-VF$p V P4V P4K& VhV# +'giEL+;iuupi +'giL;i \dp T pRp ? KRp ? ii;i \dLli;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. Raise max_hosts or kill some sandboxes.) max_workers)r;rPr8r/rrhrrrsubmit _boot_hostrrr rnrh) rHrcurrentallowedr_futuresr]rfuturerrs && r*rXSandboxPool._provision_hostssq ZZZ$++&G >> %'G*;dnn*Lnnw.GgY&B4>>BRS"1g//]_  C,< = =AFwPAt7GP>')"&F  fmmo.   #%%'LLN !K ;ZZQ> =   !LLNseE 3E&#E!$E&8E9%F E !E&& E6 9 FF  F F"F%!F""F%%F7c <V^8dQhRS[/#r?r%)r)rBs"r*r+r2s>>N>r,c  >\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 P1VP24V # \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.NFrr SBX_HOST_MODErKrJr)rDr%r-r.r&r'rlrr)!r:r9rr4rr5r(r-r/rrrrr}rrr+rrrr6r%rLrrr7r rnrGr*rrrh) rHr$r%r-rrrrrrDrrs & r*rSandboxPool._boot_hosts#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 ;G H H%G>9H>HHcR<V^8dQhRRRS[S[S[3,RS[R,RR/#)r#rpr%rrlNr&r)r r(r r7)r)rBs"r*r+r2s:$$ 0$tCH~$RUX\R\$aq$r,c R^/pVeW4R&V'dW$R&VPRRVR7P4pR TnTPR 4;'g.p\TPR ^44'g T'g1TP;_uu_4TPTnRRR4R#T^,p\TP \ TR , 2TTR ,R RR7p 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_secsrrrrz!Dropping unreachable cached host rT sandboxesrejectedrGFr)r]rrrrr>rrr) _drop_hostrr7r;r'r=rur_on_sandbox_killedr) rHrprrlbodyrrrrrs &&&& r*rgSandboxPool._create_onesJ!(|  (1$ % K <<d<CHHJD HH[)//R txx A& ' 'y MM |++}od4j\:$Z   22+eoo. }}} LL*>*B#CGOO ZZZs 7A A' c$<V^8dQhRS[RR/#)r#rpr&Nr)r)rBs"r*r+r2/s~$r,c *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)r;r8rCaddr)rh)rHrprqs&& r*rSandboxPool._drop_host/sa ZZZ&*kkCkd]11kCDK    # #DKK 0 DZs BA=A=-B=B B c<V^8dQhRR/#rjrZ)r)rBs"r*r+r28s+++r,c \VP4pVfR#\VP4pVP;_uu_4VP Uu0uFq3P kK ppVPFpVP V9gVPVP8dK1\VP VPVPVPVP\W%P4VP\!VP"^,R4VPR7 pVPVnRVnVP P'V4K RRR4R#uupi +'giR#;i)uAdopt the pool's cached hosts without any HTTP (rebuilt from cached URL + nonce). Best-effort and unverified: each adopted host is confirmed on the 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. NrrFF)rr}r:r9r;r8r)rr=r'r%r*r+r,r%r4rr-r>r)rHrOr$rprchrs& r*r"SandboxPool._seed_hosts_from_cache8s   * = #DII. ZZZ-1[[9[T[[[E9kk99%BKK)?'99((**[[(("7(("K $'(?(?!(CS$I[[ !gg "' ""6*!"Z9ZZsE5E0(C>E50E55 F c<V^8dQhRR/#rjrZ)r)rBs"r*r+r2Xs  T r,c tVP;_uu_4VPUu.uFdp\VPVPVP VP VPVP\P!4R7NKf pp\VP4pRRR4\VPVPVPVP VP"VP$e\'VP$4MRVP(XXR7 R#uupi +'giL;i)zOPersist the pool config + current hosts (with their live counts) for next time.)r)r*r,r%r'r= updated_atN)r+rr-r/rrmr dead_host_ids)r;r8rr)r*r,r%r'r=rurBrCrr}r+rr-r/r5r;r6)rHrprdeads& r*rZSandboxPool._save_cacheXs ZZZ!KK (D;;**!]]**!]]#yy{(  t**+D  II**;;#66nnBFBTBTB`*4+=+=>fjoo  ZsD'A*D"D'"D'' D7 )r9r=r>rCr8r5r;r6rAr@r7r4r?r<rr+r/r}r-))"r[r\r]r^r_r)rNr*rrrYr^rr`rTr~r[rhrrrDrerfrrWrXrrgrrrrZrbrcrds@r*r,r,s!J#`%" `% #= `%  `%!%`% `%2F`%!%`% %`%!`%$`%`%H4 d4 X\4 4 4 l6e&*e2F e "' eeN$$ :: 99 ))0 ''R''8$$L&/&/PB>>@$$LDD ++@  r,r,c0V^8dQhR\R\/#)r#r.r&)rr()r)s"r*r+r+us%Cr,c\VP\4'd VPM \4pV'g \ R4hV#)zMA Hugging Face token is required to use sandboxes. Run `hf auth login` first.)r:rr(rr)r.rs& r*r:r:us3#CIIs33CIIE jkk Lr,cV^8dQhR\R\R\\\3,R,R\\\3,R,R\\ ,R,R\ \,\,R,R\R \R \\\,\\\3,\\\3,\\ ,3,/ #) r#r.r$rNrrrrr-r&) rr(r r r rr7r8rArr)r)s"r*r+r+|s$6$6 $6$6 c3h$  $6 #s(^d " $6 &\D $6+#d*$6$6$6 49d38nd38nd6l BC$6r,c /T;'g/CR\\4/Cp/T;'g/CRV/Cp \T;'g.4p Ve\\V44VR&V'dWR&VP R\ P R2VR&WR&\VR &V P\R \ P \R R 74R R\.p WW3#)aEBuild 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. SBX_PORT SBX_TOKENrIrbz /buckets/z/resolve/sbx-serverSBX_SERVER_URL SBX_DL_TOKENSBX_SERVER_MOUNTbucketT)rsource mount_path read_onlyz/bin/shz-c) r(rrr;endpointrSANDBOX_SERVER_BUCKET_SERVER_MOUNT_PATHrr_BOOTSTRAP_DOWNLOAD) r.r$rrrrrr-rrrrs &&$$$$$$ r*rr|s&T#))Sj#>Q:RSG"Qgmm"Qk="QKw}}"%K&)*;L*I&J"#"*J#&<<. ):Y:Y9ZZm nG "*#5G HY%D%DQcost$ 34G [ 55r,c xV^8dQhR\R\R\R,R\\\3,/#)r#r.rDrmNr&)rrr(r r )r)s"r*r+r+s45wcDjT#s(^r,c\VP\4'd VPM/pRV9dLVPVPVR7P;'g/p\V\4'dTM/pV#)z6Return a host job's env vars (where pool config lives)rKrl)r: environmentr rwrG)r.rDrmrs&&$ r*rMrMsb'>>#//BCS ooSVVyoAMMSSQST**c Jr,rmcVV^8dQhR\R\R\R,R\/#)r#r.rGrmNr&)rr(r)r)s"r*r+r+s-  U S d V] r,czVPR\\\V/VR7FpVu# \ RV R24h)zNReturn any running host job belonging to `pool_id` (found via the pool label).rrrcrd)rrrrr)r.rGrmrDs&&$ r*rLrLsT}}*iW!MYb   *7)4K K r,cVV^8dQhR\R\R\R,R\/#)r#r.rrmNr&)rr(r%)r)s"r*r+r+s-u3cDjTbr,c VPWR7pVP;'g/pVP\4pVeVP\4\ 8wd\ RV R24hVPPR8wd'\ RV RVPP R24h\PVV\\V4V4V\P^,R7#) z?Reattach to a running host job and return its server transport.rlrz is not a sandbox host.rz Sandbox host rrtr)rwrrrrrrrxryr%rLr4r:rr)r.rrmrDrr%s&&$ r*rrs /// BC ZZ  2F JJ{ #E } :.);T+.EFGG zz9$];-7PQTQ[Q[QaQaPbbdeff  " " +,.s&EutD6{us)rfetch_job_logsr r)r.r)rmrliness&&$$ r*r{r{sbS''v'KLeVWUJO?TYY&Eu&EE EVTVV sA AAiX) COMPLETEDERRORDELETEDCANCELED)Vr1r.rr9ruconcurrent.futuresr contextlibr dataclassesrrpathlibrrrtypingr r r r r rrrr{r_sandbox_cacherrrr _space_apirerrorsrrrhf_apirrutilsrrutils._parsingr get_loggerr[rrrrrrrrr)r*rrNrrzrjrrr4r;r=rfrzrrrr#r%rrur,r:rrMrLrrrJr{rZr,r*rs  1%(MMM  EE"%*   H %     !   A' c$ ss s& CC C.  ANANH sxkxkv"{{| ^  ^  B$6N T 4$ *gWtWZ\WWr,