@runblackcat/sdk 0.1.0-alpha.70 → 0.1.0-alpha.72

package/README.md

@@ -212,6 +212,47 @@ blackcat_placement_rejected_total{reason="…"}    no_capacity
 A fleet pinned at its ceiling shows up as `blackcat_capacity_target_nodes`
 persistently above `blackcat_nodes`.
 
+## Recommended production shape: bare metal
+
+Run workers on bare metal, one or a few large `.metal` hosts, and keep nested virtualization (a VM with `/dev/kvm`) as the quick-start
+default: it launches in under a minute and needs no special quota. On metal every guest page fault costs about 7.6 times less than
+nested, so the same fleet restores 2 to 3 times faster, fans out 30 times faster at 100 clones, costs a third as much per clone and
+does not lose VMs to nested VM-entry failures.
+
+| | bare metal (`c7i.metal-24xl`) | nested (`m8i.4xlarge`) |
+|---|---|---|
+| create p50 | 29 ms | 60 ms |
+| first exec | 33 ms | 67 ms |
+| snapshot restore | 13 ms | 43 ms |
+| fan-out of 100 clones | 0.6 s | 17.9 s |
+| cost per clone-hour | $0.0043 | $0.0132 |
+| VM-entry deaths | 0 | 2.9 per 1,000 hot restores, 325 per 1,000 at density |
+
+(Bake-off, 2 vCPU / 1 GiB app template, `contrib/bench/bakeoff/RESULTS.md`, "Huge pages". The hosts are different CPU
+generations and metal has 12 times the CPUs, so the fan-out column is not virtualization alone. Metal is cheaper per clone because it
+carries about 1,000 clones where the nested host was measured at 64.)
+
+North star on one `c7i.metal-48xl` (500 clones of a built-from-source web app at once, each running a short test then destroyed):
+99% done 112 s after the PR arrived, all 500 passed with no replacements and no VMM deaths, about $0.34 per PR from a stopped node,
+against 300 s, 264 replacements and about $1.00 on five `m8i.8xlarge`.
+
+Trade-offs, plainly:
+
+* **Boot.** A metal reboot has been quoted at about 7.5 minutes. Measured on a `c7i.metal-48xl`: a fresh launch was registered with SSM
+  in 74 s and a stopped node was serving again 47 s after `StartInstances`, but stopping it took 320 s (unbilled). Time from a
+  planner launch to an enrolled node on metal has not been measured (see
+  `contrib/bench/results/2026-10-04-wave-c-metal-northstar.md`). Nested hosts register in 40 to 45 s.
+* **Coarse sizes.** Metal is `.metal` sizes only: 96 or 192 vCPUs on the `c7i` family. A small or spiky fleet pays for a whole box
+  or runs nested.
+* **Thin Spot capacity.** Metal Spot pools are small; the planner falls back to on-demand when one refuses, and the price you plan
+  with is the cheaper Spot one.
+* **Large blast radius.** One host carries up to about a thousand clones. Losing it, or restarting its agent, hits all of them; keep
+  `fleet max-clones-per-host` as the cap you can accept and keep more than one host for anything that must survive a host loss.
+
+The capacity planner prefers metal when a reservation's `needed_by` allows its boot time and the price per clone is lower
+([docs/capacity-planning.md](docs/capacity-planning.md)); `blackcat_vm_entry_deaths` counts the VM-entry failures that make nested
+hosts unreliable at density. Setup: [docs/bare-mode.md](docs/bare-mode.md#recommended-production-shape-bare-metal).
+
 ## Install (alpha)
 
 Identical on bare metal and on AWS:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runblackcat/sdk",
-  "version": "0.1.0-alpha.70",
+  "version": "0.1.0-alpha.72",
   "description": "TypeScript SDK for the Blackcat sandbox gateway",
   "license": "Apache-2.0",
   "repository": "https://github.com/TreebeardHQ/blackcat",

package/sdk/dist/index.d.ts

@@ -262,7 +262,13 @@ export interface CreateTemplateResponse {
     };
 }
 export type CreateSandboxInput = {
-    template: string;
+    /**
+     * The template name or version id. Omitted, it is the tenant's `default`
+     * template, which the gateway builds on the tenant's first use: that first
+     * create fails with a 503 `default_template_building` until the build is
+     * ready, and repeating the same request is how to wait for it.
+     */
+    template?: string;
     /** Must equal the checkpoint's vCPUs, which are fixed at capture; omit it. */
     vcpus?: number;
     /**

package/sdk/dist/index.js

@@ -18,6 +18,9 @@ var BLACKCAT_ERROR_CODES = {
   SANDBOX_TRANSITIONING: "sandbox_transitioning",
   FLEET_UPGRADE_QUIESCING: "fleet_upgrade_quiescing"
 };
+function withTemplate(input) {
+  return { ...input, template: input.template ?? "default" };
+}
 
 class BlackcatApiError extends Error {
   status;
@@ -444,10 +447,10 @@ class SandboxesResource {
     return this.client.json("GET", "/v1/sandboxes", undefined, "token");
   }
   async create(input) {
-    return parseCreateSandboxResponse(await this.client.json("POST", "/v1/sandboxes", input, "token", false), input.request_id);
+    return parseCreateSandboxResponse(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
   }
   async createBatch(input) {
-    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", input, "token", false), input.request_id);
+    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
   }
   async batch(requestId) {
     return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "token"), requestId);