warpmetal 0.8.8 → 0.8.10

package/README.md

@@ -156,11 +156,15 @@ receipt finality while provisioning or renewal proceeds.
 
 For an interactive initial purchase, `checkout challenge` may also return a
 short-lived `humanCheckout` object. Its `url` and `qrPayload` are the same
-`https://pay.x402api.com/c/...` bearer capability for the exact charge; encode
-that URL as the QR, never the WarpMetal recipient address. The buyer connects
-their own wallet and needs only the advertised USDC/USDT balance because
-x402api sponsors the native gas. This is an alternative to the agent-wallet
-workflow, not a second payment. After browser payment, run the exact
+`https://pay.x402api.com/c/...` bearer capability for the exact charge.
+Present the exact URL as a clickable x402api handoff. If a QR is useful for
+another device, encode only the identical `qrPayload` and explain that
+scanning opens the hosted checkout without authorizing payment. x402api owns
+any wallet selection or wallet-specific opening QR inside that page; never
+synthesize a wallet link or encode the WarpMetal recipient address. The buyer
+needs only the advertised USDC/USDT balance because x402api sponsors the native
+gas. This is an alternative to the agent-wallet workflow, not a second
+payment. After browser payment, run the exact
 `humanCheckout.afterPayment.argv` status command. When the ready result asks
 for `ask_human_for_notification_email`, ask the owner and add the optional
 lifecycle-notification address they provide. Autonomous purchases and renewals
@@ -363,42 +367,79 @@ warpmetal sandbox access keygen \
   --json
 ```
 
-On the first install in a server trust epoch, JSON output includes
-`hostKeyTrust.state: "trusted_first_use"` and the safe Ed25519 fingerprint.
-Later installs report `"matched"`. First-use trust protects continuity after
-that observation, but it cannot detect an active attacker on the first
-connection. Provider-console host-key pre-enrollment remains an optional
-higher-assurance alternative when it is available.
+### Install a standard sandbox SSH alias
 
-WarpMetal CLI v0.8.7 with Agent Runtime v0.1.25 or newer can enable the narrowly
-scoped AppArmor exception required by a verified workload that creates an inner
-Bubblewrap PID namespace and private `/proc`:
+Use a separate keypair and access grant for each sandbox. After the grant is
+`applied`, install its token-free profile as a concrete OpenSSH alias:
 
 ```sh
-warpmetal runtime install \
-  --server <serverId> \
-  --ssh-user root \
-  --confirm INSTALL \
-  --nested-private-procfs enable \
-  --wait \
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  --alias <alias> \
   --json
