Add Run Cloud sandbox provider

[t0tl]

Summary

• add Run Cloud as a Crabbox provider, including registration, CLI/config wiring, doctor checks, metadata, and documentation
• provision persistent exposed sandboxes with the supported runcloud/agent-base image
• route SSH through runcloud sandbox proxy and support sync/run/inspect/list/stop lifecycle operations
• bootstrap compatibility prerequisites for older images, including the runcloud user, Git, and rsync
• make failed/interrupted live-smoke cleanup retain and destroy the exact requested sandbox

Why

Run Cloud's retired runcloud/box image is no longer available. Crabbox therefore targets runcloud/agent-base explicitly and uses the authenticated Run Cloud SSH proxy rather than assuming a public SSH endpoint.

The live investigation also found a production image issue: the currently published agent-base guest lacks the guest-agent SSH WebSocket bridge on port 2222. The companion Newly PR #3553 fixes that image and its SSH path.

Validation

• go test -race -count=1 ./internal/providers/runcloud ./internal/providers/all
• go build ./cmd/crabbox
• scripts/check-docs.sh
• all 65 tests in scripts/live-smoke.test.js, including a retained-lease lifecycle proving warmup → status/inspect/ssh/cache/run → exactly one stop
• exact-head Run Cloud API/CLI live lifecycle against a real shared-dev sandbox: create, expose, exec, list, and destroy all passed in Newly run 30933203610
• manual Crabbox live smoke reached real create/expose and then correctly waited for SSH readiness; it could not complete through the currently published guest image because port 2222 is absent; the exact sandbox was destroyed and no active Crabbox sandbox was left behind

Remaining live boundary

Keep this draft until Newly #3553 is merged and its normally tested runcloud/agent-base artifact is published. Then rerun scripts/live-smoke.sh --provider runcloud to prove the Crabbox binary's complete SSH/sync/run path against the released image. The provider tests and Run Cloud lifecycle prerequisites are green; the integrated Crabbox-over-edge-SSH proof is intentionally not claimed yet.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 4, 2026, 7:26 PM ET / 23:26 UTC.

ClawSweeper review

What this changes

Adds a Run Cloud SSH-lease provider with configuration, CLI lifecycle handling, live-smoke coverage, and provider documentation.

Merge readiness

⛔ Blocked until stronger real behavior proof is added - 11 items remain

Keep this draft open: it adds a new built-in provider, but the selected default image cannot yet complete its required SSH workflow and repository configuration can redirect execution to an arbitrary local CLI binary.

