RFC 0020: OpenShell Worker Provider and Credential-Brokered Session Sandboxes by sallyom · Pull Request #55 · openclaw/rfcs

sallyom · 2026-07-31T06:40:58Z

Summary

Proposes an optional OpenShell WorkerProvider for Cloud Worker sessions. Each explicitly selected Cloud/OpenShell session receives a disposable child sandbox while OpenClaw retains placement, recovery, transcripts, and session ownership.

Motivation

The existing OpenShell SandboxBackend isolates selected tools but leaves the session agent loop in the Gateway. This RFC defines the narrower delegated control path required to isolate a selected session's complete worker runtime without exposing OpenShell client mTLS, the supervisor JWT, or model-provider credentials.

Scope

Add the optional openshell WorkerProvider.
Use parent-bound delegation credentials to create and relay only server-owned child sandboxes.
Keep provider credentials in OpenShell through workspace-scoped inference.local.
Preserve explicit Cloud/OpenShell placement; automatically sandboxing every new session remains a non-goal.

Implementation status

The accompanying OpenClaw and OpenShell branches implement the proposal. The OpenClaw branch has been rebased on current origin/main; OpenShell restricts delegated child shape to the parent-owned template and permits read-only inference-route metadata.

Validation

Focused OpenClaw OpenShell worker-provider tests pass (26 tests).
Focused OpenShell delegation authorization and child-template inheritance tests pass.
RFC and implementation diffs pass whitespace checks.
A full local plugin/session E2E retest remains planned before the implementation PRs are opened.

Follow-up

An OpenShell issue will be opened to track the delegated worker capability and cross-repository implementation work.

Signed-off-by: sallyom <somalley@redhat.com>

clawsweeper · 2026-07-31T06:46:12Z

Codex review: needs real behavior proof before merge. Reviewed August 2, 2026, 1:06 PM ET / 17:06 UTC.

ClawSweeper review

What this changes

The draft RFC proposes an optional OpenShell WorkerProvider that runs explicitly selected cloud sessions in credential-brokered child sandboxes.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep this draft RFC open: it proposes a new optional worker-runtime and credential-boundary model that requires maintainer product and security-direction review, and its required rfc_pr metadata is still blank. Likely related person: sallyom (medium confidence), as proposal and proof-of-concept author.

Priority: P3
Reviewed head: 302accf512f269791dba880c3e339f26cb3d5c10
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is a substantive scoped design proposal, but required lifecycle metadata and maintainer direction remain outstanding.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.
Evidence reviewed	5 items	RFC lifecycle policy: The repository README requires a new draft RFC to set `rfc_pr` to its pull-request URL. This PR leaves that value blank in its frontmatter. Consistent current RFC convention: Recent draft RFCs on current history populate `rfc_pr` with the canonical pull-request URL, confirming this is an established repository convention rather than an unused template field. New unresolved cross-repository direction: The proposal creates a new WorkerProvider, parent-bound delegation credential, and OpenShell credential-brokered inference route, but leaves the final delegated API and authorization model as open questions.
Findings	1 actionable finding	[P2] Set the RFC pull-request URL in frontmatter
Security	None	None.

How this fits together

OpenClaw’s Gateway currently owns session placement, recovery, transcripts, and agent execution. The proposed OpenShell provider would move explicitly selected Cloud/OpenShell session runtimes into disposable child sandboxes while the Gateway retains session ownership and OpenShell brokers provider credentials.

flowchart LR
  Request[Cloud session request] --> Gateway[OpenClaw Gateway]
  Gateway --> Placement[Explicit OpenShell placement]
  Placement --> Delegation[Parent-bound delegation]
  Delegation --> Worker[Disposable worker sandbox]
  Worker --> Broker[OpenShell inference route]
  Worker --> Runtime[Session runtime and tools]
  Gateway --> Recovery[Transcript and recovery ownership]

Decision needed

Question	Recommendation
Should OpenClaw accept the proposed optional OpenShell WorkerProvider direction, including parent-bound delegated sandbox creation and OpenShell-brokered inference credentials, as the contract for cross-repository implementation?	Sponsor a bounded RFC revision: Approve the direction in principle, contingent on completing the RFC metadata and documenting the final authorization, upgrade, and compatibility contract before acceptance.

Why: The RFC adds a new session-placement mode and explicitly leaves the final delegated API and authorization model unresolved. Choosing the permanent authority boundary, credential exposure guarantees, and compatibility contract requires maintainer intent.

Before merge

Add real behavior proof - Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.
Set the RFC pull-request URL in frontmatter (P2) - The RFC lifecycle requires rfc_pr to point to this pull request, but the submitted frontmatter leaves it blank. Set the canonical URL so the draft is traceable through acceptance.
Resolve merge risk (P1) - The proposal introduces a new delegated sandbox-control and credential-brokering contract; accepting it before resolving authorization scope, recovery semantics, and compatibility behavior could create an unsafe or incompatible cross-repository boundary.
Resolve merge risk (P1) - The required rfc_pr field is blank, so the RFC lifecycle lacks its canonical review link.
Complete next step (P2) - A maintainer must choose the product and security direction before the RFC can be accepted; filling the frontmatter URL is a small contributor follow-up, not a repair-lane task.

