gdkbox 0.1.0

data/lib/gdkbox/docker.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module GDKBox
+  # A small, focused wrapper around the `docker` CLI.
+  #
+  # Only the verbs gdkbox needs are exposed. Every container created by gdkbox
+  # is tagged with the `gdkbox=true` label plus a `gdkbox.name` label so they
+  # can be discovered later without relying on local metadata alone.
+  class Docker
+    def initialize(shell: Shell.new)
+      @shell = shell
+    end
+
+    def available?
+      !@shell.which("docker").nil?
+    end
+
+    def pull(image)
+      @shell.run!("docker", "pull", image)
+    end
+
+    # Start a detached container, returning its id.
+    def run_container(name:, image:, publish: [], labels: {}, env: {}, args: [])
+      cmd = ["docker", "run", "-d", "--name", name]
+      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) }
+      cmd << image
+      cmd.concat(args)
+      @shell.run!(*cmd).stdout.strip
+    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.
+    #
+    # When check is true (the default) a non-zero exit raises; pass check:
+    # false to capture output and exit status without raising, which is what
+    # agent runs want so the caller can surface the agent's output either way.
+    def exec(name, script, user: nil, workdir: nil, env: {}, input: nil, check: true)
+      cmd = ["docker", "exec", "-i"]
+      cmd.push("-u", user) if user
+      cmd.push("-w", workdir) if workdir
+      env.each { |key, value| cmd.push("-e", "#{key}=#{value}") }
+      cmd.push(name, "bash", "-lc", script)
+      check ? @shell.run!(*cmd, input: input) : @shell.run(*cmd, input: input)
+    end
+
+    # Copy a host path into a container at dest (a full destination path).
+    def cp_into(name, src, dest)
+      @shell.run!("docker", "cp", src, "#{name}:#{dest}")
+    end
+
+    def start(name)
+      @shell.run!("docker", "start", name)
+    end
+
+    def stop(name)
+      @shell.run!("docker", "stop", name)
+    end
+
+    def rm(name, force: true)
+      cmd = ["docker", "rm"]
+      cmd << "-f" if force
+      cmd << name
+      @shell.run(*cmd)
+    end
+
+    # The container's lifecycle state, or :absent if it does not exist.
+    def state(name)
+      result = @shell.run("docker", "inspect", "-f", "{{.State.Status}}", name)
+      return :absent unless result.success?
+
+      result.stdout.strip.to_sym
+    end
+
+    # Names of all gdkbox-managed containers, derived from labels.
+    def list_names
+      result = @shell.run(
+        "docker", "ps", "-a",
+        "--filter", "label=gdkbox=true",
+        "--format", '{{index .Labels "gdkbox.name"}}'
+      )
+      return [] unless result.success?
+
+      result.stdout.split("\n").map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/gdkbox/harness.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module GDKBox
+  # An agent CLI ("harness") that can be installed into a box and dispatched to
+  # run tasks headlessly. gdkbox ships a small registry of harnesses; each box
+  # runs exactly one, chosen at `gdkbox up --harness`.
+  #
+  # The npm-installable harnesses reuse the same mise-aware install path as
+  # Claude Code (install into ~/.local, symlink the binary + node into
+  # /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
+    @registry = {}
+
+    class << self
+      def register(**kwargs)
+        harness = new(**kwargs)
+        @registry[harness.id] = harness
+        harness
+      end
+
+      def [](id)
+        @registry.fetch(id.to_s) do
+          raise Error, "Unknown harness '#{id}'. Available: #{ids.join(', ')}."
+        end
+      end
+
+      def all
+        @registry.values
+      end
+
+      def ids
+        @registry.keys
+      end
+
+      # The harness used when none is specified.
+      def default
+        "claude"
+      end
+    end
+
+    attr_reader :id, :npm_package, :npm_flags, :bin, :key_env, :config_key,
+      :summary, :skills_subdir
+
+    def initialize(id:, bin:, key_env:, config_key:, summary:, run:, skills_subdir:,
+      npm_package: nil, npm_flags: nil)
+      @id = id
+      @npm_package = npm_package
+      @npm_flags = npm_flags
+      @bin = bin
+      @key_env = key_env
+      @config_key = config_key
+      @summary = summary
+      @run = run
+      @skills_subdir = skills_subdir
+    end
+
+    # True when gdkbox knows how to install this harness automatically.
+    def installable?
+      !@npm_package.nil?
+    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)
+    end
+
+    register(
+      id: "claude",
+      npm_package: "@anthropic-ai/claude-code",
+      bin: "claude",
+      key_env: "ANTHROPIC_API_KEY",
+      config_key: "anthropic_api_key",
+      summary: "Anthropic Claude Code",
+      skills_subdir: ".claude/skills",
+      run: lambda do |json:, yolo:|
+        cmd = +%(claude -p "$GDKBOX_TASK")
+        cmd << " --output-format json" if json
+        cmd << " --dangerously-skip-permissions" if yolo
+        cmd
+      end
+    )
+
+    register(
+      id: "codex",
+      npm_package: "@openai/codex",
+      bin: "codex",
+      key_env: "OPENAI_API_KEY",
+      config_key: "openai_api_key",
+      summary: "OpenAI Codex CLI",
+      skills_subdir: ".codex/skills",
+      run: lambda do |json:, yolo:|
+        cmd = +%(codex exec "$GDKBOX_TASK")
+        cmd << " --json" if json
+        # The box is disposable, so let the agent write to the workspace.
+        cmd << " --sandbox workspace-write" if yolo
+        cmd
+      end
+    )
+
+    register(
+      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",
+      summary: "opencode (sst)",
+      skills_subdir: ".config/opencode/skills",
+      run: lambda do |json:, yolo:|
+        # `opencode run` is non-interactive and has no skip-permissions flag.
+        +%(opencode run "$GDKBOX_TASK")
+      end
+    )
+
+    register(
+      id: "pi",
+      npm_package: "@earendil-works/pi-coding-agent",
+      # pi's npm package runs postinstall scripts that need network/build; the
+      # 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",
+      summary: "pi (earendil-works)",
+      skills_subdir: ".pi/skills",
+      run: lambda do |json:, yolo:|
+        cmd = +%(pi -p "$GDKBOX_TASK")
+        cmd << " --mode json" if json
+        cmd
+      end
+    )
+  end
+end

