devzero-sandbox 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,546 @@
1
+ """Authenticated HTTP transport to one sandbox through the gateway (ADR-005-W11).
2
+
3
+ This is the layer the Phase 1 client (ADR-007-W13) builds files, exec, SSE and
4
+ the terminal on. It owns:
5
+
6
+ - the sandbox's base URL on either route: ``https://<host>/t/<team>/s/<id>``
7
+ (the ``connect.url`` DevZero returns) or, in-cluster,
8
+ ``https://devzero-sandbox-gateway.devzero-system.svc/p/<policy>/s/<id>``;
9
+ - the bearer: ``Authorization: Bearer <token>`` on every request, chosen per
10
+ request scope from :mod:`devzero_sandbox.auth` credentials, never in the URL,
11
+ a cookie or the WebSocket subprotocol (that carrier is for browsers);
12
+ - TLS trust: the in-cluster CA bundle, or a caller's bundle for a BYO gateway,
13
+ re-read when the file changes; verification cannot be turned off here;
14
+ - retries: ``503`` answers the gateway marks retryable (``Retry-After`` honoured,
15
+ otherwise backoff) for up to 10 s, and ``404 sandbox_not_found`` for 10 s
16
+ after :meth:`GatewayTransport.mark_ready` (the informer-lag window of
17
+ ADR-007 §Request pipeline step 4); one retry after a ``401`` when the
18
+ credentials have another token to offer;
19
+ - a gone sandbox (``409 sandbox_terminating`` / ``410 sandbox_expired``):
20
+ never retried, and handed to :attr:`GatewayTransport.on_gone` before it is
21
+ raised, so the owner can say why it went (ADR-010-W11).
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import os
27
+ import re
28
+ import ssl
29
+ import threading
30
+ import time
31
+ from collections.abc import Callable, Collection, Iterator, Mapping
32
+ from contextlib import contextmanager
33
+ from dataclasses import dataclass
34
+ from types import TracebackType
35
+ from typing import Any, Literal, Self
36
+ from urllib.parse import urlsplit
37
+
38
+ import httpx
39
+
40
+ from devzero_sandbox import errors
41
+ from devzero_sandbox.auth import (
42
+ BearerToken,
43
+ Credentials,
44
+ ProjectedTokenCredentials,
45
+ SandboxToken,
46
+ Scope,
47
+ TokenCredentials,
48
+ )
49
+ from devzero_sandbox.incluster import (
50
+ IN_CLUSTER_CA_PATH,
51
+ IN_CLUSTER_GATEWAY_URL,
52
+ IN_CLUSTER_TOKEN_PATH,
53
+ in_cluster_ssl_context,
54
+ )
55
+ from devzero_sandbox.redaction import get_logger
56
+
57
+ log = get_logger(__name__)
58
+
59
+ # ADR-007 §URL scheme grammar.
60
+ _ID = re.compile(r"sb[a-z0-9]{10}")
61
+ _TEAM = re.compile(r"[a-z0-9]([a-z0-9-]{0,22}[a-z0-9])?")
62
+ _POLICY = re.compile(r"[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?")
63
+ _PATH = re.compile(r"/v1(/[^?#]*)?")
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class SandboxEndpoint:
68
+ """One sandbox's base URL at the gateway.
69
+
70
+ ``route`` is ``"t"`` (external; ``scope_key`` is the team slug) or ``"p"``
71
+ (in-cluster; ``scope_key`` is the policy name).
72
+ """
73
+
74
+ origin: str
75
+ route: Literal["t", "p"]
76
+ scope_key: str
77
+ sandbox_id: str
78
+
79
+ @classmethod
80
+ def external(cls, connect_url: str) -> SandboxEndpoint:
81
+ """Parse ``connect.url`` (``https://<host>/t/<team>/s/<id>``)."""
82
+ u = urlsplit(connect_url)
83
+ parts = u.path.rstrip("/").split("/")
84
+ if u.scheme != "https":
85
+ raise ValueError(
86
+ "the gateway URL must be https; a bearer is never sent in clear text"
87
+ )
88
+ if u.username is not None or u.password is not None or u.query or u.fragment:
89
+ raise ValueError(
90
+ "the gateway URL must not carry credentials, a query or a fragment"
91
+ )
92
+ if len(parts) != 5 or parts[0] != "" or parts[1] != "t" or parts[3] != "s":
93
+ raise ValueError(
94
+ "expected a sandbox URL of the form https://<host>/t/<team>/s/<id>"
95
+ )
96
+ _check(_TEAM, parts[2], "team slug")
97
+ _check(_ID, parts[4], "sandbox id")
98
+ return cls(f"https://{u.netloc}", "t", parts[2], parts[4])
99
+
100
+ @classmethod
101
+ def in_cluster(
102
+ cls, policy: str, sandbox_id: str, gateway_url: str = IN_CLUSTER_GATEWAY_URL
103
+ ) -> SandboxEndpoint:
104
+ u = urlsplit(gateway_url)
105
+ if u.scheme != "https" or u.path not in ("", "/") or u.username or u.query:
106
+ raise ValueError("the in-cluster gateway URL must be https://<host>[:port]")
107
+ _check(_POLICY, policy, "policy name")
108
+ _check(_ID, sandbox_id, "sandbox id")
109
+ return cls(f"https://{u.netloc}", "p", policy, sandbox_id)
110
+
111
+ @property
112
+ def base_url(self) -> str:
113
+ return f"{self.origin}/{self.route}/{self.scope_key}/s/{self.sandbox_id}"
114
+
115
+ def url(self, path: str) -> str:
116
+ """The absolute URL of a gateway path such as ``/v1/exec`` for this sandbox."""
117
+ if not _PATH.fullmatch(path) or any(
118
+ seg in (".", "..") for seg in path.split("/")
119
+ ):
120
+ raise ValueError(f"not a sandbox API path: {path!r}")
121
+ return self.base_url + path
122
+
123
+
124
+ def _check(pattern: re.Pattern[str], value: str, what: str) -> None:
125
+ if not pattern.fullmatch(value):
126
+ raise ValueError(f"invalid {what} {value!r}")
127
+
128
+
129
+ @dataclass(frozen=True)
130
+ class RetryPolicy:
131
+ """How long the transport keeps trying before surfacing a gateway error.
132
+
133
+ ``window_s`` bounds both retries of retryable answers (from the first
134
+ attempt of a request) and retries of ``404 sandbox_not_found`` (from
135
+ :meth:`GatewayTransport.mark_ready`); ADR-007 sets both at 10 s.
136
+ """
137
+
138
+ window_s: float = 10.0
139
+ initial_backoff_s: float = 0.5
140
+ max_backoff_s: float = 4.0
141
+
142
+
143
+ class GatewayTransport:
144
+ """Sends authenticated requests to one sandbox; see the module docstring."""
145
+
146
+ def __init__(
147
+ self,
148
+ endpoint: SandboxEndpoint,
149
+ credentials: Credentials,
150
+ *,
151
+ ca_bundle: str | None = None,
152
+ retry: RetryPolicy | None = None,
153
+ timeout: float | httpx.Timeout = 60.0,
154
+ http_transport: httpx.BaseTransport | None = None,
155
+ clock: Callable[[], float] = time.monotonic,
156
+ sleep: Callable[[float], None] = time.sleep,
157
+ ) -> None:
158
+ if credentials.route != endpoint.route:
159
+ raise ValueError(
160
+ f"credentials for the /{credentials.route}/ route cannot be used on the "
161
+ f"/{endpoint.route}/ route (the gateway answers 401 wrong_auth_for_route)"
162
+ )
163
+ self.endpoint = endpoint
164
+ self.credentials = credentials
165
+ self._in_cluster = endpoint.route == "p"
166
+ # In-cluster, the operator's CA bundle is the only trust there is.
167
+ self._ca_bundle = (
168
+ IN_CLUSTER_CA_PATH if self._in_cluster and ca_bundle is None else ca_bundle
169
+ )
170
+ self._retry = retry or RetryPolicy()
171
+ self._timeout = timeout
172
+ self._http_transport = http_transport
173
+ self._clock = clock
174
+ self._sleep = sleep
175
+ self._lock = threading.Lock()
176
+ #: Called with a :class:`~devzero_sandbox.errors.SandboxGone` before it is
177
+ #: raised; :class:`~devzero_sandbox.sandbox.Sandbox` asks DevZero for the reason.
178
+ self.on_gone: Callable[[errors.SandboxGone], None] | None = None
179
+ self._ready_at: float | None = None
180
+ self._ca_key: tuple[int, int, int] | None = None
181
+ self._ssl: ssl.SSLContext | None = None
182
+ self._client: httpx.Client | None = None
183
+ # Requests and open streams per client, and clients a CA rotation
184
+ # replaced: a retired client is closed only once nothing uses it, so a
185
+ # rotation never cuts an open SSE stream or another thread's request.
186
+ self._users: dict[httpx.Client, int] = {}
187
+ self._retired: set[httpx.Client] = set()
188
+ self._ensure_client() # fail now, not on the first request, if the bundle is missing
189
+
190
+ @classmethod
191
+ def external(
192
+ cls,
193
+ connect_url: str,
194
+ token: TokenCredentials | SandboxToken | str,
195
+ *,
196
+ ca_bundle: str | None = None,
197
+ **kwargs: Any,
198
+ ) -> GatewayTransport:
199
+ """A transport for ``connect.url`` with sandbox JWT(s).
200
+
201
+ ``ca_bundle`` is a PEM file for a gateway whose certificate a private
202
+ CA issued (a BYO endpoint); it replaces the default trust store, as
203
+ ``curl --cacert`` does. Without it, public CAs are trusted.
204
+ """
205
+ creds = (
206
+ token if isinstance(token, TokenCredentials) else TokenCredentials(token)
207
+ )
208
+ return cls(
209
+ SandboxEndpoint.external(connect_url), creds, ca_bundle=ca_bundle, **kwargs
210
+ )
211
+
212
+ @classmethod
213
+ def in_cluster(
214
+ cls,
215
+ policy: str,
216
+ sandbox_id: str,
217
+ *,
218
+ gateway_url: str = IN_CLUSTER_GATEWAY_URL,
219
+ token_path: str = IN_CLUSTER_TOKEN_PATH,
220
+ ca_path: str = IN_CLUSTER_CA_PATH,
221
+ **kwargs: Any,
222
+ ) -> GatewayTransport:
223
+ """A transport for a pod in the cluster: SA token and CA from ``/var/run/dz-sandbox``.
224
+
225
+ No DevZero credential is needed. The CA bundle is required: there is
226
+ no fallback to the system trust store or to an unverified connection.
227
+ """
228
+ return cls(
229
+ SandboxEndpoint.in_cluster(policy, sandbox_id, gateway_url),
230
+ ProjectedTokenCredentials(token_path),
231
+ ca_bundle=ca_path,
232
+ **kwargs,
233
+ )
234
+
235
+ # --- TLS -------------------------------------------------------------------
236
+
237
+ def _build_ssl(self) -> ssl.SSLContext:
238
+ if self._in_cluster and self._ca_bundle is not None:
239
+ return in_cluster_ssl_context(self._ca_bundle)
240
+ if self._ca_bundle is not None:
241
+ ctx = ssl.create_default_context(
242
+ ssl.Purpose.SERVER_AUTH, cafile=self._ca_bundle
243
+ )
244
+ else:
245
+ ctx = httpx.create_ssl_context()
246
+ ctx.minimum_version = ssl.TLSVersion.TLSv1_2
247
+ return ctx
248
+
249
+ def _ensure_client(self) -> httpx.Client:
250
+ """The HTTP client, rebuilt when the CA bundle file has changed."""
251
+ with self._lock:
252
+ return self._current_client_locked()
253
+
254
+ def _current_client_locked(self) -> httpx.Client:
255
+ """:meth:`_ensure_client` with ``self._lock`` held.
256
+
257
+ The client a rotation replaces is retired, not closed, while requests
258
+ or streams still use it; :meth:`_release` closes it after the last one.
259
+ """
260
+ key = None
261
+ if self._ca_bundle is not None:
262
+ try:
263
+ st = os.stat(self._ca_bundle)
264
+ key = (st.st_ino, st.st_size, st.st_mtime_ns)
265
+ except FileNotFoundError:
266
+ key = None # _build_ssl raises the typed error
267
+ if self._client is None or key != self._ca_key:
268
+ ctx = self._build_ssl()
269
+ old, self._client = (
270
+ self._client,
271
+ httpx.Client(
272
+ verify=ctx,
273
+ transport=self._http_transport,
274
+ follow_redirects=False,
275
+ timeout=self._timeout,
276
+ ),
277
+ )
278
+ self._ssl, self._ca_key = ctx, key
279
+ if old is not None:
280
+ log.debug(
281
+ "CA bundle %s changed; rebuilt the TLS context", self._ca_bundle
282
+ )
283
+ if self._users.get(old, 0) > 0:
284
+ self._retired.add(old)
285
+ else:
286
+ old.close()
287
+ return self._client
288
+
289
+ def _acquire(self) -> httpx.Client:
290
+ """The current client, counted as in use until :meth:`_release`."""
291
+ with self._lock:
292
+ client = self._current_client_locked()
293
+ self._users[client] = self._users.get(client, 0) + 1
294
+ return client
295
+
296
+ def _release(self, client: httpx.Client) -> None:
297
+ with self._lock:
298
+ n = self._users.get(client, 0) - 1
299
+ if n > 0:
300
+ self._users[client] = n
301
+ return
302
+ self._users.pop(client, None)
303
+ if client in self._retired:
304
+ self._retired.discard(client)
305
+ client.close()
306
+
307
+ def ssl_context(self) -> ssl.SSLContext | None:
308
+ """The current TLS context, for a WebSocket client (the terminal)."""
309
+ self._ensure_client()
310
+ return self._ssl
311
+
312
+ # --- requests --------------------------------------------------------------
313
+
314
+ def mark_ready(self) -> None:
315
+ """Start the 10 s window in which ``404 sandbox_not_found`` is retried.
316
+
317
+ ``sandboxes.create`` calls it when the control plane reports ``ready``:
318
+ the gateway's routing index may lag that by a few seconds.
319
+ """
320
+ self._ready_at = self._clock()
321
+
322
+ def auth_headers(self, scope: Scope) -> dict[str, str]:
323
+ """The headers that authenticate a request of ``scope`` (for a WebSocket upgrade)."""
324
+ bearer = self.credentials.bearer_for(scope, self.endpoint.sandbox_id)
325
+ return {"Authorization": f"Bearer {bearer.reveal()}"}
326
+
327
+ def request(
328
+ self,
329
+ method: str,
330
+ path: str,
331
+ *,
332
+ scope: Scope,
333
+ json: Any = None,
334
+ content: bytes | Iterator[bytes] | None = None,
335
+ params: Mapping[str, str] | None = None,
336
+ headers: Mapping[str, str] | None = None,
337
+ timeout: float | httpx.Timeout | None = None,
338
+ retry_codes: Collection[str] | None = None,
339
+ ) -> httpx.Response:
340
+ """Send a request and return the read ``2xx`` response; raise :class:`GatewayError` otherwise.
341
+
342
+ ``timeout`` overrides the transport's for this request. ``retry_codes``,
343
+ when given, limits the retried answers to those codes (a command must
344
+ not run twice: exec retries only codes that mean it never started).
345
+ """
346
+ resp, client = self._send(
347
+ method,
348
+ path,
349
+ scope,
350
+ json,
351
+ content,
352
+ params,
353
+ headers,
354
+ stream=False,
355
+ timeout=timeout,
356
+ retry_codes=retry_codes,
357
+ )
358
+ self._release(client)
359
+ return resp
360
+
361
+ @contextmanager
362
+ def stream(
363
+ self,
364
+ method: str,
365
+ path: str,
366
+ *,
367
+ scope: Scope,
368
+ json: Any = None,
369
+ content: bytes | Iterator[bytes] | None = None,
370
+ params: Mapping[str, str] | None = None,
371
+ headers: Mapping[str, str] | None = None,
372
+ timeout: float | httpx.Timeout | None = None,
373
+ retry_codes: Collection[str] | None = None,
374
+ ) -> Iterator[httpx.Response]:
375
+ """Like :meth:`request`, but yields the ``2xx`` response unread (SSE, downloads).
376
+
377
+ Retries happen only before a ``2xx`` arrives; once streaming, an
378
+ interruption is the caller's to handle (ADR-007-W13).
379
+ """
380
+ resp, client = self._send(
381
+ method,
382
+ path,
383
+ scope,
384
+ json,
385
+ content,
386
+ params,
387
+ headers,
388
+ stream=True,
389
+ timeout=timeout,
390
+ retry_codes=retry_codes,
391
+ )
392
+ try:
393
+ yield resp
394
+ finally:
395
+ try:
396
+ resp.close()
397
+ finally:
398
+ self._release(client)
399
+
400
+ def _send(
401
+ self,
402
+ method: str,
403
+ path: str,
404
+ scope: Scope,
405
+ json: Any,
406
+ content: bytes | Iterator[bytes] | None,
407
+ params: Mapping[str, str] | None,
408
+ headers: Mapping[str, str] | None,
409
+ *,
410
+ stream: bool,
411
+ timeout: float | httpx.Timeout | None = None,
412
+ retry_codes: Collection[str] | None = None,
413
+ ) -> tuple[httpx.Response, httpx.Client]:
414
+ """Send with retries; the returned client stays acquired for the caller to release."""
415
+ url = self.endpoint.url(path)
416
+ replayable = content is None or isinstance(content, bytes)
417
+ extra = {
418
+ k: v for k, v in (headers or {}).items() if k.lower() != "authorization"
419
+ }
420
+ start = self._clock()
421
+ attempt = 0
422
+ reauthed = False
423
+ while True:
424
+ bearer: BearerToken = self.credentials.bearer_for(
425
+ scope, self.endpoint.sandbox_id
426
+ )
427
+ client = self._acquire()
428
+ try:
429
+ req = client.build_request(
430
+ method,
431
+ url,
432
+ json=json,
433
+ content=content,
434
+ params=params,
435
+ headers={**extra, "Authorization": f"Bearer {bearer.reveal()}"},
436
+ timeout=self._timeout if timeout is None else timeout,
437
+ )
438
+ resp = client.send(req, stream=stream)
439
+ if resp.is_success:
440
+ return resp, client
441
+ try:
442
+ resp.read()
443
+ finally:
444
+ resp.close()
445
+ except BaseException:
446
+ self._release(client)
447
+ raise
448
+ self._release(client)
449
+ err = errors.from_response(resp)
450
+ log.debug(
451
+ "gateway %s %s -> %d %s (attempt %d)",
452
+ method,
453
+ path,
454
+ err.status,
455
+ err.code,
456
+ attempt + 1,
457
+ )
458
+ if (
459
+ isinstance(err, errors.AuthError)
460
+ and not reauthed
461
+ and replayable
462
+ and self.credentials.on_rejected(
463
+ bearer, err.code, scope, self.endpoint.sandbox_id
464
+ )
465
+ ):
466
+ reauthed = True
467
+ log.debug("retrying %s %s with a fresh credential", method, path)
468
+ continue
469
+ limited = retry_codes is not None and err.code not in retry_codes
470
+ delay = (
471
+ self._retry_delay(err, attempt, start)
472
+ if replayable and not limited
473
+ else None
474
+ )
475
+ if delay is None:
476
+ raise self.surface(err)
477
+ log.debug("retrying %s %s in %.1fs after %s", method, path, delay, err.code)
478
+ self._sleep(delay)
479
+ attempt += 1
480
+
481
+ def surface(self, err: errors.GatewayError) -> errors.GatewayError:
482
+ """The error to raise for a final refusal: a gone sandbox goes through :attr:`on_gone` first."""
483
+ if isinstance(err, errors.SandboxGone) and self.on_gone is not None:
484
+ self.on_gone(err)
485
+ return err
486
+
487
+ def now(self) -> float:
488
+ """The transport's monotonic clock (the start of a retry window)."""
489
+ return self._clock()
490
+
491
+ def retry_delay(
492
+ self, err: errors.GatewayError, attempt: int, start: float
493
+ ) -> float | None:
494
+ """How long to wait before attempt ``attempt + 1`` of a request first sent at
495
+ ``start`` (``None``: surface ``err``). The rules :meth:`request` follows,
496
+ for a client that sends outside it (the terminal's WebSocket upgrade)."""
497
+ return self._retry_delay(err, attempt, start)
498
+
499
+ def pause(self, seconds: float) -> None:
500
+ self._sleep(seconds)
501
+
502
+ def _retry_delay(
503
+ self, err: errors.GatewayError, attempt: int, start: float
504
+ ) -> float | None:
505
+ now = self._clock()
506
+ if isinstance(err, errors.SandboxNotFound):
507
+ if self._ready_at is None:
508
+ return None
509
+ deadline = self._ready_at + self._retry.window_s
510
+ elif err.retryable and err.status in (429, 503):
511
+ deadline = start + self._retry.window_s
512
+ else:
513
+ return None
514
+ if now >= deadline:
515
+ return None
516
+ backoff = min(
517
+ self._retry.initial_backoff_s * 2**attempt, self._retry.max_backoff_s
518
+ )
519
+ delay = err.retry_after_s if err.retry_after_s is not None else backoff
520
+ return min(delay, deadline - now)
521
+
522
+ # --- lifecycle -------------------------------------------------------------
523
+
524
+ def close(self) -> None:
525
+ """Close the current client and every retired one, open streams included."""
526
+ with self._lock:
527
+ for client in (*self._retired, self._client):
528
+ if client is not None:
529
+ client.close()
530
+ self._client = None
531
+ self._retired.clear()
532
+ self._users.clear()
533
+
534
+ def __enter__(self) -> Self:
535
+ return self
536
+
537
+ def __exit__(
538
+ self,
539
+ exc_type: type[BaseException] | None,
540
+ exc: BaseException | None,
541
+ tb: TracebackType | None,
542
+ ) -> None:
543
+ self.close()
544
+
545
+ def __repr__(self) -> str:
546
+ return f"GatewayTransport({self.endpoint.base_url!r}, credentials={self.credentials!r})"
@@ -0,0 +1,113 @@
1
+ Metadata-Version: 2.5
2
+ Name: devzero-sandbox
3
+ Version: 0.1.0
4
+ Summary: DevZero self-hosted sandboxes SDK (control plane + data plane clients) and MCP server
5
+ License-Expression: Apache-2.0
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: googleapis-common-protos>=1.63
9
+ Requires-Dist: httpx-sse>=0.4
10
+ Requires-Dist: httpx>=0.27
11
+ Requires-Dist: protobuf>=5.29.3
12
+ Requires-Dist: pydantic>=2
13
+ Requires-Dist: websockets>=13
14
+ Provides-Extra: mcp
15
+ Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
16
+ Description-Content-Type: text/markdown
17
+
18
+ # devzero-sandbox
19
+
20
+ The Python SDK and MCP server for DevZero self-hosted sandboxes: isolated Linux containers that
21
+ run in your own Kubernetes cluster, created through DevZero. Python 3.11+, Apache-2.0.
22
+
23
+ ```bash
24
+ pip install devzero-sandbox # the SDK
25
+ pip install 'devzero-sandbox[mcp]' # the SDK and the sandbox-mcp server
26
+ ```
27
+
28
+ ## A script
29
+
30
+ Set `DEVZERO_TOKEN` to a DevZero personal access token (`dzu-...`) or team service-account token
31
+ (`dzs-...`) of a Developer on the cluster's team. `DEVZERO_DAKR_URL` points at a DevZero API
32
+ other than the default.
33
+
34
+ ```python
35
+ from devzero_sandbox import Client
36
+
37
+ client = Client() # DEVZERO_TOKEN, DEVZERO_DAKR_URL
38
+ sbx = client.sandboxes.create("default", cluster_id="<cluster id>") # waits until ready
39
+
40
+ result = sbx.commands.run("echo hello")
41
+ print(result.exit_code, result.stdout_text)
42
+
43
+ sbx.files.write("data.bin", b"\x00\x01 any bytes")
44
+ assert sbx.files.read("data.bin") == b"\x00\x01 any bytes"
45
+
46
+ sbx.delete()
47
+ ```
48
+
49
+ `cluster_id` is needed only when the policy name exists on more than one cluster;
50
+ `client.policies()` lists the policies you can use. When the cluster's gateway endpoint serves a
51
+ certificate from a private CA (a bring-your-own endpoint), pass it:
52
+ `Client(gateway_options={"ca_bundle": "/path/to/ca.crt"})`.
53
+
54
+ The same calls run against preproduction in `make real-cp-run`
55
+ (`operators/sandbox-operator/hack/lib/real_cp_sdk.py script`).
56
+
57
+ More: `sbx.commands.run(cmd, background=True)` returns a `Process` you can `attach` to again from
58
+ any process, `sbx.terminal()` opens an interactive terminal, `sbx.extend(ttl)` keeps the sandbox
59
+ longer, `sbx.tokens.mint(scope=[...])` / `.revoke(jti)` manage its tokens. Every failure is a
60
+ typed exception from `devzero_sandbox.errors`.
61
+
62
+ ## In the cluster
63
+
64
+ A pod in the cluster reaches a sandbox without a DevZero credential, with its ServiceAccount, when
65
+ the sandbox's policy lists that ServiceAccount in `access.serviceAccounts`. Mount a projected token
66
+ for the gateway's audience and the CA bundle the sandbox operator publishes into the pod's
67
+ namespace:
68
+
69
+ ```yaml
70
+ volumes:
71
+ - name: dz-sandbox
72
+ projected:
73
+ sources:
74
+ - serviceAccountToken: { audience: sandbox-gateway.devzero.io, expirationSeconds: 3600, path: token }
75
+ - configMap: { name: devzero-sandbox-ca, items: [{ key: ca.crt, path: ca.crt }] }
76
+ # containers[].volumeMounts: [{ name: dz-sandbox, mountPath: /var/run/dz-sandbox, readOnly: true }]
77
+ ```
78
+
79
+ ```python
80
+ from devzero_sandbox import Sandbox
81
+
82
+ # reads /var/run/dz-sandbox/{token,ca.crt}
83
+ sbx = Sandbox.in_cluster("<policy>", "<sandbox id>")
84
+ print(sbx.commands.run("echo hello").stdout_text)
85
+ ```
86
+
87
+ The sandbox id is the `sandbox.devzero.io/sandbox-id` label of the `SandboxClaim` the pod's
88
+ ServiceAccount created in the policy's namespace.
89
+
90
+ ## MCP server
91
+
92
+ `sandbox-mcp` is a stdio MCP server with seven tools: `create_sandbox`, `run_command`,
93
+ `read_file`, `write_file`, `list_files`, `upload` and `delete_sandbox`. Sandboxes a session created
94
+ are deleted when it ends, and it writes nothing to disk. It is configured from its environment only:
95
+
96
+ ```json
97
+ {
98
+ "mcpServers": {
99
+ "devzero-sandbox": {
100
+ "command": "sandbox-mcp",
101
+ "env": {
102
+ "DEVZERO_TOKEN": "dzu-...",
103
+ "DEVZERO_SANDBOX_POLICY": "default",
104
+ "DEVZERO_SANDBOX_CLUSTER_ID": "<cluster id>"
105
+ }
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ The other variables (`DEVZERO_SANDBOX_CA_BUNDLE`, `DEVZERO_SANDBOX_MCP_UPLOAD_ROOT`, which turns
112
+ `upload` on, and the output and timeout limits) are listed by `sandbox-mcp --help` and in
113
+ `devzero_sandbox/mcp/config.py`.
@@ -0,0 +1,31 @@
1
+ devzero_sandbox/__init__.py,sha256=CKV9xMet69EPrRMGfPPWaqvlJ_ArexAxv-v_t5biyvE,1274
2
+ devzero_sandbox/_bgscript.py,sha256=ekRfpHmC5gWZyINp0iBC2uVzQx_hq7kcDBpJMz12KwE,4049
3
+ devzero_sandbox/auth.py,sha256=YicFQjtjqRg6xU5pNk5qCib5-6VG4po69yvIWeNZTmM,13464
4
+ devzero_sandbox/commands.py,sha256=5H_5pUU-qV-_9qcPnxderuXUE1f7HSAzhfwlFcsz1U0,30497
5
+ devzero_sandbox/connect.py,sha256=QfvrnRoNuhtDDdKa1RT32ZNXN1wjSNufDekYhI60ZwY,14417
6
+ devzero_sandbox/errors.py,sha256=DyWWOKsuR0Y3nyB2zMVC9qwNaZtZ5qIhsKXZCTezCMI,16182
7
+ devzero_sandbox/files.py,sha256=WZ-nfKK35c-behb_2P095JAvffAbqleLUEkcgdpvDZg,7428
8
+ devzero_sandbox/incluster.py,sha256=FWxK4jfnwgZc1i0lh3IvKdo-eDSWaIkIPBNtv0Lpq4s,1887
9
+ devzero_sandbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
10
+ devzero_sandbox/redaction.py,sha256=qo3rzvyjty2V5FcpaMonMifz8ny8C3KsMlGAsEK6-2g,3135
11
+ devzero_sandbox/sandbox.py,sha256=JDcHFnxF_nFxq_J1cmsAoZt6dbjsfmuUWKKL83gIH8U,24414
12
+ devzero_sandbox/terminal.py,sha256=k4hIAksbEZy5HmG7bCi_XwUEZX00lZa6EVBaKTIkXZY,18561
13
+ devzero_sandbox/transport.py,sha256=nOHA7-91ydnlQGVZsjlq7r667DhWx66dcmYkIjhRYwo,20195
14
+ devzero_sandbox/_proto/__init__.py,sha256=B_0Yscb1i6s4ngKwiLVwqv4nRbmLkVvcekMU2Zf2sT0,83
15
+ devzero_sandbox/_proto/sandbox/__init__.py,sha256=B_0Yscb1i6s4ngKwiLVwqv4nRbmLkVvcekMU2Zf2sT0,83
16
+ devzero_sandbox/_proto/sandbox/v1/__init__.py,sha256=B_0Yscb1i6s4ngKwiLVwqv4nRbmLkVvcekMU2Zf2sT0,83
17
+ devzero_sandbox/_proto/sandbox/v1/error_pb2.py,sha256=U9KDALHsN52UV0vZnA7K9SzgwukwAp9-9RxzKZGbfGI,1870
18
+ devzero_sandbox/_proto/sandbox/v1/error_pb2.pyi,sha256=hWlsOK45CV-NwRi7Tjbdj5mL05NLixOmBedEDTpw4gA,1007
19
+ devzero_sandbox/_proto/sandbox/v1/service_connect.py,sha256=po-GelHcOOVsSgqSgU8dSH7G-ddCr4hw_lwkAcWH0O0,13689
20
+ devzero_sandbox/_proto/sandbox/v1/service_pb2.py,sha256=GapxUFCbDWFAJliSKSkVAX501zB-Ww2Elqz4u8WV74U,35962
21
+ devzero_sandbox/_proto/sandbox/v1/service_pb2.pyi,sha256=FJcgWuLawDwFiuhdftzqRYksMn8uPRsAR0JONBbCDTI,44325
22
+ devzero_sandbox/mcp/__init__.py,sha256=utia6nvwodwb-BRFNqr_ft3RwucQkO89Ef0iPD1v1SE,1620
23
+ devzero_sandbox/mcp/__main__.py,sha256=lqV2oQ0wprUO6xB2dwItAKA5LGzCDQqYLikAGECokjw,150
24
+ devzero_sandbox/mcp/config.py,sha256=rUq3Hu15rKmbnjAx2UijxvbiXxjedubiFYSuqrWd20E,5885
25
+ devzero_sandbox/mcp/server.py,sha256=o7cqeO2HQcrGxRt70Jk25OQe1kfprDdu8y2m_s5RqtY,9955
26
+ devzero_sandbox/mcp/tools.py,sha256=CyPgx5bovuIZ6BBs5Y46NKYPJSoLIyzr_MKe7E27F8I,41061
27
+ devzero_sandbox-0.1.0.dist-info/METADATA,sha256=kVePtvp8xENbOfDO95LL4lHplONfn1ooVWhNiA7yH1k,4085
28
+ devzero_sandbox-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
29
+ devzero_sandbox-0.1.0.dist-info/entry_points.txt,sha256=BkN5_ocEfktR18IXfbK_6YMZ_wH5CG6KCGDCdJZPu6k,57
30
+ devzero_sandbox-0.1.0.dist-info/licenses/LICENSE,sha256=mxc313jymA4pAKMY0xHPXlvEyadngzmQsm16LrAsW68,11344
31
+ devzero_sandbox-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any