docs: define trusted runtime environment policy

[skevetter]

Document the trusted-plugin environment and executable-trust policy in the public Runtime Protocol guide. Default inheritance preserves current MicroSandbox compatibility; reduced inheritance requires an explicit consumer choice. Explain provider checksum verification, absolute executable paths, supervisor ownership limits, transport metadata precedence, and diagnostic redaction.

Update the implementation summary for the merged SDK conformance, supervisor, and streaming probes. Distinguish forwarding regressions from the still-outstanding real-runtime compatibility experiment and supervisor startup comparison.

Validation: website link checks and production build; file-scoped prek; task cli:lint:ci; diff whitespace checks.

Companion SDK regressions: devsy-org/devsy-runtime-sdk#18

Local CodeRabbit reviewed the initial complete guide with no findings. Greptile identified optional checksums in the existing downloader; the follow-up explicitly requires nonempty expected checksums and successful verification for downloaded, cached, and local paths before future runtime/supervisor launch. Final head 89cae89 has passed all applicable CI and Greptile 5/5. The checksum finding is resolved. Hosted CodeRabbit completed the final-head review with no actionable findings. Commit signatures are verified and all actionable review threads are resolved. SDK #18 has merged.

[netlify]

✅ Deploy Preview for devsydev ready!

Name	Link
🔨 Latest commit	89cae89
🔍 Latest deploy log	https://app.netlify.com/projects/devsydev/deploys/6ac14e6bdd15d30008ff8041
😎 Deploy Preview	https://deploy-preview-1360--devsydev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7a8fe876-d163-402e-9dc7-6564d73c4ac0

📥 Commits

Reviewing files that changed from the base of the PR and between 8f27ff9 and 89cae89.

📒 Files selected for processing (1)

• sites/docs-devsy-sh/content/docs/developing-providers/runtime-protocol.mdx

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The runtime protocol documentation now covers process ownership, executable verification, plugin-process environment handling, and implementation status.

Changes

Runtime protocol documentation

Layer / File(s)	Summary
Process ownership and executable trust sites/docs-devsy-sh/content/docs/developing-providers/runtime-protocol.mdx	The guidance distinguishes SDK server bootstrap from optional process supervision and assigns cleanup responsibilities. It requires checksums for provider-distributed runtime and supervisor executables and clarifies the limits of the magic cookie and SecureConfig.
Environment policy and implementation status sites/docs-devsy-sh/content/docs/developing-providers/runtime-protocol.mdx	The documentation describes host-environment inheritance, supervisor overrides, protected handshake metadata, and secret redaction. It records process-ownership and duplex-streaming probes, with host integration and runtime compatibility remaining later gates.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 89cae

The guidance clarifies process ownership, executable trust, and environment behavior without changing runtime behavior. No merge-blocking issue is identified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 89cae

The guidance makes executable trust and process ownership requirements more explicit without changing runtime execution. Plugins remain trusted code with access to inherited host settings. Verification enforcement and supervisor cleanup still need validation before integration and cutover.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Under the documented policy, trusted plugins and CLI children can receive host proxy credentials and configuration selecting Docker endpoints, credential locations, and user directories. Effective exposure depends on the launching account and its configuration; the evidence does not establish additional tenant-wide access or newly gained privileges.

Security Findings and Attack Paths

• observed — The existing verifier accepts an existing file when its expected checksum is empty; cached binaries use the same verifier. This behavior predates the PR. The new guidance explicitly warns that downloader success does not establish executable trust, and the scoped diff adds no downloader changes or runtime launch integration.

Trust Boundaries and Controls

• observed — The normative policy gives client-assigned handshake and transport metadata precedence over provider overrides. It also prohibits logging full environments or secret-bearing runtime arguments and requires backend diagnostic redaction. These are documented controls; production enforcement was not inspected.

Resilience and Maintainability Implications

• observed — The guide separates plugin cleanup responsibility from optional supervisor ownership and explicitly leaves host integration unfinished. The inspected evidence does not demonstrate durable cleanup ownership through startup failure, cancellation, repeated or concurrent launches, interruption, recovery, or cutover rollback.

Hardening Proposals

• proposed — For future host integration, make launch acceptance checks demonstrate checksum gating on downloaded, cached, and local executables, alongside ownership and cleanup across failed startup, cancellation, repeated launches, and recovery before cutover.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: documenting trusted runtime environment and executable-trust policies.

✨ Finishing Touches

✨ Simplify code

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[netlify]

✅ Deploy Preview for images-devsy-sh canceled.

Name	Link
🔨 Latest commit	89cae89
🔍 Latest deploy log	https://app.netlify.com/projects/images-devsy-sh/deploys/6ac14e6b7e41720008311207

[skevetter]

@greptileai review

[greptile-apps]

Confidence Score: 5/5

[Low risk] Updates documentation about runtime protocol behavior.

The documentation change appears safe to merge.

Summary

The Runtime Protocol guide now sets rules for trusted runtime executables, plugin environments, and optional process ownership. It also updates the SDK implementation summary while keeping real-runtime compatibility and cutover as later work.

• Documents required checksum checks for provider runtime and supervisor executables.
• Defines host environment inheritance as the default and reduced inheritance as an explicit choice.
• Clarifies supervisor ownership limits and updates the SDK probe summary.

_{Reviews (2) · Last reviewed commit: "docs: require verified checksums before ..."}

[skevetter]

@greptileai review

[skevetter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.