data/lib/gdkbox/provisioner.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module GDKBox
+  # Runs the in-container setup steps: enabling SSH access and (optionally)
+  # installing Claude Code. All steps are idempotent so they can be re-run
+  # safely, for example after a `gdkbox start`.
+  class Provisioner
+    # Installs and starts the OpenSSH server, then authorizes the gdkbox public
+    # key for the GDK user. Values are passed via the environment to dodge
+    # shell quoting.
+    #
+    # The official GDK image ships an sshd_config that listens on a non-default
+    # port (2022) and runs GitLab's own `gitlab-sshd` for git-over-SSH, so we
+    # cannot assume a vanilla sshd on port 22. We drop in our own config
+    # (loaded via the `Include` near the top of sshd_config, so it overrides
+    # the image's later `Port` line) pinning the listen port to the container
+    # port gdkbox publishes, ensure host keys exist, and restart sshd so it
+    # rebinds. This is idempotent and also re-run by `gdkbox start`.
+    SSH_SETUP = <<~'BASH'
+      set -e
+      if [ ! -x /usr/sbin/sshd ] && ! command -v sshd >/dev/null 2>&1; then
+        apt-get update -qq
+        DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openssh-server >/dev/null
+      fi
+      mkdir -p /run/sshd
+      ssh-keygen -A >/dev/null 2>&1 || true
+      mkdir -p /etc/ssh/sshd_config.d
+      printf 'Port %s\nPasswordAuthentication no\n' "$GDKBOX_SSH_PORT" \
+        > /etc/ssh/sshd_config.d/00-gdkbox.conf
+      # The stock ~/.bash_logout runs `clear_console -q`, which fails (no TTY)
+      # under `docker exec ... bash -lc` and clobbers the command's exit
+      # status with 1. We run agents through a login shell, so neutralize it
+      # to keep `gdkbox dispatch` exit codes (and the rest) honest.
+      : > "/home/$GDKBOX_USER/.bash_logout" 2>/dev/null || true
+      # The GDK image manages its toolchain (ruby, node, bundle, ...) with mise
+      # but only activates it in ~/.bashrc (interactive shells). `gdkbox
+      # dispatch` and `gdkbox ssh <box> <cmd>` use non-interactive login shells,
+      # which source ~/.profile, not ~/.bashrc. Put mise's shims on PATH there
+      # so dispatched agents can actually run the GDK toolchain. Shims resolve
+      # the correct tool version from the directory's mise/.tool-versions config.
+      profile="/home/$GDKBOX_USER/.profile"
+      touch "$profile"
+      if ! grep -q 'gdkbox:mise-shims' "$profile" 2>/dev/null; then
+        {
+          echo '# gdkbox:mise-shims'
+          echo 'if [ -d "$HOME/.local/share/mise/shims" ]; then PATH="$HOME/.local/share/mise/shims:$PATH"; fi'
+        } >> "$profile"
+      fi
+      chown "$GDKBOX_USER:$GDKBOX_USER" "$profile"
+      install -d -m 700 -o "$GDKBOX_USER" -g "$GDKBOX_USER" "/home/$GDKBOX_USER/.ssh"
+      printf '%s\n' "$GDKBOX_PUBKEY" > "/home/$GDKBOX_USER/.ssh/authorized_keys"
+      chown "$GDKBOX_USER:$GDKBOX_USER" "/home/$GDKBOX_USER/.ssh/authorized_keys"
+      chmod 600 "/home/$GDKBOX_USER/.ssh/authorized_keys"
+      /usr/sbin/sshd -t
+      # Restart our sshd so it binds the configured port (gitlab-sshd and any
+      # pre-existing sshd may be on other ports). Match only the OpenSSH daemon.
+      pkill -x sshd >/dev/null 2>&1 || true
+      sleep 1
+      /usr/sbin/sshd
+    BASH
+
+    # Installs an agent harness CLI (an npm package) for the GDK user.
+    #
+    # The official GDK image manages Node with `mise`, so `node`/`npm` are not
+    # on PATH in a plain shell. We install into `~/.local` (which is on PATH
+    # for every shell) using mise's npm when a direct npm is unavailable, and
+    # symlink the mise-managed node so the agent's `env node` shebang can find
+    # an interpreter. Both `npm` and the plain-npm case are handled so this
+    # works on the GDK image and on simpler images alike. The binary name and
+    # package come from the harness via the environment.
+    AGENT_SETUP = <<~'BASH'
+      set -e
+      mkdir -p "$HOME/.local/bin"
+      # Pin a concrete node: the agent CLIs are node scripts with `env node`
+      # shebangs, and the mise *shim* for node errors outside a directory that
+      # configures a node version. Symlinking the real mise install makes node
+      # resolvable everywhere (and gets linked into /usr/local/bin afterwards).
+      # Done before the early-exit so re-provisioning fixes the PATH too.
+      if command -v mise >/dev/null 2>&1 && mise which node >/dev/null 2>&1; then
+        ln -sf "$(mise which node)" "$HOME/.local/bin/node"
+      fi
+      if command -v "$GDKBOX_AGENT_BIN" >/dev/null 2>&1; then
+        echo "$GDKBOX_AGENT_BIN already installed: $("$GDKBOX_AGENT_BIN" --version 2>/dev/null || echo unknown)"
+        exit 0
+      fi
+      if command -v npm >/dev/null 2>&1; then
+        npm install -g --prefix "$HOME/.local" $GDKBOX_NPM_FLAGS "$GDKBOX_NPM_PKG"
+      elif command -v mise >/dev/null 2>&1 && mise which npm >/dev/null 2>&1; then
+        mise exec -- npm install -g --prefix "$HOME/.local" $GDKBOX_NPM_FLAGS "$GDKBOX_NPM_PKG"
+      else
+        echo "Neither npm nor mise-managed node found in box; cannot install $GDKBOX_AGENT_BIN" >&2
+        exit 1
+      fi
+      "$HOME/.local/bin/$GDKBOX_AGENT_BIN" --version || true
+    BASH
+
+    # Symlinks the user-installed agent binary (and the mise-managed `node` it
+    # needs) into /usr/local/bin so they are on PATH for every shell, not just
+    # login shells. Without this, `ssh box <agent>` (a non-login shell) would
+    # not find the CLI even though `gdkbox dispatch` (a login shell) does.
+    AGENT_LINK = <<~'BASH'
+      set -e
+      home="/home/$GDKBOX_USER"
+      if [ -e "$home/.local/bin/$GDKBOX_AGENT_BIN" ]; then
+        ln -sf "$home/.local/bin/$GDKBOX_AGENT_BIN" "/usr/local/bin/$GDKBOX_AGENT_BIN"
+      fi
+      if [ -e "$home/.local/bin/node" ]; then
+        ln -sf "$home/.local/bin/node" /usr/local/bin/node
+      fi
+    BASH
+
+    # Writes the harness's API key into the box so dispatched agents can
+    # authenticate without a human. The key is exported under the env var the
+    # harness's provider reads (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY). It is
+    # stored only inside the container, at a 0600 file owned by the GDK user,
+    # sourced explicitly by `gdkbox dispatch` and wired into interactive
+    # shells. The key never touches host-side metadata.
+    API_KEY_SETUP = <<~'BASH'
+      set -e
+      home="/home/$GDKBOX_USER"
+      install -d -m 700 -o "$GDKBOX_USER" -g "$GDKBOX_USER" "$home/.gdkbox"
+      umask 077
+      printf "export %s='%s'\n" "$GDKBOX_API_KEY_ENV" "$GDKBOX_API_KEY" > "$home/.gdkbox/env"
+      chown "$GDKBOX_USER:$GDKBOX_USER" "$home/.gdkbox/env"
+      chmod 600 "$home/.gdkbox/env"
+      line='[ -f "$HOME/.gdkbox/env" ] && . "$HOME/.gdkbox/env"'
+      for f in "$home/.bashrc" "$home/.profile"; do
+        touch "$f"
+        grep -qF "$line" "$f" || printf '%s\n' "$line" >> "$f"
+        chown "$GDKBOX_USER:$GDKBOX_USER" "$f"
+      done
+    BASH
+
+    def initialize(docker:, config:)
+      @docker = docker
+      @config = config
+    end
+
+    def setup_ssh(container_name, public_key)
+      @docker.exec(
+        container_name, SSH_SETUP,
+        user: "root",
+        env: {
+          "GDKBOX_USER" => @config.ssh_user,
+          "GDKBOX_PUBKEY" => public_key,
+          "GDKBOX_SSH_PORT" => Config::SSH_CONTAINER_PORT.to_s
+        }
+      )
+    end
+
+    # Install the given harness (an npm-installable agent CLI) into the box.
+    def setup_agent(container_name, harness)
+      unless harness.installable?
+        raise Error, "gdkbox cannot auto-install the '#{harness.id}' harness yet."
+      end
+
+      @docker.exec(
+        container_name, AGENT_SETUP, user: @config.ssh_user,
+        env: {
+          "GDKBOX_AGENT_BIN" => harness.bin,
+          "GDKBOX_NPM_PKG" => harness.npm_package,
+          "GDKBOX_NPM_FLAGS" => harness.npm_flags.to_s
+        }
+      )
+      @docker.exec(
+        container_name, AGENT_LINK, user: "root",
+        env: { "GDKBOX_USER" => @config.ssh_user, "GDKBOX_AGENT_BIN" => harness.bin }
+      )
+    end
+
+    def setup_api_key(container_name, api_key, key_env)
+      @docker.exec(
+        container_name, API_KEY_SETUP,
+        user: "root",
+        env: {
+          "GDKBOX_USER" => @config.ssh_user,
+          "GDKBOX_API_KEY" => api_key,
+          "GDKBOX_API_KEY_ENV" => key_env
+        }
+      )
+    end
+  end
+end

