Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/source/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
51 changes: 43 additions & 8 deletions rfcs/002-env-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**: 2026-11-19
**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.
**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.

**November 12, 2025**: Added tool duality (sim vs prod), Docker Compose patterns, positioning framework (OpenEnv vs systems built on top), and graceful degradation principles.

Expand Down Expand Up @@ -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 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
Expand Down Expand Up @@ -214,9 +214,14 @@ 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 three
plaintext exceptions: a loopback proxy that forwards over `https`/`wss`
(`HFSandboxProvider` returns `http://127.0.0.1:{port}`), an in-cluster
Service address (`KubernetesProvider` returns
`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
Expand Down Expand Up @@ -251,6 +256,36 @@ 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 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
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.
Expand Down
8 changes: 1 addition & 7 deletions src/openenv/core/containers/runtime/aca_provider.py
Original file line number Diff line number Diff line change
@@ -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<n>`` 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

Expand Down
5 changes: 0 additions & 5 deletions src/openenv/core/containers/runtime/novita_provider.py
Original file line number Diff line number Diff line change
Expand Up @@ -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<n>`` 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
Expand Down
Loading