gdkbox 0.1.19 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17efb5fee81f15043aed3c8dbabe3e9259c70a8d8a03dd400b8103231b36a9d6
-  data.tar.gz: d926bbae45cbe226fec0530f43e11e12f1ef346450e5801909c251e6f159bf66
+  metadata.gz: ed8db8e33eb456eab81c33ec420fccbb86294d1569373da95d4eab9aebf1ee79
+  data.tar.gz: 23812d9d52938ddbdbd5613f412bdb5e35ed588ec177c5f1ad8acfbfa76fe214
 SHA512:
-  metadata.gz: 179859b546c7b76825d22d6e100b39446d96205adaab696982f960409f14041a8135daf67600d3755545613537a011131302c238de44fefd64df5a7980834227
-  data.tar.gz: 59f9e916539ca282cc16ec86e8fde2ab8437541aad4c433d4c5a2895f49017cf747880f75e3777e80c39b88e767591c9a8b18d115badfae9fcabf4525bc22f2d
+  metadata.gz: 588e9c4a5beaa9f7ddcfd0cdfe3c897de80b230646a24b1c580bdb1cf008ec9aa86531d5f5a03d2234bf128918dd821f02dba7b41a79470b172d5607b2abd8c2
+  data.tar.gz: d1369eb4dadb712a8e2cacef481c55475e4239f447daad5ef952bdb956d5651ca13ac7fe80a29e8390ac609228514ed3bbcac3cf659f1c050bcc22ce8d679ca5

data/README.md

@@ -122,6 +122,8 @@ Or run it straight from the checkout without installing:
 | `--ttl SECS` | no expiry | Lease duration for `--owner`'s claim. |
 | `--docker` | off | Mount the host Docker socket + per-box network so docker-executor CI jobs work. **Grants the box root-equivalent host access** — see "Docker inside a box". |
 | `--publish PORT [PORT...]` | (none) | Publish extra container ports on `127.0.0.1`, same number on both sides (e.g. AI Gateway `5052`, Duo Workflow `50052`). |
+| `--key-env NAME` | the harness's | Env var this box's API key is seeded under (e.g. `GITLAB_TOKEN`); see "opencode with GitLab Duo". |
+| `--model ID` | the harness's own | Model the box's agent runs with on `dispatch` (claude, codex, opencode; e.g. `gitlab/duo-chat-sonnet-4-5`). |
 
 ## Typical workflow
 
@@ -373,8 +375,8 @@ harness the box was created with.
 | --- | --- | --- | --- | --- |
 | `claude` | Claude Code | `claude -p` | `ANTHROPIC_API_KEY` | `~/.claude/skills` |
 | `codex` | OpenAI Codex | `codex exec` | `OPENAI_API_KEY` | `~/.codex/skills` |
-| `opencode` | opencode (sst) | `opencode run` | `OPENAI_API_KEY` | `~/.config/opencode/skills` |
-| `pi` | pi (earendil-works) | `pi -p` | `ANTHROPIC_API_KEY` | `~/.pi/skills` |
+| `opencode` | opencode (sst) | `opencode run` | `GITLAB_TOKEN` | `~/.config/opencode/skills` |
+| `pi` | pi (earendil-works) | `pi -p` | `GITLAB_TOKEN` | `~/.pi/skills` |
 
 ```sh
 gdkbox up reviewer --harness codex          # a Codex box
@@ -385,8 +387,39 @@ gdkbox harnesses                             # list available harnesses
 ```
 
 Skills use the same `SKILL.md` format across all four, so a skill installed by
