gdkbox 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbe76156f93120de2292273e79d4c49cb904abdd94ad795846d4d5f9f1799cc3
-  data.tar.gz: 35fbbb2d4117272ba07c9cbaebed129224aea4ee0762095324139d896e50cd21
+  metadata.gz: 17efb5fee81f15043aed3c8dbabe3e9259c70a8d8a03dd400b8103231b36a9d6
+  data.tar.gz: d926bbae45cbe226fec0530f43e11e12f1ef346450e5801909c251e6f159bf66
 SHA512:
-  metadata.gz: 01243dc3ba079e8e2120a14bd7d352d6e8ac41977afa4cb53da4677fc0dc2f0ed0e7eab0e47ebcd2ced1fe19ee7e781dc0d5f56674a5fcfc1f1843a5ae828ec7
-  data.tar.gz: 95fe2b453bf0a0e44453633c0f947069bfecb550bdc7317f1c996f6fe9019cf6f5aed0e2324c52a45db843abd0ded19ddffc62654b7c3164f1a3ed3293aab40c
+  metadata.gz: 179859b546c7b76825d22d6e100b39446d96205adaab696982f960409f14041a8135daf67600d3755545613537a011131302c238de44fefd64df5a7980834227
+  data.tar.gz: 59f9e916539ca282cc16ec86e8fde2ab8437541aad4c433d4c5a2895f49017cf747880f75e3777e80c39b88e767591c9a8b18d115badfae9fcabf4525bc22f2d

data/README.md

@@ -91,6 +91,7 @@ Or run it straight from the checkout without installing:
 | `gdkbox set-key NAME` | Seed/rotate the Anthropic API key in the box for unattended dispatch. |
 | `gdkbox set-host` | Add the `gdk.local` entry to your `/etc/hosts` so box web UIs resolve (`--remove` to undo). Also runs during `up`. |
 | `gdkbox set-git NAME` | Seed your git identity (`user.name`/`user.email`) into the box so `git commit` works. Also runs during `up`. |
+| `gdkbox set-gcloud NAME` | Copy the host's Google Cloud application-default credentials into the box (Duo / Vertex AI model access; `--file` to override). |
 | `gdkbox set-remote NAME [REMOTE]` | Point the box's GitLab checkout at a different remote (URL or `namespace/project`, e.g. `gitlab-org/gitlab`); default from config.yml. |
 | `gdkbox hydrate NAME` | Backfill the box's treeless GitLab clone so deep rebases/blame/bisect work (`--trees` for a much smaller trees-only fetch). |
 | `gdkbox claim [NAME]` | Claim a box for exclusive use — any free box when NAME is omitted (`--owner ID`, optional `--ttl SECS` lease, `--json`). Advisory lock for orchestrators. |
@@ -119,6 +120,8 @@ Or run it straight from the checkout without installing:
 | `--gitlab-remote REMOTE` | config.yml, else image default | Point the GitLab checkout at this remote (URL or `namespace/project`); the image ships pointing at the community mirror. |
 | `--owner ID` | (unclaimed) | Claim the box for this owner at creation — no window for another orchestrator to grab it. |
 | `--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`). |
 
 ## Typical workflow
 
@@ -159,6 +162,108 @@ gdkbox hydrate demo           # full backfill: several GB, then the clone
                               # behaves like a normal full clone
 ```
 
+### Docker inside a box (CI docker executor)
+
+Some workloads — notably GitLab Duo agentic flows — finish by running a CI job
+with the **docker executor**, which needs a Docker daemon. Boxes have none by
+default. `gdkbox up NAME --docker` wires it up:
+
+- The **host Docker socket** is mounted into the box and the Docker CLI is
+  installed there, so the box drives the *host* daemon. Containers the box
+  starts are **siblings on the host**, not children of the box.
+- The box joins a per-box network (`gdkbox-NAME`) with the alias `gdk.local`,
+  so sibling containers can reach the box's GitLab by hostname. Point the
+  box's GitLab Runner at it in `config.toml`:
+
+  ```toml
+  [runners.docker]
+    network_mode = "gdkbox-NAME"   # job containers resolve gdk.local natively
+  ```
+
+**Security:** the socket is root-equivalent control of the **host** — anything
+running in a `--docker` box (including dispatched agents, which skip permission
+prompts) can start privileged containers, mount host paths, and read other
+boxes. Only use `--docker` on boxes whose workloads you trust like your own
+shell, and never combine it with unattended agent tasks you wouldn't run on
+the host directly.
+
+### Running Duo agentic flows in a box
+
+The main consumer of `--docker` is the GitLab Duo Agent Platform: a flow ends
+by running a docker-executor CI job.
+
+<details>
+<summary><strong>Step-by-step setup</strong> (distilled from a real end-to-end
+run; verify commands against the
+<a href="https://gitlab-org.gitlab.io/gitlab-development-kit/howto/ai">GDK AI
+howto</a>)</summary>
+
+
+
+1. **Provision**:
+   `gdkbox up duo-1 --docker --publish 5052 50052` then
+   `gdkbox set-gcloud duo-1` (Vertex AI credentials; the flow model routes
+   through Vertex, project selected by `AIGW_GOOGLE_CLOUD_PLATFORM__PROJECT`).
+2. **AI services** (inside the box): `gdk rake setup_ai_services` clones the
+   `gitlab-ai-gateway` monorepo and builds its Python env — **~20 minutes**,
+   needs a valid `ANTHROPIC_API_KEY` (a dead key blocks Chat, service boot,
+   and flows). Budget memory: GDK + AI stack + flow containers want well over
+   10 GB free.
+3. **The env asymmetry that causes most failures**: the AI Gateway reads
+   `gitlab-ai-gateway/.env`, but the Duo Workflow Service reads **`env.runit`**
+   at the GDK root. `ANTHROPIC_API_KEY` (unquoted),
+   `DUO_WORKFLOW_AUTH__ENABLED=false`, the demo JWT keys from `example.env`,
+   and `AIGW_GOOGLE_CLOUD_PLATFORM__PROJECT` all go in `env.runit`.
+4. **Agentic WebSocket 403 fix**: `gdk config set gitlab_http_router.enabled
+   false && gdk config set nginx.enabled true && gdk reconfigure` — the
+   http-router rewrites the upstream Host and workhorse rejects the flow's
+   WebSocket upgrade (classic Chat works, flows 403). Also set the acting
+   user's `duo_default_namespace_id` to the seeded `gitlab-duo` group.
+5. **Point at the local gateway and seed**:
+   `gdk config set gitlab_ai_gateway.environment local`, then from `gitlab/`:
+   `DEVELOPMENT_AI_GATEWAY_URL="http://gdk.local:5052" GITLAB_SIMULATE_SAAS=1
+   bundle exec rake gitlab:duo:setup` and `... gitlab:duo:onboard_dap`.
+   A fresh box has no license, so `gitlab:duo:setup` aborts with
+   **"No license found"** — import one first (e.g. copy the `data` column from
+   your host GDK's `licenses` table and load it in the box's Rails console
+   with `License.new(data: data, cloud: true).save!`).
+6. **Runner**: in a `--docker` box the socket is already at
+   `/var/run/docker.sock` (no `docker_host` override needed). Three
+   `[runners.docker]` settings in the generated `gitlab-runner-config.toml`
+   matter — GDK's template doesn't persist them, so re-apply after any
+   `gdk reconfigure`:
+
+   ```toml
+   [runners.docker]
+     network_mode = "gdkbox-duo-1"  # job containers resolve gdk.local natively
+     privileged = false             # privileged breaks the flow sandbox (below)
+     volumes = ["/tmp/gdkbox-docker-cfg/certs.d:/etc/docker/certs.d",
+                "/certs/client", "/cache"]
+   ```
+
+   Because the box drives the **host** daemon, volume *source* paths must
+   exist **on the host**, not in the box — a box-only path fails the job with
+   `mounts denied: path not shared from host`. And with `privileged = true`
+   the flow's `unshare` sandbox loses network access to `gdk.local`, so the
+   job dies with "Workflow could not connect to the Workflow service /
+   User: not authenticated"; keep the runner unprivileged.
+7. **Verify**: AI Gateway answers on `http://gdk.local:5052/docs` (published
+   by `--publish`), the workflow service binds `:50052`, and triggering the
+   `developer` flow from an issue in the seeded `gitlab-duo` project completes
+   and opens a Draft MR.
+
+> **Note — rate-limited Anthropic keys**: if your key returns `429
+> rate_limit_error` on the default Sonnet models, chat and flows fail even
+> though the setup is correct. Pin Duo to a model your key can use (e.g.
+> Haiku): per namespace, run
+> `Ai::ModelSelection::Namespace::UpdateService.new(feature_setting, group,
+> {offered_model_ref: "claude_haiku_4_5_20251001"}).execute` in the box's
+> Rails console (needs `GITLAB_SIMULATE_SAAS=1`, silently returns `nil`
+> without it), and for the AI Gateway defaults rewrite the model refs in
+> `gitlab-ai-gateway/ai_gateway/model_selection/unit_primitives.yml`.
+
+</details>
+
 ## Orchestrating a fleet of agents
 
 The end goal of `gdkbox` is to back an **orchestrator** that runs a pool of

data/lib/gdkbox/box.rb

@@ -91,7 +91,7 @@ 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)
+      claim_owner: nil, claim_ttl: nil, docker_access: false, extra_ports: [])
       raise Error, "Box '#{name}' already exists" if exists?
 
       harness = Harness[harness]
@@ -110,10 +110,28 @@ module GDKBox
       # choose ports *and* persist a preliminary record makes each sibling see
       # the others' reservations.
       ssh_port, web_port, vite_port = reserve_ports!(
-        cname, ssh_port, web_port, vite_port,
+        cname, ssh_port, web_port, vite_port, extra_ports,
         claim_owner: claim_owner, claim_ttl: claim_ttl
       )
 
+      publish = [
+        "127.0.0.1:#{ssh_port}:#{Config::SSH_CONTAINER_PORT}",
+        "127.0.0.1:#{web_port}:#{Config::GDK_WEB_CONTAINER_PORT}",
+        # Same number on both sides: asset URLs embed this port, so what
+        # the browser dials must be where vite listens (see VITE_PORT_BASE).
+        "127.0.0.1:#{vite_port}:#{vite_port}"
+      ]
+      # Extra ports publish same-numbered too: in-box services advertise
+      # their own port, so what the host dials must match.
+      extra_ports.each { |port| publish << "127.0.0.1:#{port}:#{port}" }
+
+      # Docker access: mount the host socket (containers the box starts are
+      # siblings on the host daemon) and put the box on its own network with
+      # a gdk.local alias, so those siblings — docker-executor CI jobs — can
+      # reach the box's GitLab by hostname.
+      net = docker_access ? @config.docker_network(name) : nil
+      @docker.ensure_network(net) if net
+
       begin
         @docker.run_container(
           name: cname,
@@ -122,19 +140,17 @@ module GDKBox
           # set inside the container, workhorse and the http-router crash-loop
           # on DNS timeouts.
           hostname: Config::GDK_HOSTNAME,
-          publish: [
-            "127.0.0.1:#{ssh_port}:#{Config::SSH_CONTAINER_PORT}",
-            "127.0.0.1:#{web_port}:#{Config::GDK_WEB_CONTAINER_PORT}",
-            # Same number on both sides: asset URLs embed this port, so what
-            # the browser dials must be where vite listens (see VITE_PORT_BASE).
-            "127.0.0.1:#{vite_port}:#{vite_port}"
-          ],
+          publish: publish,
+          volumes: (docker_access ? ["#{Config::DOCKER_SOCKET}:#{Config::DOCKER_SOCKET}"] : []),
+          network: net,
+          network_alias: (net ? Config::GDK_HOSTNAME : nil),
           labels: { "gdkbox" => "true", "gdkbox.name" => name }
         )
       rescue StandardError
         # The container never started, so release the reserved ports rather
         # than stranding a record that points at nothing.
         @store.delete(name)
+        @docker.rm_network(net) if net
         raise
       end
 
@@ -152,8 +168,24 @@ module GDKBox
         "harness" => harness.id,
         "created_at" => Time.now.utc.iso8601
       )
+      if docker_access
+        @data["docker_access"] = true
+        @data["docker_network"] = net
+      end
       @store.save(@data)
 
+      # Docker CLI + socket access for the gdk user. Best-effort (needs the
+      # network for the static CLI download); the outcome is recorded so the
+      # CLI can print a retry hint.
+      if docker_access
+        @data["docker_cli_installed"] = begin
+          provisioner.setup_docker_cli(cname)
+          true
+        rescue StandardError
+          false
+        end
+      end
+
       # Align vite's in-container listen port with the published one so asset
       # URLs work from the host browser. Best-effort — the box is fully
       # usable for SSH/agent work without it — but the outcome is recorded