Priority: P1
Reviewed head: 46207fbd2f1cba9ad6ba0741eb294c86c0165a32
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	Partial live lifecycle evidence is useful, but the patch has unresolved P1 security and core-availability blockers.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: The PR reports real lifecycle work but explicitly lacks a successful Crabbox SSH, sync, and run result with the default image; post redacted after-fix live output after the image is released. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🧂 unranked krab (1/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The PR reports real lifecycle work but explicitly lacks a successful Crabbox SSH, sync, and run result with the default image; post redacted after-fix live output after the image is released. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	6 items	Repository policy applied: The full repository policy requires provider-specific behavior behind adapters and prohibits passing provider credentials through repository configuration or argv. Repository config redirects local execution: The new file-config path applies runCloud.cliPath without checking the existing trusted-config flag; a repository-controlled config can therefore select an arbitrary local executable. Configured CLI is executed: The provider passes the configured CLI path directly to the local command runner for account, lifecycle, bootstrap, and proxy operations.
Findings	2 actionable findings	[P1] Reject repository-controlled Run Cloud CLI paths [P1] Do not default to an image without the SSH bridge
Security	Needs attention	Repository config controls the credentialed CLI executable: An untrusted config can replace runcloud with an arbitrary executable, allowing local code execution when a user invokes the provider and potentially exposing credentials managed by that CLI.

How this fits together

Crabbox providers create remote execution leases from CLI configuration. This adapter creates a Run Cloud sandbox and sends its proxied SSH connection into Crabbox’s normal sync, command, status, and cleanup workflow.

flowchart LR
  A[Crabbox CLI and config] --> B[Run Cloud provider]
  B --> C[Run Cloud CLI lifecycle]
  C --> D[Persistent sandbox]
  D --> E[Authenticated SSH proxy]
  E --> F[Crabbox sync and commands]
  F --> G[Lease cleanup]

Loading

Decision needed

Question	Recommendation
Should Crabbox sponsor Run Cloud as a built-in supported provider after the security and live-image blockers are resolved?	Sponsor after the blockers are fixed: Accept the built-in direction once the CLI trust boundary is repaired and complete proof against the released image is supplied.

Why: A built-in provider creates an ongoing compatibility and support contract that source review cannot establish from the proposed implementation alone.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The PR reports real lifecycle work but explicitly lacks a successful Crabbox SSH, sync, and run result with the default image; post redacted after-fix live output after the image is released. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Reject repository-controlled Run Cloud CLI paths (P1) - runCloud.cliPath is applied even for untrusted repository configuration, then used as the executable for commands that rely on the user’s Run Cloud login. Gate this assignment on trusted config while retaining explicit flag and environment overrides, and add an untrusted-config regression test. This path was unchanged since the earlier reviewed head; this is a late-discovered blocker.
• Do not default to an image without the SSH bridge (P1) - The branch default remains runcloud/agent-base, while the PR states that its published version lacks the bridge required by runcloud sandbox proxy. Fresh users therefore cannot complete SSH, sync, or run. Keep the provider unavailable by default or change the default only after a released image proves the path.
• Resolve security concern: Repository config controls the credentialed CLI executable - An untrusted config can replace runcloud with an arbitrary executable, allowing local code execution when a user invokes the provider and potentially exposing credentials managed by that CLI.
• Resolve merge risk (P1) - A checked-in .crabbox.yaml can set runCloud.cliPath to a repository executable; running this provider would execute that program on the developer machine with access to the local Run Cloud credential store.
• Resolve merge risk (P1) - Fresh users select runcloud/agent-base by default even though the PR identifies that published image as unable to complete the proxied SSH, sync, and run workflow.
• Complete next step (P2) - A maintainer must sponsor the new built-in provider direction, while the contributor supplies the external-image proof and fixes the concrete security boundary.
• Improve patch quality - Trust-gate runCloud.cliPath and add a regression test for untrusted repository config.
• Improve patch quality - Use the released proxy-capable image and post redacted complete live-smoke output.
• Improve patch quality - Update the PR body with the proof; if review does not refresh, ask a maintainer to comment @clawsweeper re-review.

Findings

• [P1] Reject repository-controlled Run Cloud CLI paths — internal/cli/config.go:7444-7445
• [P1] Do not default to an image without the SSH bridge — internal/cli/config.go:3234-3237
• [high] Repository config controls the credentialed CLI executable — internal/cli/config.go:7444

Agent review details

Security

Needs attention: The new repository-configurable CLI path can execute an attacker-controlled local binary in a workflow that uses the local Run Cloud credential store.

Review metrics

Metric	Value	Why it matters
Change surface	24 files affected; production +1,240, tests +471	This is a broad provider addition spanning local configuration, remote lifecycle code, documentation, and smoke coverage.

Merge-risk options

Maintainer options:

1. Gate CLI paths and prove the supported image (recommended)
   Require trusted-only repository CLI paths, regression coverage for untrusted config, and redacted successful full-path live output against the released default image before merge.
2. Pause pending product sponsorship
   Keep the draft paused if no maintainer wants to own the provider’s external CLI and image compatibility contract.

Technical review

Best possible solution:

Land a built-in provider only after its CLI path is trust-gated, its default image supports the released SSH bridge, and a redacted live run proves warmup, SSH, sync, command execution, and cleanup end to end.

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

Yes for the security finding: an untrusted repository config can set runCloud.cliPath and the provider executes that value directly. The advertised complete SSH workflow remains unprovable until the published image gains its required bridge.

Is this the best way to solve the issue?

No: the current implementation should not ship with a repository-controlled local CLI path or a default image known to fail the core execution path.

Full review comments:

• [P1] Reject repository-controlled Run Cloud CLI paths — internal/cli/config.go:7444-7445
runCloud.cliPath is applied even for untrusted repository configuration, then used as the executable for commands that rely on the user’s Run Cloud login. Gate this assignment on trusted config while retaining explicit flag and environment overrides, and add an untrusted-config regression test. This path was unchanged since the earlier reviewed head; this is a late-discovered blocker.
  Confidence: 0.99
  Late finding: first raised on code an earlier review cycle already covered.
• [P1] Do not default to an image without the SSH bridge — internal/cli/config.go:3234-3237
  The branch default remains runcloud/agent-base, while the PR states that its published version lacks the bridge required by runcloud sandbox proxy. Fresh users therefore cannot complete SSH, sync, or run. Keep the provider unavailable by default or change the default only after a released image proves the path.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add merge-risk: 🚨 security-boundary: Repository-controlled configuration can replace the locally executed CLI that accesses Run Cloud’s credential store.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦐 gold shrimp and patch quality is 🧂 unranked krab.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

• P1: The provider would expose users to both a local execution boundary weakness and a default SSH workflow that is known not to complete.
• merge-risk: 🚨 security-boundary: Repository-controlled configuration can replace the locally executed CLI that accesses Run Cloud’s credential store.
• merge-risk: 🚨 availability: The branch default image is documented as missing the bridge required for the provider’s core SSH path.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦐 gold shrimp and patch quality is 🧂 unranked krab.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR reports real lifecycle work but explicitly lacks a successful Crabbox SSH, sync, and run result with the default image; post redacted after-fix live output after the image is released. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

Security concerns:

• [high] Repository config controls the credentialed CLI executable — internal/cli/config.go:7444
  An untrusted config can replace runcloud with an arbitrary executable, allowing local code execution when a user invokes the provider and potentially exposing credentials managed by that CLI.
  Confidence: 0.99

What I checked:

• Repository policy applied: The full repository policy requires provider-specific behavior behind adapters and prohibits passing provider credentials through repository configuration or argv. (AGENTS.md:1, e73b02f6455f)
• Repository config redirects local execution: The new file-config path applies runCloud.cliPath without checking the existing trusted-config flag; a repository-controlled config can therefore select an arbitrary local executable. (internal/cli/config.go:7444, 46207fbd2f1c)
• Configured CLI is executed: The provider passes the configured CLI path directly to the local command runner for account, lifecycle, bootstrap, and proxy operations. (internal/providers/runcloud/client.go:269, 46207fbd2f1c)
• Known unavailable default path: The branch defaults to runcloud/agent-base, while the PR body states that the published image lacks the port-2222 SSH bridge required for the proxy and cannot complete Crabbox SSH, sync, and run. (internal/cli/config.go:3236, 46207fbd2f1c)
• Current credential-boundary precedent: Current main documents and enforces protection around repository-controlled destinations when a provider uses native CLI credentials; the new Run Cloud path does not participate in that boundary. (internal/cli/credential_provenance.go:1084, 797f20736844)
• Not implemented on main: Current main contains no Run Cloud provider path; the feature exists only on this unmerged PR head. (internal/providers/runcloud/provider.go:1, e73b02f6455f)

Likely related people:

• steipete: Peter Steinberger last updated the current provider registry and shared configuration surface that this integration extends. (role: recent provider-registry and configuration contributor; confidence: high; commits: 797f20736844; files: internal/providers/all/all.go, internal/cli/config.go, internal/cli/credential_provenance.go)

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 (6 earlier review cycles)

• reviewed 2026-08-04T07:01:21.054Z sha fd8f9c9 :: needs real behavior proof before merge. :: [P1] Avoid exposing the guest application port | [P1] Do not ship a known-unusable default image
• reviewed 2026-08-04T10:07:18.447Z sha 23c0871 :: needs real behavior proof before merge. :: [P1] Use an image that supports the required SSH proxy
• reviewed 2026-08-04T10:17:11.112Z sha c5b0fe5 :: needs real behavior proof before merge. :: [P1] Use an image that supports the required SSH proxy
• reviewed 2026-08-04T15:01:57.607Z sha 46207fb :: needs real behavior proof before merge. :: [P1] Use a proxy-capable default image
• reviewed 2026-08-04T18:01:38.313Z sha 46207fb :: needs real behavior proof before merge. :: [P1] Do not default to an image without the required SSH bridge
• reviewed 2026-08-04T21:06:08.697Z sha 46207fb :: needs real behavior proof before merge. :: [P1] Use a proxy-capable default image