Findings

[P2] Set the RFC pull-request URL in frontmatter — rfcs/0020-openshell-session-workers.md:9

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC surface	1 added document; 377 lines	The change is documentation-only but specifies a new cross-repository worker and credential-boundary contract.
Open design questions	3 listed	The unresolved API and policy questions show this remains a proposal rather than an acceptance-ready contract.

Merge-risk options

Maintainer options:

Resolve the RFC contract before acceptance (recommended)
Document the delegated authorization scope, credential-exposure guarantees, and explicit placement and upgrade behavior, then fill in metadata and request maintainer review.
Defer the cross-repository proposal
Keep this draft open until the OpenShell delegated-worker API and its owner review are available.

Technical review

Best possible solution:

Keep the RFC draft open, set rfc_pr to its canonical URL, and accept it only after maintainers agree on the delegated authorization contract, upgrade and compatibility behavior, and ownership of the OpenShell counterpart.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a design RFC, not a report of broken existing behavior. It supplies a future smoke-test outline rather than a current-main defect reproduction.

Is this the best way to solve the issue?

Unclear: a dedicated OpenShell WorkerProvider may be a viable direction, but the RFC deliberately leaves its permanent delegation API and authorization model unresolved, so acceptance requires maintainer confirmation.

Full review comments:

[P2] Set the RFC pull-request URL in frontmatter — rfcs/0020-openshell-session-workers.md:9
The RFC lifecycle requires rfc_pr to point to this pull request, but the submitted frontmatter leaves it blank. Set the canonical URL so the draft is traceable through acceptance.
Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f.

Labels

Label justifications:

P3: This is a draft architecture proposal with no demonstrated current user regression or release-blocking failure.
merge-risk: 🚨 compatibility: The RFC proposes a new optional WorkerProvider and session-placement contract that affects future deployment and plugin compatibility.
merge-risk: 🚨 security-boundary: The proposal delegates child-sandbox control while constraining access to mTLS, supervisor, and model-provider credentials.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.

Evidence

What I checked:

RFC lifecycle policy: The repository README requires a new draft RFC to set rfc_pr to its pull-request URL. This PR leaves that value blank in its frontmatter. (README.md:74, af708f0ddb6f)
Consistent current RFC convention: Recent draft RFCs on current history populate rfc_pr with the canonical pull-request URL, confirming this is an established repository convention rather than an unused template field. (rfcs/0026-automations-terminology.md:8, c876de6210bf)
New unresolved cross-repository direction: The proposal creates a new WorkerProvider, parent-bound delegation credential, and OpenShell credential-brokered inference route, but leaves the final delegated API and authorization model as open questions. (rfcs/0020-openshell-session-workers.md:16, 302accf512f2)
Current main has not adopted the RFC: The current-main comparison has no corresponding proposal file; the PR file is absent from current main, so this RFC is neither implemented nor superseded in the checked-out repository. (rfcs/0020-openshell-session-workers.md:1, af708f0ddb6f)
Current proposal provenance: The unmerged RFC was introduced by sallyom on July 31, 2026; local Git history could not provide a broader owner trail because this proposal has not landed on main. (rfcs/0020-openshell-session-workers.md:1, 302accf512f2)

Likely related people:

sallyom: The RFC frontmatter and the only local commit identify sallyom; it also names sallyom’s OpenShell and OpenClaw proof-of-concept branches. There is no merged current-main history for this unaccepted design. (role: proposal and proof-of-concept author; confidence: medium; commits: 302accf512f2; files: rfcs/0020-openshell-session-workers.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

Set rfc_pr to the canonical pull-request URL.
Obtain maintainer agreement on the delegated authorization and credential-isolation contract before changing the RFC status.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (9 earlier review cycles; latest 8 shown)

reviewed 2026-07-31T13:34:40.785Z sha 302accf :: needs real behavior proof before merge. :: none
reviewed 2026-07-31T17:57:57.442Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
reviewed 2026-07-31T19:46:25.839Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
reviewed 2026-08-01T06:13:31.030Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
reviewed 2026-08-01T07:20:01.095Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
reviewed 2026-08-01T10:56:34.295Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
reviewed 2026-08-01T15:20:01.945Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
reviewed 2026-08-01T20:35:35.323Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter

Full rewrite. Same argument and same design, ~35% shorter: drops the repetition and hedging that accumulated across revisions, uses plainer language, and merges the migration, phasing, and rollback material into a single Rollout section instead of three. Adds crosslinks throughout to openclaw#58, #42026, openclaw#55, RFC 0025, the public microsoft/mxc backend docs, and the Windows Insider build that gates the primitive. Fixes two defects found while rewriting: a typo in the summary, and a capability named hostPathSharing in the Windows section that no longer matched the descriptor table after it was split into hostPathProjection and stagingChannel. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: ccc616c5-8e0a-4098-b8ef-c19695e5c27b

Fixes several factual errors, verified against microsoft/mxc at 0aaa2afa (2026-08-18). The earlier draft was written against a clone that was eight days stale, and the preview API had changed underneath it. Corrections: - Lifecycle was wrong. The real phases are provision, start, exec, stop, deprovision. The draft omitted exec and invented an attach phase the provider explicitly defers. - "Every operation is idempotent" was false and dangerous: provision mints a fresh identity on every call, so a naive retry leaks accounts. Replaced with per-operation semantics and a durable pre-provision record. - Detached execution is deferred upstream and a spawned process stays tethered to its caller, so the launcher cannot exit. It is a long-lived supervisor, not a bootstrapper, and that cost is now stated. - The caller-supplied identity bundle was removed upstream. Dropped the workloadIdentity capability and the claim built on it; appId is now described as inert forward-compatibility metadata rather than a mechanical link to package identity. - PR openclaw#55 was mischaracterized. It also contains the long-lived Gateway, and brokers model credentials so neither Gateway nor worker holds provider values, which solves a residual risk this RFC cannot. Now positioned as complementary and the better answer where available, differing by deployment context rather than by scope. - openclaw#58 proposes a launcher, it does not already build one. #42026 would make the unit of containment a live question, not a drop-in swap. - AppContainer dismissal was too glib. It is MXC's default Windows backend; the real objection is that it is an allowlist over the same token, and its universally available tier enforces filesystem policy by mutating DACLs on host paths. - The downgrade requirement was impossible as written. An older launcher cannot be taught to reject config it never knew; this needs a minimum version enforced by packaging. - Fallback no longer contradicts fail-closed: it means another provider of equal or greater strength, never uncontained. Threat model restructured around the right baseline. Several residual risks are unchanged from an uncontained Gateway rather than regressions - shared-ACL reach, local IPC, egress, and persistence, which is now confined to a throwaway account instead of the user's profile. Separated from the risks containment actually shifts or introduces: the host-side state store, the staging channel, and the launcher. Added a TCB table covering the SDK, the SYSTEM service, and the kernel, and noted that a compromised Gateway commanding an authorized desktop node is not contained by this boundary. Also drops the claim that the Gateway is unaffected. It needs no containment code, but a new principal means a different profile, registry hive, and credential store, and whether the Docker and SSH sandbox backends survive that is now an explicit phase 2 question. All MXC citations pinned to a commit with a verification date, since a load-bearing claim went stale within a week. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: ccc616c5-8e0a-4098-b8ef-c19695e5c27b

Follow-up pass on the re-check: - Clarify that probe is the launcher's own step, not a provider phase, and drop the suggestion that the launcher could reattach later, since no such API exists. - Admit the orphan case a write-ahead record cannot fix: a crash during provisioning can leave an identity that no launcher can address, and reclaiming it is an out-of-band operator task. Added to the readiness bar. - Fix a stale Non-Goals line that still described openclaw#55 as containing only a session's work, and restate the boundary as deployment context. - Correct the AppContainer argument again: the ACEs it needs are removable by a matching unprepare step, so the real objection is the elevated, machine-wide host-prep required before a per-user agent can run, not permanent damage. - Stop calling the launcher "the trusted computing base" where the TCB table already shows it is only the part we own. - Pin the README citation, show exec and supervision in Figure 1, and add readiness items for sandbox-backend survival and downgrade prevention. - Decision requested now states what a yes actually accepts: a second always-on process, a larger TCB, and an identity-only boundary. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: ccc616c5-8e0a-4098-b8ef-c19695e5c27b

docs(rfc): propose OpenShell session workers

302accf

Signed-off-by: sallyom <somalley@redhat.com>

sallyom marked this pull request as ready for review July 31, 2026 06:41

sallyom marked this pull request as draft August 1, 2026 07:12

This was referenced Aug 18, 2026

docs: propose gateway containment via Windows Isolation Sessions #61

Open

docs: propose gateway containment via Windows Isolation Sessions paulcam206/rfcs#1

Closed

Navigation Menu

Uh oh!

RFC 0020: OpenShell Worker Provider and Credential-Brokered Session Sandboxes - #55

RFC 0020: OpenShell Worker Provider and Credential-Brokered Session Sandboxes#55
sallyom wants to merge 1 commit into
openclaw:mainfrom
sallyom:openshell-worker-provider

sallyom commented Jul 31, 2026

clawsweeper Bot commented Jul 31, 2026 •

edited

Loading

Security

Review metrics

Merge-risk options

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

History

Labels

1 participant

Uh oh!

Conversation

sallyom commented Jul 31, 2026

Summary

Motivation

Scope

Implementation status

Validation

Follow-up

clawsweeper Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ClawSweeper review

What this changes

Merge readiness

Review scores

Verification

How this fits together

Decision needed

Before merge

Findings

Security

Review metrics

Merge-risk options

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

History

Labels

1 participant

clawsweeper Bot commented Jul 31, 2026 •

edited

Loading