warpmetal 0.8.11 → 0.8.13

package/README.md

@@ -41,11 +41,15 @@ x402api help --json
 Install the bundled skill for supported coding agents:
 
 ```sh
+warpmetal agent install --target <codex|claude|all>
 warpmetal agent install --target codex
 warpmetal agent install --target claude
 warpmetal agent install --target all
 ```
 
+`warpmetal agent install` installs only the bundled WarpMetal skill; it does
+not install sandbox tools or select a sandbox tool profile.
+
 Use `--scope project` to install into the current repository instead of the
 user-level agent directory.
 
@@ -58,7 +62,7 @@ integration.
 
 The repository also contains a skills-only WarpMetal plugin for the public
 Plugins Directory shared by Codex and ChatGPT. The plugin remains a separate
-artifact from the npm CLI and requires `warpmetal` CLI version 0.8.1 or newer.
+artifact from the npm CLI and requires `warpmetal` CLI version 0.8.13 or newer.
 
 To test the repository marketplace after the plugin lands on `main`:
 
@@ -317,9 +321,10 @@ compatible external signer.
   Wallet key management and signing remain outside this package.
 - Destructive or state-changing commands require explicit confirmations and
   generate idempotency keys by default.
-- Runtime bootstrap credentials remain memory-only and are requested only after
-  the first host key has been pinned and strictly reverified. Signed supervisor
-  bundles are checksum- and signature-verified before OpenSSH uploads them.
+- Runtime bootstrap credentials remain memory-only. Manual installation asks
+  for one only after the first host key has been pinned and strictly reverified;
+  automatic reload bootstrap is rendered directly into provider-bound
+  cloud-init. Signed supervisor bundles are checksum- and signature-verified.
 - Each agent gets a distinct SSH key forced into exactly one sandbox. Token-free
   connection profiles pin the VPS host key and contain no owner credential or
   private-key material.
@@ -332,11 +337,43 @@ compatible external signer.
   external workspace, lifetime, and start time. The wait completes only when
   the observed digest and generation both match the accepted target.
 - Guarded reload powers the server off first. Runtime-enabled reload requires a
-  second acknowledgment, after which the CLI guides supervisor reinstall and
-  pinned connection-profile refresh. Only a locally recorded reload operation
-  that succeeds and reports an owner-host-key refresh opens one new managed
-  trust epoch; failed or ambiguous reloads retain the old pin and never permit
-  replacement. Erased workspaces are never described as recoverable.
+  second acknowledgment because all sandbox workspaces are erased. WarpMetal
+  places the approved signed Runtime bootstrap in reload cloud-init
+  automatically; wait for Runtime readiness, then refresh pinned sandbox
+  connection profiles. Only a locally recorded reload operation that succeeds
+  and reports an owner-host-key refresh opens one new managed trust epoch;
+  failed or ambiguous reloads retain the old pin and never permit replacement.
+  Erased workspaces are never described as recoverable.
+- New agent-enabled candidate orders and Runtime-enabled reloads pass the
+  closed nested-sandbox opt-in inside verified provider cloud-init. The signed
+  Runtime bundle installs the exact-path AppArmor policy for the neutral
+  image's immutable Bubblewrap helper; this needs no follow-up customer SSH
+  key and adds no public order field or CLI flag. VPS-only cloud-init is
+  unchanged. Existing enrolled hosts use reload/reprovision; the CLI does not
+  claim a silent in-place policy repair command.
+- Runtime reports a new or replaced sandbox generation as running only after a
+  fixed, credential-free inner-Bubblewrap oracle proves nested namespaces, an
+  inherited read-only view of the outer Agent Box's already isolated procfs,
+  an allowed workspace write, empty Linux capability sets,
+  `no-new-privileges`, and protected-root write denial. Failure stops the
+  container before access grants or tool setup advance.
+
+For a Runtime-enabled reload, no separate installation command is part of the
+successful path:
+
+```sh
+warpmetal server reload \
+  --server <serverId> --confirm ERASE --power-off-first \
+  --acknowledge-agent-runtime-reset --wait --json
+warpmetal runtime get --server <serverId> --wait --json
+warpmetal sandbox access refresh \
+  --server <serverId> --sandbox <sandboxId> --grant <grantId> \
+  --connection-file <profile-path> --confirm REFRESH --wait --json
+```
+
+The successful reload records a new operation-bound owner SSH trust epoch.
+Verify the replacement host key before using owner SSH; sandbox access remains
+strictly pinned through each refreshed connection profile.
 
 ## Agent Runtime example
 
