ghostdock 0.0.17 → 0.0.18

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.

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 |
@@ -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: