From 367926389b0762693b9f573c9f410b67afc39fe4 Mon Sep 17 00:00:00 2001 From: burtenshaw Date: Thu, 12 Nov 2026 11:49:14 +0100 Subject: [PATCH 1/2] RFC 002: ratify the Cloud Sandbox Providers amendment with admission criteria Mark the amendment accepted, with the date left as YYYY-MM-DD until the 7-day objection window closes. Add admission criteria for new cloud sandbox providers, and correct S1 to allow the loopback and in-cluster plaintext legs that HFSandboxProvider and KubernetesProvider already use. Drop the "proposed amendment" notes from the ACA and Novita provider docstrings and point the contributing guide at the criteria. Signed-off-by: burtenshaw Co-authored-by: Cursor --- docs/source/contributing.md | 5 +- rfcs/002-env-spec.md | 49 ++++++++++++++++--- .../core/containers/runtime/aca_provider.py | 8 +-- .../containers/runtime/novita_provider.py | 5 -- 4 files changed, 45 insertions(+), 22 deletions(-) diff --git a/docs/source/contributing.md b/docs/source/contributing.md index 8d89c468b..c11e68233 100644 --- a/docs/source/contributing.md +++ b/docs/source/contributing.md @@ -36,8 +36,9 @@ To support a new runtime (a cloud sandbox, a scheduler, etc.), subclass - In the [Runtime Providers guide](guides/runtime-providers.md), add a row to the table and a "Per-provider setup" subsection (kept in alphabetical order). - Add a test (the providers under `tests/test_core/` inject a fake SDK, so no network is needed). -See the Cloud Sandbox Providers amendment proposed in RFC 002 for the -provider-neutral invariants (direct base URL, WebSocket conformance, network posture). +See the Cloud Sandbox Providers section of RFC 002 for the provider-neutral +invariants (direct base URL, WebSocket conformance, network posture) and the +admission criteria a new provider must meet. ### 📝 Improve Documentation diff --git a/rfcs/002-env-spec.md b/rfcs/002-env-spec.md index 08ea08a6c..c5964fc52 100644 --- a/rfcs/002-env-spec.md +++ b/rfcs/002-env-spec.md @@ -2,13 +2,15 @@ **Status**: In Review **Created**: 10/14/2025 -**Amended**: November 12, 2025 _(a "Cloud Sandbox Providers" amendment is proposed below, pending author sign-off — see Amendment History)_ +**Amended**: YYYY-MM-DD **Authors**: @Darktex, @pankit-eng, @jspisak, @zkwentz **RFC ID:** 002 ## Amendment History -**June 14, 2026** (proposed by @thegovind — pending review/sign-off by the RFC 002 authors): Added the "Cloud Sandbox Providers" subsection — a provider-neutral capability mapping, protocol invariants, and security invariants for adapting hosted sandbox runtimes onto the existing `ContainerProvider` contract without changing the client/server protocol. +**YYYY-MM-DD** (ratified by @burtenshaw after a 7-day objection window): Accepted the "Cloud Sandbox Providers" amendment. Added its admission criteria, and corrected S1 to allow the loopback and in-cluster plaintext legs that `HFSandboxProvider` and `KubernetesProvider` already use. + +**June 14, 2026** (proposed by @thegovind): Added the "Cloud Sandbox Providers" subsection — a provider-neutral capability mapping, protocol invariants, and security invariants for adapting hosted sandbox runtimes onto the existing `ContainerProvider` contract without changing the client/server protocol. **November 12, 2025**: Added tool duality (sim vs prod), Docker Compose patterns, positioning framework (OpenEnv vs systems built on top), and graceful degradation principles. @@ -145,9 +147,7 @@ class ContainerProvider(ABC): #### Cloud Sandbox Providers -> **Status:** proposed amendment, pending review/sign-off by the RFC 002 authors. -> The normative invariants below (protocol + security) are not finalized until -> the original authors approve. +> **Status:** accepted YYYY-MM-DD. See Amendment History. Cloud sandbox platforms expose the same small set of capabilities under different names. A cloud sandbox provider is an adapter that maps those @@ -214,9 +214,13 @@ data, steal credentials, or reach the orchestrator. Treat the workload as hostile — no provider feature may rely on in-sandbox code being well-behaved — and enforce: -S1. **Encrypted transport only.** The returned `base_url` is `https`/`wss`; - plaintext (`http`/`ws`) is rejected so episode traffic is never sent in the - clear. +S1. **Encrypted transport only.** Episode traffic never leaves the host or the + cluster in the clear. The returned `base_url` is `https`/`wss`, with two + plaintext exceptions: a loopback proxy that forwards over `https`/`wss` + (`HFSandboxProvider` returns `http://127.0.0.1:{port}`), and an in-cluster + Service address (`KubernetesProvider` returns + `http://{name}.{namespace}:{port}`). Any other plaintext (`http`/`ws`) URL is + rejected. S2. **Ingress URLs are bearer capabilities.** An anonymous or self-authenticating URL grants full control of the environment to whoever holds it: never logged, scoped and time-boxed, and network-restricted where possible. Authenticated @@ -251,6 +255,35 @@ satisfying the invariants above. No change to the `EnvClient`/server protocol is required, and multiple unrelated provider SDKs can sit behind the same contract — which is what keeps it genuinely provider-neutral. +##### Admission criteria + +A new cloud sandbox provider is admitted to core when it meets all of these: + +1. **Contract only.** One module that subclasses `ContainerProvider`, with no + changes to `EnvClient`, the server protocol, or the runtime package + re-exports. +2. **An optional extra that resolves.** The SDK is OSI-licensed and published + on PyPI, the provider imports it lazily, and the extra resolves under + `uv sync --all-extras` on every supported Python. Environment markers are + allowed. +3. **A generally available backend.** Self-hostable open source, or a hosted + service anyone can sign up for. +4. **Security invariants.** S1 to S6 hold, with two exceptions: plaintext only + on a loopback or in-cluster leg (S1), and public ingress only behind an + explicit opt-in such as `public=True`. The provider documents its egress + and cloud metadata posture. +5. **Evidence.** Fake-SDK tests that pin the real SDK's method names and + arguments, plus one live round trip recorded at the PR head: the `/ws` + upgrade returns `101`, `reset()` and `step()` complete, and cleanup is + confirmed. Hosted backends also show that the metadata endpoint is denied. +6. **A named owner.** The provider's guide section names an owner for SDK + breakage. A provider whose extra stays broken in CI can be excluded from CI + and deprecated under the deprecation policy in `.claude/docs/INVARIANTS.md`: + a `FutureWarning` that names the removal release, at least two minor + releases after the first warning. +7. **When to use which.** If an existing provider reaches the same backend, + the guide says when to use each. + ### Key Design Decisions In this RFC, we want to align on four decisions that will shape the overall design of the framework. diff --git a/src/openenv/core/containers/runtime/aca_provider.py b/src/openenv/core/containers/runtime/aca_provider.py index a378a3e11..f4750af61 100644 --- a/src/openenv/core/containers/runtime/aca_provider.py +++ b/src/openenv/core/containers/runtime/aca_provider.py @@ -1,12 +1,6 @@ # SPDX-License-Identifier: BSD-3-Clause -"""Azure Container Apps Sandbox provider for OpenEnv environments. - -Note: the ``RFC 002 security invariant S`` references in this module point to -the **proposed** "Cloud Sandbox Providers" amendment to RFC 002, which is pending -review/sign-off by the RFC authors. They describe the security properties this -provider enforces; treat them as proposed (not yet ratified) until that sign-off. -""" +"""Azure Container Apps Sandbox provider for OpenEnv environments.""" from __future__ import annotations diff --git a/src/openenv/core/containers/runtime/novita_provider.py b/src/openenv/core/containers/runtime/novita_provider.py index 6b5926efa..919d3707e 100644 --- a/src/openenv/core/containers/runtime/novita_provider.py +++ b/src/openenv/core/containers/runtime/novita_provider.py @@ -8,11 +8,6 @@ The provider boots an OpenEnv server inside a Novita sandbox, exposes port 8000 on the sandbox's public host, and returns an ``https://`` URL that ``EnvClient`` connects to over ``wss://``. - -Note: the ``RFC 002 security invariant S`` references in this module point to -the **proposed** "Cloud Sandbox Providers" amendment to RFC 002, which is pending -review/sign-off by the RFC authors. They describe the security properties this -provider enforces; treat them as proposed (not yet ratified) until that sign-off. """ from __future__ import annotations From bf623b7a10ec633f0489a38b48952518bcc998e4 Mon Sep 17 00:00:00 2001 From: burtenshaw Date: Thu, 12 Nov 2026 13:03:00 +0100 Subject: [PATCH 2/2] RFC 002: allow local cluster gateways behind an opt-in; set the ratification date S1 now also allows a plaintext gateway of a local development cluster on the same host (Kind, Minikube) behind an explicit opt-in such as allow_insecure=True, which AgentSandboxProvider documents. The traffic never leaves the host, so the invariant's intent holds. Criterion 4 points at the legs S1 allows. The placeholders become 2026-11-19, the end of the 7-day objection window. Signed-off-by: burtenshaw Co-authored-by: Cursor --- rfcs/002-env-spec.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/rfcs/002-env-spec.md b/rfcs/002-env-spec.md index c5964fc52..ab6726a82 100644 --- a/rfcs/002-env-spec.md +++ b/rfcs/002-env-spec.md @@ -2,13 +2,13 @@ **Status**: In Review **Created**: 10/14/2025 -**Amended**: YYYY-MM-DD +**Amended**: 2026-11-19 **Authors**: @Darktex, @pankit-eng, @jspisak, @zkwentz **RFC ID:** 002 ## Amendment History -**YYYY-MM-DD** (ratified by @burtenshaw after a 7-day objection window): Accepted the "Cloud Sandbox Providers" amendment. Added its admission criteria, and corrected S1 to allow the loopback and in-cluster plaintext legs that `HFSandboxProvider` and `KubernetesProvider` already use. +**2026-11-19** (ratified by @burtenshaw after a 7-day objection window): Accepted the "Cloud Sandbox Providers" amendment. Added its admission criteria, and corrected S1 to allow the loopback and in-cluster plaintext legs that `HFSandboxProvider` and `KubernetesProvider` already use, plus local development cluster gateways behind an explicit opt-in. **June 14, 2026** (proposed by @thegovind): Added the "Cloud Sandbox Providers" subsection — a provider-neutral capability mapping, protocol invariants, and security invariants for adapting hosted sandbox runtimes onto the existing `ContainerProvider` contract without changing the client/server protocol. @@ -147,7 +147,7 @@ class ContainerProvider(ABC): #### Cloud Sandbox Providers -> **Status:** accepted YYYY-MM-DD. See Amendment History. +> **Status:** accepted 2026-11-19. See Amendment History. Cloud sandbox platforms expose the same small set of capabilities under different names. A cloud sandbox provider is an adapter that maps those @@ -215,12 +215,13 @@ hostile — no provider feature may rely on in-sandbox code being well-behaved and enforce: S1. **Encrypted transport only.** Episode traffic never leaves the host or the - cluster in the clear. The returned `base_url` is `https`/`wss`, with two + cluster in the clear. The returned `base_url` is `https`/`wss`, with three plaintext exceptions: a loopback proxy that forwards over `https`/`wss` - (`HFSandboxProvider` returns `http://127.0.0.1:{port}`), and an in-cluster + (`HFSandboxProvider` returns `http://127.0.0.1:{port}`), an in-cluster Service address (`KubernetesProvider` returns - `http://{name}.{namespace}:{port}`). Any other plaintext (`http`/`ws`) URL is - rejected. + `http://{name}.{namespace}:{port}`), and a gateway of a local development + cluster on the same host (Kind, Minikube) behind an explicit opt-in such as + `allow_insecure=True`. Any other plaintext (`http`/`ws`) URL is rejected. S2. **Ingress URLs are bearer capabilities.** An anonymous or self-authenticating URL grants full control of the environment to whoever holds it: never logged, scoped and time-boxed, and network-restricted where possible. Authenticated @@ -269,9 +270,10 @@ A new cloud sandbox provider is admitted to core when it meets all of these: 3. **A generally available backend.** Self-hostable open source, or a hosted service anyone can sign up for. 4. **Security invariants.** S1 to S6 hold, with two exceptions: plaintext only - on a loopback or in-cluster leg (S1), and public ingress only behind an - explicit opt-in such as `public=True`. The provider documents its egress - and cloud metadata posture. + on the legs S1 allows (loopback, in-cluster, or a local development cluster + behind an explicit opt-in such as `allow_insecure=True`), and public ingress + only behind an explicit opt-in such as `public=True`. The provider documents + its egress and cloud metadata posture. 5. **Evidence.** Fake-SDK tests that pin the real SDK's method names and arguments, plus one live round trip recorded at the PR head: the `/ws` upgrade returns `101`, `reset()` and `step()` complete, and cleanup is