@@ -367,6 +404,61 @@ warpmetal sandbox access keygen \
   --json
 ```
 
+### Registered sandbox tools
+
+WarpMetal can apply only registered, immutable tool profiles. These commands use
+the owner credential already stored in the private WarpMetal state file; they do
+not accept a bearer token on the command line or permit a caller-supplied URL,
+shell command, environment, or artifact override.
+
+```sh
+warpmetal tools list --server <serverId> --json
+warpmetal tools install --server <serverId> --sandbox <sandboxId> --profile <profileId> \
+  [--idempotency-key <key>] [--wait] [--timeout-seconds <n>] --json
+warpmetal tools status --server <serverId> [--wait] [--timeout-seconds <n>] --json
+```
+
+`tools install` posts only the selected registered `profileId`. Waiting is
+bounded: `ready` exits 0, `failed` or `cancelled` exits 5, and a timeout exits 8.
+JSON output contains public profile, operation, and receipt metadata only.
+Successful non-wait installs and status inspections exit 0 while reporting the
+accepted or current state; exit 8 is reserved for an actual `--wait` deadline
+timeout.
+
+Codex is a released automatic tool profile when the public
+`/agent-tool-profiles` endpoint advertises it as `available`. WarpMetal installs
+the exact registered artifacts when selected at order time or through
+`tools install`. Claude Code uses the released `claude-code` automatic tool
+profile under the same public availability gate. Claude Managed Agents are separate:
+`claude-managed-ant` is an install-only CLI profile. Installing `ant` does not
+authenticate a worker and does not activate Managed Agents. Cursor CLI remains
+manual and unavailable as an automatic profile until separately qualified later.
+Gemini CLI remains manual.
+
+An order `--runtime-file` may add the closed optional setup intent beside its
+`sandboxes` array:
+
+```json
+{
+  "sandboxes": [
+    { "name": "codex-worker", "size": "small" },
+    { "name": "claude-worker", "size": "small" },
+    { "name": "managed-worker", "size": "small" }
+  ],
+  "setup": {
+    "version": 1,
+    "sandboxProfiles": [
+      { "sandboxName": "codex-worker", "profileId": "codex" },
+      { "sandboxName": "claude-worker", "profileId": "claude-code" },
+      { "sandboxName": "managed-worker", "profileId": "claude-managed-ant" }
+    ]
+  }
+}
+```
+
+Only those fields are accepted. Each setup entry must name a sandbox in the
+same file and a registered profile ID.
+
 ### Install a standard sandbox SSH alias
 
 Use a separate keypair and access grant for each sandbox. After the grant is
@@ -390,10 +482,16 @@ ssh -t <alias> gemini
 ssh <alias> gemini -p '<task>'
 ```
 
-Install and authenticate Codex, Claude Code, Cursor CLI, or Gemini CLI inside
-the sandbox first. Provider credentials are sandbox-owned and remain in its
-persistent home; WarpMetal does not install these tools, perform their login,
-or receive their credentials.
+Authenticate Codex or Claude Code inside the sandbox after its selected profile
+is ready. The public `/agent-tool-profiles` response is authoritative for
+availability and checkout selection. Claude Code uses the `claude-code`
+automatic tool profile. Claude Managed Agents are
+separate: `claude-managed-ant` is an install-only CLI profile. Installing `ant`
+does not authenticate a worker and does not activate Managed Agents. Cursor CLI
+remains manual and unavailable as an automatic profile until separately
+qualified later. Install and authenticate Cursor CLI or Gemini CLI inside the
+sandbox. Provider credentials are sandbox-owned and remain in its
+persistent home; WarpMetal does not perform provider login or receive them.
 
 The alias is local-only. It prepends a managed include to `~/.ssh/config` and
 uses the profile's pinned host key plus the sandbox identity. It never uses or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {

package/skills/warpmetal/SKILL.md

@@ -11,7 +11,7 @@ with ad hoc HTTP commands.
 
 ## Start safely
 
-1. Run `warpmetal --version` and require version `0.8.1` or newer for this
+1. Run `warpmetal --version` and require version `0.8.13` or newer for this
    plugin. If it is missing or older, explain the compatibility requirement,
    ask before installing or upgrading software, and use only the official npm
    package from `https://www.npmjs.com/package/warpmetal`.
@@ -254,8 +254,8 @@ warpmetal server power \
 For a destructive reload, explain that every server-disk file is erased and
 obtain explicit approval. If Agent Runtime is enabled, also explain that every
 sandbox workspace is lost, desired sandboxes return as empty workspaces after
-reinstall, and pinned profiles must be refreshed. Then use only the guarded
-command:
+automatic Runtime setup, and pinned profiles must be refreshed. Then use only
+the guarded command:
 
 ```sh
 warpmetal server reload \
@@ -271,14 +271,18 @@ warpmetal server reload \
 The CLI requires the recovery owner credential so it can keep polling after
 reload revokes SSH-derived access tokens. CLI 0.8.8 records a new SSH trust
 epoch only when that exact local reload operation succeeds and reports that the
-owner host key needs refresh. The next Runtime install may trust the first
-observed Ed25519 host key once in that epoch, then must reconnect strictly
-before requesting bootstrap. Failed or ambiguous reloads retain the prior pin;
+owner host key needs refresh. Failed or ambiguous reloads retain the prior pin;
 never bypass a mismatch or delete a pin to force a retry. A provider-console
-pre-seed is the optional higher-assurance path. Then wait for grants to become applied and refresh
-every connection profile with `sandbox access refresh --confirm REFRESH`
-before connecting. Do not fall back to raw API calls for deletion, networking,
-or another unsupported mutation.
+pre-seed is the optional higher-assurance path.
+
+After a successful Runtime-enabled reload, WarpMetal performs signed Runtime
+setup automatically. Do not run a separate installation command. Wait with
+`warpmetal runtime get --server <serverId> --wait --json`, then wait for grants
+to become `applied` and refresh every connection profile with
+`sandbox access refresh --confirm REFRESH` before connecting. The successful
+operation created a new owner host-trust epoch, so verify the replacement host
+key before owner SSH. Do not fall back to raw API calls for deletion,
+networking, or another unsupported mutation.
 
 ## Use Agent Runtime
 
@@ -286,12 +290,13 @@ Agent Runtime is optional and shares one owner's VPS only among that owner's
 agents. Discover live `agentRuntime` capacity and OS support before choosing
 sizes. Use `--runtime-file` to include sandbox intent in an unpaid order, or
 `warpmetal runtime enable` after the VPS is ready. Supervisor installation is
-separate and requires approval plus `--confirm INSTALL`.
+separate and requires approval plus `--confirm INSTALL` for initial setup or
+explicit repair; Runtime-enabled OS reloads use automatic signed cloud-init.
 
 With CLI 0.8.8, that confirmation also authorizes managed trust on first use
 when the exact server trust epoch has no pin. The CLI performs only an owner-
 key-authenticated `ssh true`, pins the first observed Ed25519 key, immediately
-reconnects strictly, and requests bootstrap only afterward. Later connections
+reconnects strictly before requesting bootstrap. Later connections
 must match. Explain that TOFU cannot detect an active attacker on the first
 connection; never use `ssh-keyscan`, accept a mismatch, or expose a generic pin
 reset.

package/skills/warpmetal/references/cli-reference.md

@@ -201,7 +201,18 @@ Reload requires the recovery owner credential rather than a short-lived
 SSH-derived token. `--power-off-first` authorizes shutdown and powered-off
 verification inside the same operation. When Agent Runtime is enabled,
 `--acknowledge-agent-runtime-reset` is required because workspaces are erased,
-the supervisor must be reinstalled, and connection profiles must be refreshed.
+the Runtime identity is replaced, empty sandboxes are reconciled automatically,
+and connection profiles must be refreshed. After a successful reload, wait for
+automatic setup before refreshing profiles:
+
+```sh
+warpmetal runtime get --server <serverId> --wait --json
+```
+
+The successful operation records a new owner SSH trust epoch. Verify the
+replacement host key before owner SSH. Manual Runtime installation remains an
+explicit repair path when automatic setup fails; it is not part of a
+successful reload.
 
 Use `--token-file` only for recovery when local state is unavailable. Prefer
 `WARPMETAL_OWNER_TOKEN` or `WARPMETAL_ACCESS_TOKEN` for a single command over a
@@ -210,6 +221,13 @@ process listings.
 
 ## Agent Runtime and sandboxes
 
+Agent-enabled first boot and Runtime-enabled reload automatically carry the
+closed nested-sandbox opt-in inside verified provider cloud-init. The signed
+Runtime bundle installs the exact-path policy for the image's immutable
+Bubblewrap helper without a later customer SSH key. This is not a public order
+field or CLI flag; VPS-only cloud-init remains unchanged, and existing enrolled
+hosts use reload/reprovision. There is no silent in-place policy repair.
+
 ```sh
 warpmetal runtime enable --server <serverId> [--idempotency-key <key>] --json
 warpmetal runtime get --server <serverId> [--wait] [--timeout-seconds <n>] --json