-`add-skill`/`--skill` works regardless of harness. The key env / provider for
-`opencode` and `pi` are configurable defaults — adjust per your provider.
+`add-skill`/`--skill` works regardless of harness. The key env is a per-harness
+default (claude → `ANTHROPIC_API_KEY`, codex → `OPENAI_API_KEY`, opencode and
+pi → `GITLAB_TOKEN`): point a box at another provider with
+`gdkbox up --key-env NAME`.
+`gdkbox up --model ID` pins the model a box's agent is dispatched with
+(claude, codex, and opencode; not pi yet). Both are fixed when the box is
+created.
+
+### opencode with GitLab Duo
+
+The `opencode` harness defaults to opencode's GitLab Duo provider, which reads
+a personal access token from `GITLAB_TOKEN`. Pin a Duo model with `--model`:
+
+```sh
+GITLAB_TOKEN=<token> gdkbox up duo --harness opencode --model gitlab/duo-chat-sonnet-4-5
+gdkbox dispatch duo --task "review the diff"
+```
+
+- The `duo-chat-*` models are GitLab Duo Agentic Chat and work with the token
+  alone. The `duo-workflow-*` models need a login stored with opencode's
+  `/connect`, so they are not available this way.
+- GitLab Duo needs a Premium or Ultimate subscription with the Duo Agent
+  Platform turned on.
+- Without `--model`, opencode picks its own default model.
+- For another provider, seed its key instead, e.g.
+  `gdkbox up NAME --harness opencode --key-env OPENAI_API_KEY`.
+
+> **The token acts as you.** opencode needs the `api` scope, which lets the
+> agent read and write anything you can on GitLab. That is what lets it post
+> MR review comments, but it also means a prompt injection in an issue, MR, or
+> file the agent reads can act with your permissions. Use a dedicated,
+> short-lived token. `gdkbox up --harness opencode` picks up `$GITLAB_TOKEN`
+> from your shell, so check what that variable holds first.
 
 ## Shell completion
 
@@ -439,15 +472,17 @@ skills:
   # - ./path/to/a/local/skill
 
 # API keys seeded into boxes for unattended `gdkbox dispatch`, per provider.
-# anthropic_api_key: sk-ant-...   # used by the claude / pi harnesses
-# openai_api_key: sk-...          # used by the codex / opencode harnesses
+# anthropic_api_key: sk-ant-...   # used by the claude harness
+# openai_api_key: sk-...          # used by the codex harness
+# gitlab_token: <personal access token, api scope>  # used by the opencode / pi harnesses
 ```
 
 `gdkbox up` installs the skills on top of any `--skill` you pass; use
 `--no-default-skills` to skip them for one run. Precedence for the image is
 `--image` > `$GDKBOX_IMAGE` > `config.yml` > built-in default; for the API key
 it is `--api-key` > the harness's provider env var (e.g. `$ANTHROPIC_API_KEY`,
-`$OPENAI_API_KEY`) > `config.yml`.
+`$GITLAB_TOKEN`, or the `--key-env` name) > `config.yml` (the env var's name
+lowercased, e.g. `gitlab_token:`).
 
 > **API keys in `config.yml` are plaintext secrets on disk.** Prefer the
 > provider env var; if you do put a key in `config.yml`, keep the file mode

data/lib/gdkbox/box.rb

@@ -73,9 +73,16 @@ module GDKBox
     end
 
     # The agent harness this box runs (defaults to Claude for boxes created
-    # before harness support existed).
+    # before harness support existed), with the box's own key env override
+    # (`up --key-env`) applied.
     def harness
-      Harness[(data && data["harness"]) || Harness.default]
+      Harness[(data && data["harness"]) || Harness.default].with_key_env(data && data["key_env"])
+    end
+
+    # The model the box's agent is pinned to (`up --model`), or nil to let
+    # the harness pick its own default.
+    def model
+      data && data["model"]
     end
 
     def state
@@ -91,10 +98,12 @@ module GDKBox
     # box this one is still provisioning.
     def create!(image: nil, ssh_port: nil, web_port: nil, vite_port: nil,
       harness: Harness.default, install_agent: true, api_key: nil,
-      claim_owner: nil, claim_ttl: nil, docker_access: false, extra_ports: [])
+      claim_owner: nil, claim_ttl: nil, docker_access: false, extra_ports: [],
+      key_env: nil, model: nil)
       raise Error, "Box '#{name}' already exists" if exists?
 
-      harness = Harness[harness]
+      harness = Harness[harness].with_key_env(key_env)
+      model = harness.check_model!(model)
       image ||= @config.default_image
       public_key = @ssh_key.ensure!
       cname = @config.container_name(name)
@@ -168,6 +177,8 @@ module GDKBox
         "harness" => harness.id,
         "created_at" => Time.now.utc.iso8601
       )
+      @data["key_env"] = harness.key_env if key_env
+      @data["model"] = model if model
       if docker_access
         @data["docker_access"] = true
         @data["docker_network"] = net
@@ -493,12 +504,12 @@ module GDKBox
 
     # Run this box's agent harness non-interactively and capture its output.
     # This is the primitive an orchestrator uses to dispatch a task to a box.
-    # The task text is passed through the environment so arbitrary prompts
-    # cannot break out of the shell command.
+    # The task text (and the pinned model, if any) is passed through the
+    # environment so arbitrary values cannot break out of the shell command.
     def run_agent(task:, json: false, yolo: true, timeout: nil)
       raise Error, "Box '#{name}' does not exist" unless exists?
 
-      agent = harness.agent_command(json: json, yolo: yolo)
+      agent = harness.agent_command(json: json, yolo: yolo, model: model)
       agent = "timeout #{Integer(timeout)} #{agent}" if timeout
       # Source the seeded API key (if any) so the agent authenticates unattended.
       command = %([ -f "$HOME/.gdkbox/env" ] && . "$HOME/.gdkbox/env"; #{agent})
@@ -507,7 +518,7 @@ module GDKBox
         container_name, command,
         user: @config.ssh_user,
         workdir: remote_path,
-        env: { "GDKBOX_TASK" => task },
+        env: { "GDKBOX_TASK" => task, "GDKBOX_MODEL" => model }.compact,
         check: false
       )
       AgentResult.new(result.stdout, result.stderr, result.status)
@@ -515,6 +526,7 @@ module GDKBox
 
     # A machine-readable summary for orchestrators (`gdkbox ls --json`).
     def summary(state: nil)
+      harness = self.harness
       {
         "name" => name,
         "state" => (state || self.state).to_s,
@@ -529,6 +541,8 @@ module GDKBox
         # Back-compat: orchestrators predating multi-harness check this field.
         "claude_installed" => (harness.id == "claude" && (data && data["agent_installed"])) || false,
         "api_key_set" => (data && data["api_key_set"]) || false,
+        "key_env" => harness.key_env,
+        "model" => model,
         # Vite assets: the published port (nil on boxes created before vite
         # support) and whether the in-box alignment step succeeded.
         "vite_port" => vite_port,

data/lib/gdkbox/cli.rb

@@ -54,6 +54,12 @@ module GDKBox
     option :publish, type: :array, default: [],
       desc: "Extra container port(s) to publish on 127.0.0.1, same number on both sides " \
         "(e.g. --publish 5052 50052)"
+    option :key_env, type: :string,
+      desc: "Env var to seed the harness API key under for this box " \
+        "(e.g. GITLAB_TOKEN for opencode + GitLab Duo; default: the harness's own)"
+    option :model, type: :string,
+      desc: "Model this box's agent runs with on dispatch " \
+        "(e.g. gitlab/duo-chat-sonnet-4-5 for opencode; default: the harness's own)"
     def up(name)
       if options[:ttl] && options[:owner].to_s.strip.empty?
         raise Error, "--ttl only makes sense with --owner (it is the claim's lease)."
@@ -61,7 +67,8 @@ module GDKBox
       ensure_docker!
       box = build_box(name)
       raise Error, "Box '#{name}' already exists. Use `gdkbox rm #{name}` first." if box.exists?
