Skip to content

feat: add Box remote execution environment provider - #1601

Open
zozo123 wants to merge 6 commits into
stacklok:mainfrom
zozo123:feat/box-remote-environment-v2
Open

zozo123 wants to merge 6 commits into
stacklok:mainfrom
zozo123:feat/box-remote-environment-v2

Conversation

@zozo123

@zozo123 zozo123 commented Sep 15, 2026

Copy link
Copy Markdown

Summary

Adds an ASCII Box-backed remote execution-environment provider on top of mecatl's existing placement / durable EnvironmentRef seam.

  • provisions a fresh Box for the deployment-default placement and reattaches the exact persisted Box by opaque ID
  • keeps model/provider/GitHub/SSH account secrets out of guests by forcing Box noEnv: true on create and resume
  • binds Workspace and CommandRunner to the same Box namespace and exposes the server affinity proof
  • implements Read, versioned ReadVersion, atomic create-only / compare-and-replace, glob, grep, and namespace operations
  • preserves mecatl's CAS contract with a guest-side lock + SHA-256 version protocol instead of weakening remote writes to blind overwrites
  • archives the provisional Box through PlacementBinding.Close; reattachment resumes the same durable Box
  • preserves the existing no-FS attenuation without provisioning remote compute
  • uses a non-secret configuration fingerprint as EnvironmentRef.Revision; the Box credential never enters refs, logs, metadata, or source

Why this shape

Mecatl already models execution as a durable placement (EnvironmentRef + coherent Workspace/CommandRunner), and EnvironmentKind is intentionally open for remote backends. This adapter therefore plugs into server.PlacementProvider / PlacementReattacher without widening the engine API.

This PR deliberately does not invent a second user-facing placement-selection/config grammar while #580 is actively establishing the operator surface for execution placement. The adapter is injectable today through app.Config.PlacementProvider; the eventual operator selector can wire this provider without changing its execution contract.

Safety / correctness

  • Box API credentials are host-only and bearer values are never rendered into diagnostics.
  • Non-loopback custom API endpoints must use HTTPS.
  • User/model paths are validated twice: lexically in Go and physically in the guest helper; symlink/path escapes are rejected.
  • File mutations are serialized in the guest and conditional replacement returns the standard tool.VersionMismatchError on stale versions.
  • Shell and file operations target the same Box working directory.
  • Partial provisioning is stopped best-effort on readiness failure.

Tests

Added deterministic fake-Box coverage for:

  • create -> use -> archive -> exact reattach/resume
  • noEnv enforcement on create/resume
  • Workspace / Shell namespace affinity
  • read/version/create/replace semantics and stale-version rejection
  • concurrent replacement: exactly one writer wins
  • glob/grep/list/copy/rename/remove
  • no-FS attenuation and configuration/path guards

Also adds TestLiveBox, an opt-in live contract smoke driven only by BOX_API_KEY; ordinary CI skips it and the credential is never persisted or logged.

A local execution of the same guest filesystem helper passed create/read/versioned replace/copy/glob/grep/read-dir including stale-version rejection. The current execution container cannot resolve external hosts, so I could not run the live Box API test from here; upstream CI remains the full repository build/test authority.

@jhrozek

jhrozek commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

@zozo123 thanks for the PR! I think this is exciting in the sense that the PR does show how the harness can be decoupled from the execution environment.

I'm not familiar with Box but checking the wiring with mecatl I think this is missing a builder composition (something like boxenv.New?) to be testable? Also, check out PR #1614 that adds a native k8s execution environment - I would suggest to coordinate e.g. internal/adapter/executioncontroller/podexec.go is a good place to look there for inspiration.

Thanks again for the contribution! Feel free to jump on Discord or GH discussions if you want to discuss anything!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants