diff --git a/CLAUDE.md b/CLAUDE.md index 0cf1665..8045721 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/` | +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 +`.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..fc1dc7f --- /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 sandbox 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..58c7a34 --- /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 sandbox setup orca --recipe", + "destroy": "createos sandbox setup orca --recipe" +}