-      harness = Harness[options[:harness] || config.default_harness]
+      harness = Harness[options[:harness] || config.default_harness].with_key_env(options[:key_env])
+      model = harness.check_model!(options[:model])
       api_key = resolve_api_key(harness)
 
       say "Spinning up GDK box '#{name}' (#{harness.summary}; first run pulls a large image)...", :green unless options[:json]
@@ -76,7 +83,9 @@ module GDKBox
         claim_owner: options[:owner],
         claim_ttl: options[:ttl],
         docker_access: options[:docker],
-        extra_ports: parse_extra_ports(options[:publish])
+        extra_ports: parse_extra_ports(options[:publish]),
+        key_env: options[:key_env],
+        model: model
       )
       rewrite_ssh_config
       seed_skills(box)
@@ -754,6 +763,7 @@ module GDKBox
       say "  Web UI:    #{box.web_url} (http://#{HostsFile::HOSTNAME}:#{box.web_port})", :cyan
       say "  Assets:    vite on port #{box.vite_port}", :cyan if box.vite_port
       say "  Agent:     ssh #{box.ssh_host_alias} -t #{box.harness.bin}", :cyan
+      say "  Model:     #{box.model} (on dispatch)", :cyan if box.model
     end
   end
 end

data/lib/gdkbox/harness.rb

@@ -10,6 +10,10 @@ module GDKBox
   # /usr/local/bin). A harness declares the env var its provider reads for
   # credentials and the config.yml key gdkbox looks under for a default.
   class Harness
