warpmetal 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,8 @@ The official command-line client and portable Agent Skill for WarpMetal.
 
 The CLI uses the public API at `https://api.warpmetal.com`, stores generated
 WarpMetal credentials in a user-private state file, and never reads or stores
-wallet private keys or SSH private-key contents.
+wallet private keys or SSH private-key contents. Version 0.2 adds the optional
+Agent Runtime workflow for fixed-size, isolated sandboxes on one owner's VPS.
 
 ## Distribution
 
@@ -68,8 +69,44 @@ alternate state directory.
   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. Signed supervisor bundles
+  are checksum- and signature-verified before OpenSSH uploads them.
+- 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.
+- Sandboxes use the fixed runtime image and fixed sizes. Persistent is the
+  default; temporary sandboxes require explicit confirmation and permanently
+  delete their workspace after 15 minutes to 24 hours.
 
-## Publishing status
+## Agent Runtime example
 
-This package is an initial development release. Choose the public-source
-license and replace `UNLICENSED` before publishing it to npm.
+```sh
+warpmetal runtime enable --server <serverId> --json
+warpmetal runtime install \
+  --server <serverId> \
+  --identity ~/.ssh/warpmetal-owner \
+  --ssh-user ubuntu \
+  --confirm INSTALL \
+  --wait \
+  --json
+warpmetal sandbox create \
+  --server <serverId> \
+  --name planner \
+  --size small \
+  --wait \
+  --json
+warpmetal sandbox access keygen \
+  --output ~/.ssh/warpmetal-planner \
+  --confirm GENERATE \
+  --json
+```
+
+See `skills/warpmetal/references/runtime.md` for the complete lifecycle,
+cleanup, access-grant, and strict host-key connection workflow.
+
+## Release status
+
+The initial development release is published at
+`https://www.npmjs.com/package/warpmetal`. The source is publicly visible but
+remains `UNLICENSED`; choose an explicit license before describing the project
+as open source or inviting third-party reuse.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "warpmetal",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent-safe CLI and skill for purchasing and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {
-    "warpmetal": "./bin/warpmetal.js"
+    "warpmetal": "bin/warpmetal.js"
   },
   "files": [
     "bin/",
@@ -16,7 +16,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/ssh.js && node --check src/state.js",
+    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
     "test": "node --test",
     "prepack": "npm run check && npm test"
   },

package/skills/warpmetal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warpmetal
-description: Safely purchase and manage WarpMetal VPS servers with the warpmetal CLI. Use when Codex, Claude Code, Cursor, Windsurf, or another shell-capable agent needs to inspect live VPS plans and operating systems, prepare or pay for an x402 order, poll provisioning, prove ownership with an SSH key, inspect a server, or run supported lifecycle operations.
+description: Safely purchase and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI. Use when a shell-capable agent needs live VPS discovery, x402 ordering, provisioning, server management, optional runtime installation, fixed-size sandbox creation, persistent or temporary lifetime, per-agent SSH access, sandbox connection, access revocation, or workspace deletion.
 ---
 
 # WarpMetal
@@ -19,6 +19,8 @@ with ad hoc HTTP commands.
    authorizing payment, using an SSH identity, or changing a server.
 5. Read [references/cli-reference.md](references/cli-reference.md) when choosing
    a command or interpreting an exit code.
+6. Read [references/runtime.md](references/runtime.md) before requesting,
+   installing, accessing, expiring, or deleting Agent Runtime sandboxes.
 
 Never read, print, summarize, upload, or commit the WarpMetal state file. Never
 read an SSH private-key file. Pass its path only to a command designed to use
@@ -109,3 +111,27 @@ warpmetal server power \
 Do not fall back to raw API calls for reload, deletion, networking, renewal,
 or another unsupported mutation. Explain that the installed CLI version does
 not yet expose that guarded operation.