data/lib/gdkbox/shell.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module GDKBox
+  # Raised when a shelled-out command exits non-zero.
+  class CommandError < Error
+    attr_reader :command, :status, :stderr
+
+    def initialize(command, status, stderr)
+      @command = Array(command)
+      @status = status
+      @stderr = stderr
+      super("Command failed (exit #{status}): #{@command.join(' ')}\n#{stderr}".strip)
+    end
+  end
+
+  # Thin wrapper around shelling out to external commands.
+  #
+  # All arguments are passed as an explicit argv array (never a single
+  # interpolated string) so user-supplied values cannot be interpreted by a
+  # shell. Tests inject a fake that records the commands instead of running
+  # them.
+  class Shell
+    Result = Struct.new(:stdout, :stderr, :status) do
+      def success?
+        status.zero?
+      end
+    end
+
+    # Run a command, returning a Result. Never raises on a non-zero exit.
+    def run(*args, input: nil)
+      argv = args.map(&:to_s)
+      stdout, stderr, status = Open3.capture3(*argv, stdin_data: input)
+      Result.new(stdout, stderr, status.exitstatus || 1)
+    end
+
+    # Run a command, raising CommandError on a non-zero exit.
+    def run!(*args, input: nil)
+      result = run(*args, input: input)
+      raise CommandError.new(args, result.status, result.stderr) unless result.success?
+
+      result
+    end
+
+    # Run a command and return its stdout, raising on failure.
+    def capture(*args, input: nil)
+      run!(*args, input: input).stdout
+    end
+
+    # Resolve an executable on PATH, returning its path or nil.
+    def which(command)
+      result = run("sh", "-c", "command -v #{command}")
+      result.success? ? result.stdout.strip : nil
+    end
+  end
+end

data/lib/gdkbox/skills.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module GDKBox
+  # Discovers and installs agent skills.
+  #
+  # A skill is a directory containing a `SKILL.md` file. gdkbox knows about
+  # skills from three roots: the ones bundled in this repo's top-level
+  # `skills/` directory, the user-wide `~/.claude/skills`, and the current
+  # project's `./.claude/skills`. They can be installed into a host Claude
+  # Code skills directory or pushed into a box for dispatched agents to use.
+  class Skills
+    # A discovered skill: where it lives and a one-line summary for listings.
+    Skill = Struct.new(:name, :path, :origin, :description)
+
+    # Where the bundled skills live inside the gem/repo: <root>/skills.
+    SOURCE_DIR = File.expand_path("../../skills", __dir__)
+
+    # User-wide Claude Code skills directory.
+    GLOBAL_DEST = File.expand_path("~/.claude/skills")
+
+    # Project-local Claude Code skills directory, relative to a working dir.
+    def self.project_dest(dir = Dir.pwd)
+      File.join(dir, ".claude", "skills")
+    end
+
+    # The skill roots searched by `discover`, most specific first so that a
+    # project or user skill shadows a bundled one with the same name.
+    def self.roots(project_dir: Dir.pwd)
+      [
+        [:project, project_dest(project_dir)],
+        [:global, GLOBAL_DEST],
+        [:bundled, SOURCE_DIR]
+      ]
+    end
+
+    # Every skill gdkbox can see, across all roots, deduped by name (the
+    # first/most-specific root wins). Returns Skill structs sorted by name.
+    def self.discover(project_dir: Dir.pwd)
+      found = {}
+      roots(project_dir: project_dir).each do |origin, dir|
+        next unless File.directory?(dir)
+
+        Dir.children(dir).sort.each do |entry|
+          path = File.join(dir, entry)
+          next if found.key?(entry)
+          next unless File.file?(File.join(path, "SKILL.md"))
+
+          found[entry] = Skill.new(entry, path, origin, description_for(path))
+        end
+      end
+      found.values.sort_by(&:name)
+    end
+
+    # Resolve a token (a discovered skill name, or a path to a skill
+    # directory) to a Skill. Raises Error when it cannot be found.
+    def self.resolve(token, project_dir: Dir.pwd)
+      maybe_path = File.expand_path(token)
+      if token.match?(%r{[/\\]}) || File.directory?(maybe_path)
+        unless File.file?(File.join(maybe_path, "SKILL.md"))
+          raise Error, "'#{token}' is not a skill directory (no SKILL.md)."
+        end
+
+        return Skill.new(File.basename(maybe_path), maybe_path, :path, description_for(maybe_path))
+      end
+
+      skill = discover(project_dir: project_dir).find { |s| s.name == token }
+      unless skill
+        names = discover(project_dir: project_dir).map(&:name)
+        hint = names.empty? ? "" : " Available: #{names.join(', ')}."
+        raise Error, "No skill named '#{token}'.#{hint}"
+      end
+      skill
+    end
+
+    # Best-effort one-line summary pulled from a skill's SKILL.md frontmatter.
+    def self.description_for(path)
+      text = File.read(File.join(path, "SKILL.md"))
+      front = text[/\A---\s*\n(.*?)\n---\s*\n/m, 1]
+      return nil unless front
+
+      data = begin
+        YAML.safe_load(front)
+      rescue StandardError
+        nil
+      end
+      desc = data.is_a?(Hash) ? data["description"] : nil
+      desc&.to_s&.gsub(/\s+/, " ")&.strip
+    end
+
+    # Names of the skills shipped with this repo, sorted.
+    def self.available
+      return [] unless File.directory?(SOURCE_DIR)
+
+      Dir.children(SOURCE_DIR)
+        .select { |entry| File.directory?(File.join(SOURCE_DIR, entry)) }
+        .sort
+    end
+
+    def initialize(dest: GLOBAL_DEST)
+      @dest = dest
+    end
+
+    attr_reader :dest
+
+    # Copy a single named skill into the destination directory.
+    #
+    # Raises Error if the skill is unknown, or if it is already installed and
+    # `force` is false. Returns the path it was installed to.
+    def install(name, force: false)
+      source = File.join(SOURCE_DIR, name)
+      raise Error, "No skill named '#{name}' in this repo." unless File.directory?(source)
+
+      target = File.join(@dest, name)
+      if File.exist?(target) && !force
+        raise Error, "Skill '#{name}' is already installed at #{target}. Use --force to overwrite."
+      end
+
+      FileUtils.mkdir_p(@dest)
+      FileUtils.rm_rf(target)
+      FileUtils.cp_r(source, target)
+      target
+    end
+  end
+end

