Skip to content

Show the backend reason when it rejects a sandbox policy during Attach #4739

Open

Description

@shiju-nv

User Story

I maintain an external OpenShell compute driver whose isolation backend rejects policies it cannot enforce during the Attach startup step. When that happens, I need sandbox status to explain the rejection. Today, users only see that the supervisor exited.

Problem Statement

In run_sandbox_with_backend (crates/openshell-supervisor/src/lib.rs), the call selected_backend.attach(...) ends in .await?. When the backend refuses (BackendError::Denied, Descriptor or Attach), the supervisor returns the error and exits without telling the gateway:

  • No configuration rejection: the startup loop already reports rejected configuration through reject_startup_configuration with ConfigurationAdmissionState::Rejected, for example "Effective policy is unavailable after image discovery". An Attach refusal is the backend rejecting the same configuration, but it doesn't take that path.
  • No policy status: report_initial_policy_failure reports a policy that fails to build, but not one the backend refuses.
  • A write before admission: the startup loop runs enrich_proto_baseline_paths and syncs the widened policy back as a new sandbox revision ("Enriched policy synchronization") before Attach. When Attach then refuses that policy, the revision stays in the store with status Pending and no error until something supersedes it.

The gateway learns of the failure only from the compute driver's own report that the supervisor exited, which can't carry the backend's reason.

Impact / Why This Matters

Users see a generic startup failure even though the backend supplied a specific reason. Finding that reason requires access to supervisor stderr, which may be stored in a root-owned log.

The policy history is also misleading: a revision created by the supervisor can remain Pending with an empty ERROR column after the backend has rejected it. Users cannot tell where it came from or why it never loaded.

RFC 0012 requires a backend to reject policies it cannot enforce. That rejection also needs to be visible through normal sandbox and policy status.

Acceptance Criteria

  • When Attach fails with a backend error, the supervisor reports the configuration as Rejected with the backend's message before it exits, as reject_startup_configuration does.
  • A revision the supervisor wrote during startup, and that the backend then refused, ends Failed with that message instead of Pending.
  • openshell sandbox get shows the backend's reason in the ConfigurationReady condition.

Reproduction Steps

Reproduced live at b58e24c9d with an out-of-tree macOS backend whose Attach refuses any policy except one fixed offline profile:

  1. openshell sandbox create --name iso3 --policy <fixed offline policy> --detach -- /bin/sleep 3600; it reaches Ready.

  2. openshell policy update iso3 --add-endpoint example.com:443; version 2 is reported Effective.

  3. openshell sandbox stop iso3, then openshell sandbox start iso3.

  4. Observed:

    • the start fails with SupervisorExited: native supervisor exited without a stop request (the driver's reason);
    • openshell policy list iso3 shows a version 3 that the supervisor wrote at startup (version 2 plus the baseline paths such as /tmp), Pending with no error;
    • the gateway log has UpdateConfig: new policy version persisted ... version=3, then the phase change to Error, and nothing from the backend.

    Expected: ConfigurationReady False with the backend's message, runtime policy does not match the admitted native offline profile, and version 3 Failed with the same message.

Suggested UX (if applicable)

$ openshell sandbox get iso3
Phase:  Error
  - ConfigurationReady: False (ConfigurationRejected) - isolation backend 'macos-appsandbox' refused attachment: runtime policy does not match the admitted native offline profile

Environment

  • OpenShell: main at b58e24c9d; not yet in a release
  • OS: macOS 26.7.1 (25G241), Apple silicon
  • OpenShell deployment mode and runtime: gateway with an out-of-tree compute driver and a registered isolation backend that validates the policy at Attach

Logs

INFO openshell_server::grpc::policy: UpdateConfig: new policy version persisted sandbox_id=ad1f057c-... version=3
INFO openshell_server::compute: Sandbox phase changed sandbox_name=iso3 old_phase=Starting new_phase=Error
WARN openshell_server::compute: Sandbox failed to become ready sandbox_name=iso3 reason=SupervisorExited native supervisor exited without a stop request

Activity

  1. added 2 commits that reference this issue on Oct 20, 2026
    085e666
    882780f
  2. added a commit that references this issue on Nov 2, 2026
    dc58469
  3. changed the title [-]bug(supervisor): an isolation backend's Attach refusal is not reported to the gateway[/-] [+]Show the backend reason when it rejects a sandbox policy during Attach[/+] on Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions