gdkbox 0.1.3 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2087c010d2c52bff4fddfd421d1ba713b9f0721c701674753813ecca7093054d
-  data.tar.gz: 9e697f3f33e5823296bc3e963f94025819b02b9dc340b9234d350b80b737498a
+  metadata.gz: e1c7b818ffd457d8f32f3d80073585222be0140ba3ae5c32a76b587bae5a98f5
+  data.tar.gz: 35b56df278015bbf0ad44cf175665c481cddd3939bc2130a5b72d193aec44c90
 SHA512:
-  metadata.gz: d449dca72e949adb5cc497a7dedb8b707c6a0b03ee01b2bbae0ad2193f8e8287294f3281b95d5b2bf01241c014a2c9db4b4b7cea04ce348ddbe370a63df248b6
-  data.tar.gz: 67f02e778e1aa18e7a9463e2527c7f9eaed877ecb6d3b9c8a2b8b2f761efe3147083f7745155a98ff36453d1396447ef2d53370b15e96873608e85a9387c38c7
+  metadata.gz: d0fd71a1460e658cd975298666fc7afaa1110a2b154a0da005bc80c7c4e9bdb21545ab544091c5a2f2773eab48e2e9520311e24b39c16962a7ae2416b9024bcf
+  data.tar.gz: 44638a681108d58ddafdb1a9d4703f5a1f84cd6da764dae608d25ead66a3ebba8f4bb9057d57c38176ecd4f3c49e5c6809636c159c5c8ebbd0803c4b0ff2415d

data/README.md

@@ -1,5 +1,9 @@
 # gdkbox
 