+    # Env var names end up in an `export NAME=...` line inside the box, so
+    # only plain shell identifiers are accepted.
+    ENV_VAR_NAME = /\A[A-Z_][A-Z0-9_]*\z/
+
     @registry = {}
 
     class << self
@@ -43,8 +47,9 @@ module GDKBox
       :summary, :skills_subdir
 
     def initialize(id:, bin:, key_env:, config_key:, summary:, run:, skills_subdir:,
-      npm_package: nil, npm_flags: nil)
+      npm_package: nil, npm_flags: nil, model_flag: nil)
       @id = id
+      @model_flag = model_flag
       @npm_package = npm_package
       @npm_flags = npm_flags
       @bin = bin
@@ -55,15 +60,45 @@ module GDKBox
       @skills_subdir = skills_subdir
     end
 
+    # A copy of this harness that seeds its key under `key_env` instead
+    # (`up --key-env`), or self when blank. The config.yml fallback key
+    # follows the env var (GITLAB_TOKEN -> gitlab_token) so the override stays
+    # self-consistent.
+    def with_key_env(key_env)
+      key_env = key_env.to_s.strip
+      return self if key_env.empty?
+      unless ENV_VAR_NAME.match?(key_env)
+        raise Error, "Invalid --key-env '#{key_env}': not an env var name (use e.g. GITLAB_TOKEN)."
+      end
+
+      dup.tap do |copy|
+        copy.key_env = key_env
+        copy.config_key = key_env.downcase
+      end
+    end
+
     # True when gdkbox knows how to install this harness automatically.
     def installable?
       !@npm_package.nil?
     end
 
+    # The model id (`up --model`) stripped, or nil when blank. Raises when
+    # this harness cannot pin a model. The id reaches the agent only through
+    # the environment, so it needs no further validation.
+    def check_model!(model)
+      model = model.to_s.strip
+      return nil if model.empty?
+      raise Error, "The #{id} harness does not support --model yet." unless @model_flag
+
+      model
+    end
+
     # The in-box shell snippet that runs the agent against $GDKBOX_TASK. The
-    # caller wraps it with a timeout and sources the seeded API key.
-    def agent_command(json:, yolo:)
-      @run.call(json: json, yolo: yolo)
+    # caller wraps it with a timeout and sources the seeded API key. With a
+    # model, the snippet reads it from $GDKBOX_MODEL, which the caller sets.
+    def agent_command(json:, yolo:, model: nil)
+      cmd = @run.call(json: json, yolo: yolo)
+      check_model!(model) ? %(#{cmd} #{@model_flag} "$GDKBOX_MODEL") : cmd
     end
 
     register(
@@ -74,6 +109,7 @@ module GDKBox
       config_key: "anthropic_api_key",
       summary: "Anthropic Claude Code",
       skills_subdir: ".claude/skills",
+      model_flag: "--model",
       run: lambda do |json:, yolo:|
         cmd = +%(claude -p "$GDKBOX_TASK")
         cmd << " --output-format json" if json
@@ -90,6 +126,7 @@ module GDKBox
       config_key: "openai_api_key",
       summary: "OpenAI Codex CLI",
       skills_subdir: ".codex/skills",
+      model_flag: "-m",
       run: lambda do |json:, yolo:|
         cmd = +%(codex exec "$GDKBOX_TASK")
         cmd << " --json" if json
@@ -103,11 +140,15 @@ module GDKBox
       id: "opencode",
       npm_package: "opencode-ai",
       bin: "opencode",
-      # opencode reads provider keys from the environment; default to OpenAI.
-      key_env: "OPENAI_API_KEY",
-      config_key: "openai_api_key",
+      # opencode reads provider keys from the environment; default to its
+      # GitLab Duo provider (a personal access token with the `api` scope).
+      # Point a box at another provider with `up --key-env` (e.g.
+      # OPENAI_API_KEY).
+      key_env: "GITLAB_TOKEN",
+      config_key: "gitlab_token",
       summary: "opencode (sst)",
       skills_subdir: ".config/opencode/skills",
+      model_flag: "-m",
       run: lambda do |json:, yolo:|
         # `opencode run` is non-interactive and has no skip-permissions flag.
         +%(opencode run "$GDKBOX_TASK")
@@ -121,9 +162,10 @@ module GDKBox
       # docs recommend installing with --ignore-scripts.
       npm_flags: "--ignore-scripts",
       bin: "pi",
-      # pi is multi-provider; default the seeded key to Anthropic.
-      key_env: "ANTHROPIC_API_KEY",
-      config_key: "anthropic_api_key",
+      # pi is multi-provider; default the seeded key to GitLab Duo
+      # (GITLAB_TOKEN). Point a box at another provider with `up --key-env`.
+      key_env: "GITLAB_TOKEN",
+      config_key: "gitlab_token",
       summary: "pi (earendil-works)",
       skills_subdir: ".pi/skills",
       run: lambda do |json:, yolo:|
@@ -132,5 +174,9 @@ module GDKBox
         cmd
       end
     )
+
+    protected
+
+    attr_writer :key_env, :config_key
   end
 end

data/lib/gdkbox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GDKBox
-  VERSION = "0.1.19"
+  VERSION = "0.1.21"
 end

data/skills/gdkbox-fleet/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: gdkbox-fleet
+version: 1.0.0
 description: >-
   Orchestrate a fleet of GDK-in-a-box environments with the `gdkbox` CLI:
   provision a reusable pool of GitLab Development Kit boxes, then dispatch
@@ -66,6 +67,30 @@ Violating these is how "another agent stole my box" happens:
    user) and never in host-side metadata. Check readiness with the
    `api_key_set` field from `gdkbox ls --json` / `status --json`.
 
