ghostdock 0.0.19 → 0.0.20

package/dist/cli.md

@@ -37,10 +37,10 @@ bun run --cwd packages/cli dev -- --help  # run from source without building
 Every command prints for people by default: one line per event, a symbol, then the message.
 
 ```
-$ ghostdock sandboxes list
+$ ghostdock vm list
   ⚓ Marketing site  quiet-harbor  running
   ◌ teal-jetty  stopped
-$ ghostdock sites publish ./dist
+$ ghostdock site publish ./dist
   ↗ https://foggy-teal-bollard.static.ghostdock.app
   ✓ Published site foggy-teal-bollard.
 ```
@@ -48,27 +48,27 @@ $ ghostdock sites publish ./dist
 `⚓` ready, `✓` done, `↗` a URL, `◌` stopped or gone, `✗` failed, `▂▄▆` in progress. Every line
 carries the name and id the next command needs.
 
-Commands that wait show a progress line on stderr while they run. Starting a sandbox
-(`sandboxes create`, `sandboxes wake`) prints how long each step took, measured on the server, each
+Commands that wait show a progress line on stderr while they run. Starting a VM
+(`vm create`, `vm wake`) prints how long each step took, measured on the server, each
 step with its own time:
 
 ```
-$ ghostdock sandboxes wake quiet-harbor
+$ ghostdock vm wake quiet-harbor
   ⚓ quiet-harbor  running
-  ⚓ sandbox started in 125ms
+  ⚓ VM started in 125ms
   ✓ container started in 3.0s
 ```
 
 The container line is missing when no container was started, or when the host is older and did
-not report it. `sandboxes status` prints the same lines for the last start. With `--json` they are
-the `boot` field: `{ trigger, sandbox: { startedAt, readyAt, ms }, container: { … } | null }`, or
+not report it. `vm status` prints the same lines for the last start. With `--json` they are
+the `boot` field: `{ trigger, vm: { startedAt, readyAt, ms }, container: { … } | null }`, or
 `null` when the command started nothing.
 
 **Scripts and agents pass `--json`.** It prints the result as one JSON document on stdout, with
 every field, and nothing else there. It works on every command and anywhere on the line:
 
 ```bash
-ghostdock sandboxes list --json | jq -r '.sandboxes[].name'
+ghostdock vm list --json | jq -r '.vms[].name'
 ```
 
 - **stdout is the result, stderr is everything else**: notices (`Using organization acme …`),
@@ -96,28 +96,29 @@ Commands are grouped by resource, like `gh` or `kubectl`: `ghostdock <resource>
 
 <!-- generated:command-groups:start (bun run sync:cli-reference; do not edit) -->
 ```