@@ -232,6 +250,11 @@ warpmetal sandbox action \
   [--wait] --json
 warpmetal sandbox delete \
   --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json
+
+warpmetal tools list --server <serverId> --json
+warpmetal tools install --server <serverId> --sandbox <sandboxId> --profile <profileId> \
+  [--idempotency-key <key>] [--wait] [--timeout-seconds <n>] --json
+warpmetal tools status --server <serverId> [--wait] [--timeout-seconds <n>] --json
 ```
 
 CLI 0.8.8 manages owner-facing VPS host trust during `runtime install`. With no
@@ -245,7 +268,52 @@ reloads never replace trust. This TOFU step cannot detect an active attacker on
 the first connection. Provider-console pre-enrollment is optional and stronger.
 
 See [runtime.md](runtime.md) for capacity, lifetime, cleanup, polling, and
-installation safety. Exit 8 means accepted or pending, never applied.
+installation safety. Exit 8 is reserved for an actual bounded `--wait`
+deadline timeout; a successful non-wait inspection exits 0 while reporting an
+accepted, pending, applying, ready, or empty current state.
+
+The `tools` commands use only the owner token already stored for the named
+server. They do not accept token argv or `--token-file`. `tools list` returns
+the registered immutable profiles. `tools install` sends only `{profileId}`
+with an idempotency key; callers cannot supply download URLs, shell commands,
+argv, environment variables, or artifacts. With `--wait`, `ready` exits 0,
+`failed` or `cancelled` exits 5, and a bounded timeout exits 8. JSON contains
+only the public profile/setup-operation fields returned by WarpMetal.
+
+Codex is a released automatic tool profile when the public
+`/agent-tool-profiles` endpoint advertises it as `available`. WarpMetal installs
+the exact registered artifacts when selected at order time or through
+`tools install`. Claude Code uses the released `claude-code` automatic tool
+profile under the same public availability gate. Claude Managed Agents are separate:
+`claude-managed-ant` is an install-only CLI profile. Installing `ant` does not
+authenticate a worker and does not activate Managed Agents. Cursor CLI remains
+manual and unavailable as an automatic profile until separately qualified later.
+Gemini CLI remains manual.
+
+For order-time setup, the runtime JSON file may contain the exact optional
+shape below in addition to `sandboxes`:
+
+```json
+{
+  "sandboxes": [
+    { "name": "codex-worker", "size": "small" },
+    { "name": "claude-worker", "size": "small" },
+    { "name": "managed-worker", "size": "small" }
+  ],
+  "setup": {
+    "version": 1,
+    "sandboxProfiles": [
+      { "sandboxName": "codex-worker", "profileId": "codex" },
+      { "sandboxName": "claude-worker", "profileId": "claude-code" },
+      { "sandboxName": "managed-worker", "profileId": "claude-managed-ant" }
+    ]
+  }
+}
+```
+
+Every selection must reference a sandbox name in the same file. Unknown fields,
+including URL, shell, command, argv, environment, or artifact overrides, are
+rejected before an API request.
 
 ## Per-agent access
 
@@ -277,7 +345,7 @@ returns the OpenSSH or remote exit status. `--connection-file` on grant
 creation requires `--wait`.
 `sandbox access refresh` atomically replaces a stale token-free profile with
 the currently applied grant and API-reported pinned host keys; use it after an
-OS reload and supervisor reinstall.
+OS reload once automatic Runtime reconciliation is ready.
 
 `sandbox access install-ssh` is local-only and requires CLI 0.8.10 or newer.
 It turns the reviewed profile and sandbox-private identity into a concrete
@@ -304,9 +372,16 @@ ssh -t <alias> gemini
 ssh <alias> gemini -p '<task>'
 ```
 