+### Other harnesses (e.g. opencode with GitLab Duo)
+
+The steps above assume the default Claude Code harness. If you are told to use
+another agent, or GitLab Duo, the harness, key env var and model are fixed
+**when the box is created**, so pass them to every `up`:
+
+```sh
+export GITLAB_TOKEN=<token>   # personal access token, api scope
+gdkbox up "pool-$i" --owner "$OWNER" --ttl 7200 --json \
+  --harness opencode --model gitlab/duo-chat-sonnet-4-5
+```
+
+- The opencode harness seeds `$GITLAB_TOKEN` (GitLab Duo) by default. For
+  another provider, pass `--key-env <VAR>` (e.g. `OPENAI_API_KEY`) and export
+  that variable instead.
+- `--model` pins the model `dispatch` uses. Use a `gitlab/duo-chat-*` model;
+  `duo-workflow-*` models do not work with a token.
+- An existing box cannot switch harness, key env or model. `gdkbox rm` it and
+  `up` it again.
+- Verify with `gdkbox ls --json`: `"harness"`, `"key_env"` and `"model"` must
+  match what you asked for, and `"api_key_set"` must be `true`.
+- `dispatch --json` output is harness-specific. For opencode it is plain text,
+  so rely on the exit status rather than parsing it.
+
 In the examples below, `gdkbox` means "the gdkbox CLI, however it is invoked".
 
 ## Command reference (what the orchestrator uses)
@@ -73,7 +98,8 @@ In the examples below, `gdkbox` means "the gdkbox CLI, however it is invoked".
 | Goal | Command |
 | --- | --- |
 | Create/start a box (claimed from birth) | `gdkbox up <name> --owner <id> --ttl <secs> [--json]` |
-| Seed/rotate API key | `gdkbox set-key <name>` (uses `$ANTHROPIC_API_KEY`) |
+| Create a non-Claude box | add `--harness <id> [--key-env <VAR>] [--model <id>]` to `up` (see above) |
+| Seed/rotate API key | `gdkbox set-key <name>` (uses the box's `key_env`, `$ANTHROPIC_API_KEY` by default) |
 | List the fleet (parseable) | `gdkbox ls --json` |
 | Inspect one box | `gdkbox status <name> --json` |
 | **Claim a free box** | `gdkbox claim --owner <id> --ttl <secs> --json` (or `gdkbox claim <name> ...`) |
@@ -97,8 +123,11 @@ In the examples below, `gdkbox` means "the gdkbox CLI, however it is invoked".
     "web_port": 3000,
     "web_url": "http://127.0.0.1:3000",
     "remote_path": "/home/gdk/gdk",
+    "harness": "claude",
     "claude_installed": true,
     "api_key_set": true,
+    "key_env": "ANTHROPIC_API_KEY",
+    "model": null,
     "claimed_by": "agent-7",
     "claim_expires_at": "2026-08-12T13:00:00Z"
   }
@@ -108,7 +137,8 @@ In the examples below, `gdkbox` means "the gdkbox CLI, however it is invoked".
 `claimed_by` is `null` for a free box (an expired lease counts as free).
 
 `dispatch` exits with the agent's own exit status (0 = success). With `--json`
-its stdout is Claude's structured result, which you can parse per task.
+its stdout is the agent's structured result (Claude's by default), which you
+can parse per task.
 
 ## Orchestration workflow
 
@@ -161,8 +191,10 @@ its stdout is Claude's structured result, which you can parse per task.
    ```
 
    When a dispatch returns, that box is idle again — assign it the next task
-   from the queue. Never run two dispatches against the same box at once,
-   and never dispatch into a box whose `claimed_by` is not your owner id.
+   from the queue, or **stop it immediately if nothing is queued for it**
+   (`gdkbox stop <box>`; see the "never leave a box running idle" guardrail).
+   Never run two dispatches against the same box at once, and never dispatch
+   into a box whose `claimed_by` is not your owner id.
 
    **Delegating to subagents:** the renewal in `run_task` above is for when
    *you* run the loop. If you hand a task to a subagent instead, do the
@@ -185,14 +217,20 @@ its stdout is Claude's structured result, which you can parse per task.
    and summarize per task: success/failure (exit status), what the agent did,
    and any follow-ups. Surface failures explicitly.
 
-6. **Wind down — release every box you claimed.** When the batch is done,
-   release **all** your boxes so the pool is usable by others (a lease would
-   expire eventually, but do not rely on it for normal completion). Then keep
-   them warm (`gdkbox stop`, later `gdkbox start`) or `gdkbox rm --force` to
-   discard:
+6. **Stop idle boxes as you go; release everything at wind-down.** A box with
+   no task running right now must not be left running — `gdkbox stop <box>`
+   it the moment it goes idle (stopping keeps the claim, license and seeded
+   data; `gdkbox start <box>` brings it straight back). Do this throughout the
+   batch, not only at the end — especially whenever you pause to wait on the
+   user, on a review, or on another box. See the guardrail below.
+
+   When the **whole batch is done**, stop every box, then release **all** of
+   them so the pool is usable by others (a lease would expire eventually, but
+   do not rely on it for normal completion), or `gdkbox rm --force` to discard:
 
    ```sh
    for b in $(gdkbox ls --json | jq -r ".[] | select(.claimed_by==\"$OWNER\") | .name"); do
+     gdkbox stop "$b"                      # no box left running once its work is done
      gdkbox release "$b" --owner "$OWNER"
    done
    ```
@@ -216,7 +254,8 @@ for i in 1 2 3; do
   gdkbox dispatch "pool-$i" --task-file "tasks/$i.md" --json > "out/$i.json" 2>&1 &
 done
 wait
-for i in 1 2 3; do gdkbox release "pool-$i" --owner "$OWNER"; done
+# batch done: stop each box so none is left running, then release the pool
+for i in 1 2 3; do gdkbox stop "pool-$i"; gdkbox release "pool-$i" --owner "$OWNER"; done
 ```
 
 Adopt one more existing free box when the queue outgrows the pool (each call
@@ -274,6 +313,15 @@ rest of the pool accordingly, and give the claim a generous `--ttl`.
   heavy. Prefer reusing the pool over creating more boxes.
 - **One dispatch per box at a time.** Serialize tasks on a box; parallelize
   *across* boxes.
+- **Never leave a box running idle.** A box is expensive (a full GDK
+  container); it must be running *only* while a dispatch is actually using it.
+  The moment a box has no task queued for it — including whenever the
+  orchestration pauses to wait on the user, on a review, or on another box —
+  `gdkbox stop <box>` it. Stopping frees the host's memory and CPU but **keeps
+  the claim, license and seeded data**, so `gdkbox start <box>` resumes it in
+  seconds. Keep the claim while the box is yours and only *release* at session
+  wind-down; stopping is for idleness, releasing is for "done with it". If you
+  stopped boxes mid-session, `gdkbox start` them again before dispatching.
 - **Own every box you touch, for the whole batch.** Provision with
   `up --owner`, adopt with `claim`, and hold the claims until wind-down —
   then release them all. Claims are advisory: `dispatch` will not stop you

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gdkbox
 version: !ruby/object:Gem::Version
-  version: 0.1.19
+  version: 0.1.21
 platform: ruby
 authors:
 - jotolo