ghostdock 0.0.17 → 0.0.19

package/dist/cli-reference.md

@@ -28,6 +28,24 @@ ghostdock apps list [flags]
 
 MCP tool: `apps_list`.
 
+## `ghostdock docker`
+
+Docker over the private network: a sandbox's Docker engine from this machine.
+
+### `ghostdock docker context`
+
+Point Docker at a sandbox's Docker engine over the private network: plain `docker` and `docker compose` then run there. Creates (or updates) the Docker context ghostdock-<org>-<sandbox> for tcp://<sandbox>.<org>.ghostdock.internal:2376 with a client certificate of this machine's device, and makes it the current context. Needs `ghostdock network connect` first, and Docker's CLI. The certificate lives 30 days; `network connect` and this command renew it with 10 days left. An expired certificate fails Docker's TLS handshake with Docker's own error: run this command again. Docker's `no such host` on a ghostdock.internal address means this machine is not connected: run `ghostdock network connect`. After an organization rename the old name stops resolving: run it again to update the host.
+
+```
+ghostdock docker context <sandbox> [flags]
+```
+
+| Argument | Description |
+| --- | --- |
+| `<sandbox>` | Sandbox name, from `network ls`. Required. |
+| `--org <value>` | Organization id or slug, from `ghostdock organizations list` (default: GHOSTDOCK_ORG, then `ghostdock organizations use`). |
+| `--use` | Make it the current Docker context (`docker context use`). `--no-use` only creates or updates it. Default: `true`. |
+
 ## `ghostdock env`
 
 Manage organization environment variables and secrets.
@@ -129,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`.
@@ -529,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. |
@@ -557,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. |
 
@@ -825,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]
@@ -838,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 |
@@ -851,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 |
@@ -871,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`
 
@@ -909,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]
@@ -923,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]
@@ -935,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) |
 
@@ -968,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]
@@ -978,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`.
 
@@ -1061,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]
@@ -1072,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`.
@@ -1087,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. |
@@ -1097,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]
@@ -1116,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]
@@ -1231,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.
@@ -1284,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`.
@@ -1429,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]
@@ -1441,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

@@ -97,6 +97,7 @@ 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…
@@ -632,6 +633,56 @@ ghostdock network disconnect
   Without that, names of the private network hang while you are disconnected. `network status`
   says when such a file is still there.
 
+### `ghostdock docker context`
+
+Point your own `docker` and `docker compose` at a sandbox'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.
+
+```bash
+ghostdock network connect
+ghostdock docker context quiet-harbor --org acme
+#   ✓ Docker context ghostdock-acme-quiet-harbor (in use)
+#       tcp://quiet-harbor.acme.ghostdock.internal:2376
+#       Certificate for this device, valid until 2026-11-20.
+#       → docker ps
+docker ps
+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;
+  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
+  `~/.config/ghostdock/docker/<organizationId>/`: `key.pem` (ECDSA P-256, made on this machine,
+  0600; only a certificate request is sent), `cert.pem` and `ca.pem`. The certificate names your
+  user, this machine's device and the organization, and lives 30 days. A new one replaces the
+  earlier one of this device for that organization: the old one stops working at once.
+- **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.
+- **`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,
+  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
+  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
+  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.
+
 ## Command index
 
 Every command with its arguments and what it does. Run `ghostdock <command> --help` for its flags,
@@ -644,6 +695,12 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | --- | --- |
 | `ghostdock apps 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… |
+
 #### env
 
 | Command | What it does |
@@ -742,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. |
@@ -754,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). |
@@ -775,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. |
@@ -828,7 +885,7 @@ and secrets, see [`ghostdock env`](#ghostdock-env).
 | ------------------------------- | ------------------------------------------------------------- | --------------------------------- |
 | `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 |
-| `XDG_CONFIG_HOME`              | Base directory for the CLI's per-machine state (`ghostdock/credentials.json`, `ghostdock/settings.json`, `ghostdock/network/`). | `~/.config` (native Windows: `%APPDATA%`) |
+| `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` |
 
 Example for local development against a Nuxt dev server: