ghostdock 0.0.16 → 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.
@@ -259,7 +277,7 @@ The private network: reach your sandboxes by address and name from this machine.
 
 ### `ghostdock network connect`
 
-Put this machine into the private network through one provider: WireGuard and split DNS. The organization (--org, else the default) becomes this machine's short-name organization. Asks for sudo once.
+Put this machine into the private network through one provider: WireGuard and split DNS. The organization (--org, else the default) becomes this machine's short-name organization. Also re-arms a paused device: with the tunnel up and nothing changed, without sudo.
 
 ```
 ghostdock network connect [provider] [flags]
@@ -292,7 +310,7 @@ ghostdock network devices remove <id>
 
 ### `ghostdock network disconnect`
 
-Take this machine out of the private network.
+Take this machine out of the private network, and remove split DNS an earlier connection left (macOS).
 
 ```
 ghostdock network disconnect
@@ -942,6 +960,7 @@ ghostdock sandboxes create --source <object> [flags]
 | `--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. |
 | `--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) |
 

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…
@@ -607,8 +608,80 @@ ghostdock network disconnect
     (`iptables -A INPUT`, an nft `hook input` chain): `FORWARD` and `DOCKER-USER` rules no
     longer see them, because the guard connects to a published container port from inside
     the VM.
-- `ghostdock network devices` lists your devices, `ghostdock network devices remove <id>`
-  removes one.
+- **The network pause** ([ADR 0033](../../docs/adr/0033-gdo-net-dead-mans-switch.md)): a
+  device that sent no traffic to a sandbox for its idle timeout (default 4 h), or whose session
+  since the last connect reached its maximum (default 12 h), is paused at the gateway. Your
+  organizations set both (Settings → Security). If you are in several, the strictest value
+  applies. `connect` ends with this device's own numbers and names the organization that set a
+  stricter one.
+  - **While paused**, names still resolve, but every port of a sandbox answers `Connection
+    refused`, and UDP and ping get *administratively prohibited*. Browsers get a pause page
+    with a *Reconnect* button, and Docker gets `Ghostdock: network access for this device is
+    paused (idle 4 h)`. Every `ghostdock` command prints `! Network access for this device is
+    paused (…). Run: ghostdock network connect` once.
+  - **To resume**, run `ghostdock network connect`, or click *Reconnect* in the web app (User
+    settings → Network devices). With the tunnel up and nothing changed, `connect` only
+    re-arms: no sudo, *Re-armed: network access for this device runs until 22:14 (pauses after
+    4 h idle).* *Pause now* in the web app pauses a device at once.
+  - DNS, WireGuard keepalives and ping do not count as traffic. A long stream does (a `docker
+    logs -f`, an open desktop tab).
+- `ghostdock network devices` lists your devices with their state (*Active, pauses in 3 h 12
+  min*, *Paused: idle 4 h*, *Paused: 12 h session limit*, *Paused by you*, *Not connected
+  (…)*). `ghostdock network devices remove <id>` removes one.
+- **`ghostdock network disconnect`** also removes the split-DNS files a reboot or a crashed
+  `wg-quick` left on macOS (`/etc/resolver/<zone>`), even when the tunnel is already down.
+  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
 
@@ -622,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 |
@@ -663,7 +742,7 @@ or read [`cli-reference.md`](cli-reference.md) for every command's full descript
 | `ghostdock network connect [provider] [flags]` | Put this machine into the private network through one provider: WireGuard and… |
 | `ghostdock network devices <command>` | Your devices in the private network. |
 | `ghostdock network devices remove <id>` | Remove one of your devices from the private network. |
-| `ghostdock network disconnect` | Take this machine out of the private network. |
+| `ghostdock network disconnect` | Take this machine out of the private network, and remove split DNS an earlier… |
 | `ghostdock network ls [flags]` | Sandboxes of an organization with their private addresses and names, and which… |
 | `ghostdock network status` | Whether this machine is connected, through which provider, and as which device. |
 
@@ -806,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: