Skip to content

feat: add Ascii Box remote execution environment - #1603

Closed
zozo123 wants to merge 17 commits into
stacklok:mainfrom
zozo123:feat/box-execution-environment
Closed

zozo123 wants to merge 17 commits into
stacklok:mainfrom
zozo123:feat/box-execution-environment

Conversation

@zozo123

@zozo123 zozo123 commented Sep 15, 2026

Copy link
Copy Markdown

Summary

Adds an Ascii Box-backed Mecatl execution-environment / placement-provider adapter directly on main.

What it provides

  • server.PlacementProvider + exact PlacementReattacher backed by the Box API
  • durable EnvironmentRef{Kind: "box", ID: <box-id>, Revision: "box-api-v1"}
  • Box filesystem adapter implementing Mecatl's versioned Workspace contract
  • Shell CommandRunner bound to the same Box workspace namespace
  • POSIX-like namespace operations (ReadDir, Remove, Rename, CopyFile)
  • create / readiness / stop / resume lifecycle handling
  • noEnv: true by default so account/model/GitHub/SSH secrets are not injected into agent sandboxes
  • bounded API responses, path confinement, safe shell quoting, HTTPS-only API endpoint configuration
  • offline httptest coverage for creation, exact reattachment, version conflicts, grep, path escape, auth/error handling
  • opt-in real API smoke test behind box_live

The API key is host-side configuration only and is never placed in EnvironmentRef, the Box environment, tests, or repository state.

Live verification

The live contract test is opt-in and excluded from normal CI:

BOX_API_KEY=... go test -tags=box_live ./internal/adapter/boxenv -run TestLiveBoxEnvironment -v

It exercises:

  1. create isolated Box
  2. file create + versioned read
  3. Shell observes the same workspace
  4. workspace observes a Shell-created file
  5. exact reattach to the same Box ID
  6. cleanup via Box stop

Why Box fits this seam

Mecatl's environment identity is already provider-open and the placement layer owns environment construction/reattachment. Box maps directly onto that contract: opaque Box ID for durable placement identity, remote file operations for Workspace, and remote command execution for the bound CommandRunner.

Scope

This PR intentionally keeps Box isolated in internal/adapter/boxenv; it does not add a parallel sandbox abstraction or leak Box concepts into engine/. Operator-facing execution-placement selection can be wired separately once the provider-registration surface is finalized.

JAORMX and others added 17 commits September 14, 2026 11:49
Co-Authored-By: mecatl <noreply@stacklok.com>
Co-Authored-By: mecatl <noreply@stacklok.com>
Co-Authored-By: mecatl <noreply@stacklok.com>
Move source-checkout validation into the microVM placement adapter and cover generic remote composition context and fail-closed behavior.

Co-Authored-By: mecatl <noreply@stacklok.com>
Preserve microVM execution configuration alongside provider unification, restore microVM vet coverage, align release guards, and resolve the proposed ADR numbering collision.

Co-Authored-By: mecatl <noreply@stacklok.com>
Persist schedule-owned and borrowed placements, retain first-claim worktrees, and clean up lifecycle state atomically with pending-recovery metadata.

Co-Authored-By: mecatl <noreply@stacklok.com>
Co-Authored-By: mecatl <noreply@stacklok.com>
Co-Authored-By: mecatl <noreply@stacklok.com>
Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-Authored-By: mecatl <noreply@stacklok.com>
Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-Authored-By: mecatl <noreply@stacklok.com>
@zozo123
zozo123 changed the base branch from acc/microvm-execution-environments to main September 15, 2026 19:10

zozo123 commented Sep 15, 2026

Copy link
Copy Markdown
Author

Superseded by #1604. The replacement is the same Box adapter rebuilt directly on current main, so upstream GitHub Actions can run normally without the stacked #580 history.

@zozo123 zozo123 closed this Sep 15, 2026
@zozo123
zozo123 deleted the feat/box-execution-environment branch September 15, 2026 19:17
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