@@ -199,7 +231,9 @@ module GDKBox
     end
 
     def destroy!
+      network = data && data["docker_network"]
       @docker.rm(container_name, force: true)
+      @docker.rm_network(network) if network
       @store.delete(name)
     end
 
@@ -366,6 +400,27 @@ module GDKBox
       result
     end
 
+    # Copy Google Cloud application-default credentials into the box so Duo /
+    # Vertex AI model calls can authenticate. The file holds a refresh token,
+    # so copying works where an in-box `gcloud auth` login cannot (no
+    # browser). Stored 0600, owned by the GDK user, inside the container only.
+    def set_gcloud_credentials!(source_path)
+      unless File.file?(source_path)
+        raise Error, "No credentials file at #{source_path}. Run " \
+          "`gcloud auth application-default login` on the host first, or pass --file."
+      end
+
+      dir = "/home/#{@config.ssh_user}/.config/gcloud"
+      dest = "#{dir}/application_default_credentials.json"
+      @docker.exec(container_name, 'install -d -m 700 -o "$GDKBOX_USER" -g "$GDKBOX_USER" "$GDKBOX_DIR"',
+        user: "root", env: { "GDKBOX_USER" => @config.ssh_user, "GDKBOX_DIR" => dir })
+      @docker.cp_into(container_name, source_path, dest)
+      @docker.exec(container_name,
+        'chown "$GDKBOX_USER:$GDKBOX_USER" "$GDKBOX_DEST" && chmod 600 "$GDKBOX_DEST"',
+        user: "root", env: { "GDKBOX_USER" => @config.ssh_user, "GDKBOX_DEST" => dest })
+      dest
+    end
+
     # Seed a git identity into the box so `git commit` works there. Falls back
     # to the host's `git config` when name/email are not given; raises when
     # neither source has anything to seed. Returns the [name, email] seeded.
@@ -478,6 +533,12 @@ module GDKBox
         # support) and whether the in-box alignment step succeeded.
         "vite_port" => vite_port,
         "vite_port_configured" => (data && data["vite_port_configured"]) || false,
+        "extra_ports" => (data && data["extra_ports"]) || [],
+        # Docker access (up --docker): host socket mounted; docker_network is
+        # the per-box network CI job containers should use as network_mode.
+        "docker_access" => (data && data["docker_access"]) || false,
+        "docker_network" => (data && data["docker_network"]),
+        "docker_cli_installed" => (data && data["docker_cli_installed"]) || false,
         # Active claim (nil when free; an expired lease counts as free).
         "claimed_by" => claimed_by,
         "claim_expires_at" => (claimed_by ? data["claim_expires_at"] : nil)
@@ -518,11 +579,15 @@ module GDKBox
     # than the cryptic bind error `docker run` would produce later.
     # A claim_owner is written into this same record, so the box is claimed
     # from the instant it becomes visible to other processes.
-    def reserve_ports!(cname, ssh_port, web_port, vite_port, claim_owner: nil, claim_ttl: nil)
-      { "--ssh-port" => ssh_port, "--web-port" => web_port,
-        "--vite-port" => vite_port }.each do |flag, port|
+    def reserve_ports!(cname, ssh_port, web_port, vite_port, extra_ports,
+      claim_owner: nil, claim_ttl: nil)
+      checks = { "--ssh-port" => ssh_port, "--web-port" => web_port,
+                 "--vite-port" => vite_port }
+      extra_ports.each_with_index { |port, i| checks["--publish #{i}"] = port }
+      checks.each do |flag, port|
         if port && Ports.bound?(port)
-          raise Error, "Port #{port} (#{flag}) is already in use on 127.0.0.1."
+          raise Error,
+            "Port #{port} (#{flag.sub(/ \d+\z/, '')}) is already in use on 127.0.0.1."
         end
       end
 
@@ -536,6 +601,7 @@ module GDKBox
           "ssh_port" => ssh_port,
           "web_port" => web_port,
           "vite_port" => vite_port,
+          "extra_ports" => extra_ports,
           "agent_installed" => false,
           "api_key_set" => false
         }

data/lib/gdkbox/cli.rb

