ghostdock 0.0.18 → 0.0.19

package/dist/cli-reference.md

@@ -147,7 +147,7 @@ ghostdock images add-compose --name <string> [flags]
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
 | `--name <string>` | Image name, unique in the organization. Required. |
 | `--files <object>` | Compose files by file name. Must include docker-compose.yml/yaml or compose.yml/yaml. (JSON object) |
-| `--reference <string>` | A published Compose project instead of files, e.g. oci://docker.io/ghostdockhq/vm-compose:ubuntu-26.04. |
+| `--reference <string>` | A published Compose project instead of files, e.g. oci://docker.io/ghostdockhq/headless-compose:ubuntu-26.04. |
 | `--override <string>` | With reference: a Compose file merged into it (services, environment, labels). |
 
 MCP tool: `images_add_compose`.
@@ -547,7 +547,7 @@ ghostdock projects publish [path] [flags]
 | `--display-name <value>` | Optional display name. |
 | `--tag <value>` | Optional caller tag (git SHA or free-form label) stored on the deployment. |
 | `--auto-stop-interval-minutes <value>` | Same as `sandboxes create`. Omit for the 20-minute default. Pass -1 to keep it running. 0 is rejected. |
-| `--auto-delete-interval-minutes <value>` | Same as `sandboxes create`. Omit for the 14-day default. Pass 0 to delete the record when it stops, or -1 to keep it. |
+| `--auto-delete-after-days <value>` | Same as `sandboxes create`: days stopped before the record is deleted (0–365). Omit for the 14-day default. Pass 0 to delete the record when it stops. |
 | `--resources <value>` | Same as `sandboxes create`: JSON { cpu, memoryGiB, diskGiB }. |
 | `--environment <value>` | Same as `sandboxes create --environment`: JSON { organization, bindings, local }. Required after awaiting_configuration. |
 | `--auto-wake <value>` | Same as `sandboxes urls create --auto-wake`. Default true for the minted URL. |
@@ -575,10 +575,10 @@ ghostdock projects redeploy <project-id> [flags]
 | `--tag <string>` | Optional caller tag stored on the new deployment. Metadata only. |
 | `--resources <object>` | Compute sizing. For image/dockerfile/compose: layered on platform defaults when omitted. For snapshot: optional override applied via resize after create. (JSON object) |
 | `--auto-stop-interval-minutes <number>` | Minutes of inactivity before the platform worker idle-stops the sandbox. -1 means always on. 0 is rejected. Omit for the platform default. Provider-native timers are optional backup. |
-| `--auto-delete-interval-minutes <number>` | Minutes the sandbox stays stopped before the platform worker deletes the record. 0 deletes it when it stops. -1 keeps it until a person deletes it. Omit for the platform default. Provider-native timers are optional backup. |
+| `--lifecycle <string>` | What may make the sandbox disappear on its own. ephemeral: every stop wipes the VM and its disk, and the next start runs its Compose project again (edits in the project folder kept, everything else gone; locks too). auto_delete (default): a stop keeps the disk, and the record goes autoDeleteAfterDays after the stop. keep: never removed automatically. Omit for the image label ghostdock.ephemeral, else auto_delete. ephemeral is chosen here only. |
+| `--auto-delete-after-days <integer>` | Days the sandbox stays stopped before the platform worker deletes the record (0–365; 0 deletes it when it stops). Omit for the platform default (14). Not with keep. A container a person locked holds it. |
 | `--sandbox-provider-id <string>` | Configured sandbox-provider instance id from providers list (not the provider kind). Omit to use the organization default (the org choice, else the platform default); if that provider lacks a capability this create needs, the first listed provider that accepts new sandboxes and has it is used. When no provider fits, the call fails with a not-configured error. |
 | `--environment <object>` | Environment to give this sandbox. organization: names of organization entries (from env list) to export under their own names. bindings: remap org entries onto slot names ({ name: slot, organization: orgEntryName }). local: sandbox-only variables/secrets to create with the sandbox (kind required for each). Both land as ordinary process environment variables ($NAME / process.env.NAME); a local entry overrides an organization entry of the same name. When booting from an organization snapshot, omit organization/bindings/local to keep manifest env defaults, but still supply every name in requiredEnvironment (via organization, bindings, or local). Otherwise a sandbox gets nothing unless listed here. (JSON object) |
-| `--ephemeral` | Mark the sandbox ephemeral: every stop destroys the machine and the next start boots fresh, while the record, URLs, and settings stay. Omit to use the image label ghostdock.ephemeral, or false when that label is absent. Does not change idle-stop or auto-delete. |
 | `--auto-wake` | Same as urls[].autoWake on sandboxes create. Default true for the minted URL. |
 | `--public` | Same as urls[].public on sandboxes create. Default true for the minted URL. |
 
@@ -843,7 +843,7 @@ Containers of a sandbox’s Docker engine.
 
 ### `ghostdock sandboxes containers list`
 
-List the containers of a sandbox, running or not. Each with state, health, restart policy, ports, Compose project and service, deletion protection, ghostdock.* labels, and which one is the default. A stopped sandbox lists none (it is not started for this).
+List the containers of a sandbox, running or not. Each with state, health, restart policy, ports, Compose project and service, its lock (locked, and whether a person or its ghostdock.lock label decided), ghostdock.* labels, and which one is the default. A stopped sandbox lists none (it is not started for this).
 
 ```
 ghostdock sandboxes containers list <sandbox-id> [flags]
@@ -856,12 +856,12 @@ ghostdock sandboxes containers list <sandbox-id> [flags]
 
 MCP tool: `sandboxes_containers_list`.
 
-### `ghostdock sandboxes containers logs`
+### `ghostdock sandboxes containers lock`
 
-Read a container’s output, as docker logs does. Oldest first, each line with its stream (stdout, stderr) and time. The last tail lines (default 200), or with after only the lines after that time: pass the last line’s time to follow. truncated says lines were left out. A stopped sandbox has none (it is not started for this).
+Lock a container against removal. A locked container cannot be removed, renamed or recreated through Docker (docker rm, compose down, a compose up that would recreate it) until it is unlocked here; start, stop and restart still work. It also pauses the sandbox’s auto-delete. An ephemeral sandbox’s stop still wipes it. Never starts the sandbox: a stopped one gets the lock at its next start.
 
 ```
-ghostdock sandboxes containers logs <sandbox-id> <container> [flags]
+ghostdock sandboxes containers lock <sandbox-id> <container> [flags]
 ```
 
 | Argument | Description |
@@ -869,19 +869,15 @@ ghostdock sandboxes containers logs <sandbox-id> <container> [flags]
 | `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
 | `<container>` | Container, by name. Required. |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