-Install and authenticate Codex, Claude Code, Cursor CLI, or Gemini CLI inside
-the sandbox first. WarpMetal does not install, authenticate, configure, or
-receive credentials for those tools.
+Authenticate each selected provider tool inside the sandbox after setup is
+ready. The public `/agent-tool-profiles` response is authoritative for
+availability and checkout selection. Claude Code uses the `claude-code`
+automatic tool profile. Claude Managed Agents are
+separate: `claude-managed-ant` is an install-only CLI profile. Installing `ant`
+does not authenticate a worker and does not activate Managed Agents. Cursor CLI
+remains manual and unavailable as an automatic profile until separately
+qualified later. Install and authenticate Cursor CLI or Gemini CLI inside the
+sandbox. WarpMetal does not perform provider login or receive provider
+credentials.
 
 [Codex Desktop](https://learn.chatgpt.com/docs/remote-connections) reads
 the concrete alias from `~/.ssh/config` and starts Codex through the sandbox
@@ -330,6 +405,9 @@ warpmetal agent install --target <codex|claude|all> [--scope user|project]
 warpmetal state list --json
 ```
 
+`warpmetal agent install` installs only the bundled WarpMetal skill; it does
+not install sandbox tools or select a sandbox tool profile.
+
 `state list` returns identifiers, public runtime metadata, and
 credential-presence booleans only. Never
 open the underlying state file from an agent session.

package/skills/warpmetal/references/runtime.md

@@ -46,6 +46,20 @@ Pass it to `warpmetal order prepare --runtime-file <path>`. If it contains a
 temporary sandbox, pass `--confirm TEMPORARY`. Preparing remains unpaid; keep
 the existing separate interactive-or-autonomous payment authority check.
 
+For released Codex and Claude Code automatic profiles, an agent-enabled first
+boot passes a closed nested-sandbox opt-in through verified
+provider cloud-init. The signed Runtime bundle owns the exact-path AppArmor
+policy for the neutral image's immutable Bubblewrap helper. No later customer
+SSH key is used. No public order field or CLI flag exists; VPS-only cloud-init
+remains unchanged. Existing enrolled hosts require reload/reprovision for this policy
+because no silent in-place repair command is claimed.
+Runtime does not report a new or replaced sandbox generation as running until a
+fixed, credential-free inner-Bubblewrap oracle proves nested namespaces, an
+inherited read-only view of the outer Agent Box's already isolated procfs, an
+allowed workspace write, empty Linux capability sets, `no-new-privileges`, and
+protected-root write denial; failure stops the container before access grants
+or tool setup advance.
+
 For an existing ready server:
 
 Use the WarpMetal owner account `root` for every supported host image; do not
@@ -208,11 +222,12 @@ The token-free profile is written only after the grant is `applied` and the
 API supplies verified VPS host keys. Do not print or open that profile in an
 agent conversation.
 
-After a destructive OS reload, reinstall the supervisor and wait for the
-retained active grant to become `applied`, then replace its stale pinned
-profile:
+After a successful destructive OS reload, the signed Runtime bootstrap runs
+automatically. Wait for Runtime readiness and for the retained active grant to
+become `applied`, then replace its stale pinned profile:
 
 ```sh
+warpmetal runtime get --server <serverId> --wait --json
 warpmetal sandbox access refresh \
   --server <serverId> \
   --sandbox <sandboxId> \
@@ -225,7 +240,8 @@ warpmetal sandbox access refresh \
 
 The sandbox record is retained, but its old workspace is not; reconciliation
 creates a new empty workspace. Never bypass a host-key mismatch or reuse the
-pre-reload profile.
+pre-reload profile. Use manual Runtime installation only as an explicitly
+approved repair when the backend reports that automatic setup failed.
 
 ### Install a concrete OpenSSH alias
 
@@ -298,10 +314,15 @@ ssh -t <alias> gemini
 ssh <alias> gemini -p '<task>'
 ```
 
-Install and authenticate Codex, Claude Code, Cursor CLI, or Gemini CLI inside
-the sandbox first. Provider authentication and credentials are sandbox-owned
-and persist only in the sandbox home. WarpMetal does not install, authenticate,
-configure, or receive credentials for those tools.
+Authenticate each selected provider tool inside the sandbox after setup is
+ready. The public `/agent-tool-profiles` endpoint is authoritative for profile
+availability. Claude Code uses the released `claude-code` automatic tool
+profile. Claude Managed Agents are separate: `claude-managed-ant` is an
+install-only CLI profile. Installing `ant` does not authenticate a worker and
+does not activate Managed Agents. Cursor CLI remains manual and unavailable as
+an automatic profile until separately qualified later. Provider authentication
+and credentials are sandbox-owned and persist only in the sandbox home;
+WarpMetal does not perform provider login or receive those credentials.
 
 [Codex Desktop](https://learn.chatgpt.com/docs/remote-connections)
 discovers a concrete alias through `~/.ssh/config`, requires ordinary

package/skills/warpmetal/references/safety.md

@@ -95,9 +95,10 @@ A reload requires both `confirm: "ERASE"` and `powerOffFirst: true`. Treat
 server, wait until it is powered off, and then erase and reinstall it inside
 one lifecycle operation. When Agent Runtime is enabled, also require
 `acknowledgeAgentRuntimeReset`: all sandbox workspaces are permanently erased,
-the supervisor identity is revoked, desired sandboxes are recreated empty
-after reinstall, and all pinned profiles require refresh. Use only the guarded
-CLI command and stop on `manual_review`. Reload invalidates the prior
+the supervisor identity is revoked, signed Runtime setup runs automatically,
+desired sandboxes are recreated empty, and all pinned profiles require refresh.
+Use only the guarded CLI command, wait for Runtime readiness, and stop on
+`manual_review`. Reload invalidates the prior
 owner-facing SSH host-key trust decision; the provider may rotate or preserve
 the key. CLI 0.8.8 opens one new managed trust epoch only after the exact local
 reload operation succeeds and reports that refresh is required. The first

package/src/api.js

@@ -346,6 +346,36 @@ export class WarpMetalClient {
     );
   }
 
+  listAgentToolProfiles(token) {
+    return this.request("GET", "/agent-tool-profiles", { token });
+  }
+
+  installAgentToolProfile(
+    serverId,
+    sandboxId,
+    profileId,
+    token,
+    idempotencyKey,
+  ) {
+    return this.request(
+      "POST",
+      `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/tool-setup-operations`,
+      {
+        body: { profileId },
+        token,
+        idempotencyKey,
+      },
+    );
+  }
+
+  getAgentSetup(serverId, token) {
+    return this.request(
+      "GET",
+      `/servers/${encodeURIComponent(serverId)}/agent-setup`,
+      { token },
+    );
+  }
+
   sandboxAction(serverId, sandboxId, action, token, idempotencyKey) {
     const body =
       action === "refresh_image"

package/src/cli.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 
 import {
@@ -67,6 +68,7 @@ const SANDBOX_TERMINAL_STATES = new Set([
   "failed",
 ]);
 const GRANT_TERMINAL_STATES = new Set(["applied", "revoked", "failed"]);
+const TOOL_SETUP_TERMINAL_STATES = new Set(["ready", "failed", "cancelled"]);
 const COMMON_OPTIONS = ["base-url", "json", "state-dir", "help"];
 
 const HELP = `WarpMetal CLI ${VERSION}
@@ -127,6 +129,10 @@ Usage:
     --alias <alias> [--confirm REFRESH]
   warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE
   warpmetal sandbox connect --connection-file <path> --identity <sandbox-key> [-- <command>]
+  warpmetal tools list --server <serverId>
+  warpmetal tools install --server <serverId> --sandbox <sandboxId> --profile <profileId>
+    [--idempotency-key <key>] [--wait] [--timeout-seconds <n>]
+  warpmetal tools status --server <serverId> [--wait] [--timeout-seconds <n>]
   warpmetal state list
   warpmetal agent install --target <codex|claude|all> [--scope <user|project>] [--force]
 
@@ -147,6 +153,34 @@ SSH host trust (CLI 0.8.8+):
   active attacker on the first connection. Provider-console pre-enrollment is
   the optional higher-assurance alternative.
 
+Runtime-enabled reloads:
+  Reload still requires --acknowledge-agent-runtime-reset because every
+  sandbox workspace is erased. After a successful reload, Runtime setup is
+  automatic: use warpmetal runtime get --server <serverId> --wait --json,
+  then refresh every sandbox connection profile before reconnecting. The
+  successful operation also records a new owner SSH trust epoch; verify the
+  replacement host key before owner SSH.
+  Agent-enabled first boot and reload also activate the signed Runtime's exact
+  immutable-Bubblewrap host policy through verified cloud-init. There is no
+  public nested-sandbox order field or runtime-install flag, and VPS-only
+  cloud-init is unchanged. Existing enrolled hosts use reload/reprovision;
+  no silent in-place policy repair is claimed.
+
+Sandbox tool profiles:
+  Codex is a released automatic tool profile when the public
+  /agent-tool-profiles endpoint advertises it as available. WarpMetal installs
+  the exact registered artifacts when selected at order time or with tools
+  install. Claude Code uses the released claude-code automatic tool profile
+  under the same public availability gate. Claude Managed Agents are separate: claude-managed-ant
+  is an install-only CLI profile. Installing ant does not authenticate a worker
+  and does not activate Managed Agents. Cursor CLI remains manual and unavailable
+  as an automatic profile until separately qualified later. Gemini CLI remains manual. Successful
+  non-wait installs and status inspections exit 0; exit 8 is reserved for an
+  actual --wait deadline timeout.
+
+  warpmetal agent install installs only the bundled WarpMetal skill; it does not
+  install sandbox tools or change a sandbox tool profile.
+
 Sandbox SSH aliases:
   Refresh the authenticated connection profile before refreshing an existing
   alias:
@@ -168,9 +202,16 @@ Sandbox SSH aliases:
     ssh -t <alias> gemini
     ssh <alias> gemini -p "<prompt>"
 
-  Install and authenticate Codex, Claude Code, Cursor CLI, or Gemini CLI inside
-  the sandbox first. WarpMetal does not install, authenticate, configure, or
-  receive credentials for those tools.
+  Authenticate Codex or Claude Code inside the sandbox after the selected
+  profile is ready. The public /agent-tool-profiles response is authoritative
+  for availability and checkout selection. The Claude Code automatic profile
+  ID is claude-code. Claude Managed Agents are separate:
+  claude-managed-ant is an install-only CLI profile. Installing ant does not
+  authenticate a worker and does not activate Managed Agents. Cursor CLI remains
+  manual and unavailable as an automatic profile until separately qualified later.
+  Install and authenticate Cursor CLI or Gemini CLI inside the sandbox.
+  WarpMetal never receives provider credentials; authentication remains inside
+  the sandbox.
 
   Codex Desktop discovers the concrete alias through ~/.ssh/config and opens
   the sandbox login shell, so Codex must be available on the login-shell PATH.
@@ -370,6 +411,17 @@ async function requireReloadToken(store, serverId, options, env) {
   return token;
 }
 
+async function requireStoredOwnerToken(store, serverId) {
+  const token = (await store.server(serverId))?.ownerToken;
+  if (!token) {
+    throw new CliError(
+      `No stored owner credential is available for ${serverId}. Restore the private state file created for that server.`,
+      { exitCode: 4 },
+    );
+  }
+  return token;
+}
+
 function safePreparedOrder(data, stateFile) {
   return {
     task: data.task,
@@ -432,6 +484,94 @@ async function pollRuntime(client, serverId, token, timeoutSeconds) {
   }
 }
 
+function toolSetupOutcome(result) {
+  const operations = result.data?.setupOperations || [];
+  if (operations.some((operation) => ["failed", "cancelled"].includes(operation.state))) {
+    return 5;
+  }
+  return 0;
+}
+
+function publicToolSetupOperation(operation) {
+  if (!operation || typeof operation !== "object" || Array.isArray(operation)) {
+    return {};
+  }
+  return Object.fromEntries(
+    [
+      "id",
+      "sandboxId",
+      "sandboxGeneration",
+      "profileId",
+      "profileRevision",
+      "profileDigest",
+      "state",
+      "receiptDigest",
+      "errorCode",
+    ]
+      .filter((field) => Object.hasOwn(operation, field))
+      .map((field) => [field, operation[field]]),
+  );
+}
+
+function publicToolSetupData(data) {
+  if (Array.isArray(data?.setupOperations)) {
+    return {
+      setupOperations: data.setupOperations.map(publicToolSetupOperation),
+    };
+  }
+  return { setupOperation: publicToolSetupOperation(data?.setupOperation) };
+}
+
+function publicAgentToolProfiles(data) {
+  return {
+    profiles: Array.isArray(data?.profiles)
+      ? data.profiles.map((profile) =>
+          profile && typeof profile === "object" && !Array.isArray(profile)
+            ? Object.fromEntries(
+                [
+                  "id",
+                  "displayName",
+                  "revision",
+                  "digest",
+                  "platform",
+                  "mode",
+                  "availability",
+                  "checkoutSelectable",
+                ]
+                  .filter((field) => Object.hasOwn(profile, field))
+                  .map((field) => [field, profile[field]]),
+              )
+            : {},
+        )
+      : [],
+  };
+}
+
+async function pollToolSetup(client, serverId, token, timeoutSeconds, operationId) {
+  const deadline = timeoutDeadline(timeoutSeconds);
+  while (true) {
+    const result = await client.getAgentSetup(serverId, token);
+    const operations = result.data?.setupOperations || [];
+    const selected = operationId
+      ? operations.filter((operation) => operation.id === operationId)
+      : operations;
+    const terminal = selected.every((operation) =>
+      TOOL_SETUP_TERMINAL_STATES.has(operation.state),
+    );
+    if ((operationId ? selected.length > 0 : true) && terminal) {
+      return operationId
+        ? { ...result, data: { setupOperation: selected[0] } }
+        : result;
+    }
+    ensureBeforeDeadline(deadline, `Tool setup for ${serverId}`);
+    const seconds = suggestedDelay(result);
+    const remainingMs = deadline - Date.now();
+    await new Promise((resolveDelay) =>
+      setTimeout(resolveDelay, Math.min(seconds * 1_000, Math.max(0, remainingMs))),
+    );
+  }
+}
+
 async function pollSandbox(
   client,
   serverId,
@@ -771,9 +911,12 @@ async function handlePrepareOrder(client, store, options, context) {
   }
   const email = stringOption(options, "email");
   const runtimeFile = stringOption(options, "runtime-file");
-  const sandboxes = runtimeFile
+  const runtimeIntent = runtimeFile
     ? await readSandboxFile(runtimeFile)
     : undefined;
+  const sandboxes = Array.isArray(runtimeIntent)
+    ? runtimeIntent
+    : runtimeIntent?.sandboxes;
   if (sandboxes) {
     requireTemporaryConfirmation(sandboxes, stringOption(options, "confirm"));
   }
@@ -819,7 +962,11 @@ async function handlePrepareOrder(client, store, options, context) {
     sshKeyLabel: selected.identity.keyName,
   };
   if (email) request.email = email;
-  if (sandboxes) request.agentRuntime = { sandboxes };
+  if (runtimeIntent) {
+    request.agentRuntime = Array.isArray(runtimeIntent)
+      ? { sandboxes: runtimeIntent }
+      : runtimeIntent;
+  }
   const key =
     stringOption(options, "idempotency-key") || idempotencyKey("order");
   const response = await client.prepareOrder(request, key);
@@ -830,7 +977,7 @@ async function handlePrepareOrder(client, store, options, context) {
     selected.identity.identityId,
   );
   const safe = safePreparedOrder(response.data, store.path);
-  if (sandboxes) {
+  if (runtimeIntent) {
     safe.agentRuntimeIntent = {
       sandboxes: sandboxes.map((sandbox) => ({
         name: sandbox.name,
@@ -839,6 +986,9 @@ async function handlePrepareOrder(client, store, options, context) {
         expiresInSeconds: sandbox.expiresInSeconds,
       })),
     };
+    if (!Array.isArray(runtimeIntent)) {
+      safe.agentRuntimeIntent.setup = runtimeIntent.setup;
+    }
   }
   emit(
     context.stdout,
@@ -1995,7 +2145,7 @@ async function applyReloadResult(
   await store.invalidateServerAccess(serverId);
   if (operation.result?.reloadImpact?.agentRuntimeAffected) {
     await store.saveRuntime(serverId, {
-      state: "needs_reinstall",
+      state: "pending_install",
       desiredRevision: undefined,
       appliedRevision: 0,
       lastSeenAt: null,
@@ -2103,8 +2253,8 @@ async function handleServerReload(client, store, options, context) {
       (operation?.state === "succeeded" &&
       operation.result?.reloadImpact?.ownerKnownHostsNeedRefresh
         ? operation.result?.reloadImpact?.agentRuntimeAffected
-          ? " The next Runtime install will establish the operation-bound owner SSH trust epoch, then reinstall Agent Runtime and refresh every sandbox connection profile."
-          : " The next Runtime install will establish the operation-bound owner SSH trust epoch before reconnecting."
+          ? " Agent Runtime setup is automatic. Wait for Agent Runtime to become ready, then refresh every sandbox connection profile. Verify the replacement host key before owner SSH."
+          : " Verify the replacement host key before owner SSH; the successful reload recorded a new operation-bound trust epoch."
         : operation?.state === "succeeded"
           ? " WarpMetal did not report a host-key refresh; the existing managed pin remains required."
           : ""),
@@ -2753,7 +2903,7 @@ async function handleAccessInstallSsh(options, context) {
     alias: stringOption(options, "alias", { required: true }),
     connectionFile: stringOption(options, "connection-file", { required: true }),
     identity: stringOption(options, "identity", { required: true }),
-    homeDirectory: context.env.HOME,
+    homeDirectory: context.env.HOME || context.env.USERPROFILE || homedir(),
     confirm: stringOption(options, "confirm"),
   });
   emit(
@@ -2768,7 +2918,7 @@ async function handleAccessInstallSsh(options, context) {
 async function handleAccessRemoveSsh(options, context) {
   const result = await removeSshAlias({
     alias: stringOption(options, "alias", { required: true }),
-    homeDirectory: context.env.HOME,
+    homeDirectory: context.env.HOME || context.env.USERPROFILE || homedir(),
     confirm: stringOption(options, "confirm", { required: true }),
   });
   emit(
@@ -2780,6 +2930,82 @@ async function handleAccessRemoveSsh(options, context) {
   return 0;
 }
 
+async function handleToolsList(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const token = await requireStoredOwnerToken(store, serverId);
+  const result = await client.listAgentToolProfiles(token);
+  const output = publicAgentToolProfiles(result.data);
+  emit(
+    context.stdout,
+    output,
+    context.json,
+    output.profiles
+      .map((profile) => `${profile.id} revision ${profile.revision}`)
+      .join("\n"),
+  );
+  return 0;
+}
+
+async function handleToolsInstall(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const sandboxId = stringOption(options, "sandbox", { required: true });
+  const profileId = stringOption(options, "profile", { required: true });
+  const token = await requireStoredOwnerToken(store, serverId);
+  const key =
+    stringOption(options, "idempotency-key") || idempotencyKey("tools-install");
+  let result = await client.installAgentToolProfile(
+    serverId,
+    sandboxId,
+    profileId,
+    token,
+    key,
+  );
+  const wait = booleanOption(options, "wait");
+  if (wait) {
+    result = await pollToolSetup(
+      client,
+      serverId,
+      token,
+      integerOption(options, "timeout-seconds", 900),
+      result.data?.setupOperation?.id,
+    );
+  }
+  const output = publicToolSetupData(result.data);
+  const operation = output.setupOperation;
+  emit(
+    context.stdout,
+    output,
+    context.json,
+    `Tool setup ${operation?.id || "requested"}: ${operation?.state || "pending"}.`,
+  );
+  if (["failed", "cancelled"].includes(operation?.state)) return 5;
+  if (!wait) return 0;
+  return operation?.state === "ready" ? 0 : 5;
+}
+
+async function handleToolsStatus(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const token = await requireStoredOwnerToken(store, serverId);
+  const result = booleanOption(options, "wait")
+    ? await pollToolSetup(
+        client,
+        serverId,
+        token,
+        integerOption(options, "timeout-seconds", 900),
+      )
+    : await client.getAgentSetup(serverId, token);
+  const output = publicToolSetupData(result.data);
+  emit(
+    context.stdout,
+    output,
+    context.json,
+    output.setupOperations
+      .map((operation) => `${operation.id}: ${operation.state}`)
+      .join("\n"),
+  );
+  return toolSetupOutcome({ ...result, data: output });
+}
+
 async function dispatch(positionals, options, passthrough, context) {
   const command = positionals.join(" ");
   if (passthrough.length > 0 && command !== "sandbox connect") {
@@ -3233,6 +3459,28 @@ async function dispatch(positionals, options, passthrough, context) {
     case "sandbox connect":
       rejectUnknownOptions(options, ["connection-file", "identity", "help"]);
       return handleSandboxConnect(options, passthrough, context);
+    case "tools list":
+      rejectUnknownOptions(options, [...COMMON_OPTIONS, "server"]);
+      return handleToolsList(client, store, options, context);
+    case "tools install":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "sandbox",
+        "profile",
+        "idempotency-key",
+        "wait",
+        "timeout-seconds",
+      ]);
+      return handleToolsInstall(client, store, options, context);
+    case "tools status":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "wait",
+        "timeout-seconds",
+      ]);
+      return handleToolsStatus(client, store, options, context);
     case "state list": {
       rejectUnknownOptions(options, COMMON_OPTIONS);
       const summary = await store.summary();

package/src/runtime.js

@@ -15,6 +15,9 @@ const SANDBOX_FIELDS = new Set([
   "lifetime",
   "expiresInSeconds",
 ]);
+const RUNTIME_FIELDS = new Set(["sandboxes", "setup"]);
+const SETUP_FIELDS = new Set(["version", "sandboxProfiles"]);
+const SANDBOX_PROFILE_FIELDS = new Set(["sandboxName", "profileId"]);
 
 function exactFields(value, allowed, label) {
   const unknown = Object.keys(value).find((field) => !allowed.has(field));
@@ -113,8 +116,62 @@ export async function readSandboxFile(path) {
       exitCode: 2,
     });
   }
-  exactFields(document, new Set(["sandboxes"]), "The sandbox JSON file");
-  return validateSandboxBatch(document.sandboxes);
+  exactFields(document, RUNTIME_FIELDS, "The sandbox JSON file");
+  const sandboxes = validateSandboxBatch(document.sandboxes);
+  if (document.setup === undefined) return sandboxes;
+  const setup = document.setup;
+  if (!setup || typeof setup !== "object" || Array.isArray(setup)) {
+    throw new CliError("setup must be a JSON object.", { exitCode: 2 });
+  }
+  exactFields(setup, SETUP_FIELDS, "setup");
+  if (setup.version !== 1) {
+    throw new CliError("setup.version must be 1.", { exitCode: 2 });
+  }
+  if (
+    !Array.isArray(setup.sandboxProfiles) ||
+    setup.sandboxProfiles.length < 1 ||
+    setup.sandboxProfiles.length > 32
+  ) {
+    throw new CliError(
+      "setup.sandboxProfiles must contain between 1 and 32 entries.",
+      { exitCode: 2 },
+    );
+  }
+  const sandboxNames = new Set(sandboxes.map((sandbox) => sandbox.name));
+  const selectedNames = new Set();
+  const sandboxProfiles = setup.sandboxProfiles.map((input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      throw new CliError("Every setup profile selection must be a JSON object.", {
+        exitCode: 2,
+      });
+    }
+    exactFields(input, SANDBOX_PROFILE_FIELDS, "A setup profile selection");
+    if (typeof input.sandboxName !== "string" || !NAME.test(input.sandboxName)) {
+      throw new CliError("setup sandbox names must use lowercase identifiers.", {
+        exitCode: 2,
+      });
+    }
+    if (typeof input.profileId !== "string" || !NAME.test(input.profileId)) {
+      throw new CliError("setup profile IDs must use lowercase identifiers.", {
+        exitCode: 2,
+      });
+    }
+    if (!sandboxNames.has(input.sandboxName)) {
+      throw new CliError(
+        `setup references an unknown sandbox: ${input.sandboxName}`,
+        { exitCode: 2 },
+      );
+    }
+    if (selectedNames.has(input.sandboxName)) {
+      throw new CliError(
+        `setup selects the sandbox more than once: ${input.sandboxName}`,
+        { exitCode: 2 },
+      );
+    }
+    selectedNames.add(input.sandboxName);
+    return { sandboxName: input.sandboxName, profileId: input.profileId };
+  });
+  return { sandboxes, setup: { version: 1, sandboxProfiles } };
 }
 
 export function containsTemporary(sandboxes) {

package/src/ssh-alias.js

@@ -10,7 +10,7 @@ import {
   rmdir,
   unlink,
 } from "node:fs/promises";
-import { isAbsolute, join, parse, resolve } from "node:path";
+import { isAbsolute, join, parse, posix, resolve, win32 } from "node:path";
 import { randomUUID } from "node:crypto";
 
 import {
@@ -21,7 +21,8 @@ import {
 import { CliError } from "./errors.js";
 
 const ALIAS_PATTERN = /^(?=.{1,63}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-const UNSAFE_PATH = /[\0\r\n\t%"'`$!&;<>|*?()[\]{}\\#]/;
+const POSIX_UNSAFE_PATH = /[\0\r\n\t%"'`$!&;<>|*?()[\]{}\\#]/;
+const WINDOWS_UNSAFE_PATH = /[\0\r\n\t%"'`$!&;<>|*?()[\]{}#]/;
 const MANAGED_HEADER = "# Managed by WarpMetal. Do not edit.";
 
 function invalid(message) {
@@ -37,17 +38,18 @@ export function validateSshAlias(value) {
   return value;
 }
 
-function validateAbsolutePath(value, label) {
-  if (
-    typeof value !== "string" ||
-    !isAbsolute(value) ||
-    resolve(value) !== value ||
-    value === parse(value).root ||
-    UNSAFE_PATH.test(value)
-  ) {
+export function validateAbsolutePath(value, label, platform = process.platform) {
+  const path = platform === "win32" ? win32 : posix;
+  if (typeof value !== "string" || !path.isAbsolute(value)) {
     invalid(`${label} must be an absolute path without unsafe interpolation characters.`);
   }
-  return value;
+  const resolved = path.resolve(value);
+  const unsafePath =
+    platform === "win32" ? WINDOWS_UNSAFE_PATH : POSIX_UNSAFE_PATH;
+  if (resolved === path.parse(resolved).root || unsafePath.test(resolved)) {
+    invalid(`${label} must be an absolute path without unsafe interpolation characters.`);
+  }
+  return resolved;
 }
 
 function requireOwner(metadata, label) {
@@ -420,12 +422,19 @@ async function syncDirectory(path) {
     handle = await open(path, "r");
     await handle.sync();
   } catch (error) {
-    if (!["EINVAL", "ENOTSUP", "EISDIR"].includes(error?.code)) throw error;
+    if (!isIgnorableDirectorySyncError(error)) throw error;
   } finally {
     await handle?.close().catch(() => {});
   }
 }
 
+export function isIgnorableDirectorySyncError(error, platform = process.platform) {
+  return (
+    ["EINVAL", "ENOTSUP", "EISDIR"].includes(error?.code) ||
+    (platform === "win32" && ["EPERM", "EACCES"].includes(error?.code))
+  );
+}
+
 async function commitStaged(staged) {
   try {
     for (const item of staged) {