From cab6f7ddbf76aa2d9af0570557f9c7205fe25a65 Mon Sep 17 00:00:00 2001 From: pratikbin <68642400+pratikbin@users.noreply.github.com> Date: Tue, 25 Aug 2026 18:28:35 +0530 Subject: [PATCH 1/2] feat(orca): add Orca VM recipe plugin 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. --- CLAUDE.md | 12 ++ README.md | 25 +++++ packages/orca-plugin/README.md | 155 ++++++++++++++++++++++++++ packages/orca-plugin/orca-plugin.json | 15 +++ packages/orca-plugin/vm-recipe.json | 9 ++ 5 files changed, 216 insertions(+) create mode 100644 packages/orca-plugin/README.md create mode 100644 packages/orca-plugin/orca-plugin.json create mode 100644 packages/orca-plugin/vm-recipe.json diff --git a/CLAUDE.md b/CLAUDE.md index 0cf1665..0364c4c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,6 +11,18 @@ untrusted code in disposable CreateOS sandboxes: | `@createos/opencode` | OpenCode | `packages/opencode-plugin/` | | `@nodeops-createos/dsh-createos` | DeepSeek Harness | `packages/dsh-createos/` | +A fourth package, `orca-plugin/`, is not an IDE plugin in that sense — it holds +no skill or tool code. It registers one Orca VM recipe (`orca-plugin.json` + +`vm-recipe.json`) that runs a whole Orca workspace inside a CreateOS Sandbox, by +shelling out to `createos setup orca --recipe`. It is not discovered through +`.claude-plugin/marketplace.json` — that marketplace file is Claude Code-specific +and does not apply here. + +Orca's git-URL installer clones a whole repository and requires +`orca-plugin.json` at its root, so this subdirectory cannot be installed that +way yet. The working route is Settings > Plugins > Dev Paths pointed at +`packages/orca-plugin`. Read `packages/orca-plugin/README.md` before touching it. + Marketplace index is the root `README.md`; each package has its own `README.md`. ## Decisions diff --git a/README.md b/README.md index 1c8ce50..94b24e3 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,30 @@ The Claude Code, Codex, Pi, and OpenCode integrations use the `createos` CLI, wh | [**@createos/codex**](./packages/codex-plugin) | Codex plugin — skill that teaches the `createos` CLI for sandbox lifecycle, networking, disks, and VPN. | | [**@createos/opencode**](./packages/opencode-plugin) | OpenCode plugin with 33 sandbox tools (`sandbox_exec`, `sandbox_push`, `sandbox_pull`, networks, disks, VPN, sync) and system prompt injection for sandbox-first workflows. | | [**@nodeops-createos/dsh-createos**](./packages/dsh-createos) | DeepSeek Harness bundle that replaces `ctx.fs` and `ctx.subprocess` together, so Bash, file, LSP, and PTY consumers operate inside one CreateOS sandbox without provider-specific tool forks. | +| [**orca-plugin**](./packages/orca-plugin) | Orca VM recipe — runs a whole Orca workspace on a disposable microVM instead of your laptop. Pushes your working tree, uncommitted edits included, so no git token reaches the box. Optionally installs Claude Code, Codex, Cursor, OpenCode, or Pi. | + +## Orca — run a workspace on a sandbox + +Orca creates one disposable microVM per workspace and connects to it over SSH, so +builds, installs, and test runs stay off your laptop. + +```bash +# 1. Clone this repo, then in Orca: +# Settings > Plugins > Dev Paths > add packages/orca-plugin +# 2. Create a workspace, and under "Run on" pick: +# Per-Workspace Environment > CreateOS Sandbox +``` + +Pick which coding agents get installed with `CREATEOS_AGENTS`: + +```bash +CREATEOS_AGENTS=claude,codex +``` + +Your project needs a git remote — Orca matches remote identity to confirm the +sandbox checkout is the same project. Suspend and resume are not supported yet. +Setup, configuration, limits, and troubleshooting live in the +[**Orca Plugin README**](./packages/orca-plugin/README.md). ## Claude Code — commands at a glance @@ -293,3 +317,4 @@ Issues and PRs welcome. The Claude Code, Codex, Pi, and OpenCode plugins are thi - [Codex plugin README](./packages/codex-plugin/README.md) - [OpenCode plugin README](./packages/opencode-plugin/README.md) - [DeepSeek Harness plugin README](./packages/dsh-createos/README.md) +- [Orca plugin README](./packages/orca-plugin/README.md) diff --git a/packages/orca-plugin/README.md b/packages/orca-plugin/README.md new file mode 100644 index 0000000..825e4f1 --- /dev/null +++ b/packages/orca-plugin/README.md @@ -0,0 +1,155 @@ +# CreateOS Sandbox for Orca + +Run an [Orca](https://orca.dev) workspace on a disposable [CreateOS](https://createos.sh) +Sandbox microVM instead of your laptop. + +Each workspace gets its own Firecracker microVM. Orca connects to it over SSH and +runs your coding agent there, so heavy installs, builds, and test runs stay off +your machine. + +This package holds no code. It registers one Orca VM recipe that shells out to +the `createos` CLI for every lifecycle phase. + +## Requirements + +- The `createos` CLI, signed in — run `createos login`. +- `git` and `ssh` on `PATH`. +- Orca's Settings > Cloud VM turned on. +- **A git repository with a remote.** See [Project requirements](#project-requirements). + +Check the first three with: + +``` +createos setup orca --doctor +``` + +## Install + +Orca's plugin installer clones a whole repository and expects `orca-plugin.json` +at its root. This package lives in a subdirectory of a monorepo, so installing it +by git URL does not work yet. Use a local checkout instead: + +1. Clone this repository. +2. In Orca, open Settings > Plugins > Dev Paths. +3. Add the path to `packages/orca-plugin`. +4. Approve the **CreateOS Sandbox** recipe when Orca asks. + +Then create a workspace, open the **Run on** menu, and pick **CreateOS Sandbox** +under Per-Workspace Environment. + +## Project requirements + +This recipe uses Orca's `provisioned-root` checkout mode: the sandbox creates the +workspace checkout, and Orca then adopts it. To confirm that the checkout on the +sandbox is the same project as the one on your machine, Orca compares git remote +identities. + +A repository with **no remote** gets an identity that is local to your machine and +can never match on another host. Workspace creation fails at the last step with: + +``` +Imported folder does not match the selected project identity. +``` + +Add a remote before using this recipe: + +``` +git remote add origin +``` + +A plain folder that is not a git repository cannot use this recipe either. + +## What happens on create + +1. `createos` provisions a microVM (default shape `s-4vcpu-8gb`, image `devbox:1`, + which ships sshd, git, and Node.js). +2. It wires SSH through the CreateOS gateway and waits until `sshd` accepts + connections. +3. It packs your working tree — tracked files plus untracked ones that + `.gitignore` does not exclude — and uploads it. +4. It checks the tree out on a branch named after your workspace, at the commit + Orca asked for. +5. It installs any coding agents you asked for (see below). + +Your checkout is **pushed, not cloned**, so no git token ever reaches the sandbox +and private repositories work with no extra setup. Uncommitted edits come along +with it. + +## What happens on destroy + +The sandbox is destroyed and its `~/.ssh/config` entry is removed. + +## Coding agents + +Orca does not tell a recipe which agent a workspace uses, so the recipe cannot +infer it. Name the agents you want with `CREATEOS_AGENTS`. Nothing is installed by +default. + +``` +CREATEOS_AGENTS=claude,codex +``` + +Accepted names, and the binary each one installs: + +| Name | Binary | +| ---------- | -------------- | +| `claude` | `claude` | +| `codex` | `codex` | +| `cursor` | `cursor-agent` | +| `opencode` | `opencode` | +| `pi` | `pi` | + +Note that `cursor` installs `cursor-agent`, not `cursor`. + +An agent already present on the image is skipped, so naming one that ships with +`devbox:1` costs nothing. An unknown name fails immediately, before any sandbox is +created. + +Each agent is installed by running that vendor's own install script at provision +time. Those scripts are not pinned to a version and are not checksum-verified, so +a workspace gets whatever the vendor publishes that day and it can change without +notice. To control exactly what you get, build a custom image and point +`CREATEOS_ROOTFS` at it. + +## Configuration + +Set any of these as environment variables before creating a workspace: + +| Variable | Default | Purpose | +| ---------------------------- | ----------------- | ------------------------------------------- | +| `CREATEOS_SHAPE` | `s-4vcpu-8gb` | Sandbox size | +| `CREATEOS_ROOTFS` | `devbox:1` | Sandbox image | +| `CREATEOS_PROJECT_ROOT` | `/workspace/repo` | Where the checkout lands inside the sandbox | +| `CREATEOS_SSH_READY_TIMEOUT` | `180s` | How long to wait for `sshd` | +| `CREATEOS_AGENTS` | (none) | Coding agents to install, comma-separated | + +## Limits + +- **Suspend and resume are not supported.** SSH does not reliably come back after + a sandbox resume, so this recipe declares neither phase. Every workspace is + destroy-and-recreate. +- **Large repositories can fail to upload.** Uploads of roughly 400 MB and above + can return a `503` partway through, which fails workspace creation. The size + that matters is your working tree minus what `.gitignore` excludes, so a large + `node_modules` or build directory is usually already excluded. +- **Installing by git URL does not work yet.** See [Install](#install). + +## Troubleshooting + +Orca shows `Couldn't create worktree` for any failure during creation. The real +reason is in the log panel below that message, and in the toast in the corner. + +| What you see | Cause | +| --------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| `Imported folder does not match the selected project identity.` | The project has no git remote. See [Project requirements](#project-requirements). | +| `request failed with status 503` during upload | The working tree is too large. See [Limits](#limits). | +| `unknown agent "..."` | A name in `CREATEOS_AGENTS` is not in the table above. | +| `cannot use ... as a branch name` | The workspace name is not a valid git branch name. Rename the workspace. | + +If a create fails, the recipe destroys the sandbox it made. When even that cleanup +fails, it prints the sandbox id and the exact command to remove it by hand. Check +for anything left behind with: + +``` +createos sandbox list +``` diff --git a/packages/orca-plugin/orca-plugin.json b/packages/orca-plugin/orca-plugin.json new file mode 100644 index 0000000..8d909c5 --- /dev/null +++ b/packages/orca-plugin/orca-plugin.json @@ -0,0 +1,15 @@ +{ + "manifestVersion": 1, + "id": "createos-sandbox", + "publisher": "nodeops", + "name": "CreateOS Sandbox", + "version": "0.1.0", + "description": "Run an Orca workspace on a disposable CreateOS Sandbox microVM instead of your laptop.", + "author": { "name": "pratikbin", "url": "https://createos.sh" }, + "repository": "https://github.com/NodeOps-app/createos-plugin", + "engines": { "orca": ">=1.4.0" }, + "pluginApi": 1, + "contributes": { + "vmRecipes": [{ "path": "vm-recipe.json" }] + } +} diff --git a/packages/orca-plugin/vm-recipe.json b/packages/orca-plugin/vm-recipe.json new file mode 100644 index 0000000..b8a138b --- /dev/null +++ b/packages/orca-plugin/vm-recipe.json @@ -0,0 +1,9 @@ +{ + "schemaVersion": 1, + "id": "createos-sandbox", + "name": "CreateOS Sandbox", + "description": "Firecracker microVM reached over the CreateOS SSH gateway", + "checkoutMode": "provisioned-root", + "create": "createos setup orca --recipe", + "destroy": "createos setup orca --recipe" +} From 083c566e70bf0961af26411f267842e29ecf910c Mon Sep 17 00:00:00 2001 From: pratikbin <68642400+pratikbin@users.noreply.github.com> Date: Tue, 25 Aug 2026 18:41:01 +0530 Subject: [PATCH 2/2] fix(orca): follow the createos sandbox setup rename 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. --- CLAUDE.md | 2 +- packages/orca-plugin/README.md | 2 +- packages/orca-plugin/vm-recipe.json | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0364c4c..8045721 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ untrusted code in disposable CreateOS sandboxes: | `@createos/opencode` | OpenCode | `packages/opencode-plugin/` | | `@nodeops-createos/dsh-createos` | DeepSeek Harness | `packages/dsh-createos/` | -A fourth package, `orca-plugin/`, is not an IDE plugin in that sense — it holds +One more package, `orca-plugin/`, is not an IDE plugin in that sense — it holds no skill or tool code. It registers one Orca VM recipe (`orca-plugin.json` + `vm-recipe.json`) that runs a whole Orca workspace inside a CreateOS Sandbox, by shelling out to `createos setup orca --recipe`. It is not discovered through diff --git a/packages/orca-plugin/README.md b/packages/orca-plugin/README.md index 825e4f1..fc1dc7f 100644 --- a/packages/orca-plugin/README.md +++ b/packages/orca-plugin/README.md @@ -20,7 +20,7 @@ the `createos` CLI for every lifecycle phase. Check the first three with: ``` -createos setup orca --doctor +createos sandbox setup orca --doctor ``` ## Install diff --git a/packages/orca-plugin/vm-recipe.json b/packages/orca-plugin/vm-recipe.json index b8a138b..58c7a34 100644 --- a/packages/orca-plugin/vm-recipe.json +++ b/packages/orca-plugin/vm-recipe.json @@ -4,6 +4,6 @@ "name": "CreateOS Sandbox", "description": "Firecracker microVM reached over the CreateOS SSH gateway", "checkoutMode": "provisioned-root", - "create": "createos setup orca --recipe", - "destroy": "createos setup orca --recipe" + "create": "createos sandbox setup orca --recipe", + "destroy": "createos sandbox setup orca --recipe" }