ghostdock 0.0.14 → 0.0.16

package/dist/cli-reference.md

@@ -118,17 +118,19 @@ MCP tool: `images_add`.
 
 ### `ghostdock images add-compose`
 
-Add Compose files to the organization’s image catalog. Must include docker-compose.yml/yaml or compose.yml/yaml; ghostdock.* service labels become its manifest. Fails if the name is taken.
+Add a Compose project to the organization’s image catalog. Give its files, or a reference: a Compose project published as an OCI artifact (oci://…), used through include: with an optional override. ghostdock.* service labels (of the files, or of the override) become its manifest. Fails if the name is taken.
 
 ```
-ghostdock images add-compose --name <string> --files <object> [flags]
+ghostdock images add-compose --name <string> [flags]
 ```
 
 | Argument | Description |
 | --- | --- |
-| `--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) 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`. |
+| `--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. |
+| `--override <string>` | With reference: a Compose file merged into it (services, environment, labels). |
 
 MCP tool: `images_add_compose`.
 
@@ -194,7 +196,7 @@ MCP tool: `images_remove`.
 
 ### `ghostdock images update-compose`
 
-Replace a catalog Compose image’s files and/or name. Re-parses its labels.
+Replace a catalog Compose image’s files, reference, override and/or name. Re-parses its labels.
 
 ```
 ghostdock images update-compose <image-id> [flags]
@@ -205,6 +207,8 @@ ghostdock images update-compose <image-id> [flags]
 | `<image-id>` | Catalog image id, from images list or images get. 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`. |
 | `--files <object>` | New Compose files by file name. Omit to keep the current files. (JSON object) |
+| `--reference <string>` | A new reference (oci://…): the image becomes a Compose reference. |
+| `--override <string>` | A reference’s new override; null removes it. |
 | `--name <string>` | New image name. Omit to keep it. |
 
 MCP tool: `images_update_compose`.
@@ -751,6 +755,7 @@ ghostdock sandboxes commands get <command-id> --sandbox-id <string> --session-id
 | `--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. |
 | `--session-id <string>` | Session id returned by sandboxes commands run together with the commandId. Required. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_commands_get`.
 
@@ -769,6 +774,7 @@ ghostdock sandboxes commands kill <command-id> --sandbox-id <string> --session-i
 | `--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. |
 | `--session-id <string>` | Session id returned by sandboxes commands run together with the commandId. Required. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_commands_kill`.
 
@@ -788,6 +794,7 @@ ghostdock sandboxes commands logs <command-id> --sandbox-id <string> --session-i
 | `--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>` | Session id returned by sandboxes commands run together with the commandId. Required. |
 | `--offset <integer>` | Character offset to continue reading from. Default 0. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_commands_logs`.
 
@@ -808,6 +815,7 @@ ghostdock sandboxes commands run <sandbox-id> --command <string> [flags]
 | `--session-id <string>` | Session from sandboxes shells create, to keep cwd and environment from earlier commands. Omit for a one-off session. |
 | `--cwd <string>` | Directory to run the command in. |
 | `--wait-seconds <number>` | Seconds to wait before returning handles to poll: 1 to 120, default 120. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_commands_run`.
 
@@ -830,6 +838,26 @@ ghostdock sandboxes containers list <sandbox-id> [flags]
 
 MCP tool: `sandboxes_containers_list`.
 
+### `ghostdock sandboxes containers logs`
+
+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 logs <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`. |
+| `--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`.
+
 ### `ghostdock sandboxes containers protection`
 
 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.
@@ -847,6 +875,54 @@ ghostdock sandboxes containers protection <sandbox-id> <container> --protected <
 
 MCP tool: `sandboxes_containers_protection`.
 
+### `ghostdock sandboxes containers restart`
+
+Restart a container, as docker restart does (stopping as docker stop does). Starts the sandbox when needed.
+
+```
+ghostdock sandboxes containers restart <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_restart`.
+
+### `ghostdock sandboxes containers start`
+
+Start a stopped container, as docker start does. A running container stays as it is. Starts the sandbox when needed.
+
+```
+ghostdock sandboxes containers start <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_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.
+
+```
+ghostdock sandboxes containers stop <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_stop`.
+
 ### `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.
@@ -859,7 +935,7 @@ 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`. 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" 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. |
 | `--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. |
@@ -885,6 +961,7 @@ ghostdock sandboxes default-container <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`. |
 | `--container <string>` | Container to make the default, by name. The running sandbox must have it. |
 | `--clear` | Clear the default. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_default_container`.
 
@@ -995,6 +1072,7 @@ ghostdock sandboxes files list <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`. |
 | `--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. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_files_list`.
 
@@ -1012,6 +1090,7 @@ ghostdock sandboxes files read <path> --sandbox-id <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`. |
 | `--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. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_files_read`.
 
@@ -1027,6 +1106,8 @@ ghostdock sandboxes files upload <sandbox-id> [path] [flags]
 | --- | --- |
 | `<sandbox-id>` | Sandbox name or id. Required. |
 | `--org <value>` | Organization id or slug, from `ghostdock organizations list` (default: GHOSTDOCK_ORG, then `ghostdock organizations use`). |
+| `--container <value>` | Container the files land in, by name, from `ghostdock sandboxes containers list`. Default: the sandbox's default container, else the one running container. |
+| `--start` | Start the container first when it is not running, without asking. |
 | `--zip <value>` | Local ZIP file to upload. |
 | `<path>` | File or directory to upload (additional paths are allowed). |
 
@@ -1185,6 +1266,7 @@ ghostdock sandboxes shells close <session-id> --sandbox-id <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`. |
 | `--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. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_shells_close`.
 
@@ -1202,6 +1284,7 @@ ghostdock sandboxes shells create <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`. |
 | `--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. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_shells_create`.
 
@@ -1222,6 +1305,7 @@ ghostdock sandboxes ssh get <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. |
+| `--start` | Start the container first when it is not running, without asking. |
 
 MCP tool: `sandboxes_ssh_get`.
 
@@ -1270,6 +1354,40 @@ ghostdock sandboxes stop <sandbox-id> [flags]
 
 MCP tool: `sandboxes_stop`.
 
+### `ghostdock sandboxes storage`
+
+### `ghostdock sandboxes storage delete`
+
+Delete a named volume or a top-level sandbox folder, with everything in it. Refused while a container mounts it (in any state: a stopped one counts, so stopping does not help), mounts a folder above it (a bind of /), or a volume keeps its data in the folder: remove those first.
+
+```
+ghostdock sandboxes storage delete <sandbox-id> --kind <string> --name <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`. |
+| `--kind <string>` | volume or folder. Required. |
+| `--name <string>` | The volume’s name, or the folder’s path in the sandbox (/srv, not /srv/app). Required. |
+
+MCP tool: `sandboxes_storage_delete`.
+
+### `ghostdock sandboxes storage list`
+
+List a sandbox’s volumes and sandbox folders. The sandbox folders are where bind mounts land. Each with its size and sizeState (measured; measuring: ask again in a few seconds; tooBig: too big to measure cheaply; outside: a volume bound outside the sandbox folders, not measured nor browsable) and the containers using it, plus every container’s mounts. truncated says entries were left out. A stopped sandbox lists none (it is not started for this).
+
+```
+ghostdock sandboxes storage list <sandbox-id> [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`. |
+
+MCP tool: `sandboxes_storage_list`.
+
 ### `ghostdock sandboxes tools`
 
 Tools of the MCP servers inside a sandbox.

package/dist/cli.md

@@ -451,11 +451,16 @@ multiple files, or a large ZIP, use the dedicated multipart upload command inste
 ghostdock sandboxes files upload quiet-harbor ./dist
 ghostdock sandboxes files upload quiet-harbor ./index.html ./assets
 ghostdock sandboxes files upload quiet-harbor --zip ./site.zip
+ghostdock sandboxes files upload quiet-harbor ./dist --container web --start
 ```
 
 Each positional path may be a file or directory. Directory contents are uploaded recursively,
 preserving their relative paths; a file is uploaded by its basename. A `sandboxes files upload` call needs
 at least one path or `--zip`. Uploading to a stopped sandbox resumes it automatically.
+The files land in a container as the other `files` commands do (see
+[Containers in a sandbox](#containers-in-a-sandbox)): `--container <name>`, else the default,
+else the one running, and the CLI asks which one when it cannot tell. A stopped target container
+is started after a "Start it?" at the keyboard, or at once with `--start`.
 
 ### `ghostdock env`
 
@@ -631,12 +636,12 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | Command | What it does |
 | --- | --- |
 | `ghostdock images add --ref <string> [flags]` | Bookmark an OCI image ref in the organization’s image catalog. |
-| `ghostdock images add-compose --name <string> --files <object> [flags]` | Add Compose files to the organization’s image catalog. |
+| `ghostdock images add-compose --name <string> [flags]` | Add a Compose project to the organization’s image catalog. |
 | `ghostdock images add-dockerfile --name <string> --dockerfile <string> [flags]` | Add a Dockerfile to the organization’s image catalog. |
 | `ghostdock images get <image-id> [flags]` | Get one catalog image with its spec, manifest and requirements. |
 | `ghostdock images list [flags]` | List the images an organization can boot sandboxes from. |
 | `ghostdock images remove <image-id> [flags]` | Remove an image from the organization’s catalog. |
-| `ghostdock images update-compose <image-id> [flags]` | Replace a catalog Compose image’s files and/or name. |
+| `ghostdock images update-compose <image-id> [flags]` | Replace a catalog Compose image’s files, reference, override and/or name. |
 | `ghostdock images update-dockerfile <image-id> --dockerfile <string> [flags]` | Replace a catalog Dockerfile, optionally renaming it. |
 
 #### login
@@ -715,7 +720,11 @@ 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 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 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. |
@@ -740,6 +749,8 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `ghostdock sandboxes ssh revoke <sandbox-id> [flags]` | Revoke a sandbox’s active SSH access. |
 | `ghostdock sandboxes status <sandbox-id> [flags]` | Get a sandbox’s status and lifecycle deadlines without waking it. |
 | `ghostdock sandboxes stop <sandbox-id> [flags]` | Stop a running sandbox without deleting its files. |
+| `ghostdock sandboxes storage delete <sandbox-id> --kind <string> --name <string> [flags]` | Delete a named volume or a top-level sandbox folder, with everything in it. |
+| `ghostdock sandboxes storage list <sandbox-id> [flags]` | List a sandbox’s volumes and sandbox folders. |
 | `ghostdock sandboxes tools call <name> --sandbox-id <string> --arguments <object> [flags]` | Call a tool on an MCP server inside a sandbox. |
 | `ghostdock sandboxes tools list <sandbox-id> [flags]` | List the tools of the MCP servers a sandbox exposes. |
 | `ghostdock sandboxes update <sandbox-id> [flags]` | Change a sandbox’s display name, idle-stop or auto-delete interval. |

package/dist/index.js

@@ -718,9 +718,33 @@ var GENERATED_TOOL_CATALOG = [
                 "files"
               ],
               additionalProperties: false
+            },
+            {
+              type: "object",
+              properties: {
+                type: {
+                  type: "string",
+                  const: "compose"
+                },
+                reference: {
+                  type: "string",
+                  minLength: 1,
+                  maxLength: 512,
+                  pattern: "^oci:\\/\\/(?:[a-z0-9]+(?:[.-][a-z0-9]+)*(?::\\d{1,5})?\\/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[a-f0-9]{64})?$"
+                },
+                override: {
+                  type: "string",
+                  maxLength: 262144
+                }
+              },
+              required: [
+                "type",
+                "reference"
+              ],
+              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`. 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" 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.'
         },
         resources: {
           type: "object",
@@ -4454,11 +4478,16 @@ var GENERATED_TOOL_CATALOG = [
       "images",
       "add-compose"
     ],
-    description: "Add Compose files to the organization’s image catalog. Must include docker-compose.yml/yaml or compose.yml/yaml; ghostdock.* service labels become its manifest. Fails if the name is taken.",
+    description: "Add a Compose project to the organization’s image catalog. Give its files, or a reference: a Compose project published as an OCI artifact (oci://…), used through include: with an optional override. ghostdock.* service labels (of the files, or of the override) become its manifest. Fails if the name is taken.",
     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."
+        },
         name: {
           type: "string",
           minLength: 1,
@@ -4466,6 +4495,7 @@ var GENERATED_TOOL_CATALOG = [
           description: "Image name, unique in the organization."
         },
         files: {
+          description: "Compose files by file name. Must include docker-compose.yml/yaml or compose.yml/yaml.",
           type: "object",
           propertyNames: {
             type: "string"
@@ -4474,19 +4504,24 @@ var GENERATED_TOOL_CATALOG = [
             type: "string",
             minLength: 1,
             maxLength: 512000
-          },
-          description: "Compose files by file name. Must include docker-compose.yml/yaml or compose.yml/yaml."
+          }
         },
-        organization: {
+        reference: {
+          description: "A published Compose project instead of files, e.g. oci://docker.io/ghostdockhq/vm-compose:ubuntu-26.04.",
           type: "string",
           minLength: 1,
-          description: "Organization id or slug, from organizations_list. Ids survive renames; slugs change when the organization is renamed."
+          maxLength: 512,
+          pattern: "^oci:\\/\\/(?:[a-z0-9]+(?:[.-][a-z0-9]+)*(?::\\d{1,5})?\\/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[a-f0-9]{64})?$"
+        },
+        override: {
+          description: "With reference: a Compose file merged into it (services, environment, labels).",
+          type: "string",
+          maxLength: 262144
         }
       },
       required: [
-        "name",
-        "files",
-        "organization"
+        "organization",
+        "name"
       ],
       additionalProperties: false
     },
