orca-per-workspace-env

Name: orca-per-workspace-env
Author: stablyai

713installs1.9kforks

How to install orca-per-workspace-env?

stablyai/orca/orca-per-workspace-env

$npx -y skills add stablyai/orca --skill orca-per-workspace-env

Installs into the current project.

Summary

Set up, review, debug, or validate Orca per-workspace environment recipes — on-demand, disposable runtimes (cloud sandboxes, VMs, or local) created fresh for each workspace. Covers first-time setup (provider prerequisites, the reusable base snapshot, the coding-agent auth snapsho

Files · 1

View on GitHub

SKILL.md

1	# Per-Workspace Environments
2
3	Help a user stand up and maintain a repo-owned per-workspace environment recipe end to end. Each
4	workspace gets its own on-demand, disposable runtime (a cloud sandbox, a VM, or a local one),
5	created fresh and torn down after.
6
7	Orca is a thin wrapper: you guide, detect, and scaffold; you never own the user's cloud account,
8	billing, images, or credentials.
9
10	- You DO: sequence the setup, detect what's detectable (provider CLI present/logged-in? recipe
11	present? `doctor` passing?), scaffold provider-templated scripts the user fills in, drive the slow
12	snapshot/auth phases with the user, and always show the next action.
13	- You DO NOT: create accounts, choose plans/regions, invent org/project/scope ids, store or print
14	secrets, or run anything that spends money without an explicit user OK.
15
16	First-time setup has four phases before the per-workspace recipe runs — easy to miss, so walk
17	them in order:
18
19	1. Prerequisites — cloud account, provider CLI, scope/project, plan limits, git token (§2).
20	2. Base snapshot — reusable image: tools + repo + headless build, snapshotted once (§3).
21	3. Agent-auth snapshot — boot the base, run interactive device-auth, re-snapshot (§4).
22	4. State — thread snapshot id / scope / project / port between phases via a state file (§6).
23
24	Then the per-workspace contract (create/suspend/resume/destroy) runs fast (§8).
25
26	The one branch that shapes everything — connection mode: Orca-server (`create` runs `orca serve`
27	in the env and emits a `pairingCode`; §7c/§7f) vs SSH (`create` runs no server and emits a
28	`connection.type:"ssh"` block Orca dials into; §7g/§7h). Settle this first — it changes the `create`
29	output shape and half the templates.
30
31	Quick-start (happy path): interview the user (connection mode Orca-server vs SSH, provider, agent CLI,
32	git auth — §1.2) + read the provider's CLI docs → scaffold `scripts/orca-vm/` from §7 → run the
33	base-snapshot script, then the auth script (you invoke these by hand; not via `orca.yaml`) → wire
34	`environmentRecipes` in `orca.yaml` → `orca vm recipe doctor <id> --json` (free) → then the `--provision`
35	self-test loop (§9) until it passes.
36
37	---
38
39	## 1. Setup workflow
40
41	Drive these with the user. [CHECKPOINT] steps need explicit confirmation — they spend money, take
42	a long time, or need the user at the keyboard. Never create an Orca workspace or commit unless asked.
43
44	1. Inspect the repo for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state file, or setup
45	notes. If a working recipe exists, jump to Doctor (§9) instead of rebuilding.
46	2. Interview the user up front — gather these choices and confirm them back before scaffolding
47	anything. Don't pick for them (§11); don't guess.
48	- Connection mode: how Orca attaches to the environment — an Orca server (the VM runs
49	`orca serve` and Orca pairs over its pairing URL; worked example §7f) or SSH (Orca connects to
50	the host over SSH; §7g). This decides the recipe's connection shape, so settle it first.
51	- Provider: Vercel Sandbox, Fly, Modal, an existing SSH host, … For non-obvious providers, also
52	ask scope/project/region and plan limits (§2). Then read that provider's CLI/SDK docs (or
53	`<cli> --help`) before scaffolding — you need its exact create/exec/snapshot/remove verbs.
54	If a provider advertises `ssh`, verify whether it exposes a real dialable SSH target
55	(host/port/user/key or proxy command) or only a provider-mediated interactive shell; Orca SSH mode
56	needs the former.
57	- Coding-agent CLI + account: which agent runs in the VM (`codex`, `claude`, …) and that the user
58	has an account for it — it gets logged in during the Phase-3 auth snapshot (§4).
59	- Git auth: the token source for cloning a private repo (`GH_TOKEN`/`GITHUB_TOKEN` or `gh auth
60	token`; §5).
61	3. Check prerequisites (§2) — detect the provider CLI + auth and confirm the items above are in
62	place before any paid step.
63	4. Scaffold scripts + state file from §7 (worked Vercel example: §7f; SSH host: §7g; Docker SSH:
64	§7h; Windows: §7i), filling in the provider's real commands. Make them executable.
65	5. [CHECKPOINT] Build the base snapshot (§3) — paid, slow.
66	6. [CHECKPOINT] Authenticate the agent (§4) — interactive; the user follows a URL/code. **You cannot
67	drive this st

People who liked this also viewed

6 picks

Type

orca-per-workspace-env

713installs1.9kforks

View on GitHub

How to install orca-per-workspace-env?

stablyai/orca/orca-per-workspace-env

$npx -y skills add stablyai/orca --skill orca-per-workspace-env

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Per-Workspace Environments
2
3	Help a user stand up and maintain a repo-owned per-workspace environment recipe end to end. Each
4	workspace gets its own on-demand, disposable runtime (a cloud sandbox, a VM, or a local one),
5	created fresh and torn down after.
6
7	Orca is a thin wrapper: you guide, detect, and scaffold; you never own the user's cloud account,
8	billing, images, or credentials.
9
10	- You DO: sequence the setup, detect what's detectable (provider CLI present/logged-in? recipe
11	present? `doctor` passing?), scaffold provider-templated scripts the user fills in, drive the slow
12	snapshot/auth phases with the user, and always show the next action.
13	- You DO NOT: create accounts, choose plans/regions, invent org/project/scope ids, store or print
14	secrets, or run anything that spends money without an explicit user OK.
15
16	First-time setup has four phases before the per-workspace recipe runs — easy to miss, so walk
17	them in order:
18
19	1. Prerequisites — cloud account, provider CLI, scope/project, plan limits, git token (§2).
20	2. Base snapshot — reusable image: tools + repo + headless build, snapshotted once (§3).
21	3. Agent-auth snapshot — boot the base, run interactive device-auth, re-snapshot (§4).
22	4. State — thread snapshot id / scope / project / port between phases via a state file (§6).
23
24	Then the per-workspace contract (create/suspend/resume/destroy) runs fast (§8).
25
26	The one branch that shapes everything — connection mode: Orca-server (`create` runs `orca serve`
27	in the env and emits a `pairingCode`; §7c/§7f) vs SSH (`create` runs no server and emits a
28	`connection.type:"ssh"` block Orca dials into; §7g/§7h). Settle this first — it changes the `create`
29	output shape and half the templates.
30
31	Quick-start (happy path): interview the user (connection mode Orca-server vs SSH, provider, agent CLI,
32	git auth — §1.2) + read the provider's CLI docs → scaffold `scripts/orca-vm/` from §7 → run the
33	base-snapshot script, then the auth script (you invoke these by hand; not via `orca.yaml`) → wire
34	`environmentRecipes` in `orca.yaml` → `orca vm recipe doctor <id> --json` (free) → then the `--provision`
35	self-test loop (§9) until it passes.
36
37	---
38
39	## 1. Setup workflow
40
41	Drive these with the user. [CHECKPOINT] steps need explicit confirmation — they spend money, take
42	a long time, or need the user at the keyboard. Never create an Orca workspace or commit unless asked.
43
44	1. Inspect the repo for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state file, or setup
45	notes. If a working recipe exists, jump to Doctor (§9) instead of rebuilding.
46	2. Interview the user up front — gather these choices and confirm them back before scaffolding
47	anything. Don't pick for them (§11); don't guess.
48	- Connection mode: how Orca attaches to the environment — an Orca server (the VM runs
49	`orca serve` and Orca pairs over its pairing URL; worked example §7f) or SSH (Orca connects to
50	the host over SSH; §7g). This decides the recipe's connection shape, so settle it first.
51	- Provider: Vercel Sandbox, Fly, Modal, an existing SSH host, … For non-obvious providers, also
52	ask scope/project/region and plan limits (§2). Then read that provider's CLI/SDK docs (or
53	`<cli> --help`) before scaffolding — you need its exact create/exec/snapshot/remove verbs.
54	If a provider advertises `ssh`, verify whether it exposes a real dialable SSH target
55	(host/port/user/key or proxy command) or only a provider-mediated interactive shell; Orca SSH mode
56	needs the former.
57	- Coding-agent CLI + account: which agent runs in the VM (`codex`, `claude`, …) and that the user
58	has an account for it — it gets logged in during the Phase-3 auth snapshot (§4).
59	- Git auth: the token source for cloning a private repo (`GH_TOKEN`/`GITHUB_TOKEN` or `gh auth
60	token`; §5).
61	3. Check prerequisites (§2) — detect the provider CLI + auth and confirm the items above are in
62	place before any paid step.
63	4. Scaffold scripts + state file from §7 (worked Vercel example: §7f; SSH host: §7g; Docker SSH:
64	§7h; Windows: §7i), filling in the provider's real commands. Make them executable.
65	5. [CHECKPOINT] Build the base snapshot (§3) — paid, slow.
66	6. [CHECKPOINT] Authenticate the agent (§4) — interactive; the user follows a URL/code. **You cannot
67	drive this st

People who liked this also viewed

6 picks

Type