+
+## Use Agent Runtime
+
+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`.
+
+Omitted lifetime means persistent. A temporary sandbox requires
+`--confirm TEMPORARY`, expires 15 minutes to 24 hours after first reaching
+running, and permanently deletes its workspace at expiry. Never describe a
+pending HTTP 202 response as applied; poll runtime, sandbox, and grant state.
+
+Every agent must use a distinct sandbox-specific SSH key. Ask before key
+generation, create one access grant for one sandbox, wait for `applied` plus
+pinned host keys, then connect only through `warpmetal sandbox connect`.
+Never give an agent the owner host key, owner token, SSH-derived management
+token, runtime bootstrap, or node token.
+
+If the installed CLI lacks a required runtime command, stop, explain the
+version limitation, and ask before upgrading the official npm package. Do not
+reconstruct runtime changes with raw HTTP, ad hoc SSH, Podman, Docker, or host
+configuration commands.

package/skills/warpmetal/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "WarpMetal VPS"
-  short_description: "Purchase and manage WarpMetal VPS servers"
-  default_prompt: "Use $warpmetal to choose, purchase, and manage a WarpMetal VPS safely."
+  short_description: "Manage WarpMetal VPS and agent sandboxes safely"
+  default_prompt: "Use $warpmetal to provision a VPS and manage isolated agent sandboxes safely."

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

@@ -5,6 +5,8 @@
 - Discovery
 - Purchase and provisioning
 - Server management
+- Agent Runtime and sandboxes
+- Per-agent access
 - Skill installation and state
 - Exit codes
 
@@ -26,6 +28,7 @@ warpmetal order prepare \
   --hostname <dns-label> \
   --os '<exact live OS name>' \
   --ssh-public-key-file <path> \
+  [--runtime-file <runtime.json>] [--confirm TEMPORARY] \
   [--email <address>] \
   [--idempotency-key <key>] \
   --json
@@ -77,6 +80,56 @@ Use `--token-file` only for recovery when local state is unavailable. Prefer
 shell argument, because command-line arguments can be recorded in history and
 process listings.
 
+## Agent Runtime and sandboxes
+
+```sh
+warpmetal runtime enable --server <serverId> [--idempotency-key <key>] --json
+warpmetal runtime get --server <serverId> [--wait] [--timeout-seconds <n>] --json
+warpmetal runtime install \
+  --server <serverId> --identity <owner-key> --ssh-user <admin-user> \
+  --confirm INSTALL [--wait] [--timeout-seconds <n>] --json
+
+warpmetal sandbox create \
+  --server <serverId> --name <name> --size <small|medium|large|xlarge> \
+  [--lifetime temporary] [--expires-in-seconds <900-86400>] \
+  [--confirm TEMPORARY] [--wait] [--timeout-seconds <n>] --json
+warpmetal sandbox create --server <serverId> --file <batch.json> \
+  [--confirm TEMPORARY] [--wait] [--timeout-seconds <n>] --json
+warpmetal sandbox list --server <serverId> --json
+warpmetal sandbox get --server <serverId> --sandbox <sandboxId> [--wait] --json
+warpmetal sandbox action \
+  --server <serverId> --sandbox <sandboxId> \
+  --action <start|stop|restart|make_persistent> --confirm <same-action> \
+  [--wait] --json
+warpmetal sandbox delete \
+  --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json
+```
+
+See [runtime.md](runtime.md) for capacity, lifetime, cleanup, polling, and
+installation safety. Exit 8 means accepted or pending, never applied.
+
+## Per-agent access
+
+```sh
+warpmetal sandbox access keygen --output <private-key-path> --confirm GENERATE --json
+warpmetal sandbox access grant \
+  --server <serverId> --sandbox <sandboxId> --name <name> \
+  --ssh-public-key-file <public-key-path> \
+  [--connection-file <profile-path>] [--wait] --json
+warpmetal sandbox access list --server <serverId> --sandbox <sandboxId> --json
+warpmetal sandbox access get \
+  --server <serverId> --sandbox <sandboxId> --grant <grantId> [--wait] --json
+warpmetal sandbox access revoke \
+  --server <serverId> --sandbox <sandboxId> --grant <grantId> \
+  --confirm REVOKE [--wait] --json
+warpmetal sandbox connect --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> [-- <remote-command> <arguments...>]
+```
+
+`sandbox connect` is the only runtime command that does not use `--json`; it
+returns the OpenSSH or remote exit status. `--connection-file` on grant
+creation requires `--wait`.
+
 ## Skill installation and state
 
 ```sh