@@ -48,6 +48,12 @@ module GDKBox
         "orchestrator to grab it; see `gdkbox claim`)"
     option :ttl, type: :numeric,
       desc: "Lease duration in seconds for --owner's claim (default: no expiry)"
+    option :docker, type: :boolean, default: false,
+      desc: "Mount the host Docker socket so the box can run docker-executor CI jobs " \
+        "(grants the box root-equivalent control of the HOST — see README)"
+    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)"
     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)."
@@ -68,7 +74,9 @@ module GDKBox
         install_agent: options[:agent],
         api_key: api_key,
         claim_owner: options[:owner],
-        claim_ttl: options[:ttl]
+        claim_ttl: options[:ttl],
+        docker_access: options[:docker],
+        extra_ports: parse_extra_ports(options[:publish])
       )
       rewrite_ssh_config
       seed_skills(box)
@@ -82,6 +90,18 @@ module GDKBox
       setup_host
 
       say "\nBox '#{name}' is up.", :green
+      if options[:docker]
+        if box.data["docker_cli_installed"]
+          say "\n  Docker: host socket mounted; the box drives the HOST daemon " \
+            "(containers it starts are siblings).", :yellow
+          say "  CI docker-executor jobs reach this GitLab via the box's network — " \
+            "in the runner's config.toml set:", :cyan
+          say "    network_mode = \"#{box.data['docker_network']}\"", :cyan
+        else
+          say "\n  Could not install the Docker CLI in the box (network hiccup?). " \
+            "Retry: gdkbox rm #{name} && gdkbox up #{name} --docker", :yellow
+        end
+      end
       unless box.data["vite_port_configured"]
         say "\n  Could not align the box's vite port with the published " \
           "#{box.vite_port} — browser asset loading may fail.", :yellow
@@ -401,6 +421,26 @@ module GDKBox
       say "Done. '#{name}' can now work across the full history.", :green
     end
 
+    desc "set-gcloud NAME", "Copy Google Cloud application-default credentials into the box"
+    long_desc <<~DESC
+      Duo / Vertex AI model calls from inside a box need Google Cloud
+      application-default credentials, and `gcloud auth application-default
+      login` cannot run in a box (no browser). This copies the host's ADC
+      file — which holds a refresh token, so it works from inside the
+      container — into the box at ~/.config/gcloud/, mode 0600, owned by the
+      GDK user. Defaults to the host's own ADC file; override with --file.
+    DESC
+    option :file, type: :string,
+      desc: "Credentials file to copy (default: ~/.config/gcloud/application_default_credentials.json)"
+    def set_gcloud(name)
+      box = load_box!(name)
+      source = options[:file] ||
+        File.join(Dir.home, ".config", "gcloud", "application_default_credentials.json")
+      dest = box.set_gcloud_credentials!(source)
+      say "Copied gcloud application-default credentials into '#{name}' (#{dest}).", :green
+    end
+    map "set-gcloud" => :set_gcloud
+
     desc "set-host", "Add (default) or remove the gdk.local entry in /etc/hosts"
     long_desc <<~DESC
       GDK generates URLs and redirects that use the `gdk.local` hostname, so
@@ -615,6 +655,18 @@ module GDKBox
       warn "gdkbox: retry later with: gdkbox set-remote #{box.name} #{remote}"
     end
 
+    # --publish values as integer container ports, validated.
+    def parse_extra_ports(values)
+      values.map do |value|
+        port = Integer(value, exception: false)
+        unless port&.between?(1, 65_535)
+          raise Error, "--publish expects port numbers (got '#{value}')."
+        end
+
+        port
+      end.uniq
+    end
+
     # Ensure gdk.local resolves on the host so the box's web UI is reachable
     # (GDK redirects to that hostname). Adding the entry needs sudo, so warn
     # before any password prompt appears. Failures are non-fatal: the box is

data/lib/gdkbox/completion.rb

@@ -11,8 +11,8 @@ module GDKBox
     SHELLS = %w[bash zsh].freeze
 
     # Subcommands whose first positional argument is an existing box.
-    BOX_COMMANDS = %w[status dispatch ssh code install-agent set-key set-git set-remote hydrate
-      claim release start stop rm add-skill].freeze
+    BOX_COMMANDS = %w[status dispatch ssh code install-agent set-key set-git set-remote
+      set-gcloud hydrate claim release start stop rm add-skill].freeze
 
     # Marker identifying the rc-file block `install` manages.
     MARKER = "# gdkbox:completion"

