claudegoodies
Skill

orca-per-workspace-env

From stablyai

>-

Guides setup and debugging of Orca per-workspace environment recipes in orca.yaml, scaffolding provider lifecycle scripts.

Use it when

  • Standing up a new per-workspace cloud sandbox/VM/local recipe from scratch
  • Fixing an environmentRecipes entry in orca.yaml
  • Debugging an `orca vm recipe doctor` failure
  • Scaffolding create/suspend/resume/destroy scripts for a provider like Vercel Sandbox, Fly, Modal, or SSH

Skip it if

  • You're not using the Orca CLI/workspace tooling
  • You don't have a cloud account or provider CLI already set up
  • You want a fully automated flow — this requires manual checkpoints for paid snapshot builds and interactive agent login
  • You need it to manage billing, credentials, or provider accounts directly (it won't)

Facts

Repository
stablyai/orca
Status
Actively maintained
Last commit
Source file
skills/orca-per-workspace-env/SKILL.md

Source preview

The instructions Claude Code reads when this skill runs.

# Per-Workspace Environments

Help a user stand up and maintain a repo-owned per-workspace environment recipe end to end. Each
workspace gets its own on-demand, disposable runtime (a cloud sandbox, a VM, or a local one),
created fresh and torn down after.

Orca is a **thin wrapper**: you guide, detect, and scaffold; you never own the user's cloud account,
billing, images, or credentials.

- **You DO:** sequence the setup, detect what's detectable (provider CLI present/logged-in? recipe
  present? `doctor` passing?), scaffold provider-templated scripts the user fills in, drive the slow
  snapshot/auth phases with the user, and always show the next action.
- **You DO NOT:** create accounts, choose plans/regions, invent org/project/scope ids, store or print
  secrets, or run anything that spends money without an explicit user OK.

First-time setup has **four phases before the per-workspace recipe runs** — easy to miss, so walk
them in order:

1. **Prerequisites** — cloud account, provider CLI, scope/project, plan limits, git token (§2).
2. **Base snapshot** — reusable image: tools + repo + headless build, snapshotted once (§3).
3. **Agent-auth snapshot** — boot the base, run interactive device-auth, re-snapshot (§4).
4. **State** — thread snapshot id / scope / project / port between phases via a state file (§6).

Then the **per-workspace contract** (create/suspend/resume/destroy)
View full source on GitHub →

Other skills