@@ -4509,7 +4544,7 @@ var GENERATED_TOOL_CATALOG = [
     cliArgs: [
       "imageId"
     ],
-    description: "Replace a catalog Compose image’s files and/or name. Re-parses its labels.",
+    description: "Replace a catalog Compose image’s files, reference, override and/or name. Re-parses its labels.",
     inputSchema: {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -4536,6 +4571,25 @@ var GENERATED_TOOL_CATALOG = [
             maxLength: 512000
           }
         },
+        reference: {
+          description: "A new reference (oci://…): the image becomes a Compose reference.",
+          type: "string",
+          minLength: 1,
+          maxLength: 512,
+          pattern: "^oci:\\/\\/(?:[a-z0-9]+(?:[.-][a-z0-9]+)*(?::\\d{1,5})?\\/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[a-f0-9]{64})?$"
+        },
+        override: {
+          description: "A reference’s new override; null removes it.",
+          anyOf: [
+            {
+              type: "string",
+              maxLength: 262144
+            },
+            {
+              type: "null"
+            }
+          ]
+        },
         name: {
           description: "New image name. Omit to keep it.",
           type: "string",
@@ -6159,6 +6213,320 @@ var GENERATED_TOOL_CATALOG = [
       additionalProperties: {}
     }
   },
+  {
+    id: "sandboxes_containers_start",
+    name: "sandboxes_containers_start",
+    cli: [
+      "sandboxes",
+      "containers",
+      "start"
+    ],
+    cliArgs: [
+      "sandboxId",
+      "container"
+    ],
+    description: "Start a stopped container, as docker start does. A running container stays as it is. Starts the sandbox when needed.",
+    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."
+        },
+        container: {
+          type: "string",
+          minLength: 1,
+          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_stop",
+    name: "sandboxes_containers_stop",
+    cli: [
+      "sandboxes",
+      "containers",
+      "stop"
+    ],
+    cliArgs: [
+      "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.",
+    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."
+        },
+        container: {
+          type: "string",
+          minLength: 1,
+          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_restart",
+    name: "sandboxes_containers_restart",
+    cli: [
+      "sandboxes",
+      "containers",
+      "restart"
+    ],
+    cliArgs: [
+      "sandboxId",
+      "container"
+    ],
+    description: "Restart a container, as docker restart does (stopping as docker stop does). Starts the sandbox when needed.",
+    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."
+        },
+        container: {
+          type: "string",
+          minLength: 1,
+          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_logs",
+    name: "sandboxes_containers_logs",
+    cli: [
+      "sandboxes",
+      "containers",
+      "logs"
+    ],
+    cliArgs: [
+      "sandboxId",
+      "container"
+    ],
+    description: "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).",
+    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."
+        },
+        container: {
+          type: "string",
+          minLength: 1,
+          maxLength: 255,
+          pattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
+          description: "Container, by name."
+        },
+        tail: {
+          description: "The last N lines (at most 5000).",
+          type: "integer",
+          minimum: 1,
+          maximum: 5000
+        },
+        after: {
+          description: "Only lines after this time: the time of the last line already read.",
+          type: "string",
+          pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})$"
+        }
+      },
+      required: [
+        "organization",
+        "sandboxId",
+        "container"
+      ],
+      additionalProperties: false
+    },
+    outputSchema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      propertyNames: {
+        type: "string"
+      },
+      additionalProperties: {}
+    }
+  },
+  {
+    id: "sandboxes_storage_list",
+    name: "sandboxes_storage_list",
+    cli: [
+      "sandboxes",
+      "storage",
+      "list"
+    ],
+    cliArgs: [
+      "sandboxId"
+    ],
+    description: "List a sandbox’s volumes and sandbox folders. The sandbox folders are where bind mounts land. Each with its size and sizeState (measured; measuring: ask again in a few seconds; tooBig: too big to measure cheaply; outside: a volume bound outside the sandbox folders, not measured nor browsable) and the containers using it, plus every container’s mounts. truncated says entries were left out. A stopped sandbox lists none (it is not started for this).",
+    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."
+        }
+      },
+      required: [
+        "organization",
+        "sandboxId"
+      ],
+      additionalProperties: false
+    },
+    outputSchema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      propertyNames: {
+        type: "string"
+      },
+      additionalProperties: {}
+    }
+  },
+  {
+    id: "sandboxes_storage_delete",
+    name: "sandboxes_storage_delete",
+    cli: [
+      "sandboxes",
+      "storage",
+      "delete"
+    ],
+    cliArgs: [
+      "sandboxId"
+    ],
+    description: "Delete a named volume or a top-level sandbox folder, with everything in it. Refused while a container mounts it (in any state: a stopped one counts, so stopping does not help), mounts a folder above it (a bind of /), or a volume keeps its data in the folder: remove those first.",
+    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."
+        },
+        kind: {
+          type: "string",
+          enum: [
+            "volume",
+            "folder"
+          ],
+          description: "volume or folder."
+        },
+        name: {
+          type: "string",
+          minLength: 1,
+          description: "The volume’s name, or the folder’s path in the sandbox (/srv, not /srv/app)."
+        }
+      },
+      required: [
+        "organization",
+        "sandboxId",
+        "kind",
+        "name"
+      ],
+      additionalProperties: false
+    },
+    outputSchema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      propertyNames: {
+        type: "string"
+      },
+      additionalProperties: {}
+    }
+  },
   {
     id: "sandboxes_commands_run",
     name: "sandboxes_commands_run",
@@ -8808,7 +9176,7 @@ function getCliName(argv = process.argv) {
   return CLI_NAMES.find((name) => name === invoked) ?? "ghostdock";
 }
 // package.json
-var version = "0.0.14";
+var version = "0.0.16";
 var package_default = {
   name: "ghostdock",
   description: "Ghostdock CLI — device login and agent tool invocation from the command line",
@@ -9415,6 +9783,15 @@ var envCommand = defineCommand({
 
 // src/container-picker.ts
 import { createInterface } from "node:readline/promises";
+function notRunningContainerOf(error) {
+  if (!(error instanceof ApiError) || !error.data || typeof error.data !== "object")
+    return null;
+  const { code, params } = error.data;
+  if (code !== "container_not_running")
+    return null;
+  const container = params && typeof params === "object" ? params : {};
+  return typeof container.container === "string" && container.container ? container.container : null;
+}
 function containerQuestionOf(error) {
   if (!(error instanceof ApiError) || !error.data || typeof error.data !== "object")
     return null;
@@ -9460,8 +9837,21 @@ var confirmDefaultOnTerminal = async (container) => {
     prompt.close();
   }
 };
+var confirmStartOnTerminal = async (container) => {
+  const prompt = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = (await prompt.question(`Container ${container} is not running. Start it? [Y/n] `)).trim();
+    return answer === "" || /^y(es)?$/i.test(answer);
+  } finally {
+    prompt.close();
+  }
+};
 function defaultContainerPickers() {
-  return process.stdin.isTTY && process.stderr.isTTY ? { choose: chooseContainerOnTerminal, confirmDefault: confirmDefaultOnTerminal } : undefined;
+  return process.stdin.isTTY && process.stderr.isTTY ? {
+    choose: chooseContainerOnTerminal,
+    confirmDefault: confirmDefaultOnTerminal,
+    confirmStart: confirmStartOnTerminal
+  } : undefined;
 }
 
 // src/progress.ts
@@ -9524,6 +9914,130 @@ async function withProgress(message, work, options) {
   }
 }
 
+// src/container-flow.ts
+async function withContainerPick(call, send, pickers, notice) {
+  try {
+    return await send();
+  } catch (err) {
+    const question = containerQuestionOf(err);
+    if (!pickers || !question || !call.canPick)
+      throw err;
+    const container = await pickers.choose(question);
+    if (!container)
+      throw err;
+    call.setContainer(container);
+    const result = await send();
+    if (call.sandboxId !== undefined && await pickers.confirmDefault(container)) {
+      try {
+        await authorizedRequest("/api/v1/tools/sandboxes_default_container", {
+          method: "POST",
+          body: JSON.stringify({
+            organization: call.organization,
+            sandboxId: call.sandboxId,
+            container
+          })
+        });
+        notice(eventLine("done", `Default container: ${container}.`));
+      } catch (err) {
+        notice(eventLine("failed", `The default container was not set: ${err instanceof Error ? err.message : String(err)}`));
+      }
+    }
+    return result;
+  }
+}
+async function withContainerStart(call, send, start, pickers, notice) {
+  try {
+    return await send();
+  } catch (err) {
+    const container = notRunningContainerOf(err);
+    if (!container || call.sandboxId === undefined)
+      throw err;
+    if (!start && !(pickers && await pickers.confirmStart(container)))
+      throw err;
+    await withProgress("Starting container…", () => authorizedRequest("/api/v1/tools/sandboxes_containers_start", {
+      method: "POST",
+      body: JSON.stringify({
+        organization: call.organization,
+        sandboxId: call.sandboxId,
+        container
+      })
+    }));
+    notice(eventLine("done", `Started ${container}.`));
+    return await send();
+  }
+}
+
+// src/container-logs.ts
+var FOLLOW_INTERVAL_MS = 2000;
+function defaultLogsDeps(follow) {
+  let stop = false;
+  if (follow) {
+    process.once("SIGINT", () => {
+      stop = true;
+    });
+  }
+  return {
+    request: (input) => authorizedRequest("/api/v1/tools/sandboxes_containers_logs", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    out: (line) => process.stdout.write(`${line}
+`),
+    err: (line) => process.stderr.write(`${line}
+`),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    stopped: () => stop
+  };
+}
+async function runContainerLogs(input, options, deps = defaultLogsDeps(options.follow)) {
+  const json = isJsonOutput();
+  const color = colorEnabled(process.stdout);
+  const print = (line) => {
+    if (json) {
+      deps.out(JSON.stringify(line));
+      return;
+    }
+    const text = options.timestamps && line.time ? `${dim(line.time, color)} ${line.text}` : line.text;
+    (line.stream === "stderr" ? deps.err : deps.out)(text);
+  };
+  let result = await deps.request(input);
+  if (!result.running) {
+    deps.err("The sandbox is stopped: it has no logs to show.");
+    return 1;
+  }
+  let last = null;
+  for (;; ) {
+    for (const line of result.lines) {
+      print(line);
+      if (line.time)
+        last = line.time;
+    }
+    if (!options.follow) {
+      if (result.truncated && json) {
+        deps.out(JSON.stringify({ truncated: true }));
+      } else if (result.truncated) {
+        deps.err(dim("(older lines left out: use --tail for more)", colorEnabled(process.stderr)));
+      }
+      return 0;
+    }
+    if (!result.truncated)
+      await deps.sleep(FOLLOW_INTERVAL_MS);
+    if (deps.stopped())
+      return 0;
+    const { tail: _tail, ...rest } = input;
+    try {
+      result = await deps.request(last ? { ...rest, after: last } : input);
+    } catch (error) {
+      deps.err(red(error instanceof Error ? error.message : String(error), colorEnabled(process.stderr)));
+      return 1;
+    }
+    if (!result.running) {
+      deps.err("The sandbox stopped.");
+      return 0;
+    }
+  }
+}
+
 // src/human.ts
 var ID_KEYS = [
   "sandboxId",
@@ -9827,10 +10341,10 @@ function buildToolInput(schema, rawArgs) {
 
 // src/commands/invoke.ts
 async function runToolInvoke(tool, rawArgs, log = console.log, error = printError, notice = printNotice, pickers = defaultContainerPickers()) {
+  const properties = tool.inputSchema.properties;
   let input;
   try {
     input = buildToolInput(tool.inputSchema, rawArgs);
-    const properties = tool.inputSchema.properties;
     if (properties && "organization" in properties && input.organization === undefined) {
       input.organization = await requireOrganizationRef(undefined, notice);
     }
@@ -9838,59 +10352,64 @@ async function runToolInvoke(tool, rawArgs, log = console.log, error = printErro
     error(err instanceof Error ? err.message : String(err));
     return 1;
   }
+  if (tool.name === "sandboxes_containers_logs") {
+    try {
+      return await runContainerLogs(input, {
+        follow: rawArgs.follow === true,
+        timestamps: rawArgs.timestamps === true
+      });
+    } catch (err) {
+      error(err instanceof Error ? err.message : `${tool.name} failed.`);
+      return 1;
+    }
+  }
+  const call = {
+    organization: typeof input.organization === "string" ? input.organization : undefined,
+    sandboxId: typeof input.sandboxId === "string" ? input.sandboxId : undefined,
+    canPick: !!properties && "container" in properties && !input.container,
+    setContainer: (container) => {
+      input.container = container;
+    }
+  };
   try {
-    const request = () => authorizedRequest(`/api/v1/tools/${tool.name}`, {
+    const post = () => authorizedRequest(`/api/v1/tools/${tool.name}`, {
       method: "POST",
       body: JSON.stringify(input)
     });
     const waitMessage = PROGRESS_MESSAGES[tool.name];
-    if (!waitMessage) {
-      const result = await withContainerPick(tool, input, request, pickers, notice);
-      printResult(result, () => renderResult(result, colorEnabled(process.stdout)), log);
-      return 0;
-    }
-    const { value: result, elapsed } = await withContainerPick(tool, input, () => withProgress(waitMessage, request), pickers, notice);
+    let elapsed;
+    const send = async () => {
+      if (!waitMessage)
+        return post();
+      const timed = await withProgress(waitMessage, post);
+      elapsed = timed.elapsed;
+      return timed.value;
+    };
+    const result = await withContainerPick(call, () => withContainerStart(call, send, rawArgs.start === true, pickers, notice), pickers, notice);
     printResult(result, () => {
       const color = colorEnabled(process.stdout);
       const lines = renderResult(result, color);
-      return bootLines(result, color).length > 0 ? lines : withElapsed(lines, elapsed);
+      return elapsed === undefined || bootLines(result, color).length > 0 ? lines : withElapsed(lines, elapsed);
     }, log);
+    stopNote(result, notice);
     return 0;
   } catch (err) {
     error(err instanceof Error ? err.message : `${tool.name} failed.`);
     return 1;
   }
 }
-async function withContainerPick(tool, input, send, pickers, notice) {
-  try {
-    return await send();
-  } catch (err) {
-    const properties = tool.inputSchema.properties;
-    const question = containerQuestionOf(err);
-    if (!pickers || !question || !properties || !("container" in properties) || input.container) {
-      throw err;
-    }
-    const container = await pickers.choose(question);
-    if (!container)
-      throw err;
-    input.container = container;
-    const result = await send();
-    if (typeof input.sandboxId === "string" && await pickers.confirmDefault(container)) {
-      try {
-        await authorizedRequest("/api/v1/tools/sandboxes_default_container", {
-          method: "POST",
-          body: JSON.stringify({
-            organization: input.organization,
-            sandboxId: input.sandboxId,
-            container
-          })
-        });
-        notice(eventLine("done", `Default container: ${container}.`));
-      } catch (err) {
-        notice(eventLine("failed", `The default container was not set: ${err instanceof Error ? err.message : String(err)}`));
-      }
-    }
-    return result;
+function stopNote(result, notice) {
+  if (!result || typeof result !== "object")
+    return;
+  const { action, note, container } = result;
+  if (action !== "stop" || typeof container !== "string")
+    return;
+  if (note === "default") {
+    notice(`${container} is the sandbox's default container: SSH, commands and files ask which container until it runs again.`);
+  } else if (note === "last_running") {
+    notice("No container is running now: SSH, commands and files have none to land in until one runs.");
+  } else if (note === "sandbox_stopped") {
+    notice(`The sandbox is stopped, so ${container} is too: nothing was done.`);
   }
 }
 var PROGRESS_MESSAGES = {
@@ -9901,6 +10420,9 @@ var PROGRESS_MESSAGES = {
   sandboxes_resize: "Resizing sandbox…",
   sandboxes_resize_disk: "Resizing disk…",
   sandboxes_commands_run: "Running command…",
+  sandboxes_containers_start: "Starting container…",
+  sandboxes_containers_stop: "Stopping container…",
+  sandboxes_containers_restart: "Restarting container…",
   snapshots_create: "Saving snapshot…",
   projects_redeploy: "Redeploying…",
   providers_verify_incus: "Checking the Incus host…"
@@ -9923,6 +10445,25 @@ function cliText(catalog, skills = BUILTIN_SKILL_NAMES) {
     return commands.replace(/\bthe ([a-z][a-z0-9-]*) skill\b/g, (phrase, skill) => skills.includes(skill) ? `the ${skill} skill (\`${getCliName()} skills get ${skill}\`)` : phrase);
   };
 }
+function cliOnlyArgs(tool) {
+  const schema = tool.inputSchema;
+  const args = {};
+  if (schema.properties && "container" in schema.properties && !schema.required?.includes("container")) {
+    args.start = {
+      type: "boolean",
+      description: "Start the container first when it is not running, without asking."
+    };
+  }
+  if (tool.name === "sandboxes_containers_logs") {
+    args.follow = {
+      type: "boolean",
+      alias: "f",
+      description: "Keep printing new lines until Ctrl-C."
+    };
+    args.timestamps = { type: "boolean", description: "Put each line's time in front of it." };
+  }
+  return args;
+}
 var generatedToolCommands = new WeakSet;
 function createToolCommands(catalog) {
   const commands = {};
@@ -9933,7 +10474,7 @@ function createToolCommands(catalog) {
         name: tool.cli?.at(-1) ?? tool.name,
         description: toCliText(tool.description)
       },
-      args: buildToolArgs(tool.inputSchema, toCliText, tool.cliArgs),
+      args: { ...buildToolArgs(tool.inputSchema, toCliText, tool.cliArgs), ...cliOnlyArgs(tool) },
       async run({ args }) {
         process.exitCode = await runToolInvoke(tool, args);
       }
@@ -12213,7 +12754,7 @@ async function collectPath3(path) {
   await visit(path);
   return files;
 }
-async function runSandboxUpload(options, log = console.log, error = printError) {
+async function runSandboxUpload(options, log = console.log, error = printError, notice = printNotice, pickers = defaultContainerPickers()) {
   if (options.paths.length === 0 && !options.zip) {
     error("Provide at least one path or --zip.");
     return 1;
@@ -12229,9 +12770,26 @@ async function runSandboxUpload(options, log = console.log, error = printError)
     if (options.zip) {
       form.append("zip", new Blob([await readFile7(options.zip)]), basename5(options.zip));
     }
-    const { value: result } = await withProgress("Uploading…", () => authorizedRequest(`/api/v1/sandboxes/${encodeURIComponent(options.sandboxId)}/files?organization=${encodeURIComponent(organization)}`, { method: "POST", body: form }));
+    let container = options.container;
+    const call = {
+      organization,
+      sandboxId: options.sandboxId,
+      canPick: !container,
+      setContainer: (picked) => {
+        container = picked;
+      }
+    };
+    const send = async () => {
+      const query = new URLSearchParams({ organization });
+      if (container)
+        query.set("container", container);
+      const { value } = await withProgress("Uploading…", () => authorizedRequest(`/api/v1/sandboxes/${encodeURIComponent(options.sandboxId)}/files?${query}`, { method: "POST", body: form }));
+      return value;
+    };
+    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", `Uploaded ${result.written.length} file${result.written.length === 1 ? "" : "s"} to ${options.sandboxId}.`)
+      eventLine("done", result.container ? `Uploaded ${count} to ${result.container} in ${options.sandboxId}.` : `Uploaded ${count} to ${options.sandboxId}.`)
     ], log);
     return 0;
   } catch (err) {
@@ -12255,6 +12813,14 @@ var sandboxUploadCommand = defineCommand({
       required: true
     },
     org: orgArg,
+    container: {
+      type: "string",
+      description: `Container the files land in, by name, from \`${getCliName()} sandboxes containers list\`. Default: the sandbox's default container, else the one running container.`
+    },
+    start: {
+      type: "boolean",
+      description: "Start the container first when it is not running, without asking."
+    },
     zip: {
       type: "string",
       description: "Local ZIP file to upload."
@@ -12270,7 +12836,9 @@ var sandboxUploadCommand = defineCommand({
       sandboxId: args["sandbox-id"],
       org: args.org,
       paths: args._.slice(1),
-      zip: args.zip
+      zip: args.zip,
+      container: args.container,
+      start: args.start
     });
   }
 });

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.14",
+  "version": "0.0.16",
   "type": "module",
   "bin": {
     "ghostdock": "dist/index.js",