@@ -84,7 +137,8 @@ warpmetal agent install --target <codex|claude|all> [--scope user|project]
 warpmetal state list --json
 ```
 
-`state list` returns identifiers and credential-presence booleans only. Never
+`state list` returns identifiers, public runtime metadata, and
+credential-presence booleans only. Never
 open the underlying state file from an agent session.
 
 ## Exit codes

package/skills/warpmetal/references/runtime.md

@@ -0,0 +1,194 @@
+# WarpMetal Agent Runtime
+
+## Product boundary
+
+Agent Runtime is optional. One VPS owner uses it to divide that owner's VPS
+among that owner's agents; it is not a multi-customer hosting or billing
+system. VPS price, term, renewal, power, and payment remain unchanged.
+
+All V1 sandboxes use one WarpMetal-pinned image. Callers choose a published
+size, not an arbitrary image, template, command, mount, environment, CPU,
+memory, or disk value.
+
+## Discover capacity and OS support
+
+Run `warpmetal catalog --json`. Use only the selected product's live:
+
+- `agentRuntime.supported`;
+- `agentRuntime.capacity`;
+- `agentRuntime.sizes[]`; and
+- `operatingSystems[].agentRuntimeSupported`.
+
+The API checks admission again and the installed supervisor may reject work
+when actual host capacity is lower. Never assume every size fits every VPS.
+
+## Order-time versus after provisioning
+
+For order-time intent, write a JSON file containing only `sandboxes` and the
+fields `name`, `size`, optional `lifetime`, and optional `expiresInSeconds`:
+
+```json
+{
+  "sandboxes": [
+    { "name": "planner", "size": "small" },
+    { "name": "builder", "size": "medium" },
+    {
+      "name": "reviewer",
+      "size": "small",
+      "lifetime": "temporary",
+      "expiresInSeconds": 14400
+    }
+  ]
+}
+```
+
+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 payment approval.
+
+For an existing ready server:
+
+```sh
+warpmetal runtime enable --server <serverId> --json
+warpmetal runtime install \
+  --server <serverId> \
+  --identity <owner-private-key-path> \
+  --ssh-user <os-admin-user> \
+  --confirm INSTALL \
+  --wait \
+  --json
+warpmetal runtime get --server <serverId> --wait --json
+```
+
+Ask before installation. Pass the owner key path without reading the file.
+The CLI holds the one-time bootstrap only in memory, verifies the signed
+artifact, uploads it through OpenSSH without a shell-enabled local spawn, and
+does not print or store the bootstrap.
+
+## Sizes and lifetime
+
+Use `small`, `medium`, `large`, or `xlarge` exactly as the live catalog
+publishes them. Create one sandbox or an atomic JSON batch:
+
+```sh
+warpmetal sandbox create \
+  --server <serverId> \
+  --name <name> \
+  --size <size> \
+  [--lifetime temporary] \
+  [--expires-in-seconds <900-86400>] \
+  [--confirm TEMPORARY] \
+  --wait \
+  --json
+
+warpmetal sandbox create \
+  --server <serverId> \
+  --file <batch.json> \
+  [--confirm TEMPORARY] \
+  --wait \
+  --json
+```
+
+Lifetime rules:
+
+- Omitted lifetime is persistent and has no automatic deletion.
+- Temporary defaults to 86,400 seconds, with a 900-second minimum and
+  86,400-second maximum.
+- The clock begins on first `running`; restart and stop do not reset or pause
+  it.
+- `expiresAt` is authoritative after first running.
+- Expiry revokes access, terminates sessions, removes the container, and
+  permanently deletes the workspace even during a control-plane outage.
+- Before `expiring`, `make_persistent` removes automatic expiry. V1 cannot
+  extend a temporary duration.
+
+Use `sandbox list`, `sandbox get --wait`, and guarded `sandbox action` commands
+to observe and change desired state. HTTP 202 and CLI exit 8 mean accepted or
+pending, not complete.
+
+Manual deletion is irreversible:
+
+```sh
+warpmetal sandbox delete \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --confirm DELETE \
+  --wait \
+  --json
+```
+
+State the workspace-loss consequence and get approval before running it.
+
+## One key and grant per agent sandbox
+
+The owner host key is never an agent sandbox credential. For each agent and
+sandbox, ask before generating a distinct Ed25519 keypair:
+
+```sh
+warpmetal sandbox access keygen \
+  --output <sandbox-private-key-path> \
+  --confirm GENERATE \
+  --json
+
+warpmetal sandbox access grant \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --name <grant-name> \
+  --ssh-public-key-file <sandbox-public-key-path> \
+  --connection-file <profile-path> \
+  --wait \
+  --json
+```
+
+Only the public key goes to WarpMetal. The private key stays with the agent.
+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.
+
+Connect without an owner management credential:
+
+```sh
+warpmetal sandbox connect \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path>
+
+warpmetal sandbox connect \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  -- <remote-command> <arguments...>
+```
+
+`sandbox connect` is direct SSH transport and does not use `--json`. It pins
+the API-provided host key, disables forwarding, never reads the private key,
+and returns the remote exit status. The forced gateway maps the key to exactly
+one sandbox and cannot start a host shell.
+
+Revoke access with explicit approval:
+
+```sh
+warpmetal sandbox access revoke \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --grant <grantId> \
+  --confirm REVOKE \
+  --wait \
+  --json
+```
+
+Revocation removes new access and terminates tracked active sessions while
+leaving the sandbox itself intact.
+
+## Stop conditions
+
+Stop rather than improvise when:
+
+- the CLI lacks a required runtime command;
+- the live catalog does not support the plan, size, or OS;
+- runtime is `degraded`, `offline`, or `needs_reinstall` and the documented
+  repair is not approved;
+- a sandbox or grant reaches `failed`;
+- pinned host keys are missing or differ;
+- deletion, temporary expiry, key generation, installation, or revocation has
+  not received the required approval; or
+- any command would require raw API, raw Podman/Docker, ad hoc SSH host
+  mutation, the owner key inside a sandbox, or exposure of a credential.

package/skills/warpmetal/references/safety.md

@@ -23,7 +23,12 @@
 - Treat an SSH-derived access token as a short-lived bearer credential. Let
   the CLI store and refresh it.
 - Never read or transmit an SSH private key. Pass only its filesystem path to
-  `warpmetal server login` or `ssh-keygen`.
+  `warpmetal server login`, `warpmetal runtime install`,
+  `warpmetal sandbox connect`, or `ssh-keygen`.
+- Never place the owner SSH key, owner token, management access token, runtime
+  bootstrap, supervisor node token, or state file inside a sandbox.
+- Give each agent a distinct sandbox-specific SSH key and grant. Never reuse
+  the owner host key or one agent key across multiple sandboxes.
 - Never request, read, transmit, or store a wallet seed phrase or private key.
 - Never put a token, payment signature, private key, or state-file content in
   a prompt, URL, log, screenshot, source file, or shell argument.
@@ -33,11 +38,14 @@
 Obtain explicit user approval immediately before:
 
 - installing the CLI or skill;
+- installing or repairing the Agent Runtime supervisor;
 - generating a new SSH key pair;
 - creating or funding a wallet;
 - signing or submitting an x402 payment authorization;
 - booting, rebooting, or shutting down a server; and
-- any destructive reload, deletion, or replacement-key operation.
+- creating a temporary sandbox after explaining its irreversible expiry;
+- revoking a sandbox access grant; and
+- any destructive reload, sandbox deletion, or replacement-key operation.
 
 An order preparation is unpaid but consumes a limited prepared-order slot.
 Confirm the plan, hostname, OS, and public key before preparing it.
@@ -53,3 +61,8 @@ Confirm the plan, hostname, OS, and public key before preparing it.
   mutation.
 - Treat HTTP 202 as accepted or pending, never as proof of success. Poll the
   returned task or operation until a documented terminal state.
+- Temporary sandbox expiry is a local hard deadline. Stop, restart, and
+  control-plane outages do not pause it; expiry permanently deletes the
+  workspace and revokes access.
+- Stop when the installed CLI lacks a runtime command. Do not fall back to raw
+  HTTP, raw Podman/Docker, or ad hoc SSH host mutation.