data/lib/gdkbox/ssh_config.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module GDKBox
+  # Generates an SSH config fragment describing every box, and wires it into
+  # the user's ~/.ssh/config via an Include directive.
+  #
+  # The fragment is regenerated wholesale from the current set of boxes on
+  # every change, which keeps it consistent and easy to reason about. Each box
+  # becomes a `Host gdkbox-<name>` entry that VS Code Remote-SSH and a plain
+  # `ssh gdkbox-<name>` can both use.
+  class SSHConfig
+    HEADER = "# Managed by gdkbox - generated file, do not edit by hand"
+
+    def initialize(config:)
+      @config = config
+    end
+
+    def write(boxes)
+      @config.ensure_dirs!
+      File.write(@config.ssh_config_path, render(boxes))
+      ensure_include!
+    end
+
+    def render(boxes)
+      lines = [HEADER, ""]
+      boxes.sort_by { |box| box["name"] }.each do |box|
+        lines << "Host #{@config.ssh_host_alias(box['name'])}"
+        lines << "  HostName 127.0.0.1"
+        lines << "  Port #{box['ssh_port']}"
+        lines << "  User #{box['ssh_user']}"
+        lines << "  IdentityFile #{@config.private_key_path}"
+        lines << "  IdentitiesOnly yes"
+        lines << "  StrictHostKeyChecking no"
+        lines << "  UserKnownHostsFile /dev/null"
+        lines << ""
+      end
+      "#{lines.join("\n").rstrip}\n"
+    end
+
+    # Prepend an `Include` directive to ~/.ssh/config if it is not present.
+    def ensure_include!
+      path = @config.user_ssh_config
+      include_line = "Include #{@config.ssh_config_path}"
+      existing = File.exist?(path) ? File.read(path) : ""
+      return if existing.include?(include_line)
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, "#{include_line}\n#{existing}")
+    end
+  end
+end

data/lib/gdkbox/ssh_key.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module GDKBox
+  # Manages a dedicated ed25519 keypair used to authenticate into boxes.
+  #
+  # gdkbox keeps its own key under the gdkbox home rather than touching the
+  # user's personal keys. The public half is installed into each box; the
+  # private half is referenced from the generated SSH config.
+  class SSHKey
+    def initialize(config:, shell: Shell.new)
+      @config = config
+      @shell = shell
+    end
+
+    # Generate the keypair if it does not yet exist, returning the public key.
+    def ensure!
+      return public_key if File.exist?(@config.public_key_path)
+
+      @config.ensure_dirs!
+      unless @shell.which("ssh-keygen")
+        raise Error, "ssh-keygen not found on PATH; cannot generate an SSH key"
+      end
+
+      @shell.run!(
+        "ssh-keygen", "-t", "ed25519",
+        "-N", "", "-C", "gdkbox",
+        "-f", @config.private_key_path
+      )
+      public_key
+    end
+
+    def public_key
+      File.read(@config.public_key_path).strip
+    end
+  end
+end