+[![Gem Version](https://img.shields.io/gem/v/gdkbox)](https://rubygems.org/gems/gdkbox)
+[![Gem Downloads](https://img.shields.io/gem/dt/gdkbox)](https://rubygems.org/gems/gdkbox)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 Spin up a [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit)
 "in a box" with a single command, then connect to it from **VS Code** and run
 **Claude Code** agents against a real GitLab development environment.
@@ -22,7 +26,7 @@ gdkbox ls               # list your boxes and their status
    ┌──────────────┼─────────────────────────────────────────────┐
    │              ▼                                               │
    │   1. docker pull  <official GDK image>                       │
-   │   2. docker run   -p 127.0.0.1:2222:22  -p 127.0.0.1:3000:3000
+   │   2. docker run   --hostname gdk.local  -p 127.0.0.1:2222:22  -p 127.0.0.1:3000:3000
    │   3. provision    install + start sshd, authorize gdkbox key │
    │   4. provision    npm install -g @anthropic-ai/claude-code   │
    │   5. register     Host gdkbox-demo  ->  ~/.gdkbox/ssh_config  │
@@ -51,14 +55,22 @@ gdkbox ls               # list your boxes and their status
 
 ## Install
 
-From this directory:
+`gdkbox` is published on [RubyGems](https://rubygems.org/gems/gdkbox):
+
+```sh
+gem install gdkbox
+```
+
+### From source
+
+To build and install from a checkout of this repository:
 
 ```sh
 gem build gdkbox.gemspec
-gem install ./gdkbox-0.1.0.gem
+gem install ./gdkbox-*.gem
 ```
 
-Or run it straight from a checkout without installing:
+Or run it straight from the checkout without installing:
 
 ```sh
 ./bin/gdkbox up myenv
@@ -68,7 +80,7 @@ Or run it straight from a checkout without installing:
 
 | Command | Description |
 | --- | --- |
-| `gdkbox up NAME` | Pull the GDK image, start a box, enable SSH, install Claude Code, register VS Code host. |
+| `gdkbox up NAME` | Pull the GDK image (only if not already local), start a box, enable SSH, install Claude Code, register VS Code host. |
 | `gdkbox update-image` | Pull the latest GDK-in-a-box image, with a progress bar and download speed (`--image` to override). |
 | `gdkbox ls` | List boxes and their container status (`--json` for orchestrators). |
 | `gdkbox status NAME` | Show container state and connection details (`--json`). |
@@ -77,6 +89,7 @@ Or run it straight from a checkout without installing:
 | `gdkbox ssh NAME` | Open an interactive SSH session into the box. |
 | `gdkbox claude NAME` | Install Claude Code inside the box. |
 | `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 start NAME` | Start a stopped box (and re-enable SSH). |
 | `gdkbox stop NAME` | Stop a running box. |
 | `gdkbox rm NAME` | Remove a box: container, metadata, and SSH entry. |
@@ -92,8 +105,8 @@ Or run it straight from a checkout without installing:
 | Option | Default | Description |
 | --- | --- | --- |
 | `--image` | official GDK image | Override the container image. |
-| `--ssh-port` | next free from 2222 | Host port to publish SSH on. |
-| `--web-port` | next free from 3000 | Host port to publish the GDK web UI on. |
+| `--ssh-port` | next free from 2222 | Host port to publish SSH on. Auto-allocation skips ports in use on the host (e.g. a local GDK). |
+| `--web-port` | next free from 3000 | Host port to publish the GDK web UI on. Auto-allocation skips ports in use on the host. |
 | `--harness ID` | `claude` (or config.yml) | Agent harness to install: claude, codex, opencode, pi. |
 | `--no-agent` | (agent installed) | Skip installing the agent harness. |
 | `--skill NAME [NAME...]` | (none) | Seed skill(s) into the box at creation for dispatched agents. |

data/lib/gdkbox/box.rb

@@ -88,7 +88,10 @@ module GDKBox
       public_key = @ssh_key.ensure!
       cname = @config.container_name(name)
 
-      @docker.pull(image)
+      # Only pull when the image is missing locally, so `gdkbox up` on a warm
+      # machine does not hit the registry; `gdkbox update-image` is the
+      # explicit way to refresh.
+      @docker.pull(image) unless @docker.image_exists?(image)
 
       # Reserve the host ports atomically. `next_port` reads the store, so
       # parallel `gdkbox up` runs would otherwise all pick the same "next free"
@@ -101,6 +104,10 @@ module GDKBox
         @docker.run_container(
           name: cname,
           image: image,
+          # GDK's services resolve and redirect to this hostname; without it
+          # 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}"
@@ -263,8 +270,16 @@ module GDKBox
     # Choose free host ports and persist a preliminary record claiming them,
     # all while holding an exclusive lock so concurrent `create!` calls in
     # separate processes serialize and cannot pick the same ports. Returns the
-    # chosen [ssh_port, web_port]. Caller-supplied ports are honored as-is.
+    # chosen [ssh_port, web_port]. Caller-supplied ports are honored, but fail
+    # fast with a clear message when something already holds them — better
+    # than the cryptic bind error `docker run` would produce later.
     def reserve_ports!(cname, ssh_port, web_port)
+      { "--ssh-port" => ssh_port, "--web-port" => web_port }.each do |flag, port|
+        if port && Ports.bound?(port)
+          raise Error, "Port #{port} (#{flag}) is already in use on 127.0.0.1."
+        end
+      end
+
       @config.ensure_dirs!
       File.open(@config.lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
         lock.flock(File::LOCK_EX)
@@ -283,10 +298,14 @@ module GDKBox
       end
     end
 
+    # The next port at or above base that is neither recorded by gdkbox nor
+    # actually bound on the host. The store only covers gdkbox's own boxes;
+    # a locally running GDK (typically on 2222/3000) is invisible to it, so
+    # each candidate is also probed with a real bind.
     def next_port(base, exclude: [])
       used = @store.used_ports + exclude
       port = base
-      port += 1 while used.include?(port)
+      port += 1 while used.include?(port) || Ports.bound?(port)
       port
     end
   end

data/lib/gdkbox/cli.rb

@@ -61,6 +61,8 @@ module GDKBox
         return
       end
 
+      setup_host
+
       say "\nBox '#{name}' is up.", :green
       print_connection_details(box)
       unless api_key
@@ -234,6 +236,46 @@ module GDKBox
     end
     map "set-key" => :set_key
 
+    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
+      your browser needs it mapped to loopback to reach a box's web UI. This
+      adds `#{HostsFile::ENTRY}` to /etc/hosts when no gdk.local entry exists
+      yet (writing needs sudo, so you may be prompted). `gdkbox up` runs the
+      same check automatically.
+
+      With --remove, the gdkbox-managed entry is removed again; lines you
+      added yourself are never touched.
+    DESC
+    option :add, type: :boolean, default: true, desc: "Add the entry (the default action)"
+    option :remove, type: :boolean, default: false,
+      desc: "Remove the gdkbox-managed entry instead"
+    def set_host
+      hosts = HostsFile.new
+      if options[:remove]
+        case hosts.remove
+        when :absent
+          say "No gdkbox-managed '#{HostsFile::HOSTNAME}' entry in #{hosts.path}. Nothing to do."
+        when :removed
+          say "Removed the '#{HostsFile::HOSTNAME}' entry from #{hosts.path}.", :green
+        when :manual
+          say "Could not write #{hosts.path}. Remove the line tagged " \
+            "'#{HostsFile::MARKER}' manually (e.g. with `sudoedit #{hosts.path}`).", :yellow
+        end
+      else
+        case hosts.add
+        when :present
+          say "'#{HostsFile::HOSTNAME}' already resolves via #{hosts.path}. Nothing to do."
+        when :added
+          say "Added '#{HostsFile::ENTRY}' to #{hosts.path}.", :green
+        when :manual
+          say "Could not write #{hosts.path}. Add the entry manually:", :yellow
+          say "  echo '#{HostsFile::ENTRY}' | sudo tee -a #{hosts.path}", :yellow
+        end
+      end
+    end
+    map "set-host" => :set_host
+
     desc "start NAME", "Start a stopped box (and re-enable SSH)"
     def start(name)
       box = load_box!(name)
@@ -370,6 +412,28 @@ module GDKBox
       end
     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
+    # already up, and the user can run `gdkbox set-host` later. Skipped in
+    # --json mode, where prompting would break unattended orchestrators.
+    def setup_host
+      hosts = HostsFile.new
+      return if hosts.entry?
+
+      say "\nAdding '#{HostsFile::HOSTNAME}' to #{hosts.path} so the web UI resolves " \
+        "(may prompt for sudo)...", :green
+      case hosts.add
+      when :added
+        say "Added '#{HostsFile::ENTRY}' to #{hosts.path}.", :green
+      when :manual
+        say "Could not write #{hosts.path}. Run `gdkbox set-host`, or add it manually:", :yellow
+        say "  echo '#{HostsFile::ENTRY}' | sudo tee -a #{hosts.path}", :yellow
+      end
+    rescue StandardError => e
+      say "Skipped #{hosts.path} setup: #{e.message}", :yellow
+    end
+
     # Show the discovered skills and let the user pick by number (or "all").
     def prompt_for_skills
       found = Skills.discover
@@ -432,7 +496,7 @@ module GDKBox
       say ""
       say "  SSH:       ssh #{box.ssh_host_alias}", :cyan
       say "  VS Code:   gdkbox code #{box.name}", :cyan
-      say "  Web UI:    #{box.web_url}", :cyan
+      say "  Web UI:    #{box.web_url} (http://#{HostsFile::HOSTNAME}:#{box.web_port})", :cyan
       say "  Agent:     ssh #{box.ssh_host_alias} -t #{box.harness.bin}", :cyan
     end
   end

data/lib/gdkbox/config.rb

@@ -22,6 +22,12 @@ module GDKBox
     DEFAULT_IMAGE =
       "registry.gitlab.com/gitlab-org/gitlab-development-kit/gitlab-gdk-in-a-box:main"
 
+    # The hostname GDK is configured for. It is set as the container's own
+    # hostname (so services inside the box can resolve it) and mapped to
+    # loopback in the host's /etc/hosts by HostsFile (so the host browser can
+    # follow GDK's redirects to it).
+    GDK_HOSTNAME = "gdk.local"
+
     CONTAINER_PREFIX = "gdkbox-"
     HOST_ALIAS_PREFIX = "gdkbox-"
 

data/lib/gdkbox/docker.rb

@@ -15,6 +15,11 @@ module GDKBox
       !@shell.which("docker").nil?
     end
 
+    # Whether the image is already present locally.
+    def image_exists?(image)
+      @shell.run("docker", "image", "inspect", image).success?
+    end
+
     # Pull an image. With no block the pull runs quietly and the (captured)
     # Result is returned. With a block the pull is streamed and the block is
     # called with a PullProgress after every line of `docker pull` output, so a
@@ -187,9 +192,13 @@ module GDKBox
       end
     end
 
-    # Start a detached container, returning its id.
-    def run_container(name:, image:, publish: [], labels: {}, env: {}, args: [])
+    # Start a detached container, returning its id. When a hostname is given,
+    # 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)
       cmd = ["docker", "run", "-d", "--name", name]
+      cmd.push("--hostname", hostname) if hostname
       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) }

data/lib/gdkbox/hosts_file.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module GDKBox
+  # Manages the gdk.local entry in the host's /etc/hosts.
+  #
+  # GDK generates URLs and redirects that use the `gdk.local` hostname, so the
+  # host's browser needs it mapped to loopback to reach a box's web UI. The
+  # line gdkbox adds is tagged with a marker comment so it can be recognized
+  # and removed later without touching entries the user wrote themselves.
+  #
+  # /etc/hosts is root-owned: writes are attempted directly first (covers
+  # tests and unusual setups), then via `sudo tee`. Callers get a symbol
+  # describing what happened — :present/:added/:removed/:absent/:manual —
+  # and decide how to talk to the user; :manual means nothing was changed
+  # and the user has to edit the file themselves.
+  class HostsFile
+    HOSTNAME = Config::GDK_HOSTNAME
+    MARKER = "# added by gdkbox"
+    ENTRY = "127.0.0.1 #{HOSTNAME} #{MARKER}"
+
+    attr_reader :path
+
+    def initialize(path: "/etc/hosts", shell: Shell.new)
+      @path = path
+      @shell = shell
+    end
+
+    # Whether any active (non-comment) line already maps HOSTNAME, regardless
+    # of who added it — a user's own entry counts, so we never duplicate it.
+    def entry?
+      return false unless File.readable?(path)
+
+      File.foreach(path).any? { |line| maps_hostname?(line) }
+    end
+
+    # Ensure the entry exists. Returns :present when it already does, :added
+    # on success, or :manual when the file could not be written (with sudo
+    # declined/failed or disabled).
+    def add(sudo: true)
+      return :present if entry?
+
+      File.open(path, "a") { |f| f.puts(ENTRY) }
+      :added
+    rescue Errno::EACCES
+      return :manual unless sudo
+
+      result = @shell.run("sudo", "tee", "-a", path, input: "#{ENTRY}\n")
+      result.success? ? :added : :manual
+    end
+
+    # Remove the gdkbox-managed entry (matched by MARKER; user-written lines
+    # are never touched). Returns :absent when there is nothing to remove,
+    # :removed on success, or :manual when the file could not be written.
+    def remove(sudo: true)
+      lines = File.readable?(path) ? File.readlines(path) : []
+      kept = lines.reject { |line| managed?(line) }
+      return :absent if kept.size == lines.size
+
+      content = kept.join
+      begin
+        File.write(path, content)
+        :removed
+      rescue Errno::EACCES
+        return :manual unless sudo
+
+        result = @shell.run("sudo", "tee", path, input: content)
+        result.success? ? :removed : :manual
+      end
+    end
+
+    private
+
+    # Does this line actively map HOSTNAME? Comments are stripped first, so a
+    # commented-out entry does not count.
+    def maps_hostname?(line)
+      fields = line.sub(/#.*/, "").split
+      fields.length >= 2 && fields[1..].include?(HOSTNAME)
+    end
+
+    def managed?(line)
+      line.include?(MARKER) && line.include?(HOSTNAME)
+    end
+  end
+end

data/lib/gdkbox/ports.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module GDKBox
+  # Answers whether a host port is actually usable.
+  #
+  # gdkbox's metadata store only knows about ports gdkbox itself allocated;
+  # anything else on the machine — typically a locally running GDK on 2222 and
+  # 3000 — is invisible to it. Binding is the authoritative test: gdkbox
+  # publishes container ports on 127.0.0.1, so try to bind exactly there.
+  module Ports
+    module_function
+
+    # True when something on the host already holds the port (or the bind is
+    # not permitted, which is just as unusable for publishing).
+    def bound?(port)
+      TCPServer.new("127.0.0.1", port).close
+      false
+    rescue SystemCallError
+      true
+    end
+  end
+end

data/lib/gdkbox/version.rb

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

data/lib/gdkbox.rb

@@ -10,6 +10,8 @@ require "gdkbox/shell"
 require "gdkbox/progress_bar"
 require "gdkbox/config"
 require "gdkbox/docker"
+require "gdkbox/hosts_file"
+require "gdkbox/ports"
 require "gdkbox/store"
 require "gdkbox/ssh_key"
 require "gdkbox/ssh_config"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gdkbox
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.8
 platform: ruby
 authors:
 - jotolo
@@ -62,6 +62,8 @@ files:
 - lib/gdkbox/config.rb
 - lib/gdkbox/docker.rb
 - lib/gdkbox/harness.rb
+- lib/gdkbox/hosts_file.rb
+- lib/gdkbox/ports.rb
 - lib/gdkbox/progress_bar.rb
 - lib/gdkbox/provisioner.rb
 - lib/gdkbox/shell.rb
@@ -72,9 +74,14 @@ files:
 - lib/gdkbox/version.rb
 - lib/gdkbox/vscode.rb
 - skills/gdkbox-fleet/SKILL.md
+homepage: https://gitlab.com/jotolo_gl/gdkbox
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://gitlab.com/jotolo_gl/gdkbox
+  bug_tracker_uri: https://gitlab.com/jotolo_gl/gdkbox/-/issues
+  documentation_uri: https://gitlab.com/jotolo_gl/gdkbox/-/blob/main/README.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib