On every Orca Cloud start and wake, orcad ran its disposable startup preflight child. That child is a
second full load of the 15 MB bundle plus the SQLite and node-pty probes, and it ran before main().
The cloud slot could never be qualified: qualification needed the managed-activation env, and the
marker lives in the slot directory, which is root-owned in the image. In-VM profiles showed the main
thread idle for about 580 ms waiting on that child.
- ORCA_ORCAD_STARTUP_QUALIFICATION_DIR names a writable directory for the startup-qualified marker
and opts the slot into qualification. The key is unchanged: artifact version, file stat identity,
runtime, ABI, kernel and launch env. It survives a stop and resume: inode, mtime and ctime are
identical after resume, and the first launch after resume skipped the preflight.
- The image creates /opt/orca/startup-qualification. The provisioning smoke run records the marker,
and orca-sandbox-start passes the env.
- Agent-state-rules live updates and speech-model warm-up now start after the ready line instead of
before it.
- Once the ready line is published, a terminal list warms the terminal path (worktree catalog,
daemon inventory) before the reconnecting desktop asks for it.
Real 4-vCPU VMs, readyMs median of 5: idle 1475 -> 903 ms; with 3 busy cores 1921 -> 1200 ms.
The Worker-started source build used the VM scripts, provision script and manifest pins embedded in
the Worker that started it, so a golden built from a newer commit could miss that commit's new VM
scripts (seen live: snap_HTsU from 19f900e has #122's orcad but not orca-desktop-proxy or
orca-desktop-page.js). source-build.sh now sources image/commit-provision-env.mjs from the fetched
checkout (no dependencies; mirrors provisionEnv, enforced by a test), so the image ships exactly that
commit. Tests also require every image/vm file to be a declared VM script and installed by provision.
* feat(cli,sandbox-control): orca repo add --display-name; cloud sandboxes name the project after its repository
The VM checkout lives at /vercel/sandbox/project, so boot-time registration (#104) named the repo
'project'. repo.add already accepts displayName; the CLI now exposes it as --display-name and
orca-sandbox-start passes the repository basename from ORCA_REPO_URL.
* fix(sandbox-control): golden builder polls detached builds with a bounded wait=true read; image-only merges trigger a rebuild
The provider reports a detached command's exit code only to a wait=true read (W1's finding, #123):
stepBuild's plain GET is what kept finished golden builds 'running' until the deadline. stepBuild and
the operator rotation now use the same bounded wait probe (4 s); the exit-file marker stays as a
fallback. golden-source's VM path list now includes cloud/apps/sandbox-control/image/ (VM scripts,
provision, manifest), so a script-only merge (e.g. orca-desktop-proxy) rebuilds the golden too.
* feat(cloud): remote desktop single-use tickets, fit, clipboard and keyboard release
- VM: Xvnc on a 0600 socket with no VNC auth plus an X cookie; orca-desktop-proxy (websockify
subclass) admits one WebSocket per unused 60 s ticket from the same localhost origin, refuses
rebinding Hosts, scrubs tickets from logs, serves the page with connect-src 'self'.
- Worker: POST /desktop mints a fresh ticket per call (schemaVersion 2).
- Desktop: no secret in the tab URL; main hands the page tickets on load and reconnect (backoff,
floor, pause with Reconnect), only for the exact URL of a live forward it opened; keyboard stays
in the desktop until Ctrl+Cmd / Ctrl+Alt; a paste key pushes this computer's clipboard; sandbox
copies reach this computer after a copy gesture.
- UI: keyboard hint, asleep/starting neutral tone and mapping, persistent error toasts, Beta badge.
* fix(cloud): remote desktop review fixes
- Security review: noVNC host/port/encrypt pinned to the page's origin, CSP connect-src 'self',
exact-URL + live-forward trust, mint floor and per-minute cap, copy gate on copy gestures only,
X display cookie.
- Design review: archived is its own neutral state, starting covers waking, page messages say
"Wake it in Orca", pause overlay is a status for calm states and focuses Reconnect, hint wraps
and hides from assistive tech when faded.
- FE review: paste follows the keyboard layout, AltGr never releases, page calls settle on
navigation, state notices only on change, hint once per load/release, paste always pushes,
no committed bytecode, session tests.
* fix(cloud): remote desktop archived page message, hint layout, fixtures
* fix(cloud): remote desktop copy gate counts double-clicks (pointer events have no click count)
* chore(cloud): remote desktop lint (exhaustive pause reasons, no test casts or wall clock)
Seen live twice: source-build.sh had exited (provision done, no processes left) but GET cmd kept
exitCode null for 40 min, so the build hit its deadline. source-build.sh now writes its exit code
(/tmp/source-build.exit) and the provision report (/tmp/source-build.report); the operator rotation
and the Worker's stepBuild fall back to the marker. The operator script reads the report from the
file instead of the command log stream (which never ends in that state) and prints the running build
step every ~2 min.
orcad listed the cloned project only after a client called repo.add, which only the desktop does on
connect. orca-sandbox-start now runs 'orca repo add --path /vercel/sandbox/project' (folder kind
when it is not a git checkout) in the background once orcad is ready; re-adding is a no-op. Verified
on a VM from the active golden: repo list shows /vercel/sandbox/project right after start.
* feat(sandbox-control): operator golden rotation from a git ref (image/rotate-golden-from-source.ts)
Fallback while the Worker's git-source build can't read the repo: uploads git archive of the ref
(default private/cloud/integration) into a managed-image build sandbox, runs source-build.sh (now
accepts an uploaded ORCA_SRC_DIR), wipes, snapshots, smoke-boots (SOURCE_COMMIT matches, tools, orca
CLI reaches orcad, stop/resume), and registers a smoking golden_images row with bundle_sha256
git:<sha>. Refuses a desktop-less image when the manifest pins one. Durable ledger in
~/.orca-cloud-ops (survives /tmp wipes); --cleanup deletes orphans of an interrupted run.
* fix(sandbox-control): honest create timing: create_ms/wake_ms written once per start, not ready_at - created_at
GET /v1/config said create p95 23 s. Its source, ready_at - created_at, moves on every wake, so every
sandbox slept and woken within two minutes of creation (bench and smoke cycles: 15-23 s, 35-90 s) counted
as a slow create. Real creates on dev are p50 2.9 s / p95 4.0 s. Migration 0035 adds create_ms
(write-ahead row to first ready) and wake_ms (resume claim to ready); createTiming reads create_ms.
## W4: team collaboration on Orca Cloud workspaces
### Control plane (`cloud/apps/sandbox-control`)
- **Registry** (`0024_workspace_registry.sql`, applied on dev D1): owner (reassignable), `created_by`, branch, `visibility` (private default / team), section, last activity, token spend. Reuses 0020's `name`/`archived_at`.
- **Routes under `/v1/team/*`** (W5 owns `/v1/workspaces`): list with Mine/Team/All, By, In, Archived filters; PATCH (rename, share or make private, section, archive, reassign owner); presence heartbeats; wake and lease for teammates; links resolve; org prompts/PR instructions (compare-and-set).
- **Security fix:** `/v1/sandboxes/:id` used to be account-scoped, so any org member could resume a teammate's sandbox and receive its orcad pairing code. It is now owner-only; admins can still suspend and destroy.
- **Per-member, per-device E2EE grants:**
- The VM mints a single-device orcad offer and seals it to the requesting device's X25519 key.
- The control plane stores only the orcad device id.
- Revocation runs `orca pair --revoke`, which closes the device's live sockets, plus an on-disk registry removal.
- When the VM is asleep, the revoke is queued and applied at boot before orcad starts.
- Triggers: explicit revoke, making a workspace private, archive, reassign, member removal (internal route), and phone device-session revoke (W8).
- VMs from older images get the entry points installed on demand.
- **Git as the sender:** a member's own GitHub user-to-server token (App OAuth, envelope-encrypted) is swapped in at egress only for the workspace repo. The VM gets per-member git configs and `orca-git-as`.
- **Cost:** metered compute × billing rate, plus optional token spend.
### orcad (generic)
- New owner-only RPC `pairing.revokeDevice` and `orca pair --revoke <device-id>`: revokes a device and closes its open connections immediately.
### Desktop
- A "Cloud workspaces" section on Home: Team/Mine, By, In and Archived filters; sections; live presence; cost; last activity. Single-click Open on a teammate workspace pairs this device through an E2EE grant. Also a row menu (share/private, move to section, reassign, archive) and copy link.
- Deep links `orca://cloud/w/<id>[/c/<chat>]` (open-url, argv, second instance, sidecar handoff) and the `cloudWorkspace.copyLink` keybinding.
- Messages to agents in shared workspaces carry a sender envelope.
- Uses the W10 shared primitives.
- Two rounds of adversarial design and frontend review.
### Evidence
Real Vercel VMs; see the W4 report. Numbers:
- grant issued in 0.55 s, paired in 1.35 s
- revoke closes the live desktop socket ~30 ms after the PATCH returns
- two members' pushes land on GitHub with their own author identities (shared dev Worker, preview alias w4); a push to another repo gets 403
* feat(cloud): SSH into Orca Cloud workspaces (orca ssh, ssh-proxy, VS Code/Cursor Remote-SSH)
- VM: unprivileged key-only sshd on 127.0.0.1:2222 (orca-sshd), host key and Orca-managed
authorized_keys on the persistent disk; orca-ssh-keys entry point; provision extracts only the
server binaries (dnf or apt, +1.5-2 MB) and unlocks the sandbox user for key logins.
- Control plane: POST/DELETE /v1/sandboxes/:id/ssh-keys runs the fixed entry point and answers
the pinned host key; editor Remote-SSH server hosts on the egress allowlist.
- Desktop: per-workspace ed25519 keys in userData (0600), Orca-owned ssh_config + pinned
known_hosts, ~/.ssh/config Include only after consent; wake -> key -> runtime port forward
(openRuntimePortForward reason 'ssh'); revoke (deferred while asleep); SSH traffic keeps the
workspace awake.
- CLI: orca ssh-proxy <workspace> (ProxyCommand) and orca ssh <workspace>.
- UI: Open in -> VS Code / Cursor over Remote SSH, SSH submenu (Copy SSH Command, Revoke),
include consent dialog, progress/error toasts.
* fix(cloud-ssh): review fixes — no agent forwarding, reinstall per VM boot, wake to revoke
- ForwardAgent/ForwardX11 no in Orca's host blocks; AllowAgentForwarding no in the VM's sshd.
- Reinstall the key (idempotent; restarts sshd, re-pins the host key) once per VM boot, so a
wiped disk, rollover or dead sshd heals on the next connection.
- Revoke wakes the VM to remove its copy; only an unreachable VM falls back to the queue.
- orca-ssh-keys rejects multi-line keys; sshd log truncated per start; audit log entries for
ssh key add/remove; state parsed per entry; % escaped in ssh_config paths; ProxyCommand pinned
to this app's profile; ssh-proxy flushes stdout before exit; --print shell-quotes; editors
open via --folder-uri with a checked path; "Remove from ~/.ssh/config" + one-time backup.
GOLDEN_IMAGE_SOURCE=git:<repo>#<branch>: each cron tick resolves the branch HEAD through the GitHub
App installation on that repo (read-only single-repo token, operator-only request surface) and, when
HEAD differs from the active image's commit and the compare touches VM paths, starts a source build:
fetch the commit, build orcad + bundled orca CLI, provision, then the existing wipe, snapshot, smoke,
atomic activate (previous image kept as rollback). The commit is recorded as bundle_sha256 git:<sha>
(kept through clone refreshes) and in /opt/orca/runtime/orcad/SOURCE_COMMIT. Also (W2): openssh-server
in the image (on demand only), https apt sources, unlocked password field for key-only sshd.
Follow-up to #49 (W1 environment builds), control plane only.
- **Warm pool per hot environment build** (`pool.ts`): alongside the golden pool, keep 1 ready VM booted from the active build of each environment that was used or built in the last 2 hours (standard size, at most 20 builds). A create from that environment claims it. Pool deletes never remove the image a VM booted from.
- **Smoke-boot every build before activating it**: orcad must answer on the new image. If the install script broke Orca, that build fails as `smoke_failed` and never reaches a workspace. The boot also takes the first-boot cost so users don't.
- **Prelude**: skips the fetch when the build is already on the requested branch, because Orca fetches the base right before `worktree add`.
- **GitHub token errors**: a minting error now fails the build as `github_unavailable` (step clone). Before, it cloned anonymously and failed with a misleading 404, seen live.
Evidence: shared dev preview alias, private repo, sequential, n=12.
| Create → orcad ready | p50 | p95 |
|---|---|---|
| Before | 4.99 s | 6.71 s |
| After | 3.76 s | 5.67 s |
The only sample above 3.9 s was the first one, which missed the pool while it was cold. Pool hits put the VM phase at 0.25 s. Tests: 221 pass, plus typecheck.
Control-plane half of W1, org environment builds (Conductor "Cloud Computer" parity). The desktop settings UI, CLI and disk banner follow in a second PR.
- **Org environment**: repos (GitHub, up to 50, each with a default branch), an install script, env var names, and a machine size (Standard 4/8 or Large 8/16; Large bills 2× through the existing usage path). Members can read; owners and admins edit. Edits use optimistic concurrency.
- **Versioned builds** (`#N`), with status, live log stream (ndjson), stored log, failure step, duration and snapshot.
- Each build boots a throwaway VM from the active golden image, clones every repo, and runs the install script once with `set -euo pipefail`.
- It records commits and lockfile blob ids, checks that orcad survived, then saves a manual snapshot.
- **Failed builds never replace the active build.** Rollback is instant (`activate`). The newest 5 builds plus the active one keep their snapshots.
- **New workspaces boot from the active build** (or a pinned `environmentBuildId`). Existing workspaces keep their build, and destroying a workspace never deletes the shared image.
- A first-boot prelude links the prebuilt repo as the project and fast-forwards the requested branch.
- A post-checkout hook hard-links the installed dependency folders into each new Orca worktree (about 250 ms).
- **Rebuild prompt** (`/staleness`): reports a lockfile change, a moved default branch, a config edit, or a newer base image. It uses the GitHub compare API, or anonymous smart-HTTP plus raw blob hashing when the REST API refuses Worker IPs.
- **Repos with no commits** build and open; Orca adds an empty first commit.
- **Hardening from the review**:
- Recovers a snapshot whose finalize was cut off (adopted by box name).
- Bounded log reads on cancel/timeout.
- Org secret values are redacted from live and stored logs.
- Activation is guarded in SQL.
- Build-number races return 409.
- Migration `0008_environments.sql`: number claimed in /tmp/vdrv/migrations.claims and already applied to dev D1. It is additive.
## Evidence (real Vercel VMs)
Full write-up: `.context/cloud/reports/w1-env-builds.md`.
- vercel/ms build: 15.9 s (boot 1.8 s, clone+install 6 s, snapshot 8 s).
- Private `nwparker/orca-sandbox-push-test` plus public `vercel/ms` in one environment on the shared dev preview: build succeeded in 18 s, and a workspace created from it was ready in 6.3 s.
- Create → orcad ready:
| Boots from | p50 | p95 |
|---|---|---|
| Environment build (n=10, deps installed) | 4.37 s | 8.41 s |
| Bare golden image (n=9) | 4.79 s | 7.61 s |
- Rollback, creating from build N-1, an empty repo (`rsc/empty`), and staleness `deps_changed` → Rebuild → `up_to_date` were all verified live.
## Tests
`cloud/apps/sandbox-control`: 99 vitest tests and typecheck pass. The new `test/environments.test.ts` covers RBAC, build/fail/keep-last-good, concurrent build 409, cancel, live stream, boot from active and pinned builds, rollback, prune, interrupted-snapshot recovery, and staleness.
W9 F4/F5. The build starts from vercel/sandbox/node:24 (Ubuntu) instead of the deprecated node24
runtime, so sandboxes cloned from the golden get 64 GB instead of 32 GB. The bundle's orca-cli.cjs
becomes /opt/orca/bin/orca (ORCA_USER_DATA_PATH defaults to orcad's data dir); a pinned Google Chrome
.deb provides headless Chrome and orcad gets ORCA_BROWSER_EXECUTABLE. Live smoke of the built image:
64G disk, all tools on PATH, orca status reaches orcad, chrome headless renders, create 2.3 s, orcad
2.1 s, resume 2.0 s.
Control plane (cloud/apps/sandbox-control):
- Provider presets as secrets: AI_GATEWAY_API_KEY (Vercel AI Gateway) derives Claude Code + Codex env;
custom ANTHROPIC_BASE_URL/OPENAI_BASE_URL (https, public host only) + *_MODEL. Provider hosts are
allowlisted per workspace from its agent connection (migration 0026 egress_allow_hosts, additive).
- Egress placeholder swap is host-scoped per credential (SECRET@host) incl. ai-gateway.vercel.sh and
custom hosts; staged rollout SECRETS_EGRESS_PLACEHOLDERS=accounts:<ids> (or on/off).
- GET /v1/secrets/effective, POST /v1/secrets/:scope/batch, POST /v1/sandboxes/:id/env/refresh; every
secret write refreshes running sessions of that owner (no restart, no rebuild).
- VM: orca-sandbox-env writes a tmpfs-only session env file re-read by every new shell
(/etc/profile.d hook); Codex gets a managed provider block when OPENAI_BASE_URL is set; managed env
ORCA_IS_CLOUD, ORCA_ROOT_PATH/WORKTREE_PATH/WORKSPACE_PATH/WORKSPACE_NAME/DEFAULT_BRANCH/PORT +
CONDUCTOR_* aliases. image/patch-golden-image.ts re-images scripts in ~10s.
- Redaction: pairing offer read via the files API (Vercel retains command stdout), log tails strip
injected values/token shapes, runningOrcad no longer prints the offer, no GitHub placeholder for
non-github.com repos.
Desktop: token-pattern + injected-value redaction for logs, crash reports, daemon log, emulator probe,
relayed worker spans.
Live (Vercel, W6 worker, placeholders on): org-shared gateway key, real Claude Code 2.1.319 and Codex
0.166.0 fixed+committed code through the swap; SSE long stream 978 chunks/25s and streamed tool_use
intact; real key absent from VM disk, tmpfs and every process env; secret edit visible in a new
shell 0.6s after PUT.
- pool.ts: N standard VMs booted from the current golden with egress denied; create claims one atomically
(DELETE..RETURNING), applies the caller policy + full lease in parallel, bills from the claim; cron and
each claim refill; recycled at 20 min, on golden change, pool off or kill switch; fallback to a fresh VM.
- F1: orca-sandbox-start leaked the start-lock fd into orcad, so a second start (resume of a running
sandbox, retried create) waited 60 s and 502'd. Children now close fd 9; the Worker also reads the
serving orcad's ready line without the lock (fixes VMs on older images).
- F2: a github.com repo with no App token and no anonymous access fails 409 github_not_connected before
any VM work.