data/lib/gdkbox/config.rb

@@ -29,6 +29,11 @@ module GDKBox
     # follow GDK's redirects to it).
     GDK_HOSTNAME = "gdk.local"
 
+    # The host Docker socket, mounted into a box by `up --docker` so the box
+    # can run docker-executor CI jobs (containers it starts are siblings on
+    # the host daemon).
+    DOCKER_SOCKET = "/var/run/docker.sock"
+
     CONTAINER_PREFIX = "gdkbox-"
     HOST_ALIAS_PREFIX = "gdkbox-"
 
@@ -159,6 +164,13 @@ module GDKBox
       "#{CONTAINER_PREFIX}#{name}"
     end
 
+    # Per-box user-defined network for --docker boxes. Per-box (not shared)
+    # so each box can hold the gdk.local alias without DNS round-robin
+    # between boxes.
+    def docker_network(name)
+      "#{CONTAINER_PREFIX}#{name}"
+    end
+
     def ssh_host_alias(name)
       "#{HOST_ALIAS_PREFIX}#{name}"
     end

data/lib/gdkbox/docker.rb

@@ -196,9 +196,15 @@ module GDKBox
     # Docker also maps it to the container's IP in the container's /etc/hosts
     # and re-applies that mapping on every start (a manual edit would be lost:
     # Docker regenerates the file when the container starts).
-    def run_container(name:, image:, publish: [], labels: {}, env: {}, args: [], hostname: nil)
+    def run_container(name:, image:, publish: [], labels: {}, env: {}, args: [], hostname: nil,
+      volumes: [], network: nil, network_alias: nil)
       cmd = ["docker", "run", "-d", "--name", name]
       cmd.push("--hostname", hostname) if hostname
+      cmd.push("--network", network) if network
+      # A network alias gives the box a DNS name *on that network*, so sibling
+      # containers (e.g. docker-executor CI jobs) can reach it by hostname.
+      cmd.push("--network-alias", network_alias) if network_alias
+      volumes.each { |mapping| cmd.push("-v", mapping) }
       labels.each { |key, value| cmd.push("--label", "#{key}=#{value}") }
       env.each { |key, value| cmd.push("-e", "#{key}=#{value}") }
       publish.each { |mapping| cmd.push("-p", mapping) }
@@ -207,6 +213,18 @@ module GDKBox
       @shell.run!(*cmd).stdout.strip
     end
 
+    # Create a user-defined bridge network if it does not exist (idempotent).
+    def ensure_network(name)
+      return if @shell.run("docker", "network", "inspect", name).success?
+
+      @shell.run!("docker", "network", "create", name)
+    end
+
+    # Remove a network; a failure (still in use, already gone) is not fatal.
+    def rm_network(name)
+      @shell.run("docker", "network", "rm", name)
+    end
+
     # Run a bash script inside a running container. The script is passed to
     # `bash -lc` as a single argument; values that vary (keys, usernames) are
     # passed through the environment to avoid quoting pitfalls.

data/lib/gdkbox/provisioner.rb

@@ -205,6 +205,35 @@ module GDKBox
       fi
     BASH
 
+    # Static Docker CLI release installed into --docker boxes. A pinned
+    # version keeps provisioning reproducible; the static tarball needs no
+    # apt repo and exists for both x86_64 and aarch64.
+    DOCKER_CLI_VERSION = "27.5.1"
+
+    # Give a --docker box a working `docker` command against the mounted host
+    # socket: install the (arch-matched) static CLI, then grant the GDK user
+    # access to the socket via whatever group owns it — gid 0 on Docker
+    # Desktop, the docker group's gid on Linux hosts. Group membership takes
+    # effect on new login sessions, which is what dispatch/ssh create.
+    DOCKER_CLI_SETUP = <<~'BASH'
+      set -e
+      if ! command -v docker >/dev/null 2>&1; then
+        arch=$(uname -m)
+        curl -fsSL "https://download.docker.com/linux/static/stable/${arch}/docker-${GDKBOX_DOCKER_CLI_VERSION}.tgz" \
+          | tar -xz -C /tmp docker/docker
+        install -m 755 /tmp/docker/docker /usr/local/bin/docker
+        rm -rf /tmp/docker
+      fi
+      sock_gid=$(stat -c %g "$GDKBOX_DOCKER_SOCKET")
+      group=$(getent group "$sock_gid" | cut -d: -f1)
+      if [ -z "$group" ]; then
+        group=gdkbox-docker
+        groupadd -g "$sock_gid" "$group"
+      fi
+      usermod -aG "$group" "$GDKBOX_USER"
+      docker --version
+    BASH
+
     def initialize(docker:, config:)
       @docker = docker
       @config = config
@@ -242,6 +271,18 @@ module GDKBox
       )
     end
 
+    def setup_docker_cli(container_name)
+      @docker.exec(
+        container_name, DOCKER_CLI_SETUP,
+        user: "root",
+        env: {
+          "GDKBOX_USER" => @config.ssh_user,
+          "GDKBOX_DOCKER_SOCKET" => Config::DOCKER_SOCKET,
+          "GDKBOX_DOCKER_CLI_VERSION" => DOCKER_CLI_VERSION
+        }
+      )
+    end
+
     def setup_vite_port(container_name, port)
       @docker.exec(
         container_name, VITE_PORT_SETUP,

data/lib/gdkbox/store.rb

@@ -41,7 +41,9 @@ module GDKBox
 
     # Every host port already claimed by an existing box.
     def used_ports
-      all.flat_map { |box| [box["ssh_port"], box["web_port"], box["vite_port"]] }.compact
+      all.flat_map do |box|
+        [box["ssh_port"], box["web_port"], box["vite_port"], *box["extra_ports"]]
+      end.compact
     end
   end
 end

data/lib/gdkbox/version.rb

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

data/skills/gdkbox-fleet/SKILL.md

@@ -240,6 +240,34 @@ Free a box stranded by a dead orchestrator (check `gdkbox ls` first):
 gdkbox release pool-2 --force
 ```
 
+## Running Duo agentic flows (needs `--docker`)
+
+Duo Agent Platform flows finish in a docker-executor CI job, so a flow-capable
+box needs Docker access — this is the sanctioned use of `--docker` (see the
+guardrail below; keep such boxes confined to the flow work). Provision it as
+its own claimed box:
+
+```sh
+gdkbox up duo-1 --owner "$OWNER" --ttl 14400 --docker --publish 5052 50052
+gdkbox set-gcloud duo-1      # Vertex AI credentials for the flow model
+```
+
+Then, inside the box (dispatch these as tasks or run them over `gdkbox ssh`),
+follow the README's "Running Duo agentic flows in a box" steps — in short:
+`gdk rake setup_ai_services` (~20 min, needs a valid `ANTHROPIC_API_KEY`);
+put the workflow service's env in **`env.runit`** (not `.env` — the two
+services read different files); disable `gitlab_http_router` and enable nginx
+(the router 403s the flow's WebSocket upgrade); set
+`gitlab_ai_gateway.environment local` and run the `gitlab:duo:setup` /
+`onboard_dap` seeds; add `network_mode = "gdkbox-duo-1"` to the generated
+runner config (re-apply after `gdk reconfigure`). Verified end state: the
+`developer` flow triggered from an issue in the seeded `gitlab-duo` project
+completes and opens a Draft MR.
+
+Plan for this box being expensive: the AI setup is ~20 minutes and the box
+wants >10 GB free memory once the AI stack and flow containers run — size the
+rest of the pool accordingly, and give the claim a generous `--ttl`.
+
 ## Guardrails
 
 - **Don't exceed the box count the machine can handle** — each GDK box is
@@ -263,3 +291,10 @@ gdkbox release pool-2 --force
 - **Boxes are isolated.** Dispatch runs with `--dangerously-skip-permissions`
   by default because the work happens inside a disposable container; pass
   `--no-yolo` if you need permission prompts honored.
+- **`--docker` boxes are NOT isolated.** `up --docker` mounts the host Docker
+  socket, which is root-equivalent control of the host machine — the
+  isolation argument above does not hold there. Provision `--docker` when
+  the orchestration goal requires docker-executor CI (running Duo agentic
+  flows is the canonical case), and confine such boxes to that goal's own
+  tasks: never route unrelated, untrusted, or third-party work into a
+  `--docker` box, and prefer plain boxes for everything else.

metadata

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