You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As an OpenShell operator, I want a sandbox's complete effective policy validated before its workload starts, so that an incompatible image policy, user policy, or provider configuration cannot produce a running sandbox whose traffic is only rejected later at connection time.
Problem Statement
A sandbox image may contain a policy that is not available when the gateway initially validates sandbox creation and attached providers. The supervisor later publishes that image policy to the gateway. That delivery path cannot reject the policy safely today because doing so can crash-loop the sandbox, so it may install an effective policy that would have failed the normal credential and policy gates.
This creates a split lifecycle: the sandbox can become usable before OpenShell has validated the exact combination of image policy, user-authored policy, provider layers, and gateway-derived credential provenance that the runtime will enforce. PR #3129 demonstrates one consequence: a legacy image policy contains L4-only GitHub endpoints, an attached credentialed GitHub provider causes those endpoints to become credentialed, and the network supervisor must deny the connection at runtime.
OpenShell is moving toward an unopinionated model in which the project provides only a minimal default image and users, vendors, and organizations own compatible image, policy, and provider bundles. Removing project-authored default policies reduces accidental conflicts, but it does not establish the required safety invariant for third-party bundles.
Impact / Why This Matters
Operators can currently receive a sandbox that appears to have started successfully but cannot perform expected work because its effective policy is invalid. The failure occurs late, potentially as an HTTP proxy error from an application, rather than as an actionable sandbox configuration error.
The current workaround is to diagnose the runtime denial and replace or edit the policy after startup. That is insufficient because the workload may already be running, incremental edits may be blocked by whole-policy validation, and behavior differs depending on which policy delivery path admitted the configuration.
A runtime connection-time backstop remains necessary for defense in depth, but it should not substitute for validating configuration before workload activation.
Proposed Design
Before a sandbox enters its usable state or launches its workload, OpenShell evaluates the exact effective configuration that will be activated. The candidate includes any policy supplied by the image, user-authored policy or overrides, attached provider policy layers, credential bindings, and gateway-derived credential provenance.
If the effective policy is valid, OpenShell activates that policy and allows the workload to start. The active runtime policy must correspond to the validated generation.
If validation fails, OpenShell does not start the workload or enable its egress. The sandbox exposes a stable configuration-error state and an actionable, bounded diagnostic identifying the invalid policy surface without including credentials or policy payloads. Management operations remain available so the operator can replace the policy, detach or change providers, or otherwise submit a fully valid configuration. Once the complete effective configuration validates, the sandbox can proceed to workload activation.
Images without a policy remain supported. Absence of an image policy must not imply project-authored network access or provider behavior; any effective permissions come from configuration selected by the operator.
The same externally observable invariant applies on initial creation, restart, and any transition that changes the effective policy or provider set: OpenShell never exposes a workload running against an effective configuration that has not passed the applicable validation gates.
Acceptance Criteria
When an image contains a policy, OpenShell composes it with the user policy, attached provider layers, credential bindings, and derived credential provenance before the workload starts.
A sandbox does not enter its usable/running state or enable workload egress until the exact effective policy generation has passed validation.
An invalid effective policy leaves the workload stopped and places the sandbox in a stable, externally visible configuration-error state rather than a crash loop.
The validation failure reports an actionable, bounded diagnostic that identifies the relevant rule or endpoint and reason without exposing credential values, policy payloads, or request content.
Operators can repair a rejected configuration through management operations, including submitting an atomic replacement policy or changing the provider set, without first activating the invalid workload configuration.
After a repaired effective configuration validates, OpenShell can activate it and start the workload normally.
Images with no embedded policy are supported and do not receive implicit network or provider permissions from the default image.
Initial creation, restart, and effective-policy/provider changes preserve the same validation-before-activation invariant across supported supervisor topologies.
Runtime enforcement retains its connection-time fail-closed checks as defense in depth.
Tests cover an image policy that is valid alone but becomes invalid after composition with a credentialed provider, a valid image/provider bundle, an image without a policy, configuration repair, restart, and policy-generation consistency at activation.
Architecture and user documentation describe the activation gate, failure state, repair workflow, and no-policy behavior.
Alternatives Considered
Rely on connection-time denial. The network supervisor already fails closed when it encounters unsafe traffic, but this produces late application failures and allows a workload to run in a configuration OpenShell already knows is invalid.
Grandfather violations inherited from the current policy. PR #3129 proposes differential edit-time validation so unrelated changes can proceed while inherited violations remain runtime-denied. This can improve compatibility with existing sandboxes, but it creates separate notions of policy admission and runtime usability. It should not replace validation before workload activation.
Validate image policies in isolation. An image policy can be valid by itself and become invalid only after provider composition and credential-provenance stamping. Validation must cover the exact effective candidate.
Ship project-maintained matching image policies and provider profiles. This couples OpenShell to particular workload images and becomes stale as images, tools, and provider behavior evolve. Users, vendors, and organizations should be able to own these bundles while OpenShell enforces the composition contract.
Agent Investigation
This concern is related to but distinct from #3092, which requires validation and normalization at policy-loading and supervisor-activation boundaries. This issue covers lifecycle ordering and the externally observable requirement that the workload itself must not activate until the fully composed image, user, and provider policy has been accepted.
User Story
As an OpenShell operator, I want a sandbox's complete effective policy validated before its workload starts, so that an incompatible image policy, user policy, or provider configuration cannot produce a running sandbox whose traffic is only rejected later at connection time.
Problem Statement
A sandbox image may contain a policy that is not available when the gateway initially validates sandbox creation and attached providers. The supervisor later publishes that image policy to the gateway. That delivery path cannot reject the policy safely today because doing so can crash-loop the sandbox, so it may install an effective policy that would have failed the normal credential and policy gates.
This creates a split lifecycle: the sandbox can become usable before OpenShell has validated the exact combination of image policy, user-authored policy, provider layers, and gateway-derived credential provenance that the runtime will enforce. PR #3129 demonstrates one consequence: a legacy image policy contains L4-only GitHub endpoints, an attached credentialed GitHub provider causes those endpoints to become credentialed, and the network supervisor must deny the connection at runtime.
OpenShell is moving toward an unopinionated model in which the project provides only a minimal default image and users, vendors, and organizations own compatible image, policy, and provider bundles. Removing project-authored default policies reduces accidental conflicts, but it does not establish the required safety invariant for third-party bundles.
Impact / Why This Matters
Operators can currently receive a sandbox that appears to have started successfully but cannot perform expected work because its effective policy is invalid. The failure occurs late, potentially as an HTTP proxy error from an application, rather than as an actionable sandbox configuration error.
The current workaround is to diagnose the runtime denial and replace or edit the policy after startup. That is insufficient because the workload may already be running, incremental edits may be blocked by whole-policy validation, and behavior differs depending on which policy delivery path admitted the configuration.
A runtime connection-time backstop remains necessary for defense in depth, but it should not substitute for validating configuration before workload activation.
Proposed Design
Before a sandbox enters its usable state or launches its workload, OpenShell evaluates the exact effective configuration that will be activated. The candidate includes any policy supplied by the image, user-authored policy or overrides, attached provider policy layers, credential bindings, and gateway-derived credential provenance.
If the effective policy is valid, OpenShell activates that policy and allows the workload to start. The active runtime policy must correspond to the validated generation.
If validation fails, OpenShell does not start the workload or enable its egress. The sandbox exposes a stable configuration-error state and an actionable, bounded diagnostic identifying the invalid policy surface without including credentials or policy payloads. Management operations remain available so the operator can replace the policy, detach or change providers, or otherwise submit a fully valid configuration. Once the complete effective configuration validates, the sandbox can proceed to workload activation.
Images without a policy remain supported. Absence of an image policy must not imply project-authored network access or provider behavior; any effective permissions come from configuration selected by the operator.
The same externally observable invariant applies on initial creation, restart, and any transition that changes the effective policy or provider set: OpenShell never exposes a workload running against an effective configuration that has not passed the applicable validation gates.
Acceptance Criteria
Alternatives Considered
Rely on connection-time denial. The network supervisor already fails closed when it encounters unsafe traffic, but this produces late application failures and allows a workload to run in a configuration OpenShell already knows is invalid.
Grandfather violations inherited from the current policy. PR #3129 proposes differential edit-time validation so unrelated changes can proceed while inherited violations remain runtime-denied. This can improve compatibility with existing sandboxes, but it creates separate notions of policy admission and runtime usability. It should not replace validation before workload activation.
Validate image policies in isolation. An image policy can be valid by itself and become invalid only after provider composition and credential-provenance stamping. Validation must cover the exact effective candidate.
Ship project-maintained matching image policies and provider profiles. This couples OpenShell to particular workload images and becomes stale as images, tools, and provider behavior evolve. Users, vendors, and organizations should be able to own these bundles while OpenShell enforces the composition contract.
Agent Investigation
This concern is related to but distinct from #3092, which requires validation and normalization at policy-loading and supervisor-activation boundaries. This issue covers lifecycle ordering and the externally observable requirement that the workload itself must not activate until the fully composed image, user, and provider policy has been accepted.
Related context: #2998 and #3129.