+
+ssh <alias>
+ssh -t <alias> codex
+ssh <alias> codex exec '<task>'
+ssh -t <alias> claude
+ssh <alias> claude -p '<task>'
+ssh -t <alias> agent
+ssh <alias> agent -p '<task>'
+```
+
+Install and authenticate Codex, Claude Code, or Cursor 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.
+
+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
+exposes the VPS owner management key. The server-side forced gateway maps that
+identity to only its assigned sandbox, cannot open a host shell, and retains
+`ClearAllForwardings yes` together with agent and X11 forwarding denial.
+
+An exact reinstall is safe and unchanged. If an authenticated access refresh
+produces a new profile, refresh the profile first and then explicitly replace
+the local alias:
+
+```sh
+warpmetal sandbox access refresh \
+  --server <serverId> --sandbox <sandboxId> --grant <grantId> \
+  --connection-file <profile-path> --confirm REFRESH --wait --json
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  --alias <alias> --confirm REFRESH --json
+```
+
+Remove only that managed alias and pin with explicit confirmation; unrelated
+SSH configuration is preserved:
+
+```sh
+warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE --json
 ```
 
-This is an explicit host-scoped opt-in for nested-Bubblewrap hosts, not a
-requirement for ordinary VPS or Runtime workloads that use only the outer
-sandbox. The default `preserve` action leaves the current policy state
-unchanged. Use `disable` during an approved maintenance window to unload
-WarpMetal's policy and restore the pre-install file and loaded-policy state.
-Because Runtime sandboxes share one Unix owner, treat an enabled policy as
-available to every sandbox on that Runtime host whose process matches the
-signed, root-owned bwrap path; it is not a per-sandbox permission.
-
-Common inner-boundary designs are planning with an exact read-only checkout,
-coding with only one approved checkout and output directory writable, and QA
-with an exact candidate plus isolated test processes and scratch space. The
-boundary protects a persistent trusted runner from repository-controlled
-commands and sibling attempts. GitHub access, installing Codex or another AI
-CLI, and delegating to subagents do not by themselves require this capability.
+[Codex Desktop's remote-connections contract](https://learn.chatgpt.com/docs/remote-connections)
+discovers concrete aliases from `~/.ssh/config`, requires `ssh <alias>` to
+work, and starts the remote app server through the login shell. Install Codex
+inside the sandbox and ensure Codex is on the login-shell `PATH` before choosing
+the alias in Codex Desktop.
+
+The tested Cursor Remote SSH path is incompatible with this boundary because
+it requests dynamic forwarding, which WarpMetal deliberately denies. Do not
+weaken sandbox forwarding controls to make the IDE connect. Use the supported
+[Cursor CLI](https://cursor.com/docs/cli/overview) interactively with
+`ssh -t <alias> agent` or in
+[headless mode](https://cursor.com/docs/cli/headless) with
+`ssh <alias> agent -p '<task>'` instead.
+
+On the first install in a server trust epoch, JSON output includes
+`hostKeyTrust.state: "trusted_first_use"` and the safe Ed25519 fingerprint.
+Later installs report `"matched"`. First-use trust protects continuity after
+that observation, but it cannot detect an active attacker on the first
+connection. Provider-console host-key pre-enrollment remains an optional
+higher-assurance alternative when it is available.
 
 Installation gives pre-existing Docker containers exact liveness checks and
 tracks common container-runtime processes without collecting application

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "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/connection.js && node --check src/errors.js && node --check src/host-trust.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.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/host-trust.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh-alias.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
     "plugin:check": "node --test test/plugin.test.js",
     "test": "node --test",
     "prepack": "npm run check && npm test"

package/skills/warpmetal/SKILL.md

@@ -90,11 +90,14 @@ open either file.
 
 In an interactive initial purchase, the result may also contain
 `humanCheckout`. Offer it as an alternative to the local agent wallet. Show
-`humanCheckout.url` as clickable text and render only the identical
-`humanCheckout.qrPayload` URL as the purchase QR; never render the recipient
-address as this QR. The URL is an expiring bearer capability, so do not log,
-save, or send it anywhere except to the buyer who requested this purchase. If
-the buyer uses it, do not authorize or submit through the agent wallet. Run the
+`humanCheckout.url` as clickable x402api text. If another-device acquisition
+is useful, render only the identical `humanCheckout.qrPayload` URL as a QR and
+explain that scanning opens the hosted checkout without authorizing payment.
+x402api owns any wallet selection and wallet-specific opening QR inside that
+page; never synthesize a wallet link or render the recipient address as this
+QR. The URL is an expiring bearer capability, so do not log, save, or send it
+anywhere except to the buyer who requested this purchase. If the buyer uses it,
+do not authorize or submit through the agent wallet. Run the
 exact `humanCheckout.afterPayment.argv` command, wait for the server to become
 ready, then follow `ask_human_for_notification_email`: ask the owner for the
 optional lifecycle-notification address and add only the address they provide.
@@ -293,16 +296,6 @@ 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.
 
-For any verified workload that creates an inner Bubblewrap PID namespace and
-private `/proc`, CLI 0.8.7 with Runtime 0.1.25 or newer may add
-`--nested-private-procfs enable` to the approved Runtime install. Planning with
-a read-only checkout, coding in one writable checkout, and independent QA are
-common uses. GitHub access, an AI CLI, or subagent delegation alone does not
-require it. Omission means `preserve`, which leaves policy state unchanged;
-`disable` is an explicit maintenance action. The exception is host-scoped
-rather than sandbox-scoped, so separate workloads onto different VPS hosts when
-they must not share it.
-
 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
@@ -314,6 +307,38 @@ 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.
 
+CLI 0.8.10 or newer can turn the already-applied token-free profile into a
+standard concrete OpenSSH alias. Read [references/runtime.md](references/runtime.md)
+before installing one. Use a separate keypair and grant for each sandbox, and
+pass the sandbox identity—not the VPS owner management key:
+
+```sh
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  --alias <alias> --json
+ssh <alias>
+```
+
+The local alias preserves the forced gateway: it cannot open a host shell and
+does not relax forwarding denial. Provider authentication and credentials stay
+inside the sandbox. After an authenticated profile refresh, update the alias
+only with the explicit second confirmation:
+
+```sh
+warpmetal sandbox access refresh \
+  --server <serverId> --sandbox <sandboxId> --grant <grantId> \
+  --connection-file <profile-path> --confirm REFRESH --wait --json
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  --alias <alias> --confirm REFRESH --json
+```
+
+Remove it only with
+`warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE --json`.
+Do not edit the generated fragment or host pin manually.
+
 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

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

@@ -75,8 +75,11 @@ workflow.
 For interactive initial purchases, the response may additionally include
 `humanCheckout.url`, the identical `qrPayload`, `expiresAt`, and an exact
 `afterPayment.argv` command. The URL is a short-lived bearer capability for the
-same charge, not a recipient address. If the buyer pays in the hosted checkout,
-do not submit an agent-wallet artifact; run the returned status command and,
+same charge, not a recipient address. Present the URL as a clickable x402api
+handoff. An optional QR contains that exact web link for another-device
+acquisition; scanning it does not authorize payment, and x402api owns any
+wallet-specific choices inside the hosted page. If the buyer pays there, do not
+submit an agent-wallet artifact; run the returned status command and,
 after ready, follow `ask_human_for_notification_email` to offer lifecycle
 notices. The CLI does not persist the hosted URL. Renewal commands never expose
 or use this interactive option.
@@ -213,7 +216,6 @@ warpmetal runtime get --server <serverId> [--wait] [--timeout-seconds <n>] --jso
 warpmetal runtime install \
   --server <serverId> [--identity <owner-key>] --ssh-user root \
   --confirm INSTALL \
-  [--nested-private-procfs <preserve|enable|disable>] \
   [--wait] [--timeout-seconds <n>] --json
 
 warpmetal sandbox create \
@@ -242,15 +244,6 @@ SCP operation is strict; changed keys, malformed pins, and failed or ambiguous
 reloads never replace trust. This TOFU step cannot detect an active attacker on
 the first connection. Provider-console pre-enrollment is optional and stronger.
 
-The nested-private-procfs action requires CLI 0.8.7 and Runtime 0.1.25 or
-newer. It defaults to `preserve`. `enable` is a host-level opt-in for any
-verified workload that creates an inner Bubblewrap PID namespace and private
-`/proc`; read-only planning, single-workspace coding, and independent QA are
-common examples. GitHub use, an AI CLI, or subagent delegation alone does not
-require it. `disable` unloads WarpMetal's policy and restores the recorded
-pre-enable state. It is not a per-sandbox capability because Runtime sandboxes
-share one Unix owner.
-
 See [runtime.md](runtime.md) for capacity, lifetime, cleanup, polling, and
 installation safety. Exit 8 means accepted or pending, never applied.
 
@@ -268,6 +261,10 @@ warpmetal sandbox access get \
 warpmetal sandbox access refresh \
   --server <serverId> --sandbox <sandboxId> --grant <grantId> \
   --connection-file <profile-path> --confirm REFRESH [--wait] --json
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> --identity <sandbox-private-key-path> \
+  --alias <alias> [--confirm REFRESH] --json
+warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE --json
 warpmetal sandbox access revoke \
   --server <serverId> --sandbox <sandboxId> --grant <grantId> \
   --confirm REVOKE [--wait] --json
@@ -282,6 +279,37 @@ creation requires `--wait`.
 the currently applied grant and API-reported pinned host keys; use it after an
 OS reload and supervisor reinstall.
 
+`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
+alias in `~/.ssh/config`. Exact replay is unchanged. If the profile, endpoint,
+pin, or identity changes, first run the authenticated `sandbox access refresh`
+command above, then repeat `sandbox access install-ssh ... --confirm REFRESH`.
+Removal requires exact `--confirm REMOVE` and preserves unrelated SSH config.
+
+Use a separate keypair and grant for each sandbox. The alias never uses or
+exposes the VPS owner management key; the forced gateway cannot open a host
+shell, and forwarding remains disabled with `ClearAllForwardings yes`.
+Authentication for user-installed tools happens inside the sandbox. Common
+interactive and one-shot entry points are:
+
+```sh
+ssh <alias>
+ssh -t <alias> codex
+ssh <alias> codex exec '<task>'
+ssh -t <alias> claude
+ssh <alias> claude -p '<task>'
+ssh -t <alias> agent
+ssh <alias> agent -p '<task>'
+```
+
+[Codex Desktop](https://learn.chatgpt.com/docs/remote-connections) reads
+the concrete alias from `~/.ssh/config` and starts Codex through the sandbox
+login shell, so Codex must be installed and on that login-shell `PATH`. The
+tested Cursor Remote SSH route requests prohibited dynamic forwarding and is
+not compatible with this boundary. Keep forwarding denied and use the
+[Cursor CLI](https://cursor.com/docs/cli/overview) interactive or
+[headless](https://cursor.com/docs/cli/headless) commands shown above.
+
 ## Skill installation and state
 
 ```sh

package/skills/warpmetal/references/payments.md

@@ -125,9 +125,13 @@ argv arrays returned under `paymentWorkflow`:
 
 For an interactive initial purchase, an optional `humanCheckout` object offers
 a second presentation path for the same charge. Its `url` and `qrPayload` must
-be identical hosted-checkout URLs; render that URL as the QR and copyable link,
-never a recipient address. If the buyer completes this path, skip agent-wallet
-authorization and run `humanCheckout.afterPayment.argv`. Continue bounded
+be identical hosted-checkout URLs. Present `url` as the clickable x402api
+handoff. If a QR is useful for another device, render only the exact
+`qrPayload` and explain that scanning opens the checkout without authorizing
+payment. x402api owns wallet selection and any wallet-specific opening QR
+inside that page; never synthesize a wallet link or render a recipient address.
+If the buyer completes this path, skip agent-wallet authorization and run
+`humanCheckout.afterPayment.argv`. Continue bounded
 status polling until ready, then ask for the optional lifecycle-notification
 email when the result returns `ask_human_for_notification_email`. The hosted
 URL expires at `humanCheckout.expiresAt`, is not persisted by the CLI, and is

package/skills/warpmetal/references/runtime.md

@@ -58,7 +58,6 @@ warpmetal runtime install \
   --identity <owner-private-key-path> \
   --ssh-user root \
   --confirm INSTALL \
-  [--nested-private-procfs <preserve|enable|disable>] \
   --wait \
   --json
 warpmetal runtime get --server <serverId> --wait --json
@@ -81,29 +80,6 @@ is an optional higher-assurance alternative, not a requirement. Only a locally
 recorded successful reload that reports an owner-host-key refresh creates one
 new operation-bound trust epoch; failed or ambiguous reloads do not.
 
-`--nested-private-procfs` is supported by `warpmetal` CLI 0.8.7 with Agent
-Runtime 0.1.25 or newer. Its default is `preserve`, which makes no AppArmor
-policy change. Select `enable` only when this VPS is intentionally dedicated to
-a verified workload that creates an inner Bubblewrap PID namespace and private
-procfs. Ordinary VPS users and Runtime workloads that rely only on the outer
-sandbox do not need it. Select `disable` only during an approved maintenance
-action to unload WarpMetal's policy and restore the exact file and loaded-policy
-state that existed before enablement.
-
-Examples include a planner with an exact read-only checkout, a coder with only
-one approved checkout and output directory writable, and QA with an exact
-candidate plus isolated test processes and scratch space. This protects a
-persistent trusted runner from repository-controlled commands and sibling
-attempts. GitHub access, installing an AI CLI, and subagent delegation alone do
-not require nested private procfs.
-
-This setting is host-scoped, not sandbox-scoped. Runtime sandboxes share one
-Unix owner, so every sandbox on the host can use the exception only through the
-signed, root-owned, fixed bwrap path matched by the policy. Enabling it does not
-authorize arbitrary bwrap binaries or change the trust boundary for the
-Runtime image selected by WarpMetal's authenticated backend. Isolate workloads
-on separate VPS hosts if they must not share this host capability.
-
 The signed installer is designed to preserve container workloads already
 running on a supported host. It selects `crun` for WarpMetal's private rootless
 Podman service, refuses APT removals and DNF erasures, protects installed
@@ -128,17 +104,6 @@ host automatically:
   unexpectedly; stop and review the host package logs;
 - `runtime_legacy_migration_required`: preview Podman state needs a separate,
   explicitly reviewed migration and was not reset.
-- `runtime_nested_private_procfs_architecture_unsupported`: the requested
-  coding-host policy is unsupported by this CPU architecture;
-- `runtime_apparmor_state_unverifiable`: the host's current AppArmor state
-  cannot be established safely;
-- `runtime_apparmor_policy_conflict`: an existing file or loaded-policy state
-  conflicts with WarpMetal's recorded transaction;
-- `runtime_apparmor_policy_rollback_failed`: the installer could not restore
-  the exact prior AppArmor state; stop and perform operator recovery.
-- `runtime_apparmor_policy_recovery_failed`: an interrupted prior policy
-  transaction could not be recovered; stop and perform operator recovery.
-
 There is no force bypass. If `runtime_reboot_required` is returned, schedule
 the reboot as a separate maintenance action and retry only after the host and
 its existing workloads are healthy. The ordinary installer never installs a
@@ -262,6 +227,93 @@ 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.
 
+### Install a concrete OpenSSH alias
+
+CLI 0.8.10 or newer can install the reviewed profile as a standard local alias
+without another API request:
+
+```sh
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  --alias <alias> \
+  --json
+```
+
+Use a separate keypair and grant for each sandbox. The identity must be the
+private half of that sandbox grant, never the VPS owner management key. The
+command validates the closed token-free profile and its fingerprints, then
+prepends a managed include to `~/.ssh/config`. It writes a private alias
+fragment and dedicated pinned known-hosts file. Exact reinstall is idempotent.
+
+If an authenticated access refresh changes the profile, endpoint, host pin, or
+identity, run the server-backed profile refresh first and then explicitly
+replace the local alias:
+
+```sh
+warpmetal sandbox access refresh \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --grant <grantId> \
+  --connection-file <profile-path> \
+  --confirm REFRESH \
+  --wait \
+  --json
+warpmetal sandbox access install-ssh \
+  --connection-file <profile-path> \
+  --identity <sandbox-private-key-path> \
+  --alias <alias> \
+  --confirm REFRESH \
+  --json
+```
+
+Never replace a pin merely because an SSH connection reports a mismatch. The
+alias installer consumes only the already-refreshed API profile and does not
+scan or trust a network key. Remove one alias without changing unrelated SSH
+configuration:
+
+```sh
+warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE --json
+```
+
+The generated host block pins the exact host keys, selects only the sandbox
+identity, disables password and keyboard-interactive authentication, retains
+`ClearAllForwardings yes`, disables agent/X11 forwarding and local commands,
+and contains neither `RemoteCommand` nor `RequestTTY`. The existing server-side
+forced gateway still maps the key to exactly one sandbox. The alias cannot open
+a host shell and never uses or exposes the owner management key.
+
+After installing and authenticating each provider tool inside the sandbox, use
+the alias for interactive or one-shot work:
+
+```sh
+ssh <alias>
+ssh -t <alias> codex
+ssh <alias> codex exec '<task>'
+ssh -t <alias> claude
+ssh <alias> claude -p '<task>'
+ssh -t <alias> agent
+ssh <alias> agent -p '<task>'
+```
+
+Provider authentication and credentials are sandbox-owned and persist only in
+the sandbox home. WarpMetal does not install, authenticate, configure, or
+receive credentials for Codex, Claude Code, or Cursor CLI.
+
+[Codex Desktop](https://learn.chatgpt.com/docs/remote-connections)
+discovers a concrete alias through `~/.ssh/config`, requires ordinary
+`ssh <alias>` connectivity, and launches the remote app server through the
+login shell. Codex must therefore be installed inside the sandbox and on the
+login-shell `PATH` before selecting the alias in Codex Desktop.
+
+The tested Cursor Remote SSH path requests dynamic forwarding, which the
+Runtime correctly denies, so Cursor IDE remote access is not supported by this
+restricted alias. Do not relax forwarding controls. Use the official
+[Cursor CLI](https://cursor.com/docs/cli/overview) interactively with
+`ssh -t <alias> agent` or in
+[headless mode](https://cursor.com/docs/cli/headless) with
+`ssh <alias> agent -p '<task>'` instead.
+
 Connect without an owner management credential:
 
 ```sh