warpmetal 0.8.9 → 0.8.11

package/README.md

@@ -367,42 +367,89 @@ 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>'
+ssh -t <alias> gemini
+ssh <alias> gemini -p '<task>'
 ```
 
-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.
+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.
+
+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
+```
+
+[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.
+
+Use the official Gemini CLI [installation guide](https://geminicli.com/docs/get-started/installation/)
+before running `ssh -t <alias> gemini`, or use its documented
+[headless mode](https://geminicli.com/docs/cli/headless/) with
+`ssh <alias> gemini -p '<task>'`. Gemini's optional Docker or Podman sandbox is
+normally unavailable inside the WarpMetal sandbox because no host
+container-engine socket is exposed; run Gemini directly inside the existing
+outer sandbox and choose its approvals yourself.
+
+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.9",
+  "version": "0.8.11",
   "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

@@ -296,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
@@ -317,6 +307,40 @@ 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. Install and authenticate Codex, Claude Code, Cursor CLI, or
+Gemini CLI inside the sandbox; use the entry points and compatibility guidance
+in [references/runtime.md](references/runtime.md). 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

@@ -216,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 \
@@ -245,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.
 
@@ -271,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
@@ -285,6 +279,50 @@ 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>'
+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.
+
+[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.
+
+Install Gemini CLI from its official [installation guide](https://geminicli.com/docs/get-started/installation/)
+and use its documented [headless mode](https://geminicli.com/docs/cli/headless/)
+for `gemini -p`. Gemini's optional Docker or Podman sandbox is normally
+unavailable inside the WarpMetal sandbox because no host container-engine
+socket is exposed; run Gemini directly inside the existing outer sandbox and
+choose its approvals yourself.
+
 ## Skill installation and state
 
 ```sh

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,104 @@ 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>'
+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.
+
+[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.
+
+Follow Gemini CLI's official [installation guide](https://geminicli.com/docs/get-started/installation/),
+then use `ssh -t <alias> gemini` interactively or its documented
+[headless mode](https://geminicli.com/docs/cli/headless/) with
+`ssh <alias> gemini -p '<task>'`. Gemini's optional Docker or Podman sandbox is
+normally unavailable inside the WarpMetal sandbox because no host
+container-engine socket is exposed; run Gemini directly inside the existing
+outer sandbox and choose its approvals yourself.
+
 Connect without an owner management credential:
 
 ```sh

package/src/cli.js

@@ -37,6 +37,7 @@ import {
   signSshChallenge,
   sshFingerprint,
 } from "./ssh.js";
+import { installSshAlias, removeSshAlias } from "./ssh-alias.js";
 import { resolveStateDirectory, StateStore } from "./state.js";
 import { VERSION } from "./version.js";
 
@@ -111,7 +112,7 @@ Usage:
   warpmetal operation get --operation <operationId> [--server <serverId>] [--wait]
   warpmetal runtime enable|get --server <serverId> [--wait]
   warpmetal runtime install --server <serverId> [--identity <owner-key>] --ssh-user <user>
-    --confirm INSTALL [--nested-private-procfs <preserve|enable|disable>] [--wait]
+    --confirm INSTALL [--wait]
   warpmetal sandbox create --server <serverId> --name <name> --size <size>
     [--lifetime temporary] [--expires-in-seconds <n>] [--confirm TEMPORARY] [--wait]
   warpmetal sandbox create --server <serverId> --file <batch.json> [--confirm TEMPORARY]
@@ -122,6 +123,9 @@ Usage:
   warpmetal sandbox access grant|list|get|revoke ...
   warpmetal sandbox access refresh --server <serverId> --sandbox <sandboxId>
     --grant <grantId> --connection-file <path> --confirm REFRESH [--wait]
+  warpmetal sandbox access install-ssh --connection-file <profile> --identity <sandbox-private-key-path>
+    --alias <alias> [--confirm REFRESH]
+  warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE
   warpmetal sandbox connect --connection-file <path> --identity <sandbox-key> [-- <command>]
   warpmetal state list
   warpmetal agent install --target <codex|claude|all> [--scope <user|project>] [--force]
@@ -133,16 +137,6 @@ Global options:
   --help                 Show help
   --version              Show the CLI version
 
-Nested private procfs (CLI 0.8.7+, Runtime 0.1.25+):
-  preserve               Default; do not inspect or change AppArmor policy state
-  enable                 Enable the exact-path Bubblewrap policy on an amd64 host
-  disable                Remove it and restore the recorded pre-enable policy state
-
-Use enable once per dedicated Runtime host when a verified workload creates an
-inner Bubblewrap PID namespace and private /proc. Planning, coding, and QA are
-common examples. GitHub access, an AI CLI, and subagent delegation alone do not
-require it. The capability is host-scoped, not per-sandbox.
-
 SSH host trust (CLI 0.8.8+):
   runtime install authenticates with the exact owner key and trusts the first
   observed Ed25519 host key once for that server trust epoch. It pins the key
@@ -153,6 +147,49 @@ SSH host trust (CLI 0.8.8+):
   active attacker on the first connection. Provider-console pre-enrollment is
   the optional higher-assurance alternative.
 
+Sandbox SSH aliases:
+  Refresh the authenticated connection profile before refreshing an existing
+  alias:
+    warpmetal sandbox access refresh --server <serverId> --sandbox <sandboxId> --grant <grantId> --connection-file <profile> --confirm REFRESH
+    warpmetal sandbox access install-ssh --connection-file <profile> --identity <sandbox-private-key-path> --alias <alias> --confirm REFRESH
+  Remove only the managed alias and host pins explicitly:
+    warpmetal sandbox access remove-ssh --alias <alias> --confirm REMOVE
+
+  Use a separate keypair and grant for each sandbox. Tool and provider
+  authentication stays inside the sandbox and uses sandbox-owned credentials.
+  After installation, the concrete alias supports interactive and one-shot use:
+    ssh <alias>
+    ssh -t <alias> codex
+    ssh <alias> codex exec "<prompt>"
+    ssh -t <alias> claude
+    ssh <alias> claude -p "<prompt>"
+    ssh -t <alias> agent
+    ssh <alias> agent -p "<prompt>"
+    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.
+
+  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.
+  Sandbox aliases never use or expose the VPS owner management key, cannot open
+  a host shell, and do not relax isolation: ClearAllForwardings yes keeps all
+  forwarding disabled.
+
+  Gemini's optional Docker or Podman sandbox is normally unavailable inside
+  the WarpMetal sandbox because no host container-engine socket is exposed;
+  run Gemini directly inside the existing outer sandbox and choose its
+  approvals yourself.
+
+  Compatibility references:
+    https://learn.chatgpt.com/docs/remote-connections
+    https://cursor.com/docs/cli/overview
+    https://cursor.com/docs/cli/headless
+    https://geminicli.com/docs/get-started/installation/
+    https://geminicli.com/docs/cli/headless/
+
 Credential environment variables:
   WARPMETAL_OWNER_TOKEN  Recovery/bootstrap credential for one explicit command
   WARPMETAL_ACCESS_TOKEN Short-lived SSH-derived credential for one explicit command
@@ -2164,14 +2201,6 @@ async function handleRuntimeInstall(client, store, options, context) {
     stringOption(options, "identity"),
   );
   const sshUser = stringOption(options, "ssh-user", { required: true });
-  const nestedPrivateProcfs =
-    stringOption(options, "nested-private-procfs") || "preserve";
-  if (!["preserve", "enable", "disable"].includes(nestedPrivateProcfs)) {
-    throw new CliError(
-      "--nested-private-procfs must be preserve, enable, or disable.",
-      { exitCode: 2 },
-    );
-  }
   if (stringOption(options, "confirm", { required: true }) !== "INSTALL") {
     throw new CliError(
       "Confirm supervisor installation with --confirm INSTALL.",
@@ -2215,7 +2244,6 @@ async function handleRuntimeInstall(client, store, options, context) {
     knownHostsFile: hostKeyTrust.knownHostsFile,
     trustedPublicIp: hostKeyTrust.publicIp,
     bootstrap: bootstrap.data,
-    nestedPrivateProcfs,
     fetchImpl: context.fetchImpl,
     spawnImpl: context.spawnImpl,
   });
@@ -2720,6 +2748,38 @@ async function handleSandboxConnect(options, passthrough, context) {
   );
 }
 
+async function handleAccessInstallSsh(options, context) {
+  const result = await installSshAlias({
+    alias: stringOption(options, "alias", { required: true }),
+    connectionFile: stringOption(options, "connection-file", { required: true }),
+    identity: stringOption(options, "identity", { required: true }),
+    homeDirectory: context.env.HOME,
+    confirm: stringOption(options, "confirm"),
+  });
+  emit(
+    context.stdout,
+    result,
+    context.json,
+    `SSH alias ${result.alias}: ${result.operation}.`,
+  );
+  return 0;
+}
+
+async function handleAccessRemoveSsh(options, context) {
+  const result = await removeSshAlias({
+    alias: stringOption(options, "alias", { required: true }),
+    homeDirectory: context.env.HOME,
+    confirm: stringOption(options, "confirm", { required: true }),
+  });
+  emit(
+    context.stdout,
+    result,
+    context.json,
+    `SSH alias ${result.alias}: ${result.operation}.`,
+  );
+  return 0;
+}
+
 async function dispatch(positionals, options, passthrough, context) {
   const command = positionals.join(" ");
   if (passthrough.length > 0 && command !== "sandbox connect") {
@@ -2766,6 +2826,21 @@ async function dispatch(positionals, options, passthrough, context) {
     );
     return 0;
   }
+  if (command === "sandbox access install-ssh") {
+    rejectUnknownOptions(options, [
+      "json",
+      "help",
+      "connection-file",
+      "identity",
+      "alias",
+      "confirm",
+    ]);
+    return handleAccessInstallSsh(options, context);
+  }
+  if (command === "sandbox access remove-ssh") {
+    rejectUnknownOptions(options, ["json", "help", "alias", "confirm"]);
+    return handleAccessRemoveSsh(options, context);
+  }
 
   const baseUrl = stringOption(options, "base-url");
   const stateDir =
@@ -3030,7 +3105,6 @@ async function dispatch(positionals, options, passthrough, context) {
         "identity",
         "ssh-user",
         "confirm",
-        "nested-private-procfs",
         "idempotency-key",
         "wait",
         "timeout-seconds",