gdkbox 0.1.18 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbe76156f93120de2292273e79d4c49cb904abdd94ad795846d4d5f9f1799cc3
-  data.tar.gz: 35fbbb2d4117272ba07c9cbaebed129224aea4ee0762095324139d896e50cd21
+  metadata.gz: 6a5d8a8a1fbb33083f8cfb0b306ee0d6fc4efaffad04a110ef9f1a55141baae5
+  data.tar.gz: f4ec5a9b60bf6ab209ced26b1c0ec9c6b95503ae6a65484844506553055ea900
 SHA512:
-  metadata.gz: 01243dc3ba079e8e2120a14bd7d352d6e8ac41977afa4cb53da4677fc0dc2f0ed0e7eab0e47ebcd2ced1fe19ee7e781dc0d5f56674a5fcfc1f1843a5ae828ec7
-  data.tar.gz: 95fe2b453bf0a0e44453633c0f947069bfecb550bdc7317f1c996f6fe9019cf6f5aed0e2324c52a45db843abd0ded19ddffc62654b7c3164f1a3ed3293aab40c
+  metadata.gz: 596f76ed57ea61c0fc0a00a7e0cd72a917a076aa9fcf022127d8b3ac7e5303c6ccb2c60e30c24727dcedb402f14065da1776be58832d1d28446b070850b09145
+  data.tar.gz: 1e4e94bc489cfc712b5e7a7386cad211e5cdf26b826eddeb43fa5e2bf47cacfde8c945677d896c5a21e97deef8dae99458133ebb4a3253a2530142c66404ff77

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,10 @@ 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`). |
+| `--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
 
@@ -159,6 +164,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
@@ -268,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
@@ -280,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
 
@@ -334,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)
+      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)
@@ -110,10 +119,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 +149,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 +177,26 @@ 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
+      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 +242,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 +411,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.
@@ -438,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})
@@ -452,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)
@@ -460,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,
@@ -474,10 +541,18 @@ 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,
         "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 +593,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 +615,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,18 @@ 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)"
+    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)."
@@ -55,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]
@@ -68,7 +81,11 @@ 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]),
+        key_env: options[:key_env],
+        model: model
       )
       rewrite_ssh_config
       seed_skills(box)
@@ -82,6 +99,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 +430,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 +664,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
@@ -702,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/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/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/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.20"
 end

data/skills/gdkbox-fleet/SKILL.md

@@ -66,6 +66,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 +97,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 +122,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 +136,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
 
@@ -240,6 +269,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 +320,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.20
 platform: ruby
 authors:
 - jotolo