-ghostdock apps            Published apps of an organization.
-ghostdock docker          Docker over the private network: a sandbox's Docker engine from this machine.
-ghostdock env             Manage organization environment variables and secrets.
-ghostdock images          Organization image catalog: OCI bookmarks, Dockerfiles and Compose files.
-ghostdock login           Sign in and store a device access token for this machine…
-ghostdock logout          Revoke the device session and remove stored credentials.
-ghostdock network         The private network: reach your sandboxes by address and name from this machine.
-ghostdock organizations   Organizations you belong to.
-ghostdock projects        Deployable projects, their deployments and environment.
-ghostdock providers       Sandbox providers of an organization.
-ghostdock registry        Log in to the organization container registry.
-ghostdock sandboxes       Create, run and manage sandboxes.
-ghostdock sites           Static sites on the CDN.
-ghostdock skills          List and read Agent Skills (same catalog as MCP skill://index.json).
-ghostdock snapshots       Sandbox snapshots.
-ghostdock tools           List available agent tools.
-ghostdock whoami          Show the account this CLI is currently authenticated as.
+ghostdock app            Published apps of an organization.
+ghostdock docker         Docker over the private network: a VM's Docker engine from this machine.
+ghostdock env            Manage organization environment variables and secrets.
+ghostdock image          Organization image catalog: OCI bookmarks, Dockerfiles and Compose files.
+ghostdock login          Sign in and store a device access token for this machine…
+ghostdock logout         Revoke the device session and remove stored credentials.
+ghostdock network        The private network: reach your VMs by address and name from this machine.
+ghostdock organization   Organizations you belong to.
+ghostdock project        Deployable projects, their deployments and environment.
+ghostdock provider       Providers of an organization.
+ghostdock registry       Log in to the organization container registry.
+ghostdock site           Static sites on the CDN.
+ghostdock skill          List and read Agent Skills (same catalog as MCP skill://index.json).
+ghostdock snapshot       VM snapshots.
+ghostdock template       
+ghostdock tools          List available agent tools.
+ghostdock vm             Create, run and manage VMs.
+ghostdock whoami         Show the account this CLI is currently authenticated as.
 ```
 <!-- generated:command-groups:end -->
 
 Run `ghostdock <command> --help` at any level for its subcommands or flags, e.g.
-`ghostdock sandboxes --help` or `ghostdock sandboxes urls create --help`.
+`ghostdock vm --help` or `ghostdock vm url create --help`.
 
 Most commands are generated from the tool catalog — see **Invoking a tool** below. Every command
 is listed in the [command index](#command-index); [`cli-reference.md`](cli-reference.md) has each
@@ -129,18 +130,18 @@ Every organization-scoped command acts on one organization, taken from the first
 
 1. `--org <id-or-slug>` on the command
 2. the `GHOSTDOCK_ORG` environment variable
-3. the default set with `ghostdock organizations use <id-or-slug>`, stored in
+3. the default set with `ghostdock organization use <id-or-slug>`, stored in
    `~/.config/ghostdock/settings.json`
 
 With one organization there is nothing to do: `login` makes it the default, and every command,
 in any directory, uses it.
 
 ```bash
-ghostdock organizations use acme      # the default (login sets one when it can)
-ghostdock sandboxes list              # stderr: Using organization acme (default from ~/.config/ghostdock/settings.json)
-ghostdock sandboxes list --org beta   # --org always wins
-ghostdock organizations current       # which organization, and where it comes from
-ghostdock organizations use --clear
+ghostdock organization use acme      # the default (login sets one when it can)
+ghostdock vm list              # stderr: Using organization acme (default from ~/.config/ghostdock/settings.json)
+ghostdock vm list --org beta   # --org always wins
+ghostdock organization current       # which organization, and where it comes from
+ghostdock organization use --clear
 ```
 
 When the organization does not come from `--org`, the command says which one it uses on stderr,
@@ -181,7 +182,7 @@ or the timeout elapses. Exits `0` on success, non-zero otherwise.
 
 **`--code` — paste-code fallback:**
 
-If the CLI can't poll (e.g. it's running in a sandbox with no long-lived process, or the browser
+If the CLI can't poll (e.g. it's running in a VM with no long-lived process, or the browser
 approval happened on a different machine), the browser's "Having trouble? Show code" link reveals a
 short one-time code. Redeem it directly:
 
@@ -204,7 +205,7 @@ default organization when that is unambiguous:
 - With exactly one organization, that one becomes the default.
 - With several, a person at a terminal picks one from a numbered list (Enter skips). Without a
   terminal (agents, CI) nothing is asked: `login` lists them and points to
-  `ghostdock organizations use`.
+  `ghostdock organization use`.
 
 See [Choosing an organization](#choosing-an-organization) for how commands pick it up.
 
@@ -240,19 +241,19 @@ ghostdock tools --json   # the full catalog (including each tool's JSON Schema)
 
 Requires login — prints a hint and exits `1` if there's no valid session.
 
-### `ghostdock skills`
+### `ghostdock skill`
 
 Lists and reads **Agent Skills** for the authenticated account — the same catalog MCP
 clients discover at `skill://index.json` (SEP-2640 / Agent Skills discovery 0.2.0).
-Prefer resources. The MCP tools `skills_list` and `skills_get` are fallbacks for clients that
+Prefer resources. The MCP tools `skill_list` and `skill_get` are fallbacks for clients that
 cannot use `resources/list` and `resources/read` — skip them if those work.
 
 ```bash
-ghostdock skills list                          # name, description, and skill:// URI per skill
-ghostdock skills list --json                   # official discovery index ($schema + skills[])
-ghostdock skills get skill://github/SKILL.md   # print SKILL.md
-ghostdock skills get github                    # same, by name
-ghostdock skills get org_1/release-notes       # organization skill
+ghostdock skill list                          # name, description, and skill:// URI per skill
+ghostdock skill list --json                   # official discovery index ($schema + skills[])
+ghostdock skill get skill://github/SKILL.md   # print SKILL.md
+ghostdock skill get github                    # same, by name
+ghostdock skill get org_1/release-notes       # organization skill
 ```
 
 `--json` on `get` prints `{ uri, name, description, markdown }`. If the same name exists
@@ -263,19 +264,19 @@ Requires login — prints a hint and exits `1` if there's no valid session.
 ### Invoking a tool
 
 Every catalog tool is a command at its own path, with one `--flag` per schema property
-(`sandboxProviderId` -> `--sandbox-provider-id`). The one thing a command acts on is positional instead:
-`ghostdock sandboxes stop <sandbox-id>`, `ghostdock sandboxes urls delete <url-id>`,
+(`autoWake` -> `--auto-wake`). The one thing a command acts on is positional instead:
+`ghostdock vm stop <vm>`, `ghostdock vm url delete <url-id>`,
 `ghostdock env get <name>`. The organization is always the `--org` flag, by id or slug: a slug is easier to type, an id keeps
 working after the organization is renamed (renaming changes the slug). The MCP tool name is the same path joined with
-underscores: `ghostdock sandboxes urls create` calls the `sandboxes_urls_create` tool. Run
+underscores: `ghostdock vm url create` calls the `vm_url_create` tool. Run
 `ghostdock <command> --help` to see a command's full description, its flags and which are
 required; a group's `--help` lists its commands with one line each. Output is a line per item
 for people; `--json` prints the tool's result as it comes back over MCP.
 
 ```bash
-ghostdock organizations list
+ghostdock organization list
 #   • Acme  org_123
-ghostdock organizations list --json
+ghostdock organization list --json
 # {"organizations": [{"id": "org_123", "name": "Acme", "slug": "acme"}]}
 ```
 
@@ -291,97 +292,97 @@ Command descriptions are short on purpose. Concepts and workflows live in the bu
 Skills, the same documents MCP agents read:
 
 ```bash
-ghostdock skills get sandboxes      # sources, manifests, lifecycle, providers, URLs and TCP
-ghostdock skills get sandbox-boot   # processes that must come back after idle-stop
-ghostdock skills get environment    # organization entries, bindings, local entries, secrets
-ghostdock skills get publishing     # sites publish vs projects publish, outcomes, redeploys
-ghostdock skills get incus-setup    # connecting your own Incus host
+ghostdock skill get vm       # sources, manifests, lifecycle, providers, URLs and TCP
+ghostdock skill get vm-boot   # processes that must come back after idle-stop
+ghostdock skill get environment    # organization entries, bindings, local entries, secrets
+ghostdock skill get publishing     # sites publish vs projects publish, outcomes, redeploys
+ghostdock skill get incus-setup    # connecting your own Incus host
 ```
 
-### Sandboxes
+### VMs
 
-Read `ghostdock skills get sandboxes` before your first sandbox: what it can boot from, manifests,
+Read `ghostdock skill get vm` before your first VM: what it can boot from, manifests,
 idle-stop and auto-delete, providers, URLs.
 
-Every sandbox has a name like `quiet-harbor`, unique within its organization, and every command
-that takes a sandbox accepts it with the organization (`--org`, `GHOSTDOCK_ORG` or the default).
-The long `sandboxId` in `--json` output works too, in the same organization. A name never changes
-while the sandbox exists, so scripts can keep it; once a sandbox is deleted, its name may be given to
-a new one later. The display name is a separate label you can edit. For example, create a sandbox,
+Every VM has a name like `quiet-harbor`, unique within its organization, and every command
+that takes a VM accepts it with the organization (`--org`, `GHOSTDOCK_ORG` or the default).
+The long `vmId` in `--json` output works too, in the same organization. A name never changes
+while the VM exists, so scripts can keep it; once a VM is deleted, its name may be given to
+a new one later. The display name is a separate label you can edit. For example, create a VM,
 then expose a URL:
 
 ```bash
-ghostdock sandboxes create --org org_123 --display-name "Marketing site"
-ghostdock sandboxes urls create quiet-harbor --port 8080 --auto-wake true --public true
+ghostdock vm create --org org_123 --display-name "Marketing site"
+ghostdock vm url create quiet-harbor --port 8080 --auto-wake true --public true
 ```
 
-#### Containers in a sandbox
+#### Containers in a VM
 
-On Ghostdock Cloud a sandbox runs one Docker engine; everything in it is an ordinary container.
-`ssh get`, `files`, `commands` and `shells` land in one of them: `--container <name>`, else the
-sandbox's default container, else the one running container. With several running and no default,
+On Ghostdock Cloud a VM runs one Docker engine; everything in it is an ordinary container.
+`vm ssh get`, `vm file`, `vm command` and `vm shell` land in one of them: `--container <name>`, else the
+VM's default container, else the one running container. With several running and no default,
 the CLI asks which one at the keyboard and offers to make it the default; without a terminal it
 fails and lists the names. A command runs as `docker exec` does there: as the container's
 `ghostdock.login.user`, else the image's `USER`, else root.
 
 ```bash
-ghostdock sandboxes containers list quiet-harbor
-ghostdock sandboxes default-container quiet-harbor --container web     # --clear true removes it
-ghostdock sandboxes commands run quiet-harbor --container db --command 'pg_isready'
-ghostdock sandboxes containers protection quiet-harbor workstation --protected false
+ghostdock vm container list quiet-harbor
+ghostdock vm default-container quiet-harbor --container web     # --clear true removes it
+ghostdock vm command run quiet-harbor --container db --command 'pg_isready'
+ghostdock vm container unlock quiet-harbor workstation
 ```
 
 A shell session lives in its container: pass the same `--container` to every `shells` and
 `commands` call on it.
 
-#### Environment in a sandbox
+#### Environment in a VM
 
-A sandbox exports **nothing** by default (unless you boot from an organization snapshot or catalog
+A VM exports **nothing** by default (unless you boot from an organization snapshot or catalog
 image whose manifest supplies defaults). `environment` has three parts: `organization` (plain same-name opt-ins from the
-catalogue, see [`ghostdock env`](#ghostdock-env)), `bindings` (slot ← org entry remaps), and `local` (sandbox-only variables/secrets). A local entry overrides an
+catalogue, see [`ghostdock env`](#ghostdock-env)), `bindings` (slot ← org entry remaps), and `local` (VM-only variables/secrets). A local entry overrides an
 organization export of the same name. Prefer the CLI when setting secret values so they are not
 pasted into the agent conversation.
 
 ```bash
 # At create time, in one call:
-ghostdock sandboxes create --org org_123 \
+ghostdock vm create --org org_123 \
   --environment '{"organization":["VITE_API_URL","BUILD_TOKEN"],"bindings":[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}'
 
 # Afterwards:
-ghostdock sandboxes env get quiet-harbor
-ghostdock sandboxes env select quiet-harbor --environment '["VITE_API_URL"]' \
+ghostdock vm env get quiet-harbor
+ghostdock vm env select quiet-harbor --environment '["VITE_API_URL"]' \
   --bindings '[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}]'
-ghostdock sandboxes env select quiet-harbor --environment '[]'   # clears plain + remaps (omit bindings)
-ghostdock sandboxes env set API_KEY --sandbox-id quiet-harbor --value sk_live --kind secret
-ghostdock sandboxes env delete API_KEY --sandbox-id quiet-harbor
+ghostdock vm env select quiet-harbor --environment '[]'   # clears plain + remaps (omit bindings)
+ghostdock vm env set API_KEY --vm quiet-harbor --value sk_live --kind secret
+ghostdock vm env delete API_KEY --vm quiet-harbor
 ```
 
 Values arrive as real environment variables, so read them with `process.env` / `$VAR` inside the
-sandbox. **Do not pass secrets in `sandboxes commands run` strings** — the command text is retained and
-readable through `sandboxes commands logs`. `sandboxes env get` reports every organization entry
-(selected + overriddenByLocal) and the sandbox's own local entries; `sandboxes status` reports
+VM. **Do not pass secrets in `vm command run` strings** — the command text is retained and
+readable through `vm command logs`. `vm env get` reports every organization entry
+(selected + overriddenByLocal) and the VM's own local entries; `vm status` reports
 just the resolved names.
 
 New shell commands and SSH sessions see a change immediately. Processes already running keep the
-values they booted with until restarted (pass `--restart` to `sandboxes env select` /
-`sandboxes env set` / `sandboxes env delete` to restart a running sandbox
+values they booted with until restarted (pass `--restart` to `vm env select` /
+`vm env set` / `vm env delete` to restart a running VM
 instead).
 
 ### Images
 
-Organization image catalog: OCI bookmarks (`images add`), stored Dockerfiles
-(`images add-dockerfile`), and refs currently in use on sandboxes. `images list` and `images get`
+Organization image catalog: OCI bookmarks (`image add`), stored Dockerfiles
+(`image add-dockerfile`), and refs currently in use on VMs. `image list` and `image get`
 cover the same catalog family as those add tools — each org row includes `kind`, a redacted
 `manifest` (from `ghostdock.*` Docker/OCI labels), `requiredEnvironment`, and `requiredUrls` (same
-shape as snapshots). `sandboxes create` with `--source '{"type":"image","id":"..."}'` boots a catalog
+shape as snapshots). `vm create` with `--source '{"type":"image","id":"..."}'` boots a catalog
 row by id and applies its manifest (URLs + env) like an organization snapshot.
 
 ```bash
-ghostdock images list --org org_123
-ghostdock images get img_abc --org org_123
-ghostdock images add --org org_123 --ref ghcr.io/acme/app:latest --label "Acme app"
-ghostdock images add-dockerfile --org org_123 --name my-stack --dockerfile "$(cat Dockerfile)"
-ghostdock sandboxes create --org org_123 \
+ghostdock image list --org org_123
+ghostdock image get img_abc --org org_123
+ghostdock image add --org org_123 --ref ghcr.io/acme/app:latest --label "Acme app"
+ghostdock image add-dockerfile --org org_123 --name my-stack --dockerfile "$(cat Dockerfile)"
+ghostdock vm create --org org_123 \
   --source '{"type":"image","id":"img_abc"}' \
   --environment '{"local":[{"name":"API_KEY","kind":"secret","value":"sk_test"}]}'
 ```
@@ -392,81 +393,81 @@ persisting a catalog row. That JSON source is Dockerfile text only: COPY/ADD of
 inline files (must include `docker-compose.yml`/`yaml` or `compose.yml`/`yaml`) and runs
 `docker compose up`; `ghostdock.*` service labels become the create-time manifest. A directory or
 ZIP — Dockerfile build context, or a Compose project with extra files — is
-[`ghostdock sandboxes build`](#ghostdock-sandboxes-build), not this command. Any OCI ref may still
-be passed as `{ type: "image", ref }` even when it does not appear in `images list`. Catalog compose
+[`ghostdock vm build`](#ghostdock-vm-build), not this command. Any OCI ref may still
+be passed as `{ type: "image", ref }` even when it does not appear in `image list`. Catalog compose
 rows still boot via `{ type: "image", id }`.
 
-### `ghostdock sites publish`
+### `ghostdock site publish`
 
-Publish a local directory or ZIP to the CDN (durable public URL, no sandbox):
+Publish a local directory or ZIP to the CDN (durable public URL, no VM):
 
 ```bash
-ghostdock sites publish --org org_123 ./dist
-ghostdock sites publish --org org_123 --zip ./site.zip
+ghostdock site publish --org org_123 ./dist
+ghostdock site publish --org org_123 --zip ./site.zip
 ```
 
-MCP `sites publish` is for small inline payloads. Use this command for a real directory or large ZIP.
+MCP `site_publish` is for small inline payloads. Use this command for a real directory or large ZIP.
 
-### `ghostdock projects publish`
+### `ghostdock project publish`
 
 Inspect a local source tree and publish (CDN when pre-built static, otherwise Compose from a DeploymentSpec).
 Required secrets without values return `awaiting_configuration` instead of a live URL.
-Re-invoke with `--environment` (same JSON shape as `sandboxes create`) after configuring.
-On `build_failed`, `start_failed`, or `verify_failed`, inspect the kept sandbox (unless verification tore it down), then re-invoke with `--spec` (JSON `DeploymentSpec`). The spec is executed on a fresh sandbox and stored for later replay. Do not pass `--spec` with `--replan`. Every terminal outcome stores the upload and returns authenticated `fileUrls`. Detected tests always run after the stack is up; pass `--require-verify` to refuse a deploy when they fail.
+Re-invoke with `--environment` (same JSON shape as `vm create`) after configuring.
+On `build_failed`, `start_failed`, or `verify_failed`, inspect the kept VM (unless verification tore it down), then re-invoke with `--spec` (JSON `DeploymentSpec`). The spec is executed on a fresh VM and stored for later replay. Do not pass `--spec` with `--replan`. Every terminal outcome stores the upload and returns authenticated `fileUrls`. Detected tests always run after the stack is up; pass `--require-verify` to refuse a deploy when they fail.
 
 ```bash
-ghostdock projects publish --org org_123 ./app
-ghostdock projects publish --org org_123 --auto-stop-interval-minutes -1 --zip ./app.zip
-ghostdock projects publish --org org_123 --project-id proj_123 ./app
-ghostdock projects publish --org org_123 ./app \
+ghostdock project publish --org org_123 ./app
+ghostdock project publish --org org_123 --auto-stop-interval-minutes -1 --zip ./app.zip
+ghostdock project publish --org org_123 --project-id proj_123 ./app
+ghostdock project publish --org org_123 ./app \
   --environment '{"organization":["DATABASE_URL"],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}'
-ghostdock projects publish --org org_123 ./app --spec '{"version":1,"run":{"kind":"static","outputDir":"."},"env":[]}'
-ghostdock projects publish --org org_123 --require-verify ./app
-ghostdock projects publish --org org_123 --sandbox-provider-id prov_123 ./app
+ghostdock project publish --org org_123 ./app --spec '{"version":1,"run":{"kind":"static","outputDir":"."},"env":[]}'
+ghostdock project publish --org org_123 --require-verify ./app
+ghostdock project publish --org org_123 --provider prov_123 ./app
 ```
 
-MCP `projects publish` is for small inline payloads. Use this command for a real directory or large ZIP.
+MCP `project_publish` is for small inline payloads. Use this command for a real directory or large ZIP.
 
-### `ghostdock sandboxes build`
+### `ghostdock vm build`
 
-Create a sandbox from a local Dockerfile or Compose directory. The CLI zips the directory (or sends
-`--zip`) and the server builds it. MCP `sandboxes create` stays inline text only.
+Create a VM from a local Dockerfile or Compose directory. The CLI zips the directory (or sends
+`--zip`) and the server builds it. MCP `vm_create` stays inline text only.
 
 ```bash
-ghostdock sandboxes build --org org_123 --kind dockerfile ./app
-ghostdock sandboxes build --org org_123 --kind compose --zip ./stack.zip
-ghostdock sandboxes build --org org_123 --kind dockerfile \
-  --sandbox-provider-id prov_123 --display-name "API" ./app
+ghostdock vm build --org org_123 --kind dockerfile ./app
+ghostdock vm build --org org_123 --kind compose --zip ./stack.zip
+ghostdock vm build --org org_123 --kind dockerfile \
+  --provider prov_123 --display-name "API" ./app
 ```
 
 The Dockerfile (`Dockerfile` or `dockerfile`) or a compose file (`docker-compose.yml`/`yaml`,
 `compose.yml`/`yaml`) must sit at the directory root, or at the root of the ZIP. A ZIP that wraps
 the project in one folder is unwrapped. Pass one directory or `--zip`, not both.
 
-### `ghostdock sandboxes files upload`
+### `ghostdock vm file upload`
 
-`sandboxes files upload` is convenient for small payloads. For a local directory,
+`vm file upload` is convenient for small payloads. For a local directory,
 multiple files, or a large ZIP, use the dedicated multipart upload command instead:
 
 ```bash
-ghostdock sandboxes files upload quiet-harbor ./dist
-ghostdock sandboxes files upload quiet-harbor ./index.html ./assets
-ghostdock sandboxes files upload quiet-harbor --zip ./site.zip
-ghostdock sandboxes files upload quiet-harbor ./dist --container web --start
+ghostdock vm file upload quiet-harbor ./dist
+ghostdock vm file upload quiet-harbor ./index.html ./assets
+ghostdock vm file upload quiet-harbor --zip ./site.zip
+ghostdock vm file upload quiet-harbor ./dist --container web --start
 ```
 
 Each positional path may be a file or directory. Directory contents are uploaded recursively,
-preserving their relative paths; a file is uploaded by its basename. A `sandboxes files upload` call needs
-at least one path or `--zip`. Uploading to a stopped sandbox resumes it automatically.
-The files land in a container as the other `files` commands do (see
-[Containers in a sandbox](#containers-in-a-sandbox)): `--container <name>`, else the default,
+preserving their relative paths; a file is uploaded by its basename. A `vm file upload` call needs
+at least one path or `--zip`. Uploading to a stopped VM resumes it automatically.
+The files land in a container as the other `vm file` commands do (see
+[Containers in a VM](#containers-in-a-vm)): `--container <name>`, else the default,
 else the one running, and the CLI asks which one when it cannot tell. A stopped target container
 is started after a "Start it?" at the keyboard, or at once with `--start`.
 
 ### `ghostdock env`
 
-Manage the environment variables and secrets an organization offers to its sandboxes and projects.
-A sandbox inherits nothing automatically — select the entries it needs on that sandbox.
+Manage the environment variables and secrets an organization offers to its VMs and projects.
+A VM inherits nothing automatically — select the entries it needs on that VM.
 
 ```bash
 ghostdock env list --org org_123
@@ -504,42 +505,42 @@ With `--json`, `list`, `get` and `set` print the tool's result instead. These co
 `env list`, `env get`, `env set` and
 `env delete` tools, which are also available directly (and over MCP).
 
-Names must be valid environment variable names, and names the sandbox runtime owns (`PATH`,
+Names must be valid environment variable names, and names the VM runtime owns (`PATH`,
 `HOME`, anything starting with `GHOSTDOCK_`, …) are rejected. Prefix a name with `VITE_`
 only when browser code must read it: Vite inlines those into the published bundle, so a `VITE_`
 secret is public.
 
 ### `ghostdock network`
 
-Reach your organizations' sandboxes from this machine by private address and name, over
+Reach your organizations' VMs from this machine by private address and name, over
 WireGuard ([ADR 0027](../../docs/adr/0027-private-sandbox-network.md)). Everything on a
-sandbox's address is reachable: a container that publishes port 80 answers on
-`http://quiet-harbor.acme.ghostdock.internal/`, as it would on `localhost` inside the sandbox.
-Nothing reaches your machine from a sandbox.
+VM's address is reachable: a container that publishes port 80 answers on
+`http://quiet-harbor.acme.ghostdock.internal/`, as it would on `localhost` inside the VM.
+Nothing reaches your machine from a VM.
 
 ```bash
 ghostdock network connect              # your organization's default provider; sudo once
 ghostdock network connect helsinki     # or name a provider (name or id)
-ghostdock network ls --org acme        # sandboxes, addresses, names, and what is reachable
+ghostdock network ls --org acme        # VMs, addresses, names, and what is reachable
 curl http://quiet-harbor.acme.ghostdock.internal:8080/
 open https://quiet-harbor--acme.ghostdock.net:8080/   # in a browser: HTTPS, any port
 open https://quiet-harbor.ghostdock.net:8080/         # the short name, for the connect organization
-ghostdock network connect --org beta   # short names now mean beta's sandboxes
+ghostdock network connect --org beta   # short names now mean beta's VMs
 ghostdock network status
 ghostdock network disconnect
 ```
 
-- **One provider at a time.** Each sandbox provider is its own gateway, and a device reaches
-  only the sandboxes on the provider it connected through. Without an argument, `connect` takes
-  the organization (`--org`, `GHOSTDOCK_ORG`, the default from `organizations use`) and its
-  default sandbox provider, else the platform default. Connecting through another provider
+- **One provider at a time.** Each provider is its own gateway, and a device reaches
+  only the VMs on the provider it connected through. Without an argument, `connect` takes
+  the organization (`--org`, `GHOSTDOCK_ORG`, the default from `organization use`) and its
+  default provider, else the platform default. Connecting through another provider
   replaces the connection: same interface and address, new gateway. `network status` says which
-  provider you are connected through; `network ls` marks sandboxes elsewhere as
+  provider you are connected through; `network ls` marks VMs elsewhere as
   `not reachable: on <provider>` with the `connect` command that reaches them. A provider
   without a private network (Incus, for now) is refused by the server; one your organization
   may not use answers 403.
 - **Needs `wg-quick`** (`brew install wireguard-tools`, `apt install wireguard-tools`). macOS
-  and Linux. On Windows, run the CLI in WSL: then only tools inside WSL reach sandboxes.
+  and Linux. On Windows, run the CLI in WSL: then only tools inside WSL reach VMs.
 - **Tunnel MTU 1280**, so the tunnel works on networks with a smaller path than 1500 bytes
   (DS-Lite, VPNs, mobile). A config written before 2026-10-20 has 1420: `network status` and
   `network ls` then say *This machine's tunnel has MTU 1420, the network now uses 1280*. Run
@@ -547,32 +548,32 @@ ghostdock network disconnect
 - **One key per machine**, kept in `~/.config/ghostdock/network/`.
   Only the public key is sent. The device belongs to the login it was connected with:
   `ghostdock logout` takes it out of the network, and so does not connecting for 90 days.
-- **Names**: `<sandbox>.<org>.ghostdock.internal`, for every organization you are a member
+- **Names**: `<vm>.<org>.ghostdock.internal`, for every organization you are a member
   of. A name always says its organization, so a browser origin never changes hands between
-  organizations. Only AAAA records exist: the network is IPv6, and the sandbox sees IPv4.
-- **In a browser**, use the HTTPS name `https://<sandbox>--<org>.ghostdock.net:<port>`
+  organizations. Only AAAA records exist: the network is IPv6, and the VM sees IPv4.
+- **In a browser**, use the HTTPS name `https://<vm>--<org>.ghostdock.net:<port>`
   (`network ls` shows it): any port, a real certificate, so the page is a secure context
   (clipboard, `Secure` cookies, service workers). The host's `gdo-ingress` terminates TLS and
-  forwards to the sandbox's port; it serves only devices of the sandbox's organization, and
+  forwards to the VM's port; it serves only devices of the VM's organization, and
   refuses background requests (fetch, forms, iframes, websockets) from pages outside that
   organization; pages on another HTTPS name of the same organization, any port, may call it. The
-  sandbox sees the request from `198.18.0.0`, and your device's address in
+  VM sees the request from `198.18.0.0`, and your device's address in
   `X-Forwarded-For`. The desktop image's Desktop opens only this way, never on the raw
   address.
-- **Short names** in a browser: `https://<sandbox>.ghostdock.net:<port>` means the sandbox of
+- **Short names** in a browser: `https://<vm>.ghostdock.net:<port>` means the VM of
   this machine's organization: the one `network connect` resolved (`--org`, `GHOSTDOCK_ORG`,
-  the default from `organizations use`). `connect` says which; `network status` too, and
-  `network ls` shows a sandbox's short name next to its full one when it is that
+  the default from `organization use`). `connect` says which; `network status` too, and
+  `network ls` shows a VM's short name next to its full one when it is that
   organization's. With one organization you need nothing else. To use another organization's
   short names, connect again with `--org <other>`: there is no other way to change it, so a
   short name never changes meaning behind your back (`cd` into another project does not
-  change it). Full names (`<sandbox>--<org>`) keep working for every organization and never
+  change it). Full names (`<vm>--<org>`) keep working for every organization and never
   change meaning: use them in scripts, CI, `.env` files and links you share.
   - **When the organization changes,** each short-name site clears its browser data once
-    (local storage, cache, cookies) before the other organization's sandbox sees a request, so
+    (local storage, cache, cookies) before the other organization's VM sees a request, so
     it never reads the first one's data. Cookies are cleared for the whole site, not only the
     short name: every site under the net domain's registrable domain (`ghostdock.net`: every
-    sandbox app there, full names included; a net domain under the app's domain, as on staging:
+    VM app there, full names included; a net domain under the app's domain, as on staging:
     the Ghostdock app too). `connect` names the site when the organization changes. A tab opened on a short name before the
     change keeps the old page until you reload it: reload or close those tabs (`connect` says
     so). The page *Switching organization* is that clearing and reloads by itself; *Clear this
@@ -586,17 +587,17 @@ ghostdock network disconnect
   `308` to `https://quiet-harbor--acme.ghostdock.net:3000/app`. Any other browser request on
   the raw address (`fetch`, images, scripts, forms, websockets) gets `403` with
   `X-Ghostdock-Blocked: browser-https-only` and the HTTPS address in the body. This keeps
-  websites you visit while connected from using your connection against your sandboxes,
+  websites you visit while connected from using your connection against your VMs,
   including through DNS rebinding.
   - **What counts as a browser:** a `User-Agent` that starts with `Mozilla/`, which every
     browser sends on its own requests. Browsers send no `Sec-Fetch-*` headers over plain
     `http://` to an address like this, so those cannot be the signal. (Firefox lets a page
     set its own `User-Agent` on a `fetch`; the `Host` check below stops that one.) Tools that send a
     browser's `User-Agent` (Playwright, Puppeteer, their request APIs) count as browsers too:
-    point them at the HTTPS name. A frontend outside the sandbox (a dev server on your laptop)
-    calls the sandbox's API by its HTTPS name as well.
+    point them at the HTTPS name. A frontend outside the VM (a dev server on your laptop)
+    calls the VM's API by its HTTPS name as well.
   - **Tools** (`curl`, SDKs, test runners, Prometheus) pass untouched, and every other
-    protocol does too, as long as they address the sandbox by its IP address, its
+    protocol does too, as long as they address the VM by its IP address, its
     `.internal` name (or a container's, `web.quiet-harbor.acme.ghostdock.internal`), or
     `localhost`: any other `Host` gets `421` (`X-Ghostdock-Blocked: host-not-allowed`). That
     check is what stops DNS rebinding for a page that sets its own `User-Agent`. A name of
@@ -604,17 +605,17 @@ ghostdock network disconnect
   - **One difference for tools:** a port where nothing listens accepts the connection and
     then resets it, so port checks such as `nc -z` report it open; check with a real request
     instead.
-  - **In the sandbox,** firewall rules for these clients belong in the input path
+  - **In the VM,** firewall rules for these clients belong in the input path
     (`iptables -A INPUT`, an nft `hook input` chain): `FORWARD` and `DOCKER-USER` rules no
     longer see them, because the guard connects to a published container port from inside
     the VM.
 - **The network pause** ([ADR 0033](../../docs/adr/0033-gdo-net-dead-mans-switch.md)): a
-  device that sent no traffic to a sandbox for its idle timeout (default 4 h), or whose session
+  device that sent no traffic to a VM for its idle timeout (default 4 h), or whose session
   since the last connect reached its maximum (default 12 h), is paused at the gateway. Your
   organizations set both (Settings → Security). If you are in several, the strictest value
   applies. `connect` ends with this device's own numbers and names the organization that set a
   stricter one.
-  - **While paused**, names still resolve, but every port of a sandbox answers `Connection
+  - **While paused**, names still resolve, but every port of a VM answers `Connection
     refused`, and UDP and ping get *administratively prohibited*. Browsers get a pause page
     with a *Reconnect* button, and Docker gets `Ghostdock: network access for this device is
     paused (idle 4 h)`. Every `ghostdock` command prints `! Network access for this device is
@@ -635,7 +636,7 @@ ghostdock network disconnect
 
 ### `ghostdock docker context`
 
-Point your own `docker` and `docker compose` at a sandbox's Docker engine, over the private
+Point your own `docker` and `docker compose` at a VM's Docker engine, over the private
 network with mutual TLS ([ADR 0032](../../docs/adr/0032-docker-api-over-gdo-net.md)). Connect
 first: the context uses this machine's device.
 
@@ -651,8 +652,8 @@ docker compose up -d
 ghostdock docker context north-pier --no-use   # create only: docker --context ghostdock-acme-north-pier ps
 ```
 
-- **One Docker context per sandbox**, `ghostdock-<org>-<sandbox>`, for
-  `tcp://<sandbox>.<org>.ghostdock.internal:2376`. Running the command again updates it;
+- **One Docker context per VM**, `ghostdock-<org>-<vm>`, for
+  `tcp://<vm>.<org>.ghostdock.internal:2376`. Running the command again updates it;
   without `--no-use` it also becomes Docker's current context (`docker context use`). A
   `DOCKER_HOST` or `DOCKER_CONTEXT` in your shell wins over that: the command says so.
 - **One client certificate per organization and machine**, in
@@ -663,25 +664,25 @@ ghostdock docker context north-pier --no-use   # create only: docker --context g
 - **Renewal:** `ghostdock network connect` and `ghostdock docker context` renew every
   certificate of this machine with less than 10 days left, and update the contexts they wrote
   (`~/.config/ghostdock/docker/contexts.json`). An expired certificate fails Docker's TLS
-  handshake with Docker's own error: run `ghostdock docker context <sandbox>` again.
+  handshake with Docker's own error: run `ghostdock docker context <vm>` again.
 - **`no such host`** on a `ghostdock.internal` address means this machine is not connected:
   run `ghostdock network connect`. The context's description in `docker context ls` says so
   too.
 - **Renamed organization:** the context's host keeps the old name, which stops resolving. Run
-  `ghostdock docker context <sandbox>` again to update the host.
-- **Only from this device:** the sandbox checks every request with the app (membership, device,
+  `ghostdock docker context <vm>` again to update the host.
+- **Only from this device:** the VM checks every request with the app (membership, device,
   the network pause). A copied key and certificate do not work from another machine; a refusal
   comes back as Docker's `Error response from daemon: Ghostdock: …` with what to run.
-- **Warnings:** a sandbox on another provider than this machine's connection (with the
-  `network connect` command that reaches it), and a sandbox whose base image is too old for
-  Docker over the network (restart it to update). A sandbox that cannot have a Docker engine
+- **Warnings:** a VM on another provider than this machine's connection (with the
+  `network connect` command that reaches it), and a VM whose base image is too old for
+  Docker over the network (restart it to update). A VM that cannot have a Docker engine
   over the network (its provider has no private network, it has no address there yet, or a
   name that is not a DNS label) gets no context, and the command says why.
-- **A stopped sandbox** gets its context too: the first connection to it starts it (wake on
+- **A stopped VM** gets its context too: the first connection to it starts it (wake on
   SYN), and its Docker engine answers once it runs. A start that takes longer than Docker's
   32 s dial timeout fails that one command with Docker's `i/o timeout`; the next one works.
 - **Needs Docker's CLI** (`docker` on `PATH`: Docker Desktop, OrbStack, or the CLI alone). The
-  Docker engine itself runs in the sandbox.
+  Docker engine itself runs in the VM.
 
 ## Command index
 
@@ -689,17 +690,17 @@ Every command with its arguments and what it does. Run `ghostdock <command> --he
 or read [`cli-reference.md`](cli-reference.md) for every command's full description and flags.
 
 <!-- generated:command-index:start (bun run sync:cli-reference; do not edit) -->
-#### apps
+#### app
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock apps list [flags]` | List the live published apps (sites) of an organization, with their URLs. |
+| `ghostdock app list [flags]` | List the live published apps (sites) of an organization, with their URLs. |
 
 #### docker
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock docker context <sandbox> [flags]` | Point Docker at a sandbox's Docker engine over the private network: plain… |
+| `ghostdock docker context <vm> [flags]` | Point Docker at a VM's Docker engine over the private network: plain `docker`… |
 
 #### env
 
@@ -710,18 +711,18 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `ghostdock env list [flags]` | List variables and secrets. |
 | `ghostdock env set <name> [flags]` | Create or replace a variable or secret. |
 
-#### images
+#### image
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock images add --ref <string> [flags]` | Bookmark an OCI image ref in the organization’s image catalog. |
-| `ghostdock images add-compose --name <string> [flags]` | Add a Compose project to the organization’s image catalog. |
-| `ghostdock images add-dockerfile --name <string> --dockerfile <string> [flags]` | Add a Dockerfile to the organization’s image catalog. |
-| `ghostdock images get <image-id> [flags]` | Get one catalog image with its spec, manifest and requirements. |
-| `ghostdock images list [flags]` | List the images an organization can boot sandboxes from. |
-| `ghostdock images remove <image-id> [flags]` | Remove an image from the organization’s catalog. |
-| `ghostdock images update-compose <image-id> [flags]` | Replace a catalog Compose image’s files, reference, override and/or name. |
-| `ghostdock images update-dockerfile <image-id> --dockerfile <string> [flags]` | Replace a catalog Dockerfile, optionally renaming it. |
+| `ghostdock image add --ref <string> [flags]` | Bookmark an OCI image ref in the organization’s image catalog. |
+| `ghostdock image add-compose --name <string> [flags]` | Add a Compose project to the organization’s image catalog. |
+| `ghostdock image add-dockerfile --name <string> --dockerfile <string> [flags]` | Add a Dockerfile to the organization’s image catalog. |
+| `ghostdock image get <image-id> [flags]` | Get one catalog image with its spec, manifest and requirements. |
+| `ghostdock image list [flags]` | List the images an organization can boot VMs from. |
+| `ghostdock image remove <image-id> [flags]` | Remove an image from the organization’s catalog. |
+| `ghostdock image update-compose <image-id> [flags]` | Replace a catalog Compose image’s files, reference, override and/or name. |
+| `ghostdock image update-dockerfile <image-id> --dockerfile <string> [flags]` | Replace a catalog Dockerfile, optionally renaming it. |
 
 #### login
 
@@ -743,44 +744,44 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `ghostdock network devices <command>` | Your devices in the private network. |
 | `ghostdock network devices remove <id>` | Remove one of your devices from the private network. |
 | `ghostdock network disconnect` | Take this machine out of the private network, and remove split DNS an earlier… |
-| `ghostdock network ls [flags]` | Sandboxes of an organization with their private addresses and names, and which… |
+| `ghostdock network ls [flags]` | VMs of an organization with their private addresses and names, and which are… |
 | `ghostdock network status` | Whether this machine is connected, through which provider, and as which device. |
 
-#### organizations
+#### organization
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock organizations current [flags]` | Show which organization commands use, and where it comes from. |
-| `ghostdock organizations list` | List the organizations you belong to, with their ids and slugs. |
-| `ghostdock organizations use [org] [flags]` | Set the default organization for commands run without --org (in every… |
+| `ghostdock organization current [flags]` | Show which organization commands use, and where it comes from. |
+| `ghostdock organization list` | List the organizations you belong to, with their ids and slugs. |
+| `ghostdock organization use [org] [flags]` | Set the default organization for commands run without --org (in every… |
 
-#### projects
+#### project
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock projects create --display-name <string> [flags]` | Create an empty project. |
-| `ghostdock projects deployments get <deployment-id> --project-id <string> [flags]` | Get one deploy attempt, with links to its stored files. |
-| `ghostdock projects deployments list <project-id> [flags]` | List a project’s deploy attempts, newest first. |
-| `ghostdock projects env delete <name> --project-id <string> [flags]` | Delete one of a project’s own variables or secrets. |
-| `ghostdock projects env get <project-id> [flags]` | Get a project’s stored environment. |
-| `ghostdock projects env select <project-id> --environment <array> [flags]` | Replace the organization entries a project exports. |
-| `ghostdock projects env set <name> --project-id <string> --value <string> --kind <string> [flags]` | Create or replace one of a project’s own variables or secrets. |
-| `ghostdock projects get <project-id> [flags]` | Get a project with its latest attempt and live deployment. |
-| `ghostdock projects list [flags]` | List an organization’s projects. |
-| `ghostdock projects publish [path] [flags]` | Inspect local source with the deploy agent and publish to the CDN or a sandbox. |
-| `ghostdock projects redeploy <project-id> [flags]` | Deploy a project’s stored source again, with its current environment. |
-| `ghostdock projects update <project-id> --display-name <string> [flags]` | Rename a project. |
-
-#### providers
+| `ghostdock project create --display-name <string> [flags]` | Create an empty project. |
+| `ghostdock project deployment get <deployment-id> --project-id <string> [flags]` | Get one deploy attempt, with links to its stored files. |
+| `ghostdock project deployment list <project-id> [flags]` | List a project’s deploy attempts, newest first. |
+| `ghostdock project env delete <name> --project-id <string> [flags]` | Delete one of a project’s own variables or secrets. |
+| `ghostdock project env get <project-id> [flags]` | Get a project’s stored environment. |
+| `ghostdock project env select <project-id> --environment <array> [flags]` | Replace the organization entries a project exports. |
+| `ghostdock project env set <name> --project-id <string> --value <string> --kind <string> [flags]` | Create or replace one of a project’s own variables or secrets. |
+| `ghostdock project get <project-id> [flags]` | Get a project with its latest attempt and live deployment. |
+| `ghostdock project list [flags]` | List an organization’s projects. |
+| `ghostdock project publish [path] [flags]` | Inspect local source with the deploy agent and publish to the CDN or a VM. |
+| `ghostdock project redeploy <project-id> [flags]` | Deploy a project’s stored source again, with its current environment. |
+| `ghostdock project update <project-id> --display-name <string> [flags]` | Rename a project. |
+
+#### provider
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock providers disconnect <sandbox-provider-id> [flags]` | Disconnect one of the organization’s own sandbox providers. |
-| `ghostdock providers list [flags]` | List the sandbox providers an organization can create sandboxes on. |
-| `ghostdock providers rename <sandbox-provider-id> --name <string> [flags]` | Rename one of the organization’s own sandbox providers. |
-| `ghostdock providers set-default <sandbox-provider-id> [flags]` | Set the provider used when a create omits sandboxProviderId. |
-| `ghostdock providers start-incus [flags]` | Start connecting an Incus host as a sandbox provider. |
-| `ghostdock providers verify-incus <sandbox-provider-id> [flags]` | Check or finish connecting an Incus host. |
+| `ghostdock provider disconnect <provider> [flags]` | Disconnect one of the organization’s own providers. |
+| `ghostdock provider list [flags]` | List the providers an organization can create VMs on. |
+| `ghostdock provider rename <provider> --name <string> [flags]` | Rename one of the organization’s own providers. |
+| `ghostdock provider set-default <provider> [flags]` | Set the provider used when a create omits provider. |
+| `ghostdock provider start-incus [flags]` | Start connecting an Incus host as a provider. |
+| `ghostdock provider verify-incus <provider> [flags]` | Check or finish connecting an Incus host. |
 
 #### registry
 
@@ -789,79 +790,38 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `ghostdock registry credentials [flags]` | Print registry host, username, and the one-hour password. |
 | `ghostdock registry login [flags]` | Fetch a one-hour password and run docker login --password-stdin. |
 
-#### sandboxes
+#### site
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock sandboxes build [path] --kind <value> [flags]` | Create a sandbox from a local Dockerfile or Compose directory. |
-| `ghostdock sandboxes commands get <command-id> --sandbox-id <string> --session-id <string> [flags]` | Get a shell command’s status and exit code. |
-| `ghostdock sandboxes commands kill <command-id> --sandbox-id <string> --session-id <string> [flags]` | Interrupt a running shell command. |
-| `ghostdock sandboxes commands logs <command-id> --sandbox-id <string> --session-id <string> [flags]` | Get a page of a shell command’s stdout and stderr. |
-| `ghostdock sandboxes commands run <sandbox-id> --command <string> [flags]` | Run a shell command in a sandbox. |
-| `ghostdock sandboxes containers list <sandbox-id> [flags]` | List the containers of a sandbox, running or not. |
-| `ghostdock sandboxes containers lock <sandbox-id> <container> [flags]` | Lock a container against removal. |
-| `ghostdock sandboxes containers logs <sandbox-id> <container> [flags]` | Read a container’s output, as docker logs does. |
-| `ghostdock sandboxes containers restart <sandbox-id> <container> [flags]` | Restart a container, as docker restart does (stopping as docker stop does). |
-| `ghostdock sandboxes containers start <sandbox-id> <container> [flags]` | Start a stopped container, as docker start does. |
-| `ghostdock sandboxes containers stop <sandbox-id> <container> [flags]` | Stop a container, as docker stop does. |
-| `ghostdock sandboxes containers unlock <sandbox-id> <container> [flags]` | Unlock a container so Docker can remove or recreate it. |
-| `ghostdock sandboxes create --source <object> [flags]` | Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. |
-| `ghostdock sandboxes default-container <sandbox-id> [flags]` | Show, set or clear the sandbox’s default container. |
-| `ghostdock sandboxes delete <sandbox-id> [flags]` | Permanently delete a sandbox and its files. |
-| `ghostdock sandboxes env delete <name> --sandbox-id <string> [flags]` | Delete one of a sandbox’s own variables or secrets. |
-| `ghostdock sandboxes env get <sandbox-id> [flags]` | Get a sandbox’s environment: selections, bindings and local entries. |
-| `ghostdock sandboxes env select <sandbox-id> --environment <array> [flags]` | Replace the organization entries a sandbox exports. |
-| `ghostdock sandboxes env set <name> --sandbox-id <string> --value <string> [flags]` | Create or replace one of a sandbox’s own variables or secrets. |
-| `ghostdock sandboxes files list <sandbox-id> [flags]` | List the files in a sandbox directory. |
-| `ghostdock sandboxes files read <path> --sandbox-id <string> [flags]` | Read a file from a sandbox: utf8 text, or base64 for small binaries. |
-| `ghostdock sandboxes files upload <sandbox-id> [path] [flags]` | Upload local files or directories to a sandbox's container, into its start… |
-| `ghostdock sandboxes list [flags]` | List the sandboxes of an organization, with their lifecycle and deadlines. |
-| `ghostdock sandboxes mcps create <sandbox-id> --name <string> --port <integer> [flags]` | Expose an MCP server running in a sandbox. |
-| `ghostdock sandboxes mcps delete <mcp-id>` | Delete an MCP endpoint of a sandbox. |
-| `ghostdock sandboxes mcps list <sandbox-id> [flags]` | List the MCP endpoints a sandbox exposes (name, port, path, autoWake). |
-| `ghostdock sandboxes mcps update <mcp-id> [flags]` | Change an MCP endpoint’s name, port, path or autoWake setting. |
-| `ghostdock sandboxes resize <sandbox-id> [flags]` | Change a sandbox’s CPU and/or memory. |
-| `ghostdock sandboxes resize-disk <sandbox-id> --disk-gib <number> [flags]` | Grow a sandbox’s disk. |
-| `ghostdock sandboxes shells close <session-id> --sandbox-id <string> [flags]` | Close a shell session. |
-| `ghostdock sandboxes shells create <sandbox-id> [flags]` | Open a shell session that keeps cwd and environment between commands. |
-| `ghostdock sandboxes ssh get <sandbox-id> [flags]` | Get temporary SSH access to a sandbox (command and token, 60 minutes). |
-| `ghostdock sandboxes ssh revoke <sandbox-id> [flags]` | Revoke a sandbox’s active SSH access. |
-| `ghostdock sandboxes status <sandbox-id> [flags]` | Get a sandbox’s status and lifecycle deadlines without waking it. |
-| `ghostdock sandboxes stop <sandbox-id> [flags]` | Stop a running sandbox without deleting its files. |
-| `ghostdock sandboxes storage delete <sandbox-id> --kind <string> --name <string> [flags]` | Delete a named volume or a top-level sandbox folder, with everything in it. |
-| `ghostdock sandboxes storage list <sandbox-id> [flags]` | List a sandbox’s volumes and sandbox folders. |
-| `ghostdock sandboxes tools call <name> --sandbox-id <string> --arguments <object> [flags]` | Call a tool on an MCP server inside a sandbox. |
-| `ghostdock sandboxes tools list <sandbox-id> [flags]` | List the tools of the MCP servers a sandbox exposes. |
-| `ghostdock sandboxes update <sandbox-id> [flags]` | Change a sandbox’s display name, idle-stop interval or lifecycle. |
-| `ghostdock sandboxes urls create <sandbox-id> --port <integer> [flags]` | Expose a sandbox port as a URL. |
-| `ghostdock sandboxes urls delete <url-id>` | Delete a sandbox URL. |
-| `ghostdock sandboxes urls list <sandbox-id> [flags]` | List the URLs that expose a sandbox’s ports, with protocol, access and title. |
-| `ghostdock sandboxes urls update <url-id> [flags]` | Change a sandbox URL’s port, protocol, autoWake, public setting or title. |
-| `ghostdock sandboxes wake <sandbox-id> [flags]` | Start a stopped sandbox, or reset the idle-stop countdown of a running one. |
-
-#### sites
+| `ghostdock site publish [path] [flags]` | Publish a local directory or ZIP to the CDN. |
+| `ghostdock site unpublish <site-id> [flags]` | Take a published static site offline. |
+
+#### skill
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock sites publish [path] [flags]` | Publish a local directory or ZIP to the CDN. |
-| `ghostdock sites unpublish <site-id> [flags]` | Take a published static site offline. |
+| `ghostdock skill get <uri>` | Print one SKILL.md (URI from the discovery index, or a skill name). |
+| `ghostdock skill list` | List the Agent Skills discovery index. |
 
-#### skills
+#### snapshot
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock skills get <uri>` | Print one SKILL.md (URI from the discovery index, or a skill name). |
-| `ghostdock skills list` | List the Agent Skills discovery index. |
+| `ghostdock snapshot create <vm> --name <string> [flags]` | Save a VM’s filesystem as a reusable organization snapshot. |
+| `ghostdock snapshot delete <snapshot-id> [flags]` | Permanently delete an organization snapshot (provider artifact and record). |
+| `ghostdock snapshot get <snapshot-id> [flags]` | Get one snapshot with its manifest and required environment, URLs and MCPs. |
+| `ghostdock snapshot list [flags]` | List the snapshots an organization can boot VMs from. |
+| `ghostdock snapshot update-manifest <snapshot-id> --manifest <object> [flags]` | Replace a snapshot’s manifest (URLs, environment, MCPs). |
 
-#### snapshots
+#### template
 
 | Command | What it does |
 | --- | --- |
-| `ghostdock snapshots create <sandbox-id> --name <string> [flags]` | Save a sandbox’s filesystem as a reusable organization snapshot. |
-| `ghostdock snapshots delete <snapshot-id> [flags]` | Permanently delete an organization snapshot (provider artifact and record). |
-| `ghostdock snapshots get <snapshot-id> [flags]` | Get one snapshot with its manifest and required environment, URLs and MCPs. |
-| `ghostdock snapshots list [flags]` | List the snapshots an organization can boot sandboxes from. |
-| `ghostdock snapshots update-manifest <snapshot-id> --manifest <object> [flags]` | Replace a snapshot’s manifest (URLs, environment, MCPs). |
+| `ghostdock template create --name <string> --title <string> --spec <object> [flags]` | Save a VM create request as a template of the organization. |
+| `ghostdock template delete <template> [flags]` | Delete a template of the organization by its name. |
+| `ghostdock template list [flags]` | List the templates to create a VM from (headless, desktop, nginx, …). |
+| `ghostdock template update <template> [flags]` | Change a template of the organization by its name. |
 
 #### tools
 
@@ -869,6 +829,57 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | --- | --- |
 | `ghostdock tools` | List available agent tools. |
 
+#### vm
+
+| Command | What it does |
+| --- | --- |
+| `ghostdock vm build [path] --kind <value> [flags]` | Create a VM from a local Dockerfile or Compose directory. |
+| `ghostdock vm command get <command-id> --vm <string> --session-id <string> [flags]` | Get a shell command’s status and exit code. |
+| `ghostdock vm command kill <command-id> --vm <string> --session-id <string> [flags]` | Interrupt a running shell command. |
+| `ghostdock vm command logs <command-id> --vm <string> --session-id <string> [flags]` | Get a page of a shell command’s stdout and stderr. |
+| `ghostdock vm command run <vm> --command <string> [flags]` | Run a shell command in a VM. |
+| `ghostdock vm container list <vm> [flags]` | List the containers of a VM, running or not. |
+| `ghostdock vm container lock <vm> <container> [flags]` | Lock a container against removal. |
+| `ghostdock vm container logs <vm> <container> [flags]` | Read a container’s output, as docker logs does. |
+| `ghostdock vm container restart <vm> <container> [flags]` | Restart a container, as docker restart does (stopping as docker stop does). |
+| `ghostdock vm container start <vm> <container> [flags]` | Start a stopped container, as docker start does. |
+| `ghostdock vm container stop <vm> <container> [flags]` | Stop a container, as docker stop does. |
+| `ghostdock vm container unlock <vm> <container> [flags]` | Unlock a container so Docker can remove or recreate it. |
+| `ghostdock vm create --source <object> [flags]` | Create a VM from a snapshot, OCI image, Dockerfile or Compose files. |
+| `ghostdock vm default-container <vm> [flags]` | Show, set or clear the VM’s default container. |
+| `ghostdock vm delete <vm> [flags]` | Permanently delete a VM and its files. |
+| `ghostdock vm env delete <name> --vm <string> [flags]` | Delete one of a VM’s own variables or secrets. |
+| `ghostdock vm env get <vm> [flags]` | Get a VM’s environment: selections, bindings and local entries. |
+| `ghostdock vm env select <vm> --environment <array> [flags]` | Replace the organization entries a VM exports. |
+| `ghostdock vm env set <name> --vm <string> --value <string> [flags]` | Create or replace one of a VM’s own variables or secrets. |
+| `ghostdock vm file list <vm> [flags]` | List the files in a VM directory. |
+| `ghostdock vm file read <path> --vm <string> [flags]` | Read a file from a VM: utf8 text, or base64 for small binaries. |
+| `ghostdock vm file upload <vm> [path] [flags]` | Upload local files or directories to a VM's container, into its start folder… |
+| `ghostdock vm list [flags]` | List the VMs of an organization, with their lifecycle and deadlines. |
+| `ghostdock vm mcp create <vm> --name <string> --port <integer> [flags]` | Expose an MCP server running in a VM. |
+| `ghostdock vm mcp delete <mcp-id>` | Delete an MCP endpoint of a VM. |
+| `ghostdock vm mcp list <vm> [flags]` | List the MCP endpoints a VM exposes (name, port, path, autoWake). |
+| `ghostdock vm mcp update <mcp-id> [flags]` | Change an MCP endpoint’s name, port, path or autoWake setting. |
+| `ghostdock vm resize <vm> [flags]` | Change a VM’s CPU and/or memory. |
+| `ghostdock vm resize-disk <vm> --disk-gib <number> [flags]` | Grow a VM’s disk. |
+| `ghostdock vm shell close <session-id> --vm <string> [flags]` | Close a shell session. |
+| `ghostdock vm shell create <vm> [flags]` | Open a shell session that keeps cwd and environment between commands. |
+| `ghostdock vm ssh get <vm> [flags]` | Get temporary SSH access to a VM (command and token, 60 minutes). |
+| `ghostdock vm ssh revoke <vm> [flags]` | Revoke a VM’s active SSH access. |
+| `ghostdock vm status <vm> [flags]` | Get a VM’s status and lifecycle deadlines without waking it. |
+| `ghostdock vm stop <vm> [flags]` | Stop a running VM without deleting its files. |
+| `ghostdock vm storage delete <vm> --kind <string> --name <string> [flags]` | Delete a named volume or a top-level VM folder, with everything in it. |
+| `ghostdock vm storage list <vm> [flags]` | List a VM’s volumes and VM folders. |
+| `ghostdock vm tool call <name> --vm <string> --arguments <object> [flags]` | Call a tool on an MCP server inside a VM. |
+| `ghostdock vm tool list <vm> [flags]` | List the tools of the MCP servers a VM exposes. |
+| `ghostdock vm up <template> [flags]` | Create a VM from a template by its name: `ghostdock vm up nginx`. |
+| `ghostdock vm update <vm> [flags]` | Change a VM’s display name, idle-stop interval or lifecycle. |
+| `ghostdock vm url create <vm> --port <integer> [flags]` | Expose a VM port as a URL. |
+| `ghostdock vm url delete <url-id>` | Delete a VM URL. |
+| `ghostdock vm url list <vm> [flags]` | List the URLs that expose a VM’s ports, with protocol, access and title. |
+| `ghostdock vm url update <url-id> [flags]` | Change a VM URL’s port, protocol, autoWake, public setting or title. |
+| `ghostdock vm wake <vm> [flags]` | Start a stopped VM, or reset the idle-stop countdown of a running one. |
+
 #### whoami
 
 | Command | What it does |
@@ -884,7 +895,7 @@ and secrets, see [`ghostdock env`](#ghostdock-env).
 | Variable                       | Purpose                                                      | Default                          |
 | ------------------------------- | ------------------------------------------------------------- | --------------------------------- |
 | `GHOSTDOCK_BASE_URL`           | API origin the CLI talks to. Override for local dev / self-hosted instances. | Local/dev builds default to `http://localhost:3000`. npm-published builds default to the production API origin baked at publish time. Override with `--base-url` or this env var. |
-| `GHOSTDOCK_ORG`                | Organization (id or slug) for commands run without `--org`. Takes precedence over the default from `organizations use`. | unset |
+| `GHOSTDOCK_ORG`                | Organization (id or slug) for commands run without `--org`. Takes precedence over the default from `organization use`. | unset |
 | `XDG_CONFIG_HOME`              | Base directory for the CLI's per-machine state (`ghostdock/credentials.json`, `ghostdock/settings.json`, `ghostdock/network/`, `ghostdock/docker/`). | `~/.config` (native Windows: `%APPDATA%`) |
 | `GHOSTDOCK_CREDENTIALS_PATH`   | Absolute path to the credentials file, overriding the default. `settings.json` (the default organization) sits in the same directory, so each credentials file keeps its own default — handy for a second account. | `~/.config/ghostdock/credentials.json` |