Design discussion: OpenEnv provider integration and the public Python SDK boundary

[rodrigosetti]

Design discussion: OpenEnv provider integration and the public Python SDK boundary

I have implemented an external OpenEnv ContainerProvider for OpenShell.
It runs an OpenEnv environment server inside a sandbox and returns the OpenShell service URL to the existing OpenEnv client. I would like maintainer guidance on the supported Python SDK boundary for this use case.

Workflow and evidence

The caller selects an image, the exact server argv, the environment, and an explicit policy. The adapter validates those inputs, submits the workload, policy, and service exposure in a single SandboxClient.create() request, waits for readiness, and passes the service URL to OpenEnv. OpenEnv uses /health and /ws for its normal reset, step, and state lifecycle. Closing the client invokes
delete() and wait_deleted().

The EchoEnv quickstart can be reproduced from source. The compatibility record documents passing async/sync OpenEnv 0.6.0 tests on SDK/gateway 0.1.2, with a local native arm64 VM image on September 30, 2026. Both cases cover health, two episodes, six echo steps, state, and an independent sandbox absence check after client cleanup.

The coding demo additionally demonstrates allowed workspace writes, allowed pypi.org access, denied reads of synthetic canaries, and denied example.com access, followed by continued OpenEnv operation and cleanup. The access probes run through SDK exec in the same sandbox. They do not read real host secrets or establish exhaustive isolation guarantees.

SDK boundary needing guidance

The adapter uses the public SandboxClient lifecycle methods and ServiceExposure. In the pinned 0.1.2 wheel, constructing the workload and embedded policy requires SandboxSpec, SandboxTemplate, and SandboxPolicy from openshell._proto. We confine those imports to a private module and test their serialization against that exact wheel. Explicit policies use strict conversion before gateway access; malformed input never falls back to a broader policy. See the SDK contract and alternatives.

This works for the tested release, but makes upgrading sensitive to changes in the generated model. A documented public construction path would allow integrations to express an arbitrary image, exact argv/environment, and initial policy without relying on underscored modules. A named template alone does not cover that workflow in the pinned SDK, because creating the template also needs generated models.

We also retain the selected URL from the create response: subsequent readiness responses do not retain it in this release. The provider preserves the gateway's routing and authentication requirements.

Questions

1. Is there a recommended public Python construction API for this atomic workload/policy/service request, or should integrations retain the isolated generated-model dependency until one exists?
2. Is preserving create().service_urls[service_name] the intended contract for a long-running HTTP/WebSocket workload?
3. For a remote route requiring mTLS, is there a supported deployment pattern for clients without TLS client-certificate configuration? Our current behavior is to fail explicitly; we keep certificate verification enabled and gateway credentials outside the workload.

Scope and limitations

The implementation targets the official hash-pinned 0.1.2 wheel and matching gateway. It supplies startup argv/environment explicitly and uses locally built images; arbitrary images and other releases/drivers are unverified. The remote probe succeeded with a certificate-aware probe, while the unmodified OpenEnv client remains unsupported on that mTLS route. OIDC, long idle sessions, and reconnects remain unverified.

This is a pre-alpha integration with documented release limitations, including cleanup ownership and process-capacity constraints. The discussion seeks guidance on the existing SDK integration; any proposed SDK changes would be scoped separately after the maintainer's feedback. Trusted verification remains future work outside the provider contract.

[jlynn8599-sketch]

OpenShell enforces boundaries; something has to define them. We have been building that layer at JLM AI Agent LLC and would like to contribute it as a reference policy pack.

Intent Rules v1.0.0: 17 intents across four tiers (read-only, state-changing, financial, founder-only admin), four agent roles with bounded authority, signed versioned work orders per consequential action, five verifier questions answered pre-execution, deny-by-default, append-only audit. Ships as declarative YAML — the same shape as OpenShell policy.

Mapping: our YAML drops into the declarative policy format; the five verifier questions extend the policy prover's 'never grants more than intended' check to per-action runtime decisions; our short-lived capability tokens mirror the credential-brokering model.