5pj9tSSKrSSKrSSKrSSKrSSKrSSKJr SSKJr SSK J r J r SSK J r SSKJr SSKJrJrJrJrJrJrJr SSKrSS KJr SS KJrJrJrJr SS K J!r! SS K"J#r#J$r$J%r% SS K&J'r'J(r( SSK)J*r*J+r+ SSK,J-r- \+R\"\/5r0Sr1Sr2Sr3Sr4Sr5Sr6Sr7Sr8Sr9Sr:Sr;SrSr?Sr@S \AS!\AS"\A4S#jrBS$\C\D-\A-S"\C4S%jrE\ "S&S'55rF\ "S(S)55rG\ "S*S+55rH"S,S-5rIS.\A\\A-S/\JS-S"\K\A\44S0jrLS1\RS"\\K4S2jrNS1\RS"S4S3jrO"S4S55rP"S6S75rQ"S8S95rR"S:S;5rSS<\'S"\A4S=jrTS<\'S \AS>\K\A\4S-S?\K\A\4S-S@\\!S-SA\C\D-\A-S-SB\JSC\AS"\U\V\A\K\A\4\K\A\4\\!44SDjrWS<\'SE\(SF\AS-S"\K\A\44SGjrXSSH.S<\'SI\ASF\AS-S"\(4SJjjrYSSH.S<\'SK\ASF\AS-S"\P4SLjjrZSM\ASF\AS-S"\U\A\AS-44SNjr[SE\(S"\A4SOjr\SSPSQ.S<\'SR\ASF\AS-SS\CS"\A4 STjjr]g)UN)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.12iX24h2.) COMPLETEDERRORDELETEDCANCELEDz/.hf-sbx-servera#set -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" "$d"; fi chmod +x "$d" unset SBX_SERVER_URL SBX_SERVER_MOUNT exec "$d" hf_tokennoncereturnc[R"UR5SU3R5[R5R 5$)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 T/var/www/html/pdf-tiff/venv/lib/python3.13/site-packages/huggingface_hub/_sandbox.py_derive_sandbox_tokenr4^s; 88HOO%UG'<'C'C'Ew~~ V ` ` bbdurationcd[U[[45(a [U5$[U5$)zBParse a duration like 300, "300s", "10m", "2h", "1d" into seconds.) isinstanceintfloatr)r6s r3_duration_to_secsr;hs((S%L))8} ( ##r5c\rSrSr%Sr\S-\S'\\S'\\S'Sr\S-\S'Sr \ \S 'S r \\S '\ S \ 4S j5r S \4SjrSrg)SandboxCommandResultoz?Result of a command executed in a sandbox with [`Sandbox.run`].N exit_codestdoutstderrsignalF timed_outr duration_msr+c URS:H$Nr)r?selfs r3okSandboxCommandResult.okzs~~""r5c[UR5S::a UROURSSS-nSURSU<SURS3$)NPMz...zSandboxCommandResult(exit_code=z , stdout=z, duration_ms=))lenr@r?rD)rHouts r3__repr__SandboxCommandResult.__repr__~sW -3dkkSb9IE9Q00@ #P^_c_o_o^ppqrrr5)__name__ __module__ __qualname____firstlineno____doc__r9__annotations__strrBrCboolrDpropertyrIrQ__static_attributes__rSr5r3r=r=osbITz K KFC$JItK #D##s#sr5r=c\rSrSr%Sr\\S'\\\-\S'\ "SSS9r S\S'S r \S -\S 'S r \S -\S 'S r \\S 'S r\S -\S'SSjrSrg )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). pidcmdF)reprcompareSandbox_sandboxNtag started_at_msTrunningr?cVURRSSUR35 g)z:Terminate the background process (idempotent server-side).DELETEz /processes/N)rf_requestrarGs r3killSandboxProcess.kills! x;txxj)ABr5rSr+N)rTrUrVrWrXr9rYrZr rrfrgrhrir[r?rmr]rSr5r3r_r_si H tCy UE:Hi:Ct $M3:$GT IsTz Cr5r_cj\rSrSr%Sr\\S'\\S'\S\S'\\S'Sr \S-\S 'S r \\S 'S r g) FileEntryz%A file or directory inside a sandbox.namepath)filedirsymlinktypesizeNmtime_msmoderS) rTrUrVrWrXrZrYrr9rzr|r]rSr5r3rqrqs7/ I I * ++ IHcDjD#Nr5rqc \rSrSrSrSrSrSrS!SjrS \ S\ 4S jr S"S \ S \ S\ 4S jjr S#S \ S \ \ -\ -S\ S-SS4SjjrS#S\ \-S \ S\ S-SS4SjjrS \ S\ \-SS4SjrS\S\\\\44SjrS\\S\\/\4S\\4SjrS \ S\S\\ 4SjrS \ S \ S\ S-SS4SjrS \ S\\4SjrS \ S\4SjrS \ S\4SjrS$S \ S\SS4Sjjr S \ SS4Sjr!S r"g)% 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. i r+NcXlgNrfrHsandboxs r3__init__SandboxFiles.__init__s r5rtcURU5RnX R:a SRUR X55$UR R SSSU0S9nUR$)z=Read a file from the sandbox and return its content as bytes.r5GET /files/readrtparams)statryPARALLEL_THRESHOLDjoin _read_rangesrfrlcontent)rHrtryresponses r3readSandboxFiles.readsgyy## )) )88D--d9: :==))%PT~)Vr5encodingcBURU5RU5$)z@Read a file from the sandbox and return its content as a string.)rdecode)rHrtrs r3 read_textSandboxFiles.read_textsyy%%h//r5datar|c>[U[5(aUR5nO%[U[5(dUR 5n[ U5UR :aURXU5 gSU0nUbX4S'URRSSXBS9 g)zHWrite content to a file in the sandbox (parent directories are created).Nrtr|PUT /files/writerr) r8rZr/bytesrrOr _write_rangesrfrl)rHrtrr|rs r3writeSandboxFiles.writes dC ;;=DD%((99;D t9t.. .   t4 0 $  !6N unVRr5 local_pathc*[U5R5RnX@R:a+UR U[U5R 5U5 g[ US5nURX%US9 SSS5 g!,(df  g=f)z#Upload a local file to the sandbox.Nrb)r|)rrst_sizerr read_bytesopenr)rHrrtr|ryfs r3uploadSandboxFiles.uploadsrJ$$&.. )) )   tT*%5%@%@%BD I  *d #q JJtTJ *$ # #s *B BcURU5RnX0R:a?[US5nUR X5HnUR U5 M SSS5 gUR RSSSU0S9n[US5nURSS9HnUR U5 M SSS5 SSS5 g!,(df  g=f!,(df  N(=f!,(df  g=f) z!Download a file from the sandbox.wbNrrrtrr) chunk_size) rryrrrrrf_stream iter_bytes)rHrtrryrpartrchunks r3downloadSandboxFiles.downloadsyy## )) )j$'1 --d9DGGDM:(  ]] " "5- " OS[j$'1%00K0HEGGENI(P O (' ''P Os/*C  C/(C<C/ C C, (C// C=ryc xURn[SX5Vs/sHo3[X!U- 54PM sn$s snfrF)PARALLEL_CHUNK_SIZErangemin)rHryroffsets r3_rangesSandboxFiles._rangess:((BG4BWXBWU6M23BWXXXs7itemsfnc[UR[U55n[U5n[ UR X!55sSSS5 $!,(df  g=f)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_WORKERSrOrlistmap)rHrrworkersexecutors r3 _parallelSandboxFiles._parallelsA d//U<  (H R/0) ( (s A Ac^^S[[[4S[4UU4SjjnTRTR U5U5$)Nrngr+c`>UupTRRSSTXS.S9nUR$)Nrr)rtrlengthr)rfrlr)rrrrrtrHs r3fetch(SandboxFiles._read_ranges..fetchs= NF}}--}df-_.H## #r5)tupler9rrr)rHrtryrs`` r3rSandboxFiles._read_rangess? $uS#X $5 $ $~~dll40%88r5c^^^^S[[[4SS4UUUU4SjjnTRTR[ T55U5 g)Nrr+c j>UupTUS.nTbTUS'TRRSSUTXU-S9 g)N)rtrr|rrrrfrl)rrrrrr|rtrHs r3push(SandboxFiles._write_ranges..pushsK NF.2f%EF!%v MM " "5.QUV\hn_nQo " pr5)rr9rrrO)rHrtrr|rs```` r3rSandboxFiles._write_rangessD qeCHo q$ q q t||CI.5r5cURRSSSU0S9nUR5SVs/sHn[S0UD6PM sn$s snf)z List a directory in the sandbox.rz /files/listrtrentriesrS)rfrljsonrq)rHrtrentrys r3rSandboxFiles.list sO==))%PT~)V08  0JK0Ju "E"0JKKKsA cnURRSSSU0S9n[S0UR5D6$)z3Get metadata of a file or directory in the sandbox.rz /files/statrtrrS)rfrlrqr)rHrtrs r3rSandboxFiles.stats6==))%PT~)V+8==?++r5cxURU5 g![anURS:XaSnAgeSnAff=f)z+Check whether a path exists in the sandbox.TiNF)rr status_code)rHrtes r3existsSandboxFiles.existss7  IIdO }}#  s 9449 recursivecZSU0nU(aSUS'URRSSUS9 g)z*Delete a file or directory in the sandbox.rt1rrkz /files/deleterNr)rHrtrrs r3deleteSandboxFiles.deletes1$ "%F;  xHr5c>URRSSSU0S9 g)z0Create a directory (and parents) in the sandbox.POSTz /files/mkdirrtrNr)rHrts r3mkdirSandboxFiles.mkdir&s v~vtnMr5r)rrer+N)zutf-8r)F)#rTrUrVrWrXrrrrrZrrrr rrrrr9r rrr r rrrrqrrr[rrrr]rSr5r3r~r~s))    0c0S0s0 S# SS5[8%; S3: SY] S+t+3+cDj+TX+ #S #cDj #T #YCYDsCx$9Y1tCy1hucz.B1tCy199C9DK96#6U6#*66LLiL ,,, 34I3I4IDIN#N$Nr5r~rbshellcUSLa [U[5(d [S5eUSLa [U[5(a [S5eSU0nUbXS'U$)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.rbr)r8rZ ValueError)rbrpayloads r3 _exec_payloadr+s\ }ZS11^__ ~*S#..mnn$clG   Nr5rc## UR5H=nU(dM [R"U5nURS5S:wdM9Uv M? g7f)zJIterate NDJSON events from a streaming response, skipping keepalive pings.eventpingN) iter_linesrloadsget)rliners r3 _iter_eventsr7sB##%  4  99W  'K &s AA AcUR5 UR5Sn[ SUR SU3UR S9e![a URSSnN?f=f)zQRead the error body and raise a SandboxError (works for streaming responses too).errorNizSandbox API error (z): )r)rr Exceptiontextrr)rmessages r3_raise_for_statusrAsl MMO&--/'* ,X-A-A,B#gYO]e]q]q rr &--%&sA A%$A%c<\rSrSrSrSSS.S\S\S\S -S \S \S \S \S\S\SS 4Sjjr\ SSS.S\ S \S \S \S\S\SS4Sjj5r \ S\S -4Sj5r S\S\S\R4Sjr\S\S\S\\R4Sj5rSSjrSSjrS\SS 4SjrSrg )_SandboxServeriKu5HTTP 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. r)max_connectionscapacityjob_idownerimageNbase_urlr* sandbox_tokenapirrr+c XlX lX0lX@lXPlXpl[ U5UlX`lXl SUl SUl [R"SUR3US.[R"XS9SS9Ulg)NrTBearer  AuthorizationzX-Sandbox-Token)rmax_keepalive_connections)headerslimitsfollow_redirects)rr_imagerr*_api_effective_token _auth_token_sandbox_tokenrliveverifiedhttpxClientLimits_client) rHrrrrr*rrrrs r3r_SandboxServer.__init__Ss      +C0+   ||#*4+;+;*_SandboxServer.cancel_jobs! DKK4::Fr5 start_timeoutc [R"5U-nSn[R"5U:GaoURRURS-[R "S5S9nUR S:Xag[R"5U- S:a[R"5nURRURURS9nURR[;ar[URURURS 9n[!S URS URRS URR"S U35e[R$"S5 [R"5U:aGMo[!S URSUSS35e![Ra GNUf=f)zMPoll /health until the server answers; fail fast (with logs) if the job dies.gz/healthg@)r*Ng@r<r=z Sandbox job z$ terminated during startup (status: z , message: ).g333333?z did not become ready within z.0fzs.)timerrrrr0r RequestErrorr inspect_jobrrstatusstage_TERMINAL_STAGES_tail_job_logsrrsleep)rHr@deadlinelast_job_checkrrlogss r3 wait_ready_SandboxServer.wait_readys99;.iikH$ <<++DMMI,Eu}}]`Oa+b''3./yy{^+c1!%ii++4;;$**+U::##'77)$))T[[DJJWD&&t{{m4$$'JJ$4$4#5[ASAS@TTVW[V\^ JJt !iikH$"\$++6STabeSffhijj%%  sA GGG) rrrrrrrrrr*rrro)rTrUrVrWrXrZrr9r classmethodrr$r\rrResponser1rr r6r9r>r:rPr]rSr5r3rrKso" "& &  & Tz &  & & & & & &  & P "             .sTzc5>>S(5>>:RGkk$kr5rc \rSrSrSr\SSS\S\S4Sj5r\SS S\S\/S44S j5rSS S\S\S4S jrS r g) _KillMethodiz>Lets `kill` work both as a classmethod and an instance method.instanceNrr+).NcgrrSrHrVrs r3__get___KillMethod.__get__sKNr5recgrrSrXs r3rYrZsORr5Sandbox | Nonec t^Ub UR$SSS.S[S[S-S[S-SS4U4SjjjnU$)Nr=token sandbox_idr=r_r+cB>TRXUS9R5 g)Nr^)r-rm)r`r=r_rs r3rm!_KillMethod.__get__..kills MM*M G L L Nr5)_killrZ)rHrVrrms ` r3rYrZsV  >> !=AW[ OS Od  O#PT* O`d O O r5rS) rTrUrVrWrXrrxr rYr]rSr5r3rUrUsmH NNTNhy6INN R R$R8BH;MRR 0(9BUr5rUc0\rSrSrSrS\S\S\S-S\S\S S4 S jr\ \ 4S \ SSSSS S SS. S\S\S\ \ -\-S-S\\\4S-S\\\4S-S\\S-S\S-S\S\ S\S-S S4Sjjj5r\ SSS.S\S\S-S\S-S S4Sjj5r\"5rSASjrSASjrSBSjrSAS jr\S!S!S!S!S!S!S!S!S!S". S#\\\-S$\S-S\\\4S-S%\S-S&\ S-S'\S-S(\\/S4S-S)\\/S4S-S*\S+\S S \4S,jj5r\S!S!S!S-.S#\\\-S$\S-S\\\4S-S%\S-S+\S.S \4 S/jj5rSSSSSSSS.S S". S#\\\-S$\S-S\\\4S-S%\S-S&\ S-S'\S-S(\\/S4S-S)\\/S4S-S*\S+\S \\-4S0jjrS \\4S1jr \!S \S-4S2j5r"\!S \S-4S3j5r#SCS4S5.S6\ \-S7\S8\S \4S9jjjr$\!S \\\44S:j5r%S \4S;jr&S<\S=\S \'RP4S>jr)\*S<\S=\S \+\'RP4S?j5r,S@r-g)DreiaAn 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) ``` rserverlocal_idN owns_sandbox owns_serverr+cXlX lX0lUcSOSU3UlX@lXPlSUlSUl[U5Ul g)Nz/v1/v1/sandboxes/F) r_server _local_id _base_path _owns_sandbox _owns_server_on_kill_killedr~files)rHrrerfrgrhs r3rSandbox.__init__sT !$,#3%>(9T*(<@  !$' r5 cpu-basicF^@) flavor idle_timeoutenvsecretsvolumesr=forward_hf_tokenr@r_rrvrwrxryrzr=r{r@r_c [U S9n [U 5n [S5n [X5n[ U U UUUUUUS9unnnnU R UUUUU[ [S[[[U 0U=(d S[/US9 nSn[RUU UU [RS-S9nUR!U 5 U"UR&USS S S 9$!["a U R%UR&UR(R*S 9 Orrrsloggerwarningr9)r#rrvrwrxryrzr=r{r@r_rr)r*rrjob_env job_secrets job_volumesrrers r3createSandbox.createsf% #C(" -h> 5H  %-' 6 2+{kk(!3 NKQVW'4'(  +/ #,,+ , A AA E -F   m ,cffVd[_``  dcff G d!>svvhF^_`^abcc d!   s69C E.D  E E%D>9E>EEr^r`c[US9n[X5up[U;avUR[S5upV[ XEUS9nUR SS5R 5Vs1sHoSiM n nXi;a[SUSUS 35eU"XUS S S 9$URXS 9n U R=(d 0n U R[5n U R[5S:wdU c[SUS[S35eU R[5[ :Xa[SUS[S35eU R"R$S:wa&[SUSU R"R$S35e['[)U5U 5n [*R-U U U U[.R0S-S9nU"U R2USS S S 9$s snf![a UR5 ef=f)z?Reattach to a running sandbox from anywhere, using only its id.r}rrCr /v1/sandboxesrzSandbox z no longer exists on host r#FTrr<rNJob 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: rDrr)r_split_sandbox_id SHARED_ID_SEPsplit _connect_hostr1rrrr9rGrrrrr MODE_POOLrHrIr4rrr$r~rr)r#r`r=r_r host_job_idrfreitemexistingrrr*rs r3r-Sandbox.connectfs%  1* H J &$.$4$4]A$F !K"3yIF 39>>%3Y3^3^3`a3`4J3`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 &G4G G G'cUR(agURcURR5 O*URR SSUR35 SUlURbURU5 UR(aURR5 gg![ a/n[ RSURSU35 SnAgSnAff=f)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. NrkrjzFailed to kill sandbox : T) rqrlrkr>r1rrrrrpror9)rHrs r3rc Sandbox._kills <<  ~~% '') $$X?O/PQ  == $ MM$     LL      NN4TWWIRsC D  s'B8)B88 C1%C,,C1c\UR(aURR5 gg)zRelease the local HTTP client without terminating the sandbox. Idempotent. No-op for pool sandboxes (the client belongs to the pool's host). N)rorkr9rGs r3r9 Sandbox.closes"    LL    r5cU$rrSrGs r3 __enter__Sandbox.__enter__ r5chUR(aUR5 gUR5 gr)rnrmr9rHexc_infos r3__exit__Sandbox.__exit__s    IIK JJLr5.) rrxcwdr*stdin on_stdout on_stderrcheck backgroundrbrrr*rrrrrc grrS) rHrbrrxrr*rrrrrs r3run Sandbox.runs #r5)rrxrTcgrrS)rHrbrrxrrs r3rrsr5c |[X5n U(aX;S'U(aXKS'U (a<URSSU S9R5n [U SXR S5US9$UbX[S 'UbXkS '/n /nS nUR SS U S9n[ U5HnUS S:Xa&U RUS5 Ub U"US5 M0M2US S:Xa&URUS5 Ub U"US5 M_MaUS S:XdMl[USSRU 5SRU5UR S5UR SS5UR SS5S9nM S S S 5 Uc [S5eU (a*URS:wdUR(a [XS9eU$!,(df  NO=f)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`. rxrr /processesrrarg)rarbrgrfNr*rz/execrr@rrAexitr?r{rBrCFrDr)r?r@rArBrCrDz%connection lost while running command)rbresult)rrlrr_rrrappendr=rrr?rCr)rHrbrrxrr*rrrrrrr stdout_parts stderr_partsrrrs r3rrsh +  EN  EN ==G=DIIKD!d5ksZ^_ _  !(I   $G "$ "$ .2 \\&'\ 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 A4F-A"F-- F;c URSS5R5nUVs/sHHn[USUSURS5URS5USURS5US 9PMJ sn$s snf) 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. rrrarbrgrhrir?)rarbrgrhrir?rf)rlrr_r)rHrps r3 processesSandbox.processes3s}}UL1668   eHeHEE%LeeO4) %% ,    sAA7c.URR$r)rkrrGs r3r Sandbox.imageJs||!!!r5cLURbURR$S$)zIFor a shared/pool sandbox, the job id of the host running it (else None).N)rlrkrrGs r3host_idSandbox.host_idNs"'+nn&@t||""JdJr5zhttps://)schemeportrtrcURRRSS5SnURS5(aUOSU-nUUURSUU3$)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://r/z/proxy/)rkrr startswithrm)rHrrtr host_and_rests r3 proxy_url_forSandbox.proxy_url_forUsaL --33E1=bA s++tt-(9tfMMr5cbSURR3URRS.$)zPAuth headers to send with [`proxy_url_for`] requests (HF token + sandbox token).r r )rkrrrGs r3 proxy_headersSandbox.proxy_headerss0 't||'?'?&@A#||::  r5c@SUR<SUR<S3$)Nz Sandbox(id=z, image=rN)rrrGs r3rQSandbox.__repr__sTWWKx ~Q??r5r(resourcec VURR"XRU-40UD6$r)rkr1rm)rHr(rr3s r3rlSandbox._requests%||##FOOh,FQ&QQr5c+# URR"XRU-40UD6nUv SSS5 g!,(df  g=f7fr)rkr6rm)rHr(rr3rs r3rSandbox._streams9 \\ 8)C Nv NRZNO N Ns+A ; A  A A ) rmrqrlrprnrorkrrrro)r+re)r).rTrUrVrWrXrZrr[rrR DEFAULT_IMAGEDEFAULT_IDLE_TIMEOUTr9r:dictr r rrr-rUrmrcr9rrrr rr=rr_rr\rrrrrQrrSrlrr rr]rSr5r3reres ( ( ( * (  (( (:#ba"1E%))-'+ $!&$ baba ba EkC'$. ba #s(^d " bac3h$&baf$ba:bababaTzba babaHAE[_$b$bC$J$bcTXj$bdm$b$bP =D!.! !%( #2525%( # 49_ #d{ # #s(^d " # 4Z # #Tz #SE4K(4/ #SE4K(4/ # #EN #  # # !%(  49_d{  #s(^d "  4Z DM "%) $ 2626 [ 49_[d{ [ #s(^d " [ 4Z [[Tz[SE4K(4/[SE4K(4/[[[  .[z 4/ ."sTz""KtKK (Nz(N#)(N3(N(N^a(NT tCH~  @#@ RsRcRRcSx?Wr5recr\rSrSrSr\4S\SSS\SSSSS. S \S \S \ S \ S \ S-S\S-S\ \ -\-S-S\S-S\ S\S-S\ SS4Sjjjr \ SSS.S\S\S-S\S-SS4Sjj5rS;S\ S\\4SjjrS\SS.S\\\4S-S\ \ -\-S-S\ SS4Sjjr\S\ 4S j5r\S\ 4S!j5r\S\\4S"j5rSS(jrS)\S*SS'4S+jrS\ 4S,jrS>> 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 ``` rtrNruF) rvsandboxes_per_hostwarm_up max_hostsrsrwr=r@r_ _connect_moderrvrrrrsrwr=r@r_rr+c ,US:a [S5eUS:a [S5e[U S9UlXlX lX0lX@lXPlUbUO S[S53Ul Xpl Xl Xl /Ul [R"5Ul[R"5Ul[R"5UlSUlSUlXlU (+Ul[/5UlU (dUR35 gg) 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. rz sandboxes_per_host must be >= 1.zwarm_up must be >= 1.r}Nzpool-F)rrrrrvr_warm_uprrrs _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) rHrrvrrrrsrwr=r@r_rs r3rSandboxPool.__init__sl  !?@ @ Q;45 5&   "4 " ,DE)A,2H )#+,. ^^% &NN, $..* #0 -,(+   " " $r5r^pool_idc `[U5nUbOU"URURURURUUR Uc UR OUUSS9 $[US9n[XQUS9n[XVUS9nURS5nURS5n U"UR=(d UR=(d [URb[UR5OS[URS [ 55U b [U 5OSUUb [U5OSUUSS9 $) 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) rrvrrrsrwr=r_rr}rCSBX_IDLE_TIMEOUT SBX_MAX_HOSTSrt SBX_CAPACITY)rrrvrrrwr=r_find_pool_host_job _host_envrr r!rrZr9DEFAULT_SANDBOXES_PER_HOST) r#rr=r_cacherrrxidle_raw max_hosts_raws r3r-SandboxPool.connects. (  kk||#(#;#;//"//-6->%//I"  % !#)DI677-.0 ""CcllCm&)jj&<3szz?+"377>;U#VW,9,Ec-(4*2*>XD  r5 num_hostscUR(a [S5eUR5 UR U[ UR 5- nSSS5 WS:aAUR U5nUR UR RU5 SSS5 UR SUl SSS5 UR5 UR$!,(df  N=f!,(df  NW=f!,(df  NL=f)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.NrT) rr_discover_hostsrrOr_provision_hostsextendrr _save_cachehost_ids)rHr  shortfallbooteds r3warmSandboxPool.warmTs <<<= =  ZZ!C $44I q=**95F ""6*   "DO }}Z  s#C=C*-C; C'* C8; D )rxrwr{rxr{recUR(a [S5e[U=(d 05nU(a[UR5US'Ub [ U5OSn/nSnSnUR 5 UR5n U c)U(d"SnUR5 UR5n U chUR(aFU(a?UR(d.[UR5 [SURS35eURU5n U b>URXU5n U bUR'5 U $X;aUR)U 5 SnUS - nU[*:a [S 5eGM![aF UR  [#SU R$S - 5U lSSS5 e!,(df  e=ff=f![a UR  URV s/sH oU;dM U PM Os sn fsn Ul SSS5 O!,(df  O=fUHJn U R-5 O![a Of=fU R/5 M7!U R/5 f=f ef=f) 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. r HF_TOKENNFrT No running host found for pool 'X'. The pool has stopped (all its hosts were killed or idle-timed-out); create a new one.rzZCould not place sandbox: hosts kept reporting full. Raise max_hosts or sandboxes_per_host.)rrrrrr;r _reserve_oner rrrrs_boot_one_host _create_onerrmaxrrremove_MAX_PACK_ROUNDSr>r9) rHrxrwr{ sandbox_env idle_secs new_hosts discoveredroundshostrhs r3rSandboxPool.createosG: <<<= =39"o &6tyy&AK #8D7O%l3UY *,  <   " " $((*< !%J((*,,.D<..:dkk*$))4*>tyykJ__ ..y9D#"&"2"24i"P*((*& (!((." ! ,,&tU0%"ZZ(+Atyy1}(=DI((Z * *.++L+Q)9Kq+L !!OO% JJLDJJL "  s'B;G#E?5G 5G?GF=4 G= G GGJ(H!7 H H  H! J! H/ + J8I I+ II+II+J+I==JczUR [UR5sSSS5 $!,(df  g=f)z*Number of host jobs currently provisioned.N)rrOrrGs r3r SandboxPool.num_hostss!ZZt{{#ZZs, :cUR [SUR55sSSS5 $!,(df  g=f)z,SandboxPool.num_sandboxes..s9[Tyy[sN)rsumrrGs r3 num_sandboxesSandboxPool.num_sandboxess'ZZ9T[[99ZZs 3 AcUR URVs/sHoRPM snsSSS5 $s snf!,(df  g=f)z!Job ids of the provisioned hosts.N)rrrrHr$s r3rSandboxPool.host_idss5ZZ,0KK8KDKKK8Z8ZsA=AA AcUR URn/UlSUlSSS5 WH5nUR(aUR 5 UR5 M7 UR(a[UR5 gg!,(df  Nq=f![ a/n[ RSURSU35 SnANSnAff=f!UR5 f=f)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) rrrrr>rrrrr9rrs)rHhostsr$rs r3r9SandboxPool.closesZZKKEDKDLD ##OO%     dii ( Z T!? }BqcRSS T s4B!B$ B!$ C.%CC CC  C2cU$rrSrGs r3rSandboxPool.__enter__rr5c$UR5 gr)r9rs r3rSandboxPool.__exit__s  r5c`UR UR(a SSS5 gUR5 URc URO[ URUR5nUR  U[UR5- nSSS5 WS:aUR5 UR(dtUR  U[UR5- nSSS5 US:aAURU5nUR  URRU5 SSS5 SUlSSS5 UR(aUR5 gg!,(df  N=f!,(df  N=f!,(df  Nb=f!,(df  Nd=f)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. NrT)rr_seed_hosts_from_cacherrrrrOrr rr rr)rHtargetrrs r3rSandboxPool._ensure_warmed_ups+      ' ' )&*nn&E,;FE=++FF2F, E: 6F= F F F F F-_SandboxServer | NonecUR URHBnURUR- S:dM"U=RS- slUs sSSS5 $ SSS5 g!,(df  g=f)zNReserve one slot on the first host with free capacity (under lock), else None.rrN)rrrrr2s r3rSandboxPool._reserve_one1sZ ZZ ==499,q0IINIK Z#  Z s+A)A)A)) A7r!rcUR UR5nUb UsSSS5 $UR5(aUR5nUb UsSSS5 $URS5nUR U5 UR  UR R U5 SSS5 UR5sSSS5 $!,(df  N'=f!,(df  g=f)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. Nr)rr_adopt_pending_hostr rrr)rHr!r$rs r3rSandboxPool._boot_one_host:s__$$&D _''))((*#_**1-F   V $ ""6*$$&!__s.C)C.C C )C C C C)c L^^URVs1sHoRiM snm[U4SjURR S[ [ [UR0URS95S5mTcg[RSURSTRS35 [R"5UR-n[R"5U:aURRTRURS 9R R"nUS ;agUS :Xa5UR%5 ['U4S jUR55(ag [R("S5 [R"5U:aMgs snf)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. c3L># UHnURT;dMUv M g7fr)r)r+rknowns r3r,2SandboxPool._adopt_pending_host..`s, C 66& s$ $ SCHEDULINGrHrr=NFzPool 'z' host z: is already SCHEDULING; waiting for it instead of booting.r<)rJrrc3T># UHoRTR:Hv M g7frrr)r+r$pendings r3r,rIwsI[T{{gjj0[%(Tg?)rrnextr list_jobsrr POOL_LABELrsrrdebugrrErrGrHrIr anyrL)rHr$rMrIrHrNs @@r3rDSandboxPool._adopt_pending_hostVsG*.55 99..'& :tyyI"oo/     ? vdii[ |;uvw99;!4!44iikH$II))t)W^^ddE55 !$$&IT[[III JJsOiikH$96sF!c>^URVs1sHoRiM nnURRS[[ [ UR0URS9Vs/sHnURU;dMUPM nnUGH mSn[URTRURS9n[URTURS9n[URSUR55Ul[!UR#SS5R%55UlUR6 [9U4S jUR55(aUR55 OURR;U5 SSS5 GM gs snfs snf![([*R,[.4aDn[0R3STRS U35 UbUR55 SnAGMzSnAff=f!,(df  GM=f) 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. rrKNrCrrrzSkipping host z during discovery: c3T># UHoRTR:Hv M g7frrM)r+r$rs r3r,.SandboxPool._discover_hosts..sE{{cff,rO)rrrrQrrrRrsrrrrr9rrrrOr1rrrr HTTPErrorrrrSr9rrTr)rHr$rHrmatchesrerxrs ` r3r SandboxPool._discover_hosts|s*.55yy** "Iz499E//+  vvU"   CF &tyy#&&DOOT  3$//J"%cggnd>U>U&V"W!&.."H"M"M"OP EEEELLNKK&&v. !6 &!%//>B  ~cffX5HLM%LLN  s7F(F!F!B F&=AH &H 8HH  H num_newc .UR [UR5nSSS5 URbKWU-UR:a8URU- n[ SUSURS[ SU5S35e[ [US5S9n[U5Vs/sHoTRUR5PM nnSSS5 /nSnWH#n URU R55 M% Ub,UH$n U R5 U R5 M& UeU$!,(df  GN=fs snf!,(df  N=f![a n U nSn A MSn A ff=f![a Nff=f!U R5 f=f) z=Boot `num_new` host jobs in parallel, respecting `max_hosts`.Nz Pool needs z more host(s) but max_hosts=z allows only rz. more. Raise max_hosts or kill some sandboxes. ) max_workers)rrOrrrrrrrsubmit _boot_hostrrrr>r9) rHr\currentallowedr_futuresrrfuturerres r3r SandboxPool._provision_hostssj ZZ$++&G >> %'G*;dnn*Lnnw.GgY&B4>>BRS"1g//]_  C,< =AFwPAt7GP>')"&F  fmmo.   #%%'LLN !K ;ZQ> =   !LLNseD0E$$EEEE20 D?E E E/"E**E/2 E?<F>E??FFc [UR5n[S5n[X5n[ URUSSSUR SUS9upEpgSUS'[ UR5US'URb[ UR5US'[S[[[UR[U0nURRUR UUUUR"[$UU=(d S[&/UR(S 9 n Sn [*R-U UUUR[/URS -S 5URS 9n U R1UR25 U $![4a URR7U R8U R:RS 9 Orrrrr9) rHr)r*rrrrrrrrers r3raSandboxPool._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!   s7AE22 H=8F65H6 G/%G*%H*G//Hr$r r\cSS0nUbX4S'U(aX$S'URSSUS9R5nS UlURS 5=(d /n[URS S55(dU(d'UR URUlSSS5 gUSn[UR[ US3UUSS SS9n UR"U lU $![[R4aRnUR (ae[ RS URS U35 URU5 SnAgSnAff=f!,(df  g=f)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). countrNidle_timeout_secsrxrrrz!Dropping unreachable cached host rT sandboxesrejectedrrFr)r1rrrrYrrrSr _drop_hostrr9rrrrer_on_sandbox_killedrp) rHr$rxr bodyrrrorrs r3rSandboxPool._create_onesC!(|  (1$ % K <<d<CHHJD HH[)/R txx A& ' 'y MM |++}od4j\:$Z   22+eoo. }} LL*>*B#CGOO ZZs 3A  AcUR URVs/sH o"ULdM UPM snUlURRUR5 SSS5 UR 5 gs snf!,(df  N$=f)zFForget a host found dead this session (and mark it for cache pruning).N)rrraddrr9)rHr$r%s r3rqSandboxPool._drop_host0s] ZZ&*kkCkd]1kCDK    # #DKK 0 DZs A9A4A4-A94A99 Bc[UR5nUcg[UR5nUR UR Vs1sHo3R iM nnURHnUR U;dURUR:aM/[UR URURURUR[X%R5UR[!UR"S-S5URS9 nURUlSUlUR R'U5 M SSS5 gs snf!,(df  g=f)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. Nr(rjrF)rrsrrrrrr6rrrrrrr*r4rrrr)rHrr)r$rHchres r3r="SandboxPool._seed_hosts_from_cache9s   * = #DII. ZZ-1[[9[T[[[E9kk99%BKK)?'99((**[[(("7(("K $'(?(?!(CS$I[[ !gg "' ""6*!"Z9ZsE" EC5E"E"" E0cRUR URVs/sHan[URURUR UR URUR[R"5S9PMc nn[UR5nSSS5 [URURURUR UR"UR$b['UR$5OSUR(WWS9 gs snf!,(df  N=f)zOPersist the pool config + current hosts (with their live counts) for next time.)rrrr*rr updated_atN)rrvrrrwr=r6 dead_host_ids)rrrrrrr*rrrErrrrsrrvrrrr;r)rHr$r6deads r3rSandboxPool._save_cacheYs ZZ!KK (D;;**!]]**!]]#yy{(  t**+D  II**;;#66nnBFBTBTB`*4+=+=>fjoo  ZsDA(DDD D&)rrrrrrrrrrrrrrrvrrrsr)rro)r+r)r+r@)*rTrUrVrWrXrrrrZr9r:r[rrRr-r rrr rr\r r/rr9rrrrrrDr rr rarrerrrqr=rr]rSr5r3rrs!J#`%""< $1E $$ #`%`% `%  `%  `%:`%Dj`%EkC'$.`%:`%`%Tz`%`% `%H>BX\4 c4 t4 3QU:4 an4 4 lc$s)<&*1E!& e#s(^d "eEkC'$. e  e  eN$3$$ :s:: 9$s)99 )0 'R'-=(>'CZ'8$T$L&/P^0DB>N>@$ 0$tCH~$RUX\R\$aq$LD'DdD ~$+@ r5rrc[UR[5(a URO [5nU(d [ S5eU$)NzMA Hugging Face token is required to use sandboxes. Run `hf auth login` first.)r8r_rZrr)rr_s r3rrvs3#CIIs33CIIE jkk Lr5rxryrzrwr{rc 0U=(d 0ES[[50En0U=(d 0ESU0En [U=(d /5n Ub[[U55US'U(aXS'URS[ R S3US'[US'U R[S [ R [S S 95 S S [/n XX4$)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_TOKENrrz /buckets/z/resolve/sbx-serverSBX_SERVER_URLSBX_SERVER_MOUNTbucketT)rxsource mount_path read_onlyz/bin/shz-c) rZrrr;endpointrSANDBOX_SERVER_BUCKET_SERVER_MOUNT_PATHrr_BOOTSTRAP_DOWNLOAD) rr)rxryrzrwr{rrrrrs r3rr}s&T#)Sj#>Q:RSG"Qgm"Qk="QKw}"%K&)*;L*I&J"#"*J#&<<. ):Y:Y9ZZm nG #5G HY%D%DQcost$ 34G [ 55r5rr=c[UR[5(a URO0nSU;aFURURUS9R=(d 0n[U[5(aUO0nU$)z6Return a host job's env vars (where pool config lives)rr<)r8 environmentrrGr)rrr=rxs r3rrs_'>>#//BCS ooSVVyoAMMSQST**c Jr5rCrctURS[[[U0US9HnUs $ [ SUS35e)zNReturn any running host job belonging to `pool_id` (found via the pool label).rrKrr)rQrrrRr)rrr=rs r3rrsT}}*iW!MYb   *7)4K K r5rc URXS9nUR=(d 0nUR[5nUbUR[5[ :wa[ SUS35eURRS:wa&[ SUSURRS35e[RUU[[U5U5U[RS-S 9$) z?Reattach to a running host job and return its server transport.r<rz is not a sandbox host.rz Sandbox host rrDrr)rGrrrrrrrHrIrr$r4rr~r)rrr=rrr*s r3rrs /// BC ZZ 2F JJ{ #E } :.);T+.EFGG zz9$];-7PQTQ[Q[QaQaPbbdeff  " " +,.s&EutD6{us)rfetch_job_logsrr)rrr=rliness r3rKrKsbS''v'KLeVWUJO?TYY&Eu&EE EVTVV sA AA)^r0r-rrrEconcurrent.futuresr contextlibr dataclassesrrpathlibrryrtypingr r r r r rrrr{r_sandbox_cacherrrr _space_apirerrorsrrrhf_apirrutilsrrutils._parsingr get_loggerrTrrrrrrrRrrrrrrrJrrrrZr4r9r:r;r=r_rqr~r[rrrSrrrrUrerrrrrrrrrr"rKrSr5r3rs  1%(MMM  EE"%*   H %     !   A' cCccc$e c 1$c$ ss s& CC C.  ANANH sT#Y td{ tCH~ 5>>htnss4sxkxkv"{{| ^  ^  B%C#6 #6#6 c3h$  #6 #s(^d " #6 &\D #6+#d*#6#6#6 49d38nd38nd6l BC#6L5wcDjT#s(^NR U S d V] LPu3cDjTb$ *# *#* *sCRVJAW *g'gcgHLZ\WWsW#*WTWWadWr5