feat(orca): add Orca VM recipe plugin - #23
Merged
Merged
Conversation
Register a per-workspace environment that runs an Orca workspace on a disposable CreateOS Sandbox instead of the user's laptop. The package holds no code. orca-plugin.json declares one vmRecipes contribution, and vm-recipe.json points create and destroy at `createos setup orca --recipe`, which does the work. The recipe uses provisioned-root checkout: the sandbox builds the checkout and Orca adopts it, so the working tree is pushed rather than cloned and no git token reaches the box. Orca confirms the adopted checkout by matching git remote identity, so a project without a remote cannot use this recipe -- the README says so, since the error Orca raises does not. Suspend and resume are deliberately absent. SSH does not reliably come back after a sandbox resume, and Orca's schema requires the pair or neither. Installing by git URL does not work yet: Orca's installer clones a whole repository and expects orca-plugin.json at its root, so this monorepo subdirectory needs the Dev Paths route. Documented rather than left for users to discover.
The CLI moved `setup` under the sandbox group, so the recipe's create and destroy commands and the README's doctor example move with it. The command string is the contract between this plugin and the CLI, so the two have to change together.
pratikbin
force-pushed
the
feat/orca-plugin
branch
from
August 25, 2026 14:06
6f8ecbb to
083c566
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
packages/orca-plugin, which lets Orca run a whole workspace on a disposable CreateOS Sandbox instead of the user's laptop.Pairs with NodeOps-app/createos-cli#78, which adds the
createos setup orcacommand this recipe calls. That PR should merge first — without it the recipe's commands do not exist.What's in the package
Three files, no code:
orca-plugin.jsoncontributes.vmRecipesentry.vm-recipe.jsoncreateanddestroyatcreateos setup orca --recipe.README.mdOrca selects the lifecycle phase with
ORCA_VM_MODE, so both commands are the same string and the CLI branches internally.Design notes
Checkout is pushed, not cloned. The recipe uses
provisioned-root, so the sandbox builds the checkout and Orca adopts it. The user's working tree is uploaded — uncommitted edits included — which means no git token ever reaches the sandbox and private repositories work with no extra setup.A git remote is required. Orca confirms the adopted checkout is the same project by comparing git remote identities. A repo with no remote gets a host-local identity that can never match on another machine, and creation fails with
Imported folder does not match the selected project identity. That message does not hint at the cause, so the README calls it out with the fix.No suspend or resume. SSH does not reliably come back after a sandbox resume, and Orca's schema requires the pair or neither. Every workspace is destroy-and-recreate.
Install route
Installing by git URL does not work yet. Orca's installer clones a whole repository and requires
orca-plugin.jsonat its root, so this monorepo subdirectory cannot be installed that way — it would need its own single-package repo. The working route today is Settings > Plugins > Dev Paths pointed atpackages/orca-plugin.This is documented in the package README and in
CLAUDE.mdrather than left for users to discover. Thecreateos setup orcahelp text prints the same instructions.Verification
The manifest and recipe were validated against Orca's own parsers (
parsePluginManifest,parsePluginVmRecipeArtifact), including a negative control confirming the validator rejects a bad recipe — so "valid" is a real result, not a broken harness.End-to-end through Orca's UI on a real project: the recipe appears under Run on > Per-Workspace Environment, provisions a sandbox, wires SSH, seeds the checkout on a workspace-named branch, and Orca adopts it and opens the workspace. Destroy removes the sandbox; no leaks (
createos sandbox listchecked).Notes for the reviewer
README.mdandCLAUDE.mdfailprettier --checkatmainalready. I left them as-is rather than bundling an unrelated reformat into this PR; the new package README is prettier-clean.