-| `--tail <integer>` | The last N lines (at most 5000). |
-| `--after <string>` | Only lines after this time: the time of the last line already read. |
-| `--follow` | Keep printing new lines until Ctrl-C. |
-| `--timestamps` | Put each line's time in front of it. |
 
-MCP tool: `sandboxes_containers_logs`.
+MCP tool: `sandboxes_containers_lock`.
 
-### `ghostdock sandboxes containers protection`
+### `ghostdock sandboxes containers logs`
 
-Switch a container’s deletion protection on or off. A protected container cannot be removed or recreated (docker rm, compose down) until its protection is off. Starts the sandbox when needed.
+Read a container’s output, as docker logs does. Oldest first, each line with its stream (stdout, stderr) and time. The last tail lines (default 200), or with after only the lines after that time: pass the last line’s time to follow. truncated says lines were left out. A stopped sandbox has none (it is not started for this).
 
 ```
-ghostdock sandboxes containers protection <sandbox-id> <container> --protected <value> [flags]
+ghostdock sandboxes containers logs <sandbox-id> <container> [flags]
 ```
 
 | Argument | Description |
@@ -889,9 +885,12 @@ ghostdock sandboxes containers protection <sandbox-id> <container> --protected <
 | `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
 | `<container>` | Container, by name. Required. |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
-| `--protected` | true: protect it; false: allow removing it. Required. |
+| `--tail <integer>` | The last N lines (at most 5000). |
+| `--after <string>` | Only lines after this time: the time of the last line already read. |
+| `--follow` | Keep printing new lines until Ctrl-C. |
+| `--timestamps` | Put each line's time in front of it. |
 
-MCP tool: `sandboxes_containers_protection`.
+MCP tool: `sandboxes_containers_logs`.
 
 ### `ghostdock sandboxes containers restart`
 
@@ -927,7 +926,7 @@ MCP tool: `sandboxes_containers_start`.
 
 ### `ghostdock sandboxes containers stop`
 
-Stop a container, as docker stop does. It gets its own stop signal, then a kill after its own stop timeout. It stays stopped while the sandbox sleeps and wakes, as Docker keeps a stopped container stopped, unless its restart policy is always. On a stopped sandbox it does nothing (note sandbox_stopped). The container main runs the sandbox: its stop is refused (main_is_the_sandbox), pause the sandbox instead. Deletion protection does not block it. note says when it was the default container or the last one running: then SSH, commands and files have nowhere to land until one runs.
+Stop a container, as docker stop does. It gets its own stop signal, then a kill after its own stop timeout. It stays stopped while the sandbox sleeps and wakes, as Docker keeps a stopped container stopped, unless its restart policy is always. On a stopped sandbox it does nothing (note sandbox_stopped). A lock does not block it. note says when it was the default container or the last one running: then SSH, commands and files have nowhere to land until one runs.
 
 ```
 ghostdock sandboxes containers stop <sandbox-id> <container> [flags]
@@ -941,9 +940,25 @@ ghostdock sandboxes containers stop <sandbox-id> <container> [flags]
 
 MCP tool: `sandboxes_containers_stop`.
 
+### `ghostdock sandboxes containers unlock`
+
+Unlock a container so Docker can remove or recreate it. Also one its image locked with the ghostdock.lock label. Never starts the sandbox: a stopped one gets it at its next start, and an overdue auto-delete it held goes ahead.
+
+```
+ghostdock sandboxes containers unlock <sandbox-id> <container> [flags]
+```
+
+| Argument | Description |
+| --- | --- |
+| `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
+| `<container>` | Container, by name. Required. |
+| `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
+
+MCP tool: `sandboxes_containers_unlock`.
+
 ### `ghostdock sandboxes create`
 
-Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. Inline content only: for a directory or ZIP (Dockerfile COPY/ADD, Compose build files) use `ghostdock sandboxes build`. Snapshots and catalog images can require environment entries, URL ports and MCP names (requiredEnvironment / requiredUrls / requiredMcps); a missing environment entry fails with its names (missingEnvironment), and removing a required URL or MCP fails with them (missingUrls / missingMcps). Returns once the sandbox is running, with `boot`: how long the sandbox (VM) and, when one was started, its container took to start, each in ms. Idle-stop and auto-delete apply (defaults 20 minutes / 14 days). Read the sandboxes skill (`ghostdock skills get sandboxes`) for sources, manifests, lifecycle and providers.
+Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. Inline content only: for a directory or ZIP (Dockerfile COPY/ADD, Compose build files) use `ghostdock sandboxes build`. Snapshots and catalog images can require environment entries, URL ports and MCP names (requiredEnvironment / requiredUrls / requiredMcps); a missing environment entry fails with its names (missingEnvironment), and removing a required URL or MCP fails with them (missingUrls / missingMcps). Every source but a snapshot becomes a Compose project in the sandbox, run once with docker compose up -d; after that Docker is the truth. Returns once the project is up, with `boot`: how long the sandbox (VM) and the project's compose up took, each in ms, and the images it pulled. Idle-stop and auto-delete apply (defaults 20 minutes / 14 days). Read the sandboxes skill (`ghostdock skills get sandboxes`) for sources, manifests, lifecycle and providers.
 
 ```
 ghostdock sandboxes create --source <object> [flags]
@@ -953,14 +968,15 @@ ghostdock sandboxes create --source <object> [flags]
 | --- | --- |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
 | `--display-name <string>` | Display name for the sandbox. Optional. |
-| `--source <object>` | What the sandbox boots from. Required. "image" boots an org catalog row by id ({ id } from images list / images get — images add OCI bookmarks, images add-dockerfile, and images add-compose rows) or any OCI ref ({ ref }); "dockerfile" builds inline Dockerfile text only (ghostdock.* LABEL lines parsed for manifest; this tool has no build directory, so COPY/ADD of local files fails — use the CLI `ghostdock sandboxes build --kind dockerfile` with a directory or ZIP); "compose" boots Docker-in-Docker from the given inline files (must include docker-compose.yml/yaml or compose.yml/yaml; ghostdock.* service labels parsed for manifest). A Compose project that needs extra files is not accepted here — use `ghostdock sandboxes build --kind compose`. "compose" also takes a published Compose project instead of files ({ reference: "oci://…", override? }): it runs through include:, the override merged into it. Image, dockerfile, and compose sources never appear in snapshots list. Published static sites use sites publish (CDN), not a snapshot. (JSON object) Required. |
+| `--source <object>` | What the sandbox boots from. Required. "image" boots an org catalog row by id ({ id } from images list / images get — images add OCI bookmarks, images add-dockerfile, and images add-compose rows) or any OCI ref ({ ref }); "dockerfile" builds inline Dockerfile text only (ghostdock.* LABEL lines parsed for manifest; this tool has no build directory, so COPY/ADD of local files fails — use the CLI `ghostdock sandboxes build --kind dockerfile` with a directory or ZIP); "compose" runs the given inline files with docker compose up -d (must include docker-compose.yml/yaml or compose.yml/yaml; ghostdock.* service labels parsed for manifest). Every source but a snapshot becomes a Compose project in /srv/ghostdock/<sandbox name>, run once; an image is one service named after it, a Dockerfile the service app. A Compose project that needs extra files is not accepted here — use `ghostdock sandboxes build --kind compose`. "compose" also takes a published Compose project instead of files ({ reference: "oci://…", override? }): it runs through include:, the override merged into it. Image, dockerfile, and compose sources never appear in snapshots list. Published static sites use sites publish (CDN), not a snapshot. (JSON object) Required. |
+| `--restart <string>` | Restart policy of the service an image or a Dockerfile becomes, Docker's names: unless-stopped (default), always, on-failure, or no (it does not come back after the sandbox sleeps). Not for Compose: its files set restart:. |
 | `--resources <object>` | Compute sizing. For image/dockerfile/compose: layered on platform defaults when omitted. For snapshot: optional override applied via resize after create. (JSON object) |
 | `--auto-stop-interval-minutes <number>` | Minutes of inactivity before the platform worker idle-stops the sandbox. -1 means always on. 0 is rejected. Omit for the platform default. Provider-native timers are optional backup. |
-| `--auto-delete-interval-minutes <number>` | Minutes the sandbox stays stopped before the platform worker deletes the record. 0 deletes it when it stops. -1 keeps it until a person deletes it. Omit for the platform default. Provider-native timers are optional backup. |
+| `--lifecycle <string>` | What may make the sandbox disappear on its own. ephemeral: every stop wipes the VM and its disk, and the next start runs its Compose project again (edits in the project folder kept, everything else gone; locks too). auto_delete (default): a stop keeps the disk, and the record goes autoDeleteAfterDays after the stop. keep: never removed automatically. Omit for the image label ghostdock.ephemeral, else auto_delete. ephemeral is chosen here only. |
+| `--auto-delete-after-days <integer>` | Days the sandbox stays stopped before the platform worker deletes the record (0–365; 0 deletes it when it stops). Omit for the platform default (14). Not with keep. A container a person locked holds it. |
 | `--sandbox-provider-id <string>` | Configured sandbox-provider instance id from providers list (not the provider kind). Omit to use the organization default (the org choice, else the platform default); if that provider lacks a capability this create needs, the first listed provider that accepts new sandboxes and has it is used. When no provider fits, the call fails with a not-configured error. |
 | `--environment <object>` | Environment to give this sandbox. organization: names of organization entries (from env list) to export under their own names. bindings: remap org entries onto slot names ({ name: slot, organization: orgEntryName }). local: sandbox-only variables/secrets to create with the sandbox (kind required for each). Both land as ordinary process environment variables ($NAME / process.env.NAME); a local entry overrides an organization entry of the same name. When booting from an organization snapshot, omit organization/bindings/local to keep manifest env defaults, but still supply every name in requiredEnvironment (via organization, bindings, or local). Otherwise a sandbox gets nothing unless listed here. (JSON object) |
-| `--ephemeral` | Mark the sandbox ephemeral: every stop destroys the machine and the next start boots fresh, while the record, URLs, and settings stay. Omit to use the image label ghostdock.ephemeral, or false when that label is absent. Does not change idle-stop or auto-delete. |
-| `--image-base <string>` | How the disk is made for one of Ghostdock's VM images: auto (default) clones the host's image base, a disk with the image already on it, when there is one; off always starts from an empty disk that pulls the image. For tests and comparisons; other images always start empty. |
+| `--image-base <string>` | How the disk is made for one of Ghostdock's platform images: auto (default) clones the host's image base, a disk with the image already on it, when there is one; off always starts from an empty disk that pulls the image. For tests and comparisons; other images always start empty. |
 | `--urls <array>` | Changes to the image’s or snapshot’s URLs, keyed by port. Omit for the image URLs as they are; otherwise you get the image URLs plus yours: an entry on the same port replaces that URL completely (omitted fields take their defaults), and { port, remove: true } drops it; removing a port the image does not declare does nothing. A required port cannot be removed. TCP URLs are always public. (JSON array) |
 | `--mcps <array>` | Changes to the image’s or snapshot’s MCP exposures, keyed by name. Omit for the image MCPs as they are; otherwise you get the image MCPs plus yours: an entry with the same name replaces that MCP completely, and { name, remove: true } drops it; removing a name the image does not declare does nothing. A required MCP (requiredMcps) cannot be removed. (JSON array) |
 
@@ -986,7 +1002,7 @@ MCP tool: `sandboxes_default_container`.
 
 ### `ghostdock sandboxes delete`
 
-Permanently delete a sandbox and its files.
+Permanently delete a sandbox and its files. Refused while it has locked containers (sandbox_has_locked_containers, naming them) unless deleteLocked is true.
 
 ```
 ghostdock sandboxes delete <sandbox-id> [flags]
@@ -996,6 +1012,7 @@ ghostdock sandboxes delete <sandbox-id> [flags]
 | --- | --- |
 | `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
+| `--delete-locked` | Delete it with its locked containers. Without it, a locked container refuses the delete. |
 
 MCP tool: `sandboxes_delete`.
 
@@ -1079,7 +1096,7 @@ Files inside a sandbox.
 
 ### `ghostdock sandboxes files list`
 
-List the files in a sandbox directory (default /workspace).
+List the files in a sandbox directory. Default: the container's start folder (its dir).
 
 ```
 ghostdock sandboxes files list <sandbox-id> [flags]
@@ -1090,7 +1107,7 @@ ghostdock sandboxes files list <sandbox-id> [flags]
 | `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
 | `--container <string>` | Container to work in, by name, from sandboxes containers list. Default: the sandbox’s default container, else the one running container. With several running and no default the call fails and lists them. |
-| `--path <string>` | Directory to list. Absolute or relative to /. Defaults to /workspace. |
+| `--path <string>` | Directory to list: absolute, or relative to the container's start folder (its dir: the login user's home, else WORKDIR, else /). Defaults to that folder. |
 | `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_files_list`.
@@ -1105,7 +1122,7 @@ ghostdock sandboxes files read <path> --sandbox-id <string> [flags]
 
 | Argument | Description |
 | --- | --- |
-| `<path>` | File path. Absolute or relative to / (for example /workspace/src/App.vue). Required. |
+| `<path>` | File path: absolute, or relative to the container's start folder (for example src/App.vue). Required. |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
 | `--sandbox-id <string>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
 | `--container <string>` | Container to work in, by name, from sandboxes containers list. Default: the sandbox’s default container, else the one running container. With several running and no default the call fails and lists them. |
@@ -1115,7 +1132,7 @@ MCP tool: `sandboxes_files_read`.
 
 ### `ghostdock sandboxes files upload`
 
-Upload local files or directories to a sandbox using multipart form data.
+Upload local files or directories to a sandbox's container, into its start folder (the login user's home, else WORKDIR, else /).
 
 ```
 ghostdock sandboxes files upload <sandbox-id> [path] [flags]
@@ -1134,7 +1151,7 @@ MCP tool: `sandboxes_files_upload`.
 
 ### `ghostdock sandboxes list`
 
-List the sandboxes of an organization, including whether each is ephemeral. Each has a name (e.g. quiet-harbor), unique in the organization, that every sandbox tool accepts as sandboxId.
+List the sandboxes of an organization, with their lifecycle and deadlines. Each has a name (e.g. quiet-harbor), unique in the organization, that every sandbox tool accepts as sandboxId.
 
 ```
 ghostdock sandboxes list [flags]
@@ -1249,24 +1266,6 @@ ghostdock sandboxes resize-disk <sandbox-id> --disk-gib <number> [flags]
 
 MCP tool: `sandboxes_resize_disk`.
 
-### `ghostdock sandboxes set-boot`
-
-Register a command that starts now and again after every restart. For example bun dev. On Compose it runs after the stack; on a Dockerfile it replaces the image CMD. Snapshots cannot register one. Read the sandbox-boot skill (`ghostdock skills get sandbox-boot`).
-
-```
-ghostdock sandboxes set-boot <sandbox-id> --command <string> [flags]
-```
-
-| Argument | Description |
-| --- | --- |
-| `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
-| `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
-| `--command <string>` | Command to start, e.g. bun dev. Required. |
-| `--cwd <string>` | Directory to run it in. Default /. |
-| `--start` | Also start it now, not only after restarts. Default true. |
-
-MCP tool: `sandboxes_set_boot`.
-
 ### `ghostdock sandboxes shells`
 
 Shell sessions that keep cwd and environment between commands.
@@ -1302,7 +1301,7 @@ ghostdock sandboxes shells create <sandbox-id> [flags]
 | `<sandbox-id>` | Sandbox name (e.g. quiet-harbor) or id, from sandboxes list or sandboxes create. Names are unique within the organization. Required. |
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
 | `--container <string>` | Container to work in, by name, from sandboxes containers list. Default: the sandbox’s default container, else the one running container. With several running and no default the call fails and lists them. |
-| `--session-id <string>` | Id for the new session: a slug; user-cmd, image-cmd and compose are reserved. Omit to generate one. |
+| `--session-id <string>` | Id for the new session: a slug. Omit to generate one. |
 | `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_shells_create`.
@@ -1447,7 +1446,7 @@ MCP tool: `sandboxes_tools_list`.
 
 ### `ghostdock sandboxes update`
 
-Change a sandbox’s display name, idle-stop or auto-delete interval. Omit a field to keep it; null resets it to the platform default.
+Change a sandbox’s display name, idle-stop interval or lifecycle. Omit a field to keep it; null resets it to the platform default. Ephemeral is chosen at create only.
 
 ```
 ghostdock sandboxes update <sandbox-id> [flags]
@@ -1459,7 +1458,8 @@ ghostdock sandboxes update <sandbox-id> [flags]
 | `--org <string>` | Organization id or slug, from organizations list. Ids survive renames; slugs change when the organization is renamed. Defaults to GHOSTDOCK_ORG, then `organizations use`. |
 | `--display-name <string>` | New display name. Null clears it; omit to keep it. |
 | `--auto-stop-interval-minutes <number>` | Minutes of inactivity before the platform worker idle-stops the sandbox. -1 always on. 0 is rejected. Null resets to the platform default. Provider-native timers are optional backup. |
-| `--auto-delete-interval-minutes <number>` | Minutes the sandbox stays stopped before the record is deleted. 0 deletes it when it stops. -1 keeps it. Null resets to the platform default. Provider-native timers are optional backup. |
+| `--lifecycle <string>` | auto_delete: the record goes autoDeleteAfterDays after the sandbox stops. keep: never removed automatically. |
+| `--auto-delete-after-days <integer>` | Days stopped before the record is deleted (0–365; 0 deletes it when it stops). Null writes the platform default. Not with keep. |
 
 MCP tool: `sandboxes_update`.
 

package/dist/cli.md

@@ -799,11 +799,12 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `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 protection <sandbox-id> <container> --protected <value> [flags]` | Switch a container’s deletion protection on or off. |
 | `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. |
@@ -811,17 +812,16 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `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 (default /workspace). |
+| `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 using multipart form data. |
-| `ghostdock sandboxes list [flags]` | List the sandboxes of an organization, including whether each is ephemeral. |
+| `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 set-boot <sandbox-id> --command <string> [flags]` | Register a command that starts now and again after every restart. |
 | `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). |
@@ -832,7 +832,7 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `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 or auto-delete interval. |
+| `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. |

package/dist/index.js

@@ -606,7 +606,7 @@ var GENERATED_TOOL_CATALOG = [
       "sandboxes",
       "create"
     ],
-    description: "Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. Inline content only: for a directory or ZIP (Dockerfile COPY/ADD, Compose build files) use `ghostdock sandboxes build`. Snapshots and catalog images can require environment entries, URL ports and MCP names (requiredEnvironment / requiredUrls / requiredMcps); a missing environment entry fails with its names (missingEnvironment), and removing a required URL or MCP fails with them (missingUrls / missingMcps). Returns once the sandbox is running, with `boot`: how long the sandbox (VM) and, when one was started, its container took to start, each in ms. Idle-stop and auto-delete apply (defaults 20 minutes / 14 days). Read the sandboxes skill for sources, manifests, lifecycle and providers.",
+    description: "Create a sandbox from a snapshot, OCI image, Dockerfile or Compose files. Inline content only: for a directory or ZIP (Dockerfile COPY/ADD, Compose build files) use `ghostdock sandboxes build`. Snapshots and catalog images can require environment entries, URL ports and MCP names (requiredEnvironment / requiredUrls / requiredMcps); a missing environment entry fails with its names (missingEnvironment), and removing a required URL or MCP fails with them (missingUrls / missingMcps). Every source but a snapshot becomes a Compose project in the sandbox, run once with docker compose up -d; after that Docker is the truth. Returns once the project is up, with `boot`: how long the sandbox (VM) and the project's compose up took, each in ms, and the images it pulled. Idle-stop and auto-delete apply (defaults 20 minutes / 14 days). Read the sandboxes skill for sources, manifests, lifecycle and providers.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -744,7 +744,17 @@ var GENERATED_TOOL_CATALOG = [
               additionalProperties: false
             }
           ],
-          description: 'What the sandbox boots from. Required. "image" boots an org catalog row by id ({ id } from images_list / images_get — images_add OCI bookmarks, images_add_dockerfile, and images_add_compose rows) or any OCI ref ({ ref }); "dockerfile" builds inline Dockerfile text only (ghostdock.* LABEL lines parsed for manifest; this tool has no build directory, so COPY/ADD of local files fails — use the CLI `ghostdock sandboxes build --kind dockerfile` with a directory or ZIP); "compose" boots Docker-in-Docker from the given inline files (must include docker-compose.yml/yaml or compose.yml/yaml; ghostdock.* service labels parsed for manifest). A Compose project that needs extra files is not accepted here — use `ghostdock sandboxes build --kind compose`. "compose" also takes a published Compose project instead of files ({ reference: "oci://…", override? }): it runs through include:, the override merged into it. Image, dockerfile, and compose sources never appear in snapshots_list. Published static sites use sites_publish (CDN), not a snapshot.'
+          description: 'What the sandbox boots from. Required. "image" boots an org catalog row by id ({ id } from images_list / images_get — images_add OCI bookmarks, images_add_dockerfile, and images_add_compose rows) or any OCI ref ({ ref }); "dockerfile" builds inline Dockerfile text only (ghostdock.* LABEL lines parsed for manifest; this tool has no build directory, so COPY/ADD of local files fails — use the CLI `ghostdock sandboxes build --kind dockerfile` with a directory or ZIP); "compose" runs the given inline files with docker compose up -d (must include docker-compose.yml/yaml or compose.yml/yaml; ghostdock.* service labels parsed for manifest). Every source but a snapshot becomes a Compose project in /srv/ghostdock/<sandbox name>, run once; an image is one service named after it, a Dockerfile the service app. A Compose project that needs extra files is not accepted here — use `ghostdock sandboxes build --kind compose`. "compose" also takes a published Compose project instead of files ({ reference: "oci://…", override? }): it runs through include:, the override merged into it. Image, dockerfile, and compose sources never appear in snapshots_list. Published static sites use sites_publish (CDN), not a snapshot.'
+        },
+        restart: {
+          description: "Restart policy of the service an image or a Dockerfile becomes, Docker's names: unless-stopped (default), always, on-failure, or no (it does not come back after the sandbox sleeps). Not for Compose: its files set restart:.",
+          type: "string",
+          enum: [
+            "no",
+            "always",
+            "unless-stopped",
+            "on-failure"
+          ]
         },
         resources: {
           type: "object",
@@ -769,9 +779,20 @@ var GENERATED_TOOL_CATALOG = [
           description: "Minutes of inactivity before the platform worker idle-stops the sandbox. -1 means always on. 0 is rejected. Omit for the platform default. Provider-native timers are optional backup.",
           type: "number"
         },
-        autoDeleteIntervalMinutes: {
-          description: "Minutes the sandbox stays stopped before the platform worker deletes the record. 0 deletes it when it stops. -1 keeps it until a person deletes it. Omit for the platform default. Provider-native timers are optional backup.",
-          type: "number"
+        lifecycle: {
+          description: "What may make the sandbox disappear on its own. ephemeral: every stop wipes the VM and its disk, and the next start runs its Compose project again (edits in the project folder kept, everything else gone; locks too). auto_delete (default): a stop keeps the disk, and the record goes autoDeleteAfterDays after the stop. keep: never removed automatically. Omit for the image label ghostdock.ephemeral, else auto_delete. ephemeral is chosen here only.",
+          type: "string",
+          enum: [
+            "ephemeral",
+            "auto_delete",
+            "keep"
+          ]
+        },
+        autoDeleteAfterDays: {
+          description: "Days the sandbox stays stopped before the platform worker deletes the record (0–365; 0 deletes it when it stops). Omit for the platform default (14). Not with keep. A container a person locked holds it.",
+          type: "integer",
+          minimum: 0,
+          maximum: 365
         },
         sandboxProviderId: {
           description: "Configured sandbox-provider instance id from providers_list (not the provider kind). Omit to use the organization default (the org choice, else the platform default); if that provider lacks a capability this create needs, the first listed provider that accepts new sandboxes and has it is used. When no provider fits, the call fails with a not-configured error.",
@@ -859,12 +880,8 @@ var GENERATED_TOOL_CATALOG = [
           },
           additionalProperties: false
         },
-        ephemeral: {
-          description: "Mark the sandbox ephemeral: every stop destroys the machine and the next start boots fresh, while the record, URLs, and settings stay. Omit to use the image label ghostdock.ephemeral, or false when that label is absent. Does not change idle-stop or auto-delete.",
-          type: "boolean"
-        },
         imageBase: {
-          description: "How the disk is made for one of Ghostdock's VM images: auto (default) clones the host's image base, a disk with the image already on it, when there is one; off always starts from an empty disk that pulls the image. For tests and comparisons; other images always start empty.",
+          description: "How the disk is made for one of Ghostdock's platform images: auto (default) clones the host's image base, a disk with the image already on it, when there is one; off always starts from an empty disk that pulls the image. For tests and comparisons; other images always start empty.",
           type: "string",
           enum: [
             "auto",
@@ -1012,7 +1029,7 @@ var GENERATED_TOOL_CATALOG = [
       "sandboxes",
       "list"
     ],
-    description: "List the sandboxes of an organization, including whether each is ephemeral. Each has a name (e.g. quiet-harbor), unique in the organization, that every sandbox tool accepts as sandboxId.",
+    description: "List the sandboxes of an organization, with their lifecycle and deadlines. Each has a name (e.g. quiet-harbor), unique in the organization, that every sandbox tool accepts as sandboxId.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -4515,7 +4532,7 @@ var GENERATED_TOOL_CATALOG = [
           }
         },
         reference: {
-          description: "A published Compose project instead of files, e.g. oci://docker.io/ghostdockhq/vm-compose:ubuntu-26.04.",
+          description: "A published Compose project instead of files, e.g. oci://docker.io/ghostdockhq/headless-compose:ubuntu-26.04.",
           type: "string",
           minLength: 1,
           maxLength: 512,
@@ -4672,7 +4689,7 @@ var GENERATED_TOOL_CATALOG = [
     cliArgs: [
       "sandboxId"
     ],
-    description: "Upload small files or a base64 ZIP to a sandbox. For directories or large ZIPs, use `ghostdock sandboxes files upload`.",
+    description: "Upload small files or a base64 ZIP to a sandbox's container. A relative path lands in the container's start folder (its dir: the login user's home, else WORKDIR, else /), an absolute one where it says; the answer names the absolute paths written and that folder (root). For directories or large ZIPs, use `ghostdock sandboxes files upload`.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -4755,7 +4772,7 @@ var GENERATED_TOOL_CATALOG = [
     cliArgs: [
       "sandboxId"
     ],
-    description: "List the files in a sandbox directory (default /workspace).",
+    description: "List the files in a sandbox directory. Default: the container's start folder (its dir).",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -4778,7 +4795,7 @@ var GENERATED_TOOL_CATALOG = [
           pattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
         },
         path: {
-          description: "Directory to list. Absolute or relative to /. Defaults to /workspace.",
+          description: "Directory to list: absolute, or relative to the container's start folder (its dir: the login user's home, else WORKDIR, else /). Defaults to that folder.",
           type: "string",
           minLength: 1
         }
@@ -4866,7 +4883,7 @@ var GENERATED_TOOL_CATALOG = [
         path: {
           type: "string",
           minLength: 1,
-          description: "File path. Absolute or relative to / (for example /workspace/src/App.vue)."
+          description: "File path: absolute, or relative to the container's start folder (for example src/App.vue)."
         }
       },
       required: [
@@ -6082,7 +6099,7 @@ var GENERATED_TOOL_CATALOG = [
     cliArgs: [
       "sandboxId"
     ],
-    description: "List the containers of a sandbox, running or not. Each with state, health, restart policy, ports, Compose project and service, deletion protection, ghostdock.* labels, and which one is the default. A stopped sandbox lists none (it is not started for this).",
+    description: "List the containers of a sandbox, running or not. Each with state, health, restart policy, ports, Compose project and service, its lock (locked, and whether a person or its ghostdock.lock label decided), ghostdock.* labels, and which one is the default. A stopped sandbox lists none (it is not started for this).",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -6166,18 +6183,18 @@ var GENERATED_TOOL_CATALOG = [
     }
   },
   {
-    id: "sandboxes_containers_protection",
-    name: "sandboxes_containers_protection",
+    id: "sandboxes_containers_lock",
+    name: "sandboxes_containers_lock",
     cli: [
       "sandboxes",
       "containers",
-      "protection"
+      "lock"
     ],
     cliArgs: [
       "sandboxId",
       "container"
     ],
-    description: "Switch a container’s deletion protection on or off. A protected container cannot be removed or recreated (docker rm, compose down) until its protection is off. Starts the sandbox when needed.",
+    description: "Lock a container against removal. A locked container cannot be removed, renamed or recreated through Docker (docker rm, compose down, a compose up that would recreate it) until it is unlocked here; start, stop and restart still work. It also pauses the sandbox’s auto-delete. An ephemeral sandbox’s stop still wipes it. Never starts the sandbox: a stopped one gets the lock at its next start.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -6198,17 +6215,63 @@ var GENERATED_TOOL_CATALOG = [
           maxLength: 255,
           pattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
           description: "Container, by name."
+        }
+      },
+      required: [
+        "organization",
+        "sandboxId",
+        "container"
+      ],
+      additionalProperties: false
+    },
+    outputSchema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      propertyNames: {
+        type: "string"
+      },
+      additionalProperties: {}
+    }
+  },
+  {
+    id: "sandboxes_containers_unlock",
+    name: "sandboxes_containers_unlock",
+    cli: [
+      "sandboxes",
+      "containers",
+      "unlock"
+    ],
+    cliArgs: [
+      "sandboxId",
+      "container"
+    ],
+    description: "Unlock a container so Docker can remove or recreate it. Also one its image locked with the ghostdock.lock label. Never starts the sandbox: a stopped one gets it at its next start, and an overdue auto-delete it held goes ahead.",
+    inputSchema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      properties: {
+        organization: {
+          type: "string",
+          minLength: 1,
+          description: "Organization id or slug, from organizations_list. Ids survive renames; slugs change when the organization is renamed."
         },
-        protected: {
-          type: "boolean",
-          description: "true: protect it; false: allow removing it."
+        sandboxId: {
+          type: "string",
+          minLength: 1,
+          description: "Sandbox name (e.g. quiet-harbor) or id, from sandboxes_list or sandboxes_create. Names are unique within the organization."
+        },
+        container: {
+          type: "string",
+          minLength: 1,
+          maxLength: 255,
+          pattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
+          description: "Container, by name."
         }
       },
       required: [
         "organization",
         "sandboxId",
-        "container",
-        "protected"
+        "container"
       ],
       additionalProperties: false
     },
@@ -6284,7 +6347,7 @@ var GENERATED_TOOL_CATALOG = [
       "sandboxId",
       "container"
     ],
-    description: "Stop a container, as docker stop does. It gets its own stop signal, then a kill after its own stop timeout. It stays stopped while the sandbox sleeps and wakes, as Docker keeps a stopped container stopped, unless its restart policy is always. On a stopped sandbox it does nothing (note sandbox_stopped). The container main runs the sandbox: its stop is refused (main_is_the_sandbox), pause the sandbox instead. Deletion protection does not block it. note says when it was the default container or the last one running: then SSH, commands and files have nowhere to land until one runs.",
+    description: "Stop a container, as docker stop does. It gets its own stop signal, then a kill after its own stop timeout. It stays stopped while the sandbox sleeps and wakes, as Docker keeps a stopped container stopped, unless its restart policy is always. On a stopped sandbox it does nothing (note sandbox_stopped). A lock does not block it. note says when it was the default container or the last one running: then SSH, commands and files have nowhere to land until one runs.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -6827,7 +6890,7 @@ var GENERATED_TOOL_CATALOG = [
           pattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
         },
         sessionId: {
-          description: "Id for the new session: a slug; user-cmd, image-cmd and compose are reserved. Omit to generate one.",
+          description: "Id for the new session: a slug. Omit to generate one.",
           type: "string",
           minLength: 1
         }
@@ -6902,62 +6965,6 @@ var GENERATED_TOOL_CATALOG = [
       additionalProperties: {}
     }
   },
-  {
-    id: "sandboxes_set_boot",
-    name: "sandboxes_set_boot",
-    cli: [
-      "sandboxes",
-      "set-boot"
-    ],
-    cliArgs: [
-      "sandboxId"
-    ],
-    description: "Register a command that starts now and again after every restart. For example bun dev. On Compose it runs after the stack; on a Dockerfile it replaces the image CMD. Snapshots cannot register one. Read the sandbox-boot skill.",
-    inputSchema: {
-      $schema: "https://json-schema.org/draft/2020-12/schema",
-      type: "object",
-      properties: {
-        organization: {
-          type: "string",
-          minLength: 1,
-          description: "Organization id or slug, from organizations_list. Ids survive renames; slugs change when the organization is renamed."
-        },
-        sandboxId: {
-          type: "string",
-          minLength: 1,
-          description: "Sandbox name (e.g. quiet-harbor) or id, from sandboxes_list or sandboxes_create. Names are unique within the organization."
-        },
-        command: {
-          type: "string",
-          minLength: 1,
-          description: "Command to start, e.g. bun dev."
-        },
-        cwd: {
-          description: "Directory to run it in. Default /.",
-          type: "string",
-          minLength: 1
-        },
-        start: {
-          description: "Also start it now, not only after restarts. Default true.",
-          type: "boolean"
-        }
-      },
-      required: [
-        "organization",
-        "sandboxId",
-        "command"
-      ],
-      additionalProperties: false
-    },
-    outputSchema: {
-      $schema: "https://json-schema.org/draft/2020-12/schema",
-      type: "object",
-      propertyNames: {
-        type: "string"
-      },
-      additionalProperties: {}
-    }
-  },
   {
     id: "sandboxes_update",
     name: "sandboxes_update",
@@ -6968,7 +6975,7 @@ var GENERATED_TOOL_CATALOG = [
     cliArgs: [
       "sandboxId"
     ],
-    description: "Change a sandbox’s display name, idle-stop or auto-delete interval. Omit a field to keep it; null resets it to the platform default.",
+    description: "Change a sandbox’s display name, idle-stop interval or lifecycle. Omit a field to keep it; null resets it to the platform default. Ephemeral is chosen at create only.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -7005,11 +7012,21 @@ var GENERATED_TOOL_CATALOG = [
             }
           ]
         },
-        autoDeleteIntervalMinutes: {
-          description: "Minutes the sandbox stays stopped before the record is deleted. 0 deletes it when it stops. -1 keeps it. Null resets to the platform default. Provider-native timers are optional backup.",
+        lifecycle: {
+          description: "auto_delete: the record goes autoDeleteAfterDays after the sandbox stops. keep: never removed automatically.",
+          type: "string",
+          enum: [
+            "auto_delete",
+            "keep"
+          ]
+        },
+        autoDeleteAfterDays: {
+          description: "Days stopped before the record is deleted (0–365; 0 deletes it when it stops). Null writes the platform default. Not with keep.",
           anyOf: [
             {
-              type: "number"
+              type: "integer",
+              minimum: 0,
+              maximum: 365
             },
             {
               type: "null"
@@ -7263,7 +7280,7 @@ var GENERATED_TOOL_CATALOG = [
     cliArgs: [
       "sandboxId"
     ],
-    description: "Permanently delete a sandbox and its files.",
+    description: "Permanently delete a sandbox and its files. Refused while it has locked containers (sandbox_has_locked_containers, naming them) unless deleteLocked is true.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -7277,6 +7294,10 @@ var GENERATED_TOOL_CATALOG = [
           type: "string",
           minLength: 1,
           description: "Sandbox name (e.g. quiet-harbor) or id, from sandboxes_list or sandboxes_create. Names are unique within the organization."
+        },
+        deleteLocked: {
+          description: "Delete it with its locked containers. Without it, a locked container refuses the delete.",
+          type: "boolean"
         }
       },
       required: [
@@ -7321,7 +7342,7 @@ var GENERATED_TOOL_CATALOG = [
           minLength: 1
         },
         directory: {
-          description: "Sandbox directory to upload when files/zip are omitted. Defaults to dist.",
+          description: "Sandbox directory to upload when files/zip are omitted: absolute, or relative to the container's start folder (its dir). Defaults to dist there.",
           type: "string",
           minLength: 1
         },
@@ -7695,9 +7716,20 @@ var GENERATED_TOOL_CATALOG = [
           description: "Minutes of inactivity before the platform worker idle-stops the sandbox. -1 means always on. 0 is rejected. Omit for the platform default. Provider-native timers are optional backup.",
           type: "number"
         },
-        autoDeleteIntervalMinutes: {
-          description: "Minutes the sandbox stays stopped before the platform worker deletes the record. 0 deletes it when it stops. -1 keeps it until a person deletes it. Omit for the platform default. Provider-native timers are optional backup.",
-          type: "number"
+        lifecycle: {
+          description: "What may make the sandbox disappear on its own. ephemeral: every stop wipes the VM and its disk, and the next start runs its Compose project again (edits in the project folder kept, everything else gone; locks too). auto_delete (default): a stop keeps the disk, and the record goes autoDeleteAfterDays after the stop. keep: never removed automatically. Omit for the image label ghostdock.ephemeral, else auto_delete. ephemeral is chosen here only.",
+          type: "string",
+          enum: [
+            "ephemeral",
+            "auto_delete",
+            "keep"
+          ]
+        },
+        autoDeleteAfterDays: {
+          description: "Days the sandbox stays stopped before the platform worker deletes the record (0–365; 0 deletes it when it stops). Omit for the platform default (14). Not with keep. A container a person locked holds it.",
+          type: "integer",
+          minimum: 0,
+          maximum: 365
         },
         sandboxProviderId: {
           description: "Configured sandbox-provider instance id from providers_list (not the provider kind). Omit to use the organization default (the org choice, else the platform default); if that provider lacks a capability this create needs, the first listed provider that accepts new sandboxes and has it is used. When no provider fits, the call fails with a not-configured error.",
@@ -7785,10 +7817,6 @@ var GENERATED_TOOL_CATALOG = [
           },
           additionalProperties: false
         },
-        ephemeral: {
-          description: "Mark the sandbox ephemeral: every stop destroys the machine and the next start boots fresh, while the record, URLs, and settings stay. Omit to use the image label ghostdock.ephemeral, or false when that label is absent. Does not change idle-stop or auto-delete.",
-          type: "boolean"
-        },
         autoWake: {
           description: "Same as urls[].autoWake on sandboxes_create. Default true for the minted URL (sandboxes_urls_create defaults false).",
           type: "boolean"
@@ -8165,9 +8193,20 @@ var GENERATED_TOOL_CATALOG = [
           description: "Minutes of inactivity before the platform worker idle-stops the sandbox. -1 means always on. 0 is rejected. Omit for the platform default. Provider-native timers are optional backup.",
           type: "number"
         },
-        autoDeleteIntervalMinutes: {
-          description: "Minutes the sandbox stays stopped before the platform worker deletes the record. 0 deletes it when it stops. -1 keeps it until a person deletes it. Omit for the platform default. Provider-native timers are optional backup.",
-          type: "number"
+        lifecycle: {
+          description: "What may make the sandbox disappear on its own. ephemeral: every stop wipes the VM and its disk, and the next start runs its Compose project again (edits in the project folder kept, everything else gone; locks too). auto_delete (default): a stop keeps the disk, and the record goes autoDeleteAfterDays after the stop. keep: never removed automatically. Omit for the image label ghostdock.ephemeral, else auto_delete. ephemeral is chosen here only.",
+          type: "string",
+          enum: [
+            "ephemeral",
+            "auto_delete",
+            "keep"
+          ]
+        },
+        autoDeleteAfterDays: {
+          description: "Days the sandbox stays stopped before the platform worker deletes the record (0–365; 0 deletes it when it stops). Omit for the platform default (14). Not with keep. A container a person locked holds it.",
+          type: "integer",
+          minimum: 0,
+          maximum: 365
         },
         sandboxProviderId: {
           description: "Configured sandbox-provider instance id from providers_list (not the provider kind). Omit to use the organization default (the org choice, else the platform default); if that provider lacks a capability this create needs, the first listed provider that accepts new sandboxes and has it is used. When no provider fits, the call fails with a not-configured error.",
@@ -8255,10 +8294,6 @@ var GENERATED_TOOL_CATALOG = [
           },
           additionalProperties: false
         },
-        ephemeral: {
-          description: "Mark the sandbox ephemeral: every stop destroys the machine and the next start boots fresh, while the record, URLs, and settings stay. Omit to use the image label ghostdock.ephemeral, or false when that label is absent. Does not change idle-stop or auto-delete.",
-          type: "boolean"
-        },
         autoWake: {
           description: "Same as urls[].autoWake on sandboxes_create. Default true for the minted URL.",
           type: "boolean"
@@ -9201,7 +9236,7 @@ function dockerContextName(orgSlug, sandboxName) {
   return `ghostdock-${orgSlug}-${sandboxName}`;
 }
 // package.json
-var version = "0.0.18";
+var version = "0.0.19";
 var package_default = {
   name: "ghostdock",
   description: "Ghostdock CLI — device login and agent tool invocation from the command line",
@@ -12242,7 +12277,7 @@ async function runPublishAuto(options, log = console.log, error = printError) {
       form.append("displayName", options.displayName);
     appendOptional(form, "tag", options.tag);
     appendOptional(form, "autoStopIntervalMinutes", options.autoStopIntervalMinutes);
-    appendOptional(form, "autoDeleteIntervalMinutes", options.autoDeleteIntervalMinutes);
+    appendOptional(form, "autoDeleteAfterDays", options.autoDeleteAfterDays);
     appendOptional(form, "resources", options.resources);
     appendOptional(form, "environment", options.environment);
     appendOptional(form, "autoWake", options.autoWake);
@@ -12312,9 +12347,9 @@ var publishAutoCommand = defineCommand({
       type: "string",
       description: "Same as `sandboxes create`. Omit for the 20-minute default. Pass -1 to keep it running. 0 is rejected."
     },
-    "auto-delete-interval-minutes": {
+    "auto-delete-after-days": {
       type: "string",
-      description: "Same as `sandboxes create`. Omit for the 14-day default. Pass 0 to delete the record when it stops, or -1 to keep it."
+      description: "Same as `sandboxes create`: days stopped before the record is deleted (0–365). Omit for the 14-day default. Pass 0 to delete the record when it stops."
     },
     resources: {
       type: "string",
@@ -12364,7 +12399,7 @@ var publishAutoCommand = defineCommand({
       displayName: args["display-name"],
       tag: args.tag,
       autoStopIntervalMinutes: args["auto-stop-interval-minutes"],
-      autoDeleteIntervalMinutes: args["auto-delete-interval-minutes"],
+      autoDeleteAfterDays: args["auto-delete-after-days"],
       resources: args.resources,
       environment: args.environment,
       autoWake: args["auto-wake"],
@@ -13611,7 +13646,7 @@ async function runSandboxUpload(options, log = console.log, error = printError,
     const result = await withContainerPick(call, () => withContainerStart(call, send, options.start === true, pickers, notice), pickers, notice);
     const count = `${result.written.length} file${result.written.length === 1 ? "" : "s"}`;
     printResult(result, () => [
-      eventLine("done", result.container ? `Uploaded ${count} to ${result.container} in ${options.sandboxId}.` : `Uploaded ${count} to ${options.sandboxId}.`)
+      eventLine("done", result.container ? `Uploaded ${count} to ${result.root} in ${result.container} (${options.sandboxId}).` : `Uploaded ${count} to ${result.root} in ${options.sandboxId}.`)
     ], log);
     return 0;
   } catch (err) {
@@ -13626,7 +13661,7 @@ async function runSandboxUpload(options, log = console.log, error = printError,
 var sandboxUploadCommand = defineCommand({
   meta: {
     name: "upload",
-    description: "Upload local files or directories to a sandbox using multipart form data."
+    description: "Upload local files or directories to a sandbox's container, into its start folder (the login user's home, else WORKDIR, else /)."
   },
   args: {
     "sandbox-id": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ghostdock",
   "description": "Ghostdock CLI — device login and agent tool invocation from the command line",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "type": "module",
   "bin": {
     "ghostdock": "dist/index.js",