warpmetal 0.8.12 → 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`:
 
@@ -340,6 +344,19 @@ compatible external signer.
   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:
@@ -387,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
@@ -410,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.12",
+  "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`.

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

@@ -221,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
@@ -243,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
@@ -256,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
 
@@ -315,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
@@ -341,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
@@ -300,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/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

@@ -68,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}
@@ -128,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]
 
@@ -155,6 +160,26 @@ Runtime-enabled reloads:
   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
@@ -177,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.
@@ -379,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,
@@ -441,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,
@@ -780,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"));
   }
@@ -828,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);
@@ -839,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,
@@ -848,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,
@@ -2789,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") {
@@ -3242,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) {