Nikolai Emil | Devantler | Blog

How I Run KSail Autonomously with GitHub Agentic Workflows

Fri, 17 Apr 2026 00:00:00 GMT

A Mac Mini runs 24/7 in my house on Funen. It doesn’t serve media, it doesn’t compile code, it doesn’t host a website. Its only job is to fire scheduled prompts at GitHub agents so they can work on KSail in the background.

Left unsupervised, autonomous agents tend to produce a lot of output and not a lot of outcomes — PRs that don’t compile, issues that duplicate each other, roadmaps that drift from reality. I’ve hit all of those failure modes running this setup.

The thing that keeps it usable is that autonomy isn’t really the goal. The goal is narrowing the agents’ scope enough, and layering enough checks, that the failure modes get caught before they reach me. I stay in the loop at one place: the Draft → In Review transition. Everything else is automated.

This post is about how I’ve arranged that.

How I Think About Autonomy

An agent that’s free to do anything will eventually do something I don’t want. I don’t try to stop that from happening — I try to make sure it gets caught.

That shapes the setup in three ways:

Each workflow has a narrow scope so there’s a clear definition of “done” and not much room to improvise.
Deterministic guardrails sit between agent output and main — lint, tests, security scans. The kinds of checks that don’t negotiate.
One human decision stays in the loop: promoting a draft PR to In Review. That’s where I can still veto.

Nothing here is novel; it’s just what I’ve ended up with after iterating.

The Pipeline: Six Agentic Workflows

KSail runs six GitHub Agentic Workflows, each with a narrow scope and its own schedule. They’re implemented as Markdown prompt files that the gh-aw extension compiles into GitHub Actions workflows.

Weekly Strategy — Runs Monday and Wednesday. On Monday it analyzes recent issues, discussions, and competitor tools (Tilt, Skaffold, DevSpace, and the rest) and publishes a Now / Next / Later roadmap. On Wednesday it turns the roadmap into promotional content — a Reddit post, a LinkedIn snippet, or a blog draft.
Repo Assist — Runs every 12 hours. This is the busiest workflow. It picks a task via weighted random selection from 12 categories (labelling issues, investigating bugs, cleaning up stale PRs, translating roadmap items into backlog issues, writing small code improvements). Weights adjust based on repo state — if there are a lot of unlabelled issues, labelling gets heavier.
Daily Docs — Runs daily and on every push to main. Syncs documentation with code changes, and on a separate schedule scans for bloat and simplifies redundant pages. Knows which files are auto-generated and refuses to edit them.
Daily Workflow Maintenance — Runs daily. Updates action versions, applies gh-aw codemods, recompiles workflow lock files. If there’s nothing to update, it switches into a deeper mode that analyzes CI metrics and proposes optimizations.
CI Doctor — Runs on failure. When any monitored workflow fails, CI Doctor pulls the logs, runs pattern matching against previous investigations, categorizes the root cause, and files an issue with a recommended fix.
Agentics Maintenance — Runs every two hours. Closes expired discussions, issues, and PRs; keeps labels in sync. Mostly janitorial.

Each workflow has a single sentence that describes what it’s allowed to do. None of them can merge. None of them can close another workflow’s PR. Most of them can only open drafts.

How Autonomy Is Obtained

The workflows run on GitHub-hosted runners, but the prompts that kick them off are scheduled on my Mac Mini via a simple cron-like setup. Why a physical machine and not just GitHub’s built-in schedule triggers? Two reasons:

I can dispatch prompts on demand. When I’m drafting an idea and want Repo Assist to pick it up immediately, I trigger it from the Mac Mini rather than waiting for the next 12-hour window.
The prompts are themselves versioned locally, so I can iterate on them the same way I iterate on code — edit, test, commit, push. Keeping them on a machine I can see keeps the feedback loop tight.

The flow from idea to merged PR looks like this:

flowchart LR
    A["🗺️ Weekly Strategy<br/>Roadmap + content"] --> B["📋 Repo Assist<br/>Issues + draft PRs"]
    B --> C["👨‍💻 Me<br/>Promote Draft → In Review"]
    C --> D["⚙️ CI Pipeline<br/>Lint, build, test, bench"]
    D --> E["🤖 Agent Merge<br/>Rebase, fix, merge"]

    classDef agent fill:#1f6feb,stroke:#58a6ff,color:#fff;
    classDef human fill:#f0883e,stroke:#f0883e,color:#000;
    classDef ci fill:#238636,stroke:#3fb950,color:#fff;
    class A,B,E agent;
    class C human;
    class D ci;

Weekly Strategy produces the “what to work on.” Repo Assist turns that into issues and, where appropriate, draft PRs. Everything sits in Draft until I promote it. CI runs on every change. Agent Merge (implemented as a Skill) rebases and addresses final review feedback.

The Guardrails

Scheduled prompts are the easy part. The guardrails are what make the output something I’m willing to merge. Every PR — agent or human — goes through the same stack.

flowchart LR
    A["🚨 Agent opens PR"] --> B["🛡️ GHAS<br/>CodeQL + secret scanning"]
    B --> C["🔒 StepSecurity<br/>Runner egress auditing"]
    C --> D["🧹 Linting<br/>MegaLinter + golangci-lint"]
    D --> E["🧪 Unit tests<br/>go test ./..."]
    E --> F["🚀 E2E matrix<br/>Kind × K3d × Talos × VCluster"]
    F --> G["✅ Agent Merge<br/>via Skills"]

    classDef sec fill:#da3633,stroke:#f85149,color:#fff;
    classDef quality fill:#1f6feb,stroke:#58a6ff,color:#fff;
    classDef gate fill:#238636,stroke:#3fb950,color:#fff;
    class B,C sec;
    class D,E,F quality;
    class A,G gate;

What each layer does:

GHAS + CodeQL catches the class of bugs where an agent confidently introduces an injection or an unvalidated input. Cheap to enable and it has caught real issues.
StepSecurity hardens the runners. egress-policy: audit on every job means I can see which hosts a workflow is talking to, which matters when agents occasionally try to fetch from somewhere unexpected.
MegaLinter and golangci-lint keep the stylistic and correctness conventions consistent. Agents will write idiomatic Go for a while and then forget errcheck on one function; linters notice.
Unit tests run on every PR via go test ./....
E2E / system tests run on the merge queue across a matrix of distributions (Kind, K3d, Talos, VCluster) and providers (Docker, Hetzner, Omni). This is the slow and expensive layer, and also where most agent-introduced regressions actually get caught.
Agent Merge via Skills handles the final rebase and review-feedback dance. It can’t bypass any of the above.

None of these layers take the agent’s word for anything — they check independently. That’s the whole point.

My Role

Most of what I do on KSail day-to-day is promote draft PRs to In Review. I read the diff, read the linked issue, decide whether the change actually fits the roadmap, and either promote it or close it.

Beyond that:

👀 Occasional check-ins to sanity-check direction — am I comfortable with where the roadmap is going? Are there issues getting closed that shouldn’t be?
🛠️ Jumping in to build something myself when I feel like coding. I use the same workflow — draft PR, CI, agent merge — so nothing is bypassed.

Nothing merges without me promoting it. Agent Merge waits for In Review; In Review only happens when I click the button.

What I’ve Learned

A few observations from running this for a while. These are my experiences, not prescriptions.

The model matters more than the prompt. A weaker model produces worse initial output and struggles with anything that has a larger scope. Running the same workflow against a mid-tier model versus a frontier model, the frontier model is the one that ends up shipping usable code. The prompt helps, but it isn’t going to rescue a weak base.

Before Agentic Workflows, working with AI was tedious. I’d open a chat, paste context, iterate, copy results back, paste into a PR. The overhead per task was high enough that I used AI sparingly. Scheduled workflows changed that shape — the AI runs whether I’m paying attention or not, and I review in batch.

I don’t really trust AI to do a good job. That sounds harsh, but it’s the honest frame I operate from. I don’t assume a PR is correct; I assume it needs to prove itself against the checks. When CI, lint, and the E2E matrix all go green, that’s something closer to evidence. Without that stack I don’t think I’d run any of this.

The work shifts from coding to validation. My days look different now. Less time writing code, more time reading diffs, promoting drafts, and deciding whether a change fits the roadmap. The work didn’t disappear, it just moved.

Autonomous AI leans hard on good tooling. Without GHAS and StepSecurity I’d be more anxious about letting agents open PRs on their own. I’m not saying nobody should run autonomous workflows without them — I’m saying I wouldn’t.

Working code beats sexy code, and I had to learn that the hard way. My instinct is to factor, generalize, make things elegant. Newer models scratch that same itch when they get it right, which feels great. But when they duplicate code that didn’t need to be duplicated, it feels worse than if I’d written the duplication myself. Where I’ve landed: let the agent ship working code first, and treat refactoring as a separate, deliberate task.

Adding signals to the feedback loop helps. CI Doctor is a good example. A failing workflow can churn for days before an agent converges on a fix — often on things I could probably debug faster if I sat down with it myself. The trade-off is autonomy: it eventually gets there without me. New signals I’ve added to the loop (test coverage reports, benchmark regressions, lint summaries) have all made that convergence more reliable, even when they don’t make it faster.

Scheduling from a physical machine isn’t strictly necessary. Most of these schedules could move to GitHub’s built-in cron. I keep the Mac Mini because it’s one place where I can see what’s running, what’s queued, and what I’m iterating on — more of a dashboard than a trigger. That framing is worth more to me than the technical utility.

Closing

The goal of this setup isn’t to remove myself from the project. It’s to move the tedious parts (triage, labelling, dependency updates, docs drift) onto agents, while keeping the parts that benefit from judgment (scope, design, what merges) with me.

If you want to see the workflow files, they live in .github/workflows/ in the KSail repo — every *.md file in that folder is one of the agentic workflows described here. The compiled *.lock.yml files are the GitHub Actions that actually run. The setup is built on top of githubnext/agentics, which provides the gh-aw CLI and the workflow prompt framework.

I Built an MCP Server into My Kubernetes CLI

Wed, 15 Apr 2026 00:00:00 GMT

There’s a growing list of tools adopting the Model Context Protocol — the standard that lets AI assistants call external capabilities as structured tools rather than guessing from context. Most of the MCP servers I’ve seen are wrappers around databases, APIs, or SaaS products.

I added one to a Kubernetes CLI.

KSail is a tool I’ve been building for a while — it bundles kubectl, helm, flux, argocd, kind, k3d, talos, and vcluster into one binary and wraps them with a consistent CLI. The idea is that you shouldn’t need seven tools configured and version-matched just to spin up a local cluster and deploy some workloads. ksail cluster create handles Kind, K3d, Talos, or VCluster with the same workflow.

Running ksail mcp starts a local MCP server that exposes all of that to any MCP-compatible client.

What It Actually Exposes

The server surfaces five tool groups:

cluster_read — list clusters, get cluster info, inspect configuration
cluster_write — create, update, delete, start, stop, backup, restore
workload_read — get, describe, logs, explain, validate manifests
workload_write — apply, delete, scale, rollout, reconcile GitOps, push to registry
cipher_write — encrypt and decrypt secrets with SOPS/Age

That’s roughly 30 underlying CLI commands organized into read/write pairs. The read tools are lower-risk; the write tools are the ones that actually change cluster state.

Connecting It to Claude Desktop

{
  "mcpServers": {
    "ksail": {
      "command": "ksail",
      "args": ["mcp"]
    }
  }
}

Add that to claude_desktop_config.json, restart Claude Desktop, and it gains access to the full KSail tool surface. You can do things like:

“Create a K3s cluster called dev with Cilium CNI and Flux GitOps”
“Show me what’s deployed in the workload namespace”
“Scale the nginx deployment to 3 replicas”
“Encrypt this secret file before I commit it”

For Cursor, the setup is similar — add the MCP server in settings and point it at the ksail mcp command.

How the Tools Are Generated

This is the part I find genuinely interesting to think about.

KSail’s CLI is built with Cobra. Every command — ksail cluster create, ksail workload apply, ksail cipher encrypt — is defined as a Cobra command with flags, arguments, and descriptions.

Rather than manually writing MCP tool definitions for each command, I built a code generator that walks the Cobra command tree and auto-generates the tool definitions. The generator reads each command’s description, flags, and argument patterns, and produces the corresponding MCP tool schema.

The consolidation step is where it gets interesting. Exposing 30 individual tools to an AI assistant is noisy — you end up with too many choices and the model spends time deciding which narrow tool applies rather than doing the work. Instead, parent commands annotated with ai.toolgen.consolidate aggregate their subcommands into a single tool that accepts a subcommand name as an argument. The ai.toolgen.permission annotation then splits that into read and write variants.

The result: adding a new CLI command under a consolidated parent automatically makes it available as an MCP tool. No manual registration.

KSail Is Now in the MCP Registry

The server is registered in the MCP Registry as io.github.devantler-tech/ksail. This means MCP clients that support registry-based discovery can find and configure it without manual setup.

The Practical Trade-Off

The write tools (cluster_write, workload_write, cipher_write) are the ones that require thought. Giving an AI assistant the ability to ksail cluster delete or ksail workload apply against a running cluster is genuinely useful for routine tasks — and genuinely risky if the model misunderstands the context.

The read/write split exists for this reason. If you’re using an assistant primarily for inspection and debugging, you can expose only the read tools. If you’re using it for fully autonomous cluster setup (a documented cluster-as-code pattern KSail supports), you give it write access and let it run.

KSail also has a built-in ksail chat command with three modes — Interactive (write ops require approval), Plan (no execution, description only), and Autopilot (full autonomous execution) — that gives you the same control in a terminal TUI rather than an external AI client.

Where to Find It

# Install
brew install --cask devantler-tech/tap/ksail

# Start the MCP server
ksail mcp

Source: github.com/devantler-tech/ksail

The MCP server is part of the main binary — no separate installation. If you’re already using KSail, ksail mcp is already there.

GitOps Without the Git Server: OCI Registries as a Flux Source with KSail

Wed, 25 Mar 2026 00:00:00 GMT

The standard advice for running Flux locally is to point it at a Git repository. In practice that means either pushing to a remote repo and waiting for Flux to poll it, maintaining a local Git server, or wrestling with Flux’s lack of support for local file paths. None of these are great for a tight development loop.

Flux has supported OCI repositories as sources since v2.0.0, and this is a much cleaner approach for local development. Instead of a Git repo, Flux watches an OCI artifact in a container registry. You push your manifests as a versioned artifact, Flux pulls and applies it. KSail takes care of the registry for you — when you create a local cluster with a GitOps engine, KSail automatically provisions a local Docker-based OCI registry alongside the cluster. No external accounts, no tokens, no network dependency. The workflow after editing manifests comes down to two commands.

Here’s a complete walkthrough.

Prerequisites

You need Docker installed and running. Verify with:

docker ps

KSail itself only needs Docker — it bundles kubectl, helm, flux, kustomize, kind, and more into a single binary.

brew install --cask devantler-tech/tap/ksail

That’s it for local development. No registry accounts or tokens needed — KSail provisions a local registry automatically.

Setting Up a Cluster with Flux

mkdir my-cluster && cd my-cluster
ksail cluster init \
  --name dev \
  --distribution Vanilla \
  --gitops-engine Flux

This scaffolds:

ksail.yaml — KSail configuration
kind.yaml — Kind cluster config (usable directly with kind if you ever want to bypass KSail)
k8s/kustomization.yaml — root Kustomization manifest
Flux HelmRelease and OCI source configs

Create the cluster:

ksail cluster create

During cluster create, KSail:

Provisions a local OCI registry as a Docker container
Creates the Kind cluster and attaches it to the registry
Bootstraps Flux and configures it to watch the local registry as an OCI source

By the time the command finishes, Flux is running and watching the local registry. No manual registry configuration needed.

Pushing Manifests

Add something to k8s/ — a namespace, a Deployment, whatever you’re working on:

k8s/my-app/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: nginx:stable-alpine
          ports:
            - containerPort: 80

Push and reconcile:

ksail workload push
ksail workload reconcile

workload push packages your k8s/ directory as an OCI artifact and pushes it to the local registry. It auto-detects the registry from the running cluster — no flags or configuration needed. workload reconcile triggers Flux to pull the latest artifact and waits for all Kustomizations to report Ready.

The round trip from workload push to reconciliation complete is typically under 10 seconds since everything stays on localhost.

How Registry and Tag Resolution Works

When you run ksail workload push, the registry is resolved using this priority chain:

An explicit oci:// ref on the command line: ksail workload push oci://localhost:5050/k8s:v1.2.3
CLI flag or environment variable (--registry / KSAIL_REGISTRY)
spec.cluster.localRegistry in ksail.yaml
Cluster GitOps resources (FluxInstance or ArgoCD Application)
Auto-detection from Docker containers matching the cluster name

For local development, option 5 handles everything — you don’t need to configure anything.

The tag follows a similar priority:

Tag from the oci:// ref on the command line
spec.workload.tag in ksail.yaml
Tag embedded in the registry URL from config
The default: dev

Locally the dev tag is convenient — every push overwrites the same tag, and Flux detects changes via digest rather than tag, so reconciliation still fires correctly.

Extending to GHCR for CI

The same OCI workflow translates directly to CI pipelines by pointing at an external registry like GitHub Container Registry (GHCR). This gives you immutable versioned artifacts tied to specific commits.

Override the registry at the command line to tie the artifact to a commit SHA:

ksail workload push oci://ghcr.io/YOUR_ORG/my-manifests:${{ github.sha }}

Each commit produces an immutable artifact. Flux picks up changes on its regular polling interval — workload reconcile is not needed in CI since it requires cluster access (kubeconfig) which is typically unavailable on GitHub Actions runners. If a deployment goes wrong you can point Flux at an earlier digest and it will reconcile back to a known-good state automatically.

The workload push command includes retry logic specifically for GHCR (added in v5.67.0), which handles the transient authentication errors that GHCR occasionally returns under load. For pipelines that push during high-traffic windows this meaningfully improves reliability.

A minimal GitHub Actions workflow step:

- name: Push manifests to GHCR
  run: |
    echo "${{ secrets.GITHUB_TOKEN }}" | \
      docker login ghcr.io -u ${{ github.actor }} --password-stdin
    ksail workload push \
      oci://ghcr.io/${{ github.repository_owner }}/my-cluster-manifests:${{ github.sha }}
  env:
    KSAIL_CLUSTER_NAME: staging

The KSAIL_CLUSTER_NAME environment variable tells KSail which cluster configuration to load when you have multiple clusters defined.

For cloud clusters (e.g., Hetzner) where there’s no local Docker daemon, an external registry is required. Use the --local-registry flag during cluster init to configure it:

ksail cluster init \
  --distribution Talos \
  --provider Hetzner \
  --gitops-engine Flux \
  --local-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io/your-org/your-cluster'

The --local-registry flag accepts the format [user:pass@]host[:port][/path]. Environment variable placeholders like ${GITHUB_TOKEN} are expanded at runtime, keeping credentials out of your config files.

What About `workload watch`?

For purely local iteration where you don’t want to think about pushing at all, ksail workload watch is even lower friction:

ksail workload watch --path ./k8s

This watches the k8s/ directory and applies changes directly with kubectl, bypassing the OCI push step entirely. If Flux is running it will also trigger selective Kustomization reconciliation on affected CRs automatically.

The OCI push workflow is the better choice when:

You want local and CI behavior to be identical
You’re testing Flux OCI source configuration itself
You need immutable versioned artifacts (each push gets a content digest)
You’re sharing manifests across multiple clusters or environments

workload watch is better when:

You’re iterating fast and CI parity doesn’t matter right now
The push/reconcile round trip feels slow for your current task

Both workflows coexist without conflict. It’s a per-session choice.

A Note on Secret Management

Regardless of whether you use a local registry or GHCR, secrets shouldn’t be in your manifests in plain text. KSail has built-in SOPS integration (ksail cipher encrypt) for secret management — encrypt secrets before they land in k8s/.

If you use GHCR, packages inherit from your repository’s visibility by default. For anything sensitive, set the package visibility explicitly in GitHub’s package settings, or use a private repository.

KSail is open source under Apache-2.0. Full documentation including the OCI push workflow, Flux source configuration, and the composite GitHub Action for CI is at ksail.devantler.tech.

This blog post was written with the assistance of AI. The content reflects genuine experiences and opinions; the AI helped structure and articulate them.

Storing Sensitive Values in .zshrc with macOS Keychain

Thu, 12 Feb 2026 00:00:00 GMT

Storing tokens and passwords directly in ~/.zshrc means they sit on disk in plaintext. macOS Keychain provides a built-in, encrypted alternative. Here’s how to use it.

Store a Secret

Use the security CLI to add a value to your Keychain:

 security add-generic-password -a "$USER" -s 'my_secret_name' -w 'SECRET_VALUE'

-a "$USER" — associates the entry with your macOS user account.
-s 'my_secret_name' — a label to identify the secret (e.g., GITHUB_TOKEN).
-w 'SECRET_VALUE' — the actual secret value.

Retrieve a Secret

To retrieve the value later:

security find-generic-password -a "$USER" -s 'my_secret_name' -w

This prints the secret to stdout, making it easy to capture in a variable.

Use It in .zshrc

Export the secret as an environment variable by adding this to ~/.zshrc:

export GITHUB_TOKEN=$(security find-generic-password -a "$USER" -s "GITHUB_TOKEN" -w)

Summary

Task	Command
Store	`security add-generic-password -a "$USER" -s 'name' -w 'value'`
Retrieve	`security find-generic-password -a "$USER" -s 'name' -w`
Update	Delete and re-add, or use `-U` flag to update in place
Delete	`security delete-generic-password -a "$USER" -s 'name'`

That’s it — no more plaintext secrets in your .zshrc.

Building an AI Assistant for Kubernetes with GitHub Copilot SDK

Sun, 25 Jan 2026 00:00:00 GMT

What if managing Kubernetes clusters was as simple as having a conversation?

KSail has always been about reducing overhead. It started as shell scripts, became a .NET tool with embedded binaries, and is now a pure Go SDK that bundles kubectl, helm, kind, k3d, flux, and argocd into a single binary. Each iteration removed friction: first installation overhead (one binary instead of six tools), then workflow overhead (consistent commands across distributions).

The chat feature is the next step: removing cognitive overhead. Instead of memorizing that ksail cluster init --distribution Talos --provider Hetzner --cni Cilium --gitops-engine Flux --local-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io/devantler-tech/ksail/system-test-manifests' --control-planes 3 --workers 2 is the syntax to create a Talos cluster on Hetzner with three control plane nodes, two worker nodes, Cilium as a CNI, and Flux as your GitOps engine set up to sync with an OCI image in GHCR, you can just say: “Create a HA Talos cluster on Hetzner with Cilium and Flux set up to sync with ghcr.io/devantler-tech/ksail/system-test-manifests.” (pheeew).

This post covers the technical journey of building ksail chat using the GitHub Copilot SDK for Go, Bubbletea TUI framework, and glamour for markdown rendering.

See It in Action

Before diving into the implementation, let’s see what we’re building. Here’s ksail chat creating a cluster on Hetzner Cloud from a single natural language request:

1. Start the conversation — ask to create a cluster on Hetzner

2. Task complete — the assistant finishes provisioning the cluster

3. Verification — the cluster appears in Hetzner Cloud

The entire workflow happens in the terminal — no context switching, no remembering flags.

Motivation

KSail already makes Kubernetes development easier by bundling common tools into a single Go binary. But users still need to remember commands, flags, and workflows. The chat feature completes the progression:

Before KSail	With KSail CLI	With KSail Chat
5+ tools to install	1 binary	1 binary
Memorize each tool’s flags	Read `--help`	Just describe what you want
Copy commands from docs	Run unified commands	”Create a cluster”

KSail already knows how to do everything — now it understands what you want to do. The assistant needs to understand KSail’s capabilities, execute real commands (not just explain them), work entirely in the terminal, and respect security boundaries. Building that required three key pieces working together.

The Tech Stack

Each requirement above pointed to a specific technical choice: an AI backend for understanding and action, a TUI framework for terminal-native interaction, and a markdown renderer for readable output.

GitHub Copilot SDK for Go

The Copilot SDK for Go provides the AI backbone. At time of writing, I used v0.1.18. It handles:

Streaming responses — tokens arrive as they’re generated
Tool calling — the model can invoke functions you define
Conversation history — multi-turn dialogues with context

The SDK abstracts away the complexity of the Copilot API, letting me focus on building the experience.

Bubbletea TUI Framework

Bubbletea is an Elm-inspired framework for building terminal apps in Go. It uses a functional model where:

Model holds the application state
Update handles messages and returns a new model
View renders the model to a string

This architecture makes state management predictable — every state transition is explicit. See the chat TUI model for the full implementation.

Glamour for Markdown Rendering

AI responses often include markdown formatting. glamour renders it beautifully in the terminal — code blocks get syntax highlighting, headers become bold, and lists render cleanly.

Architecture Overview

The SDK, TUI, and renderer handle how the interface works. The harder question: how do we make the AI actually useful? An LLM that just talks is nice, but we need it to execute real commands and stay within security boundaries.

Auto-Generated Tools from Cobra Commands

KSail has 92+ CLI commands, all built with Cobra. This consistency is what makes auto-generation possible — every command has the same structure: name, description, flags with types and defaults.

I built a generator that walks KSail’s command tree, converts each command’s flags to JSON Schema, and creates tool handlers that invoke the actual KSail logic. The AI doesn’t shell out to ksail — it calls the same Go functions the CLI uses.

The lesson learned: auto-discovering all 92 commands broke things. LLMs have a practical limit on how many tools they can reason about effectively — this is a known issue called tool overload. When presented with too many options, the model’s ability to select the right tool degrades significantly. Some commands (like internal debug utilities) also shouldn’t be exposed at all. The solution was to keep auto-discovery but add an exclusion filter — now only ~25 curated commands become tools. Best of both worlds: no manual sync, but a focused toolset the model can actually use well.

Tools let the assistant act. But to use them well, it needs context about KSail itself.

Embedded Documentation Context

The assistant needs to understand KSail’s concepts. I use go:embed to bundle 100+ documentation files at compile time, giving the model deep knowledge of KSail’s architecture, configuration options, and best practices — without requiring network requests. See BuildSystemContext for details.

This embedded context includes KSail’s distribution and provider abstractions. The same chat conversation can create a local Kind cluster for development or a Talos cluster on Hetzner for production — the AI uses the same tools, just with different flags. Users don’t need to know which underlying tool handles which provider.

With tools and context in place, the assistant can execute commands. But power needs guardrails.

Security Boundaries for File Operations

The assistant can read and write files, but only within the current working directory. The securePath function in the tools package validates all paths by resolving symlinks and verifying the target stays within the workspace — preventing symlink escape attacks where a malicious symlink could point outside the workspace.

With the core architecture solid — tools, context, and security — the final layer is polish.

User Experience Polish

Beyond the core AI integration, the TUI includes thoughtful UX details:

Prompt history — press ↑/↓ to recall previous messages
Real-time tool streaming — see command output as it runs, not just when complete
Collapsible tool output — Tab toggles individual tools, Ctrl+T toggles all
Mouse scrolling — wheel scrolls the conversation viewport
Adaptive rendering — markdown re-renders when terminal width changes

Building with AI Assistance

Here’s the meta part: an AI assistant built using AI assistance. The same pattern — removing cognitive overhead — applied to the development process itself.

VS Code’s agent mode with Claude Opus 4.5 was invaluable throughout this project. But TUI development presents a unique challenge — the AI can’t “see” what renders in your terminal. How do you debug visual issues with a text-based assistant?

The Image Snapshot Workflow

My solution: image snapshots. The workflow:

Run the TUI with test inputs
Screenshot the terminal output
Share the image with Claude via VS Code’s attachment feature
Describe what’s wrong — “The viewport is overlapping the input field”
Apply the suggested fix and iterate

This visual feedback loop was essential for:

Debugging layout issues
Fine-tuning the viewport scroll behavior
Aligning the collapsible tool output sections

Iterating on TUI Design

The TUI went through several iterations:

Version 1: Simple streaming text, no viewport — text would scroll off screen

Version 2: Added viewport with scroll handling — but input field position was wrong

Version 3: Proper layout with input at bottom, content scrolling above — working!

Version 4: Added collapsible tool invocations with Tab toggle — polished experience

Each iteration was a conversation with Claude, showing screenshots and describing what felt wrong.

Technical Decisions and Trade-offs

Every project has its thorny edge cases. Here are the three that taught me the most.

Per-Turn Subscription Pattern

Bubbletea uses subscriptions for async events (like streaming tokens). A naive approach subscribes once at initialization, but this causes issues when starting new turns — old subscriptions conflict with new ones. The solution was to subscribe fresh for each AI turn, creating a new channel and subscription tied to that specific conversation turn. See the Model.Update method for the implementation.

Context Cancellation Challenges

The Copilot SDK doesn’t support mid-stream cancellation. If you cancel the context, the SDK panics rather than gracefully stopping. My workaround: use a context that’s never cancelled, and track “stop requested” via a separate flag. This isn’t ideal, but it’s documented in the code for future improvement when the SDK adds support.

Tool Result Ordering

Tools can execute in any order, but results should appear in the order the model requested them. The SDK’s channel-based output didn’t guarantee this, so I implemented a mutex-protected FIFO buffer to ensure consistent ordering in the UI.

What’s Next

The chat assistant is functional but still in its infancy. Each improvement targets a specific friction point — continuing the “remove overhead” theme:

Smarter clarifications — remove the overhead of being precise upfront; let vague requests trigger smart follow-up questions, or intelligent inferences
More tools — reduce the gap between what KSail can do and what the assistant can do
Permission prompts — guard write operations with user confirmation to increase safety, and allow configurable auto-approvals for power users
Conversation persistence — remove the overhead of re-explaining context across sessions
Better context — understand the user’s specific cluster state, not just general KSail knowledge
Streaming cancellation — more responsive interaction when the SDK supports it

If you want to try it:

# Install KSail v5+
brew install devantler-tech/tap/ksail

# Start a chat session (requires GitHub Copilot access)
ksail chat

# Or use non-TUI mode
ksail chat --tui=false

The full implementation is in the KSail repository — the TUI lives in pkg/cli/ui/chat/ and the tools generator in pkg/svc/chat/generator/.

Feedback and contributions welcome!

This post was written with AI assistance (Claude Opus 4.5 via VS Code), following my outline and intent.

Creating Kubernetes Clusters on Hetzner with KSail and Talos

Tue, 13 Jan 2026 00:00:00 GMT

Setting up Kubernetes environments doesn’t have to be expensive or complicated. With Hetzner Cloud’s affordable pricing, Talos Linux’s security-focused immutable OS, and KSail’s unified tooling, you can have a cluster running in minutes. This post walks through the complete setup.

Why Hetzner + Talos + KSail?

Hetzner Cloud offers some of the most affordable cloud VPS servers in the industry. A capable cx23 server (2 vCPU, 4GB RAM) costs around €3.74/month — significantly cheaper than equivalent offerings from AWS, GCP, or Azure.

Talos Linux is a minimal, immutable operating system designed specifically for Kubernetes. There’s no SSH, no shell, no package manager — just the Talos API and Kubernetes. This dramatically reduces the attack surface and eliminates configuration drift.

KSail brings it all together with a single binary that handles cluster provisioning, GitOps setup, and workload management. Instead of juggling hcloud, talosctl, kubectl, helm, and flux commands, you use one consistent interface.

Step 1: Create a Hetzner Account

If you don’t already have a Hetzner account:

Go to Hetzner Cloud Console
Click “Register” and complete the signup process
Verify your email and complete any required identity verification

Hetzner has documentation for getting started: Account Getting Started Guide.

Step 2: Create a Hetzner Project

Projects in Hetzner Cloud are organizational units that contain your resources (servers, networks, load balancers, etc.). Each project has its own API tokens and billing.

Log into the Hetzner Cloud Console
Click “New Project” in the sidebar
Name your project (e.g., “kubernetes-dev” or “my-homelab”)
Click “Create”

Step 3: Generate an API Token

KSail needs an API token to provision and manage Hetzner Cloud resources.

In your project, go to Security → API Tokens
Click Generate API Token
Name the token (e.g., “ksail-cluster-management”)
Select Read & Write permissions — KSail needs to create and delete servers
Click Generate API Token
Copy the token immediately — you won’t be able to see it again!

For more details, see Hetzner’s Generating API Token Guide.

Step 4: Export the API Token

KSail reads the Hetzner API token from the HCLOUD_TOKEN environment variable. Add it to your shell configuration:

# For the current session
export HCLOUD_TOKEN="your-api-token-here"

# To persist across sessions, add to your shell config
echo 'export HCLOUD_TOKEN="your-api-token-here"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

You can verify the token is set:

echo $HCLOUD_TOKEN | head -c 10  # Should show first 10 characters

Step 5: Install KSail

KSail is distributed as a single binary. The easiest installation method is via Homebrew:

brew install --cask devantler-tech/tap/ksail

Alternatively, if you have Go installed:

go install github.com/devantler-tech/ksail/v5@latest

Verify the installation:

ksail --version

Step 6: Scaffold Your Cluster Project

KSail’s init command scaffolds a complete project structure. For a basic Talos cluster on Hetzner with Cilium CNI:

mkdir my-cluster && cd my-cluster
ksail cluster init --distribution Talos --provider Hetzner --cni Cilium

This creates ksail.yaml (cluster configuration), talos/ (Talos configs), and k8s/ (your Kubernetes manifests).

For GitOps workflows, add a GitOps engine and external registry:

ksail cluster init \
  --distribution Talos \
  --provider Hetzner \
  --cni Cilium \
  --gitops-engine Flux \
  --local-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io/your-org/your-cluster'

This configures Flux to sync manifests from GitHub Container Registry. See Step 9: Deploying Workloads for the full GitOps workflow.

For all available flags and configuration options, see the KSail documentation:

CLI flags reference — All cluster init options
ksail.yaml reference — Configuration file schema
Features overview — CNI, CSI, GitOps, and more

Step 7: Create the Cluster

With your configuration ready, create the cluster:

ksail cluster create

This command:

Creates servers in Hetzner Cloud
Configures the private network
Bootstraps Talos Linux on each node
Initializes the Kubernetes cluster
Installs your selected CNI, CSI, and other components
Configures your local kubeconfig
Configures your local talosconfig

The process takes 3-5 minutes depending on your cluster size.

You can watch the progress as KSail outputs status updates for each stage.

Step 8: Working with Your Cluster

Once your cluster is running, KSail provides commands for common operations:

ksail cluster info      # Show cluster status
ksail cluster list      # List all KSail-managed clusters
ksail cluster connect   # Open K9s for interactive management
ksail cluster stop      # Stop the cluster
ksail cluster start     # Start a stopped cluster

Your kubeconfig is automatically configured, so standard kubectl commands work too.

For the full command reference, see Cluster Commands.

Step 9: Deploying Workloads

KSail wraps kubectl and GitOps operations under the workload command. For cloud clusters like Hetzner, you have two main options for deploying workloads.

Option A: Direct kubectl Workflow

The simplest approach applies manifests directly to the cluster:

ksail workload apply -k ./k8s    # Apply Kustomize manifests
ksail workload get pods          # Check pod status
ksail workload logs deployment/my-app  # View logs

This works well for quick iterations but doesn’t provide GitOps benefits like drift detection and automatic reconciliation.

Option B: GitOps with External Registry

For cloud clusters without a local Docker registry, you can use an external OCI registry like GitHub Container Registry (ghcr.io). This enables full GitOps workflows with Flux or ArgoCD.

Step 1: Create a GitHub Personal Access Token

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Create a token with write:packages and read:packages scopes
Export the credentials:

export GITHUB_USER="your-username"
export GITHUB_TOKEN="ghp_your-token-here"

Step 2: Initialize with GitOps and External Registry

When scaffolding your cluster, specify the GitOps engine and external registry:

ksail cluster init \
  --distribution Talos \
  --provider Hetzner \
  --cni Cilium \
  --gitops-engine Flux \
  --local-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io/your-org/your-cluster'

Step 3: Create the Cluster

ksail cluster create

This installs Flux and configures it to sync from your external registry.

Step 4: Push and Reconcile Workloads

# Package manifests and push to registry
ksail workload push

# Trigger GitOps reconciliation
ksail workload reconcile

The push command packages your k8s/ directory as an OCI artifact and pushes it to ghcr.io. Flux then pulls and applies the manifests automatically.

For the full workload command reference, see Workload Commands.

Cleaning Up

When you’re done with the cluster:

ksail cluster delete

This removes:

All Hetzner Cloud servers
The private network
Placement groups
Local kubeconfig entries
Local talosconfig entries

Cost Considerations

A minimal development setup (1 control plane) using a cx23 server costs under €4/month.

For a more robust setup (3 control planes + 2 workers) using cx23 servers:

Component	Monthly Cost
3x cx23 control planes	€11.22
2x cx23 workers	€7.48
Private network	Free
Total	~€18.70/month

This is remarkably affordable for a Kubernetes development cluster.

What’s Next

Explore the KSail documentation for advanced topics including secret management with SOPS, mirror registries, and GitOps workflows.

Planned: Production-Grade Features

Integration with Hetzner Cloud Controller Manager and Hetzner Cloud CSI Driver is planned for future releases. This will enable:

Cloud Load Balancers: Automatic provisioning of Hetzner Load Balancers for Kubernetes Services of type LoadBalancer
Persistent Storage: Dynamic provisioning of Hetzner Cloud Volumes for PersistentVolumeClaims

Feedback Welcome

This is the first iteration of Hetzner Cloud support in KSail. If you encounter bugs or find missing features, please open an issue on GitHub. Your feedback helps improve the tool for everyone.

A Note on Cloud Provider Support

Testing and maintaining cloud provider integrations comes with ongoing infrastructure costs. Hetzner is supported because I use it for my own homelab and want to manage it via KSail. Additional cloud providers (AWS, GCP, Azure, etc.) will not be added without sponsorship to cover testing costs.

If you’d like to see your preferred cloud provider supported, consider sponsoring the project on GitHub.

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5. The content is based on real-world experience running Talos development clusters on Hetzner Cloud.

AI-Powered GitHub Issues: How I Use Copilot with Claude Opus 4.5 to Create Impactful Issues

Fri, 09 Jan 2026 00:00:00 GMT

Creating good GitHub issues is an underrated skill. A well-written issue saves hours of back-and-forth during refinement, reduces misunderstandings, and helps developers focus on solving problems rather than deciphering vague descriptions. But writing those issues takes time — time spent investigating code, formulating problems clearly, and ensuring the description meets team expectations.

I’ve found a workflow that dramatically reduces this overhead: using GitHub Copilot with Claude Opus 4.5 to analyze codebases and generate structured, impactful issues.

The Problem with Traditional Issue Creation

Before adopting this workflow, creating a proper issue typically involved:

Investigation: Digging through code to understand the current state
Analysis: Identifying what’s wrong or what’s missing
Formulation: Translating technical findings into clear descriptions
Structuring: Ensuring the issue follows team conventions
Review: Double-checking that nothing important was missed

For a complex feature or bug, this process could easily take multiple hours — and that’s assuming you’re already familiar with the codebase.

My AI-Assisted Workflow

My approach flips the script. Instead of manually investigating and writing, I give GitHub Copilot a clear but short description of the expected outcome or problem, and let Claude Opus 4.5 do the heavy lifting.

flowchart LR
    A["📁 Select Context"] --> B["💬 Prompt with Intent"]
    B --> C["📋 Reference Templates"]
    C --> D["🤖 AI Analysis"]
    D --> E["🎫 Create Issue"]
    E --> F["✅ Review & Refine"]

Here’s how it works:

Step 1: Select the Context

I attach the relevant folders, repositories, or files in VS Code Chat Agent mode. This might be:

A specific service or module where I’ve noticed a problem
Multiple related files that need coordinated changes
An entire project when planning a new feature

Step 2: Prompt with Intent and Reference Templates

I provide Copilot with a concise description of what I need, always referencing my issue templates. The key is being clear about:

What to analyze — the specific area of the codebase
What the problem or goal is — the expected outcome
Which template to use — this ensures the output follows team conventions

Here are some example prompts I use:

For a bug:

Analyze the metrics-server installation in pkg/svc/installers/ and identify
why it's not working with the latest Kubernetes version. Use my bug issue
template from .github/ISSUE_TEMPLATE/BUG.yaml to create the issue.

For a feature:

Investigate the current cluster provisioning flow in pkg/svc/provisioners/
and create a feature issue for adding Hetzner Cloud support. Follow the
feature template from .github/ISSUE_TEMPLATE/FEATURE.yaml.

For process improvements:

Our team's refinement sessions often run over time because issues lack context.
Create an improvement kata issue to improve how we write and prepare issues
before refinement, using the KATA.yaml template.

Step 3: Review and Refine

Opus 4.5 generates a complete issue that typically requires minimal editing. The model is remarkably good at:

Understanding codebases and their architecture
Identifying the actual problem, not just symptoms
Writing clear, actionable descriptions
Following the template structure precisely

Structured Templates Are Key

The secret sauce isn’t just the AI — it’s combining AI with well-designed issue templates. I use YAML-based GitHub issue forms stored in .github/ISSUE_TEMPLATE/ that enforce structure and guide both humans and AI to provide the right information.

Bug Reports

For bugs, my template captures the essential debugging information:

name: 🐛 Bug
description: An unexpected problem or behavior.
title: "[bug]: "
type: Bug
body:
  - type: textarea
    id: expected_behavior
    attributes:
      label: Expected Behavior
      description: Describe what you expected to happen.
    validations:
      required: true

  - type: textarea
    id: actual_behavior
    attributes:
      label: Actual Behavior
      description: Describe what actually happened.
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: Steps to Replicate
      description: List the steps to replicate the bug.
      value: |
        1. Step 1
        2. Step 2
        3. Step 3
    validations:
      required: true

When I prompt Copilot with something like “The cluster fails to start when Cilium is enabled on ARM64 — create a bug issue”, it produces output that maps directly to these fields with accurate technical details.

Feature Requests

For features, I use the standard agile user story format with acceptance criteria:

name: 🚀 Feature
description: Submit a new feature as a user story with acceptance criteria.
title: "[feature]: "
type: Feature
body:
  - type: textarea
    id: user_story
    attributes:
      label: User Story
      description: Use the standard agile story format.
      value: |
        **As a** [role],
        **I want** [an action or feature],
        **So that** [a reason or benefit].
    validations:
      required: true

  - type: textarea
    id: acceptance_criteria
    attributes:
      label: Acceptance Criteria
      description: Provide a task list of conditions that must be satisfied.
      value: |
        - [ ] Criteria 1: Describe the first acceptance criterion here.
        - [ ] Criteria 2: Describe the second acceptance criterion here.
        - [ ] Criteria 3: Describe additional criteria as needed.
    validations:
      required: true

The user story format forces clarity about who benefits, what they need, and why it matters. Claude Opus 4.5 excels at filling this in with genuine user-centric thinking rather than developer-centric feature descriptions.

Improvement Katas

For continuous improvement initiatives, I use the Toyota Kata framework. Unlike bugs and features, katas focus on human processes rather than code — things like team communication, workflow bottlenecks, or development practices.

name: 🥋 Improvement Kata
description: Use the Improvement Kata framework for structured problem-solving.
title: "[kata]: "
type: Kata
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem
      description: Describe the current situation and why it is problematic.
      value: |
        Current situation:
        - ...

        Why this is problematic:
        - ...
    validations:
      required: true

  - type: textarea
    id: definition-of-awesome
    attributes:
      label: Definition of Awesome
      description: How would we like it to be? Describe the ideal state.
    validations:
      required: true

  - type: textarea
    id: next-target-condition
    attributes:
      label: Next Target Condition
      description: X weeks from now, what has changed?
    validations:
      required: true

  - type: textarea
    id: actions
    attributes:
      label: Actions
      description: List of actions to take toward the target condition.
      value: |
        - [ ] **Action 1:** ...
        - [ ] **Action 2:** ...
        - [ ] **Action 3:** ...
    validations:
      required: true

This template is particularly powerful with AI assistance. Opus 4.5 can help structure observations about team dynamics, identify process bottlenecks, and propose actionable improvement experiments — turning vague frustrations into measurable improvement initiatives.

You can find all my issue templates in the devantler-tech/.github repository.

A Real Example: From Prompt to Issue

To show this workflow in action, here’s a real issue I created for KSail using this approach.

What I Typed

Analyze the existing addon patterns in pkg/svc/installer/ (cert-manager,
metrics-server, CNI, CSI) and create a feature issue for adding a
--policy-engine flag that supports Kyverno and Gatekeeper. Use the
FEATURE.yaml template from .github/ISSUE_TEMPLATE/.

That’s it — one sentence describing what I wanted, plus a reference to existing patterns and my template.

What the AI Produced

Copilot analyzed the codebase, identified all the integration points, and generated this issue:

**[feature]: Add `--policy-engine` flag to install Kyverno or Gatekeeper**

**User Story**

**As a** KSail user,
**I want** to install a policy engine (Kyverno or Gatekeeper) when creating a cluster,
**So that** I can enforce policies on my workloads from the start without manual post-provisioning steps.

**Background**

Policy engines are essential for enforcing security, compliance, and best practices in Kubernetes clusters. Adding first-class support for policy engines follows the same pattern as existing addons (cert-manager, metrics-server, CNI, CSI, GitOps engines).

The AI didn’t stop there. It analyzed the existing addon implementations and produced detailed implementation requirements:

### Implementation Requirements

#### 1. API Types (`pkg/apis/cluster/v1alpha1/`)

- [ ] Add `PolicyEngine` enum type with values `PolicyEngineNone`, `PolicyEngineKyverno`, `PolicyEngineGatekeeper`
- [ ] Add `PolicyEngine PolicyEngine` field to `ClusterSpec` struct
- [ ] Implement `Set()`, `String()`, `Type()` methods for pflags compatibility

#### 2. Installer Service (`pkg/svc/installer/`)

- [ ] Create `pkg/svc/installer/kyverno/installer.go` implementing `installer.Installer`
- [ ] Create `pkg/svc/installer/gatekeeper/installer.go` implementing `installer.Installer`

#### 3. CLI Integration (`cmd/cluster/`)

- [ ] Add `--policy-engine` flag to `init.go` and `create.go`

It even included the correct Helm chart references:

Engine	Repo URL	Chart	Default Namespace
Kyverno	`https://kyverno.github.io/kyverno/`	`kyverno/kyverno`	`kyverno`
Gatekeeper	`https://open-policy-agent.github.io/gatekeeper/charts`	`gatekeeper/gatekeeper`	`gatekeeper-system`

The Result

The generated issue required minimal editing — just some polish to the acceptance criteria. And here’s the kicker: I implemented the entire feature using another single prompt:

Implement https://github.com/devantler-tech/ksail/issues/1614

The issue was so well-structured that Copilot could follow it as a specification. Total time from idea to merged PR: about 2 hours of active work, and about 4 hours in total (with the time AI was working). Imagine how much work you could do if you parallelized this across multiple issues!

Real-World Impact

I use this approach in two contexts:

Personal Projects (KSail)

For KSail, my tool for creating, maintaining and operating Kubernetes clusters with ease, this workflow has been invaluable. When I notice something that needs improvement, I can quickly generate a detailed issue without interrupting my flow. The AI understands the Go codebase, the embedded tool clients, and the overall architecture — producing issues that accurately describe both problems and solutions.

Professional Work (TV 2)

At TV 2, where I work, this approach has had an even bigger impact.

	Traditional	AI-Assisted
Investigation	1-2 hours	1 min (context selection)
Analysis	1-2 hour	1 min (prompting)
Writing	0.5-1 hour	3 min (AI generation)
Structuring	10 min	— (template handles it)
Review	30 min	25 min
Total	3-6 hours	~30 minutes

Time saved on investigation: Instead of spending hours digging through unfamiliar code, I can generate a comprehensive issue in under 30 minutes.

Better refinement sessions: When issues arrive at refinement already following our template and containing accurate technical details, the team can focus on alignment, estimation and planning rather than clarification.

Senior-level quality: Opus 4.5 is remarkably capable at writing issues that meet senior software engineers’ expectations. The descriptions are technical enough to be useful, clear enough to be actionable, and structured enough to fit our workflow.

Consistency: Every issue follows the same format, making it easier for team members to find the information they need.

When This Approach Doesn’t Work

This workflow isn’t magic. There are situations where AI-assisted issue creation falls short:

Issues requiring stakeholder input: If the issue depends on business decisions, user research, or information that isn’t in the codebase, the AI can’t help much. It can structure the issue, but it can’t interview your product owner.

Highly sensitive or confidential context: Be careful about what context you share with AI tools. If the issue involves security vulnerabilities, credentials, or proprietary business logic, you may need to write it manually or heavily redact the AI’s output.

Cross-repository or external dependencies: When issues span multiple repositories or depend on external systems the AI can’t see, the generated context may be incomplete. Always verify external references.

Vague problems without symptoms: If you can’t articulate even a rough description of what’s wrong, the AI can’t investigate effectively. “Something feels slow” is too vague — “API response times have increased” gives the AI something to search for.

Novel codebases: The AI is remarkably good at pattern recognition. In well-structured codebases with consistent patterns (like KSail’s addon system), it excels. In chaotic legacy codebases with no clear patterns, results vary.

For these situations, I fall back to traditional issue creation, or a mix of both — but I always use issue templates to ensure structure.

Tips for Getting the Best Results

After a month of using this workflow, here’s what I’ve learned:

1. Be Specific About Scope

Tell Copilot exactly which files or folders to analyze. The more focused the context, the more accurate the output.

2. Describe the Outcome, Not the Solution

Say “users can’t access the metrics endpoint” rather than “fix the metrics-server RBAC”. Let the AI investigate and propose solutions.

3. Always Reference Your Templates

Explicitly mention your issue templates. This ensures the output follows your team’s conventions.

4. Review with Fresh Eyes

While the generated issues are usually excellent, always read them as if you were a team member seeing them for the first time. Add context that only you know.

5. Iterate on Complex Issues

For large features, start with a high-level issue, then generate sub-issues for specific components.

Conclusion

GitHub Copilot with Claude Opus 4.5 has transformed how I create issues. What used to take 3-6 hours now takes around 30 minutes, and the quality is often higher than what I’d produce manually.

mindmap
  root((AI-Powered Issues))
    Fast
      30 min vs 3-6 hours
      No manual investigation
    Consistent
      Same template every time
      Team conventions followed
    Accurate
      Deep codebase analysis
      Real problems identified
    Team-Friendly
      Ready for refinement
      Clear acceptance criteria

The combination of AI analysis and structured templates creates a workflow that’s:

Fast: Minimal time spent on investigation
Consistent: Every issue follows the same format
Accurate: The AI understands codebases deeply
Team-friendly: Issues arrive at refinement ready to discuss

If you’re spending too much time writing issues, or if your team’s refinement sessions are slowed down by unclear issue descriptions, give this workflow a try. The upfront investment in good issue templates pays dividends when combined with AI-powered generation, but also if you write issues manually.

Want to try this yourself? Use my issue templates and adapt them to your team’s conventions. The combination of structured templates and AI-powered generation might just change how you work.

The future of software development isn’t AI replacing developers — it’s AI handling the tedious parts so developers can focus on what matters. I am personally ecstatic about how this workflow has improved my productivity and the quality of my work. I hope it helps you too!

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5 — the motor of the workflow it describes. The content reflects my genuine experiences and opinions; the AI helped structure and articulate them.

Building KSail: From Shell Scripts to .NET to Go

Wed, 07 Jan 2026 00:00:00 GMT

Building a developer tool is rarely a straight path. KSail started as a humble shell script in late 2023 and has evolved through three major rewrites to become what it is today: a Go-based CLI that bundles common Kubernetes tooling into a single binary. This post tells the story of that journey.

The Problem

Setting up and operating Kubernetes clusters is a skill of its own. It often requires juggling multiple CLI tools (kubectl, helm, kind, k3d, flux, argocd, sops), writing bespoke scripts, and dealing with inconsistent developer workflows determined by specific projects.

This complexity slows down development, makes Kubernetes intimidating for newcomers, and makes it difficult to maintain reproducible environments. I wanted a tool that would remove the tooling overhead so developers could focus on their workloads.

Phase 1: Shell Scripts (December 2023)

The first commit to KSail was on December 31, 2023. It started as a Bash script called ksail.sh that wrapped Talos Linux commands to create local Kubernetes clusters.

# Early KSail was literally just a shell script
./ksail.sh up   # Create a cluster
./ksail.sh down # Destroy it

This worked, but shell scripts have significant limitations:

No type safety: Bugs only surface at runtime
Limited error handling: Bash’s error handling is notoriously awkward
Cross-platform issues: Scripts that work on macOS might fail on Linux
Dependency management: Users needed every tool installed separately

Within the first week, I added K3d support alongside Talos, and the script was becoming unwieldy. It was clear that a more structured approach was needed.

Phase 2: The .NET Rewrite (January 2024)

On January 8, 2024 — just over a week after the initial commit — I rewrote KSail as a .NET console application with PR #25: “Rework KSail to .NET Project with wrapped binaries and libraries.”

Why .NET?

At the time, .NET was my primary language. I was comfortable with C#, and .NET 8 had just been released with great cross-platform support. The ecosystem had mature libraries for CLI development (System.CommandLine), and I could leverage NuGet for dependency management.

The Architecture

The .NET version took an interesting approach: it embedded the required binaries (kubectl, kind, k3d, talosctl, etc.) directly into the application and extracted them at runtime. This meant users only needed to install KSail itself — the dependencies came bundled.

// Pseudo-code of the .NET approach
public class KindClient
{
    private readonly string _binaryPath;

    public KindClient()
    {
        _binaryPath = ExtractEmbeddedBinary("kind");
    }

    public async Task CreateClusterAsync(string name, string config)
    {
        await ProcessRunner.RunAsync(_binaryPath, $"create cluster --name {name} --config {config}");
    }
}

Over 2024, the .NET version grew substantially. I presented it at KCD Denmark 2024 in a talk titled “KSail - a Kubernetes SDK for local GitOps development and CI”. By the end of 2024, the project had accumulated 788 commits and supported:

Multiple distributions (Kind, K3d, Talos)
GitOps engines (Flux, ArgoCD)
Secret management with SOPS
Declarative configuration via ksail.yaml
Mirror registries for avoiding Docker Hub rate limits

Growing Pains

Despite its functionality, the .NET version had issues:

Binary size: Bundling all those executables made the final binary quite large
Update complexity: Every upstream tool update required downloading new binaries, embedding them, and releasing a new version
Platform coverage: Supporting Linux amd64, Linux arm64, macOS arm64, and Windows meant managing multiple binary variants
Startup time: Extracting binaries on first run added latency
Ecosystem mismatch: Most Kubernetes tooling is written in Go, and calling out to external processes felt like fighting the ecosystem

Phase 3: The Go Rewrite (December 2025)

On December 18, 2025, I merged PR #1448: “BREAKING CHANGE: Migrate ksail from .NET to Go.” This wasn’t a port — it was a complete rewrite that took advantage of Go’s unique position in the Kubernetes ecosystem.

Why Go?

The Kubernetes ecosystem is built on Go. kubectl, kind, k3d, helm, flux — they’re all Go projects. This means:

Import instead of wrap: Instead of shelling out to external binaries, KSail can import these tools as Go libraries
Single binary: No embedded executables to extract; everything compiles into one binary
Fast startup: No extraction step, no JIT compilation
First-class Kubernetes support: client-go is the reference implementation for Kubernetes clients
Cross-compilation: Go’s cross-compilation is trivial compared to .NET’s AOT publishing

The New Architecture

The Go version embeds tool functionality directly:

// Instead of shelling out, we use the libraries directly
import (
    "sigs.k8s.io/kind/pkg/cluster"
    "helm.sh/helm/v4/pkg/action"
    "github.com/fluxcd/flux2/v2/pkg/bootstrap"
)

func (p *KindProvisioner) Create(ctx context.Context, config *KindConfig) error {
    provider := cluster.NewProvider()
    return provider.Create(config.Name,
        cluster.CreateWithConfigFile(config.Path),
        cluster.CreateWithWaitForReady(config.Timeout),
    )
}

The project structure is clean and idiomatic:

pkg/
├── apis/          # Configuration types
├── cli/           # Command implementations
├── client/        # Embedded tool clients (kubectl, helm, flux, etc.)
├── di/            # Dependency injection
├── io/            # File and config utilities
├── k8s/           # Kubernetes helpers
├── svc/           # Services (installers, provisioners, reconcilers)
└── utils/         # Shared utilities

Lessons Learned

After three rewrites and over 2,200 commits, here’s what I’ve learned:

1. Choose the Right Language for the Ecosystem

The Go rewrite wasn’t about Go being “better” than .NET — it was about Go being the right tool for Kubernetes development. When your tool integrates deeply with an ecosystem, speaking its native language matters.

2. Wrapping vs. Embedding

The .NET version wrapped external binaries. The Go version embeds libraries. The difference is profound:

Wrapping: You’re at the mercy of the tool’s CLI interface, which can change between versions
Embedding: You have direct access to the tool’s internals, with type safety and proper error handling

3. Start Simple, Then Structure

The shell script taught me what the tool needed to do. The .NET version taught me how to structure it properly. The Go version combined those lessons with the right technology choice.

4. Don’t Fear the Rewrite

Each rewrite made KSail better. The shell script validated the idea. The .NET version proved the concept and found users. The Go version delivered on the original vision of a single, fast, portable binary.

Where KSail Is Today

The current Go version of KSail provides:

One binary — No external dependencies except Docker
Multiple distributions — Kind, K3d, and Talos
Customizable stack — CNI (Cilium, Calico), CSI, metrics-server, cert-manager
GitOps native — Built-in Flux and ArgoCD support
Secret management — Integrated SOPS encryption
Declarative configuration — Everything as code in ksail.yaml

Installation is simple:

brew install --cask devantler-tech/tap/ksail
# or
go install github.com/devantler-tech/ksail/v5@latest

And usage is straightforward:

ksail cluster init --distribution Kind --cni Cilium --gitops-engine Flux
ksail cluster create
ksail workload apply -k ./k8s
ksail cluster connect  # Opens K9s

What’s Next

KSail is actively developed with a focus on:

Cloud providers: Hetzner Cloud support is in progress
Enhanced GitOps workflows: Better reconciliation and debugging tools
Enhanced SOPS integration: More secret management features for e.g. GitOps.

The project is open source under the Apache 2.0 license. You can find:

Repository: github.com/devantler-tech/ksail
Documentation: ksail.devantler.tech
Go Package Docs: pkg.go.dev/github.com/devantler-tech/ksail/v5

If you’re working with Kubernetes locally, give KSail a try. And if you’ve been through similar rewrites with your own projects, I’d love to hear your stories.

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5. The content reflects my genuine experiences and journey; the AI helped structure and articulate it.

Local Kubernetes Development with KSail and Talos

Sat, 27 Dec 2025 00:00:00 GMT

Talos Linux is a minimal, immutable operating system designed specifically for Kubernetes. While it’s often used in production environments, you can also run Talos locally in Docker for development. Combined with KSail, you get a security-focused local development experience. This post shows you how.

Why Talos + KSail?

Talos Linux takes a radically different approach to running Kubernetes. There’s no SSH, no shell, no package manager — just the Talos API and Kubernetes. The entire OS is immutable and managed declaratively via configuration files.

This approach provides:

Minimal attack surface — No shell means no shell exploits
No configuration drift — Immutable OS prevents unauthorized changes
Declarative everything — OS configuration is versioned and reproducible
Production parity — Your local environment matches production Talos clusters

KSail wraps Talos tooling into a single binary, handling cluster provisioning, GitOps setup, and workload management through one consistent interface.

Prerequisites

You need Docker installed and running. Verify with:

docker ps

If this command works, you’re ready to go.

Step 1: Install KSail

KSail is distributed as a single binary. Install via Homebrew:

brew install --cask devantler-tech/tap/ksail

Or with Go:

go install github.com/devantler-tech/ksail/v5@latest

Verify the installation:

ksail --version

Step 2: Scaffold Your Cluster Project

KSail’s init command scaffolds a complete project structure. For a Talos cluster with Cilium CNI:

mkdir my-cluster && cd my-cluster
ksail cluster init --distribution Talos --cni Cilium

This creates ksail.yaml (cluster configuration), talos/ (Talos configs), and k8s/ (your Kubernetes manifests).

For all available flags and configuration options, see the KSail documentation:

CLI flags reference — All cluster init options
ksail.yaml reference — Configuration file schema
Features overview — CNI, CSI, GitOps, and more

Step 3: Create the Cluster

Create and start your cluster:

ksail cluster create

This command:

Creates Docker containers running Talos Linux
Bootstraps the Talos control plane
Initializes etcd and the Kubernetes API server
Installs your selected CNI, CSI, and other components
Configures your local kubeconfig and talosconfig

The process takes 1-2 minutes. Talos clusters take slightly longer than Kind or K3d because of the additional bootstrap steps for the immutable OS.

Step 4: Working with Your Cluster

Once your cluster is running, KSail provides commands for common operations:

ksail cluster info      # Show cluster status
ksail cluster list      # List all KSail-managed clusters
ksail cluster connect   # Open K9s for interactive management
ksail cluster stop      # Stop the cluster
ksail cluster start     # Start a stopped cluster

Your kubeconfig is automatically configured, so standard kubectl commands work too.

For the full command reference, see Cluster Commands.

Step 5: Deploying Workloads

KSail wraps kubectl and GitOps operations under the workload command:

ksail workload apply -k ./k8s    # Apply manifests (kubectl workflow)
ksail workload push              # Push to GitOps source
ksail workload reconcile         # Trigger GitOps reconciliation

For the full workload command reference, see Workload Commands.

Cleaning Up

When you’re done:

ksail cluster delete

This removes the Docker containers and cleans up kubeconfig and talosconfig entries.

What’s Next

Explore the KSail documentation for advanced topics including:

Multi-node Talos clusters for testing HA scenarios
Enabling GitOps with Flux or ArgoCD
Secret management with SOPS
Mirror registries to avoid Docker Hub rate limits

Once you’re comfortable with Talos locally, you can deploy to cloud infrastructure. See Creating Development Clusters on Hetzner with KSail and Talos for a guide on running Talos in the cloud.

For simpler local setups, check out Kind with KSail for vanilla Kubernetes or K3s with KSail for a batteries-included experience.

Feedback Welcome

KSail is under active development. If you encounter bugs or find missing features, please open an issue on GitHub. Your feedback helps improve the tool for everyone.

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5.

Local Kubernetes Development with KSail and K3d

Sat, 20 Dec 2025 00:00:00 GMT

K3s is Rancher’s lightweight Kubernetes distribution, and when combined with K3d and KSail, you get a fast, batteries-included local development experience. This post shows you how to get started.

Why K3d + KSail?

K3s is a lightweight, certified Kubernetes distribution designed for resource-constrained environments. It comes with sensible defaults and includes components like Traefik ingress, local-path storage provisioner, and metrics-server out of the box.

K3d wraps K3s to run it in Docker containers, making it perfect for local development.

KSail ties it all together with a single binary that handles cluster provisioning, GitOps setup, and workload management. You get one consistent interface regardless of the underlying distribution.

Together, they provide:

Fast startup — Clusters ready in about 30 seconds
Batteries included — Storage, ingress, and metrics built in
Low resource usage — K3s is optimized for minimal overhead
Declarative configuration — Everything as code in ksail.yaml

Prerequisites

You need Docker installed and running. Verify with:

docker ps

If this command works, you’re ready to go.

Step 1: Install KSail

KSail is distributed as a single binary. Install via Homebrew:

brew install --cask devantler-tech/tap/ksail

Or with Go:

go install github.com/devantler-tech/ksail/v5@latest

Verify the installation:

ksail --version

Step 2: Scaffold Your Cluster Project

KSail’s init command scaffolds a complete project structure:

mkdir my-cluster && cd my-cluster
ksail cluster init --distribution K3s

This creates ksail.yaml (cluster configuration), k3d.yaml (K3d config), and k8s/ (your Kubernetes manifests).

For all available flags and configuration options, see the KSail documentation:

CLI flags reference — All cluster init options
ksail.yaml reference — Configuration file schema
Features overview — CNI, CSI, GitOps, and more

Step 3: Create the Cluster

Create and start your cluster:

ksail cluster create

This command:

Creates Docker containers as K3s nodes
Bootstraps the K3s control plane with built-in components
Installs any additional components you configured (Cilium, Flux, etc.)
Configures your local kubeconfig

The process takes about 30 seconds for a single-node cluster.

Step 4: Working with Your Cluster

Once your cluster is running, KSail provides commands for common operations:

ksail cluster info      # Show cluster status
ksail cluster list      # List all KSail-managed clusters
ksail cluster connect   # Open K9s for interactive management
ksail cluster stop      # Stop the cluster
ksail cluster start     # Start a stopped cluster

Your kubeconfig is automatically configured, so standard kubectl commands work too.

For the full command reference, see Cluster Commands.

Step 5: Deploying Workloads

KSail wraps kubectl and GitOps operations under the workload command:

ksail workload apply -k ./k8s    # Apply manifests (kubectl workflow)
ksail workload push              # Push to GitOps source
ksail workload reconcile         # Trigger GitOps reconciliation

For the full workload command reference, see Workload Commands.

Cleaning Up

When you’re done:

ksail cluster delete

This removes the Docker containers and cleans up kubeconfig entries.

What’s Next

Explore the KSail documentation for advanced topics including:

Swapping the default CNI for Cilium or Calico
Enabling GitOps with Flux or ArgoCD
Secret management with SOPS
Mirror registries to avoid Docker Hub rate limits

If you want a vanilla Kubernetes experience, check out the post on Kind with KSail. For an immutable, security-focused distribution, see Talos with KSail.

Feedback Welcome

KSail is under active development. If you encounter bugs or find missing features, please open an issue on GitHub. Your feedback helps improve the tool for everyone.

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5.

Local Kubernetes Development with KSail and Kind

Mon, 15 Dec 2025 00:00:00 GMT

Getting started with Kubernetes development shouldn’t require cloud infrastructure or complex setup procedures. With Kind (Kubernetes in Docker) and KSail, you can have a local cluster running in under a minute. This post shows you how.

Why Kind + KSail?

Kind (Kubernetes in Docker) runs Kubernetes clusters using Docker containers as nodes. It’s fast, lightweight, and provides a vanilla Kubernetes experience that closely matches production environments.

KSail wraps Kind and other tools into a single binary, giving you one consistent interface for cluster provisioning, GitOps setup, and workload management. Instead of learning multiple CLIs, you use ksail cluster and ksail workload commands.

Together, they provide:

Fast iteration — Clusters start in under 60 seconds
Zero cost — Everything runs locally on your machine
Vanilla Kubernetes — No distribution-specific quirks to learn
Declarative configuration — Everything as code in ksail.yaml

Prerequisites

You need Docker installed and running. Verify with:

docker ps

If this command works, you’re ready to go.

Step 1: Install KSail

KSail is distributed as a single binary. Install via Homebrew:

brew install --cask devantler-tech/tap/ksail

Or with Go:

go install github.com/devantler-tech/ksail/v5@latest

Verify the installation:

ksail --version

Step 2: Scaffold Your Cluster Project

KSail’s init command scaffolds a complete project structure:

mkdir my-cluster && cd my-cluster
ksail cluster init --distribution Vanilla

This creates ksail.yaml (cluster configuration), kind.yaml (Kind config), and k8s/ (your Kubernetes manifests).

For all available flags and configuration options, see the KSail documentation:

CLI flags reference — All cluster init options
ksail.yaml reference — Configuration file schema
Features overview — CNI, CSI, GitOps, and more

Step 3: Create the Cluster

Create and start your cluster:

ksail cluster create

This command:

Creates Docker containers as Kubernetes nodes
Bootstraps the Kubernetes control plane
Installs your selected CNI, CSI, and other components
Configures your local kubeconfig

The process takes under 60 seconds for a single-node cluster.

Step 4: Working with Your Cluster

Once your cluster is running, KSail provides commands for common operations:

ksail cluster info      # Show cluster status
ksail cluster list      # List all KSail-managed clusters
ksail cluster connect   # Open K9s for interactive management
ksail cluster stop      # Stop the cluster
ksail cluster start     # Start a stopped cluster

Your kubeconfig is automatically configured, so standard kubectl commands work too.

For the full command reference, see Cluster Commands.

Step 5: Deploying Workloads

KSail wraps kubectl and GitOps operations under the workload command:

ksail workload apply -k ./k8s    # Apply manifests (kubectl workflow)
ksail workload push              # Push to GitOps source
ksail workload reconcile         # Trigger GitOps reconciliation

For the full workload command reference, see Workload Commands.

Cleaning Up

When you’re done:

ksail cluster delete

This removes the Docker containers and cleans up kubeconfig entries.

What’s Next

Explore the KSail documentation for advanced topics including:

Adding Cilium or Calico as your CNI
Enabling GitOps with Flux or ArgoCD
Secret management with SOPS
Mirror registries to avoid Docker Hub rate limits

If Kind’s vanilla Kubernetes feels too basic, check out the posts on K3s with KSail for a more batteries-included experience, or Talos with KSail for an immutable, security-focused distribution.

Feedback Welcome

KSail is under active development. If you encounter bugs or find missing features, please open an issue on GitHub. Your feedback helps improve the tool for everyone.

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5.

MacOS as a Developer Machine

Tue, 13 May 2025 00:00:00 GMT

In this post, I will share my experience setting up MacOS as a developer machine. I will cover the following topics:

Managing Packages
Managing Dotfiles and System Configuration
Git, SSH, and GPG Keys
Passwords and Secrets
Configuring the Terminal
Setting Up Your IDE
Remote Development
Conclusion

Managing Packages

There are a few options available for managing packages on MacOS. Notable package managers include:

Due to Homebrew seemingly having the most popularity and the largest community, I went with Homebrew, and I have been using it extensively, for a few years now. In my experience, Homebrew has been reliable and easy to use, and I have yet to encounter that it is missing a feature that I need, or that it is not working as expected.

Installing and Using Homebrew

Installing Homebrew is straightforward, and is well documented on the Homebrew website. Once installed, you can install packages using the brew install command. For example, to install Git, you can run:

brew install git

It can also be used to install applications (Homebrew calls these casks), such as Visual Studio Code:

brew install --cask visual-studio-code

Homebrew can also snapshot your installed packages and applications, which can be useful when migrating to a new machine, or when you own multiple machines. You will learn how I prefer to manage my system configuration including my packages and applications in the next section Managing Dotfiles and System Configuration.

Benefits of Using Homebrew

Easy to install and use
Extensive library of packages
Ability to install applications
Ability to snapshot installed packages and applications

Managing Dotfiles and System Configuration

Many applications and packages require storing configuration files in your home directory. These files are often referred to as dotfiles, as the folders and files are prefixed with a dot (.). Examples of dotfiles include .bashrc, .gitconfig, and .vimrc, but there are many more.

When you use valuable time configuring, for example, your Git settings, you probably want to keep these settings when you switch to a new machine. This is where dotfiles come in handy. By storing your dotfiles in a version-controlled repository, you can easily sync your configuration across multiple machines.

However keeping stuff in sync is no simple task, and there are a multitude of ways to do it. I have personally tried a few different approaches, that varied in complexity and flexibility. It was not until I discovered MackUp that I found a solution that worked well for me.

MackUp is a simple utility that, when executed, will symlink your dotfiles and system configuration to a storage provider of your choice. It supports a variety of storage providers, such as Dropbox, Google Drive, OneDrive, or Git. As I prefer to keep most of my stuff in Git, I of course use the Git storage provider. As such the following examples will also assume that Git is used as the storage provider.

Installing and Using MackUp

To get started with MackUp, you can install it using Homebrew:

brew install mackup

After installing MackUp, you can configure it by creating a .mackup.cfg file in your home directory. Here is an example configuration file:

[storage]
engine = git
directory = ~/dotfiles

This configuration tells MackUp to store dotfiles in a Git repository located at ~/dotfiles. You can then run mackup backup to symlink your dotfiles to the Git repository. When you switch to a new machine, you can run mackup restore to restore your dotfiles.

Storing Brew Bundles in MackUp

In addition to storing your dotfiles, you can also store your Homebrew packages and applications in MackUp. This can be done by creating a Brewfile, which can be used to snapshot all the packages and applications you have installed on a machine. You can create a Brewfile of your installed packages and applications by running:

brew bundle dump

This will create a Brewfile in your home directory that lists all your installed packages and applications. To install these packages and applications on a new machine, you can run:

brew bundle install

Convenience Scripts

To make it easier to manage your dotfiles and system configuration, you can create convenience scripts that automate the process. Here are the scripts I use for managing my dotfiles:

Backup Script

This script will backup your dotfiles and system configuration to a Git repository, and store your Homebrew packages and applications in a Brewfile. It supports both macOS and Linux. To run the script:

chmod +x backup.sh # To make the script executable
./backup.sh

The script must be placed in the root of your dotfiles repository. Run it from your home directory.

#!/bin/bash
check_os() {
  if [ "$(uname)" != "Darwin" ] && [ "$(uname)" != "Linux" ]; then
    echo "This script is only for macOS and Linux"
    exit 1
  fi
}

create_mackup_config() {
  echo_title "📝 Creating Mackup config"
  if [ -f "$HOME/.mackup.cfg" ]; then
    return
  fi
  echo "[storage]
engine = file_system
path = $HOME/dotfiles" >"$HOME/.mackup.cfg"
}

install_homebrew() {
  if ! [ -x "$(command -v brew)" ]; then
    echo_title "🍺 Installing Homebrew"
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    (
      echo
      echo 'eval "$(/opt/homebrew/bin/brew shellenv)"'
    ) >>"$HOME"/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"
  fi
}

install_rosetta() {
  if ! [ -x "$(command -v arch)" ]; then
    echo_title "📄 Installing Rosetta 2"
    softwareupdate --install-rosetta --agree-to-license
  fi
}

install_mackup() {
  if ! [ -x "$(command -v mackup)" ]; then
    echo_title "📦 Installing Mackup"
    brew install mackup
  fi
}

echo_title() {
  local title=$1
  echo ""
  echo "$title"
}

stop_gpg_agent() {
  echo_title "🔒 Stopping GPG agent"
  if [ -x "$(command -v gpgconf)" ]; then
    gpgconf --kill gpg-agent
  elif [ -x "$(command -v gpg-connect-agent)" ]; then
    gpg-connect-agent killagent /bye
  else
    echo "GPG tools not found, skipping GPG agent stop"
  fi
}

start_gpg_agent() {
  echo_title "🔑 Starting GPG agent"
  if [ -x "$(command -v gpg-agent)" ]; then
    gpg-agent --daemon
  elif [ -x "$(command -v gpgconf)" ]; then
    gpgconf --reload gpg-agent
  else
    echo "GPG tools not found, skipping GPG agent start"
  fi
}

backup_homebrew() {
  echo_title "🍻 Backing up Homebrew packages"
  brew bundle dump -f
  brew bundle --force cleanup
  brew upgrade
}

cd ~/ || exit
check_os
create_mackup_config
install_homebrew
if [ "$(uname)" == "Darwin" ]; then
  install_rosetta
fi
install_mackup

stop_gpg_agent
backup_homebrew
mackup backup --force
start_gpg_agent

Restore Script

This script will restore your dotfiles and system configuration from a Git repository, and install your Homebrew packages and applications from a Brewfile. It supports both macOS and Linux. To run the script:

chmod +x restore.sh # To make the script executable
./restore.sh

Run this script from your home directory on a new machine to restore your complete configuration.

#!/bin/bash

check_os() {
  if [ "$(uname)" != "Darwin" ] && [ "$(uname)" != "Linux" ]; then
    echo "This script is only for macOS and Linux"
    exit 1
  fi
}

install_homebrew() {
  if ! [ -x "$(command -v brew)" ]; then
    echo_title "🍺 Installing Homebrew"
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    (
      echo
      echo 'eval "$(/opt/homebrew/bin/brew shellenv)"'
    ) >>"$HOME"/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"
  fi
}

install_rosetta() {
  if ! [ -x "$(command -v arch)" ]; then
    echo_title "📄 Installing Rosetta 2"
    softwareupdate --install-rosetta --agree-to-license
  fi
}

echo_title() {
  local title=$1
  echo ""
  echo "$title"
}

sync_homebrew() {
  echo_title "🍻 Sync Homebrew packages"
  brew bundle cleanup --force
  brew bundle install --force
  brew upgrade
}

stop_gpg_agent() {
  echo_title "🔒 Stopping GPG agent"
  if [ -x "$(command -v gpgconf)" ]; then
    gpgconf --kill gpg-agent
  elif [ -x "$(command -v gpg-connect-agent)" ]; then
    gpg-connect-agent killagent /bye
  else
    echo "GPG tools not found, skipping GPG agent stop"
  fi
}

start_gpg_agent() {
  echo_title "🔑 Starting GPG agent"
  if [ -x "$(command -v gpg-agent)" ]; then
    gpg-agent --daemon
  elif [ -x "$(command -v gpgconf)" ]; then
    gpgconf --reload gpg-agent
  else
    echo "GPG tools not found, skipping GPG agent start"
  fi
}

cd ~/ || exit
check_os
install_homebrew
if [ "$(uname)" == "Darwin" ]; then
  install_rosetta
fi

stop_gpg_agent
sync_homebrew
mackup restore --force
start_gpg_agent

Benefits of Using MackUp

Easy to install and use
Supports a variety of storage providers
Supports symlinking dotfiles and system configuration
Supports restoring dotfiles and system configuration

Git, SSH, and GPG Keys

Git is the de facto standard for version control, and it is essential for any developer. Setting up Git with SSH and GPG keys is important for secure and authenticated commits.

Installing Git

Git can be installed using Homebrew:

brew install git

Configuring Git

After installing Git, you can configure your user settings:

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
git config --global core.editor nano

I also recommend enabling some useful Git settings:

# Enable auto-pruning on fetch
git config --global fetch.prune true

# Enable auto-stash on rebase
git config --global git.autoStash true

# Enable colored diff output with moved lines detection
git config --global diff.colorMoved zebra

Setting Up SSH Keys

SSH keys are used to authenticate with remote Git repositories. To generate a new SSH key:

# Generate an Ed25519 key (recommended)
ssh-keygen -t ed25519 -C "your-email@example.com"

# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your key to the agent
ssh-add ~/.ssh/id_ed25519

To use macOS Keychain for SSH key management, create or edit ~/.ssh/config:

Host *
  UseKeychain yes

This configuration ensures that your SSH passphrase is stored securely in the macOS Keychain, so you don’t have to enter it repeatedly.

Setting Up GPG Keys for Signed Commits

GPG signing adds an extra layer of trust to your commits. It verifies that commits are actually made by you.

First, install GPG and Pinentry for macOS:

brew install gnupg pinentry-mac

Generate a new GPG key:

gpg --full-generate-key

Configure GPG to use Pinentry for passphrase entry. Create or edit ~/.gnupg/gpg-agent.conf:

default-cache-ttl 600
max-cache-ttl 7200
pinentry-program /opt/homebrew/bin/pinentry-mac

Configure Git to use your GPG key:

# Get your key ID
gpg --list-secret-keys --keyid-format=long

# Configure Git to use your key
git config --global user.signingKey YOUR_KEY_ID
git config --global commit.gpgsign true
git config --global gpg.program /opt/homebrew/bin/gpg

Benefits of SSH and GPG

SSH Keys: Secure, passwordless authentication to Git remotes
GPG Signing: Cryptographic proof that commits are made by you
Keychain Integration: Secure storage of passphrases on macOS

Passwords and Secrets

Managing passwords and secrets securely is critical for any developer. I use a combination of tools to handle this.

Apple Notes with Locked Notes

For storing sensitive values, tokens, and keys, I use Apple’s built-in Notes app with locked notes. This approach is surprisingly effective and has several advantages:

Built-in to macOS: No additional software to install
iCloud Sync: Seamlessly syncs across all Apple devices
Password or Touch ID Protection: Notes can be locked and unlocked with your device password or biometrics
End-to-End Encryption: Locked notes are encrypted with your device passcode

To lock a note in Apple Notes:

Create or open a note
Click the lock icon in the toolbar (or right-click and select “Lock Note”)
Set a password if prompted (or use your device password)

This simple approach keeps my API tokens, SSH passphrases, and other sensitive values readily accessible but secure.

SOPS for Secret Management in Code

For managing secrets in code and configuration files, I use SOPS (Secrets OPerationS). SOPS encrypts secrets in YAML, JSON, and other formats while keeping the structure readable.

Install SOPS with Homebrew:

brew install sops

SOPS integrates well with GitOps workflows, allowing you to store encrypted secrets in Git repositories safely.

mkcert for Local Development Certificates

For local HTTPS development, mkcert is invaluable. It creates locally-trusted development certificates.

brew install mkcert

# Install the local CA
mkcert -install

# Create certificates for localhost
mkcert localhost 127.0.0.1 ::1

Configuring the Terminal

A well-configured terminal can significantly boost your productivity. Here’s how I set up mine.

Using Zsh

macOS comes with Zsh as the default shell. My .zshrc is kept simple and focused:

# Source shell integrations
source /opt/homebrew/opt/chruby/share/chruby/chruby.sh
source /opt/homebrew/opt/chruby/share/chruby/auto.sh
chruby ruby-3.4.1

# VS Code shell integration
[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code-insiders --locate-shell-integration-path zsh)"

# Initialize Starship prompt
eval "$(starship init zsh)"

Starship Prompt

Starship is a minimal, fast, and customizable prompt for any shell. It shows relevant information based on your current directory context (Git status, programming language versions, etc.).

Install Starship:

brew install starship

Add to your .zshrc:

eval "$(starship init zsh)"

Starship automatically detects your project type and shows relevant information without any additional configuration.

chruby for Ruby Version Management

For Ruby version management, I use chruby which is lightweight and simple:

brew install chruby ruby-install

# Install a Ruby version
ruby-install ruby 3.4.1

Benefits of This Terminal Setup

Minimal Configuration: Keep things simple and maintainable
Fast Startup: No heavy frameworks slowing down terminal launch
Context-Aware Prompts: Starship shows relevant info automatically
Easy Version Management: chruby for Ruby, similar tools for other languages

Setting Up Your IDE

Visual Studio Code (or VS Code Insiders in my case) is my editor of choice. Here’s how I configure it for maximum productivity.

Installing VS Code

brew install --cask visual-studio-code
# Or for the Insiders build:
brew install --cask visual-studio-code@insiders

Essential Settings

Here are some of the key settings from my configuration:

Font Configuration

I use the Monaspace font family with font ligatures enabled:

{
  "editor.fontFamily": "'Monaspace Krypton', monospace",
  "editor.fontLigatures": "'ss01', 'ss02', 'ss03', 'ss04', 'ss05', 'ss06', 'ss07', 'ss08', 'calt', 'dlig'",
  "editor.fontSize": 13,
  "terminal.integrated.fontFamily": "'Monaspace Krypton', monospace"
}

Install the font with Homebrew:

brew install --cask font-monaspace

Editor Behavior

{
  "editor.formatOnSave": true,
  "editor.formatOnSaveMode": "modificationsIfAvailable",
  "editor.tabSize": 2,
  "editor.rulers": [120],
  "editor.minimap.enabled": false,
  "editor.guides.bracketPairs": true,
  "editor.smoothScrolling": true,
  "editor.cursorBlinking": "smooth",
  "editor.cursorSmoothCaretAnimation": "on"
}

Git Integration

{
  "git.enableCommitSigning": true,
  "git.alwaysSignOff": true,
  "git.autofetch": true,
  "git.pruneOnFetch": true,
  "git.rebaseWhenSync": true,
  "git.branchProtection": ["master", "main", "trunk"]
}

File Explorer

{
  "explorer.fileNesting.enabled": true,
  "explorer.sortOrder": "type",
  "explorer.confirmDelete": false,
  "files.autoSave": "afterDelay"
}

Essential Extensions

Here are some of the extensions I use, categorized by purpose:

AI and Productivity

GitHub Copilot
GitHub Copilot Chat

Languages and Frameworks

Go (golang.go)
C# Dev Kit (ms-dotnettools.csdevkit)
Docker (ms-azuretools.vscode-docker)
Kubernetes Tools (ms-kubernetes-tools.vscode-kubernetes-tools)

Git and GitHub

GitHub Pull Requests and Issues
GitHub Actions

Code Quality

ESLint
Prettier
EditorConfig
Markdownlint
ShellCheck
Code Spell Checker

Markdown and Documentation

Markdown All in One
Markdown Preview GitHub Styles
Mermaid diagrams for Markdown

Remote Development

Remote - SSH
Remote Repositories

Theme and Icons

Vira Theme (my preferred dark theme)

EditorConfig for Consistent Formatting

I use EditorConfig to maintain consistent coding styles across different editors and IDEs:

.editorconfig

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

Benefits of This IDE Setup

Consistent Formatting: EditorConfig and format-on-save ensure consistent code
Integrated Git: Signed commits and branch protection built-in
AI Assistance: GitHub Copilot for intelligent code suggestions
Language Support: First-class support for Go, C#, TypeScript, and more

Remote Development

Modern development often involves working with remote machines, containers, and cloud environments. Here’s how I handle remote development.

VS Code Remote SSH

The Remote SSH extension allows you to develop on remote machines as if they were local:

# In VS Code, press Cmd+Shift+P and type:
# "Remote-SSH: Connect to Host..."

My SSH config (~/.ssh/config) is kept simple with Keychain integration:

Host *
  UseKeychain yes

Docker Desktop

Docker is essential for containerized development. Install it with:

brew install --cask docker-desktop

Docker provides:

Local Containers: Run applications in isolated environments
Kubernetes: Built-in single-node Kubernetes cluster for testing
VS Code Integration: Seamless integration with the Docker extension

Kubernetes Tools

For Kubernetes development, I use several tools:

# Kubernetes CLI
brew install kubernetes-cli

# Helm for package management
brew install helm

# Flux for GitOps
brew install fluxcd/tap/flux

# KSail for local cluster management (my own project!)
brew install devantler-tech/tap/ksail

Cloud CLIs

For cloud development, I have the major cloud provider CLIs installed:

# AWS CLI
brew install awscli

# Azure CLI (via kubelogin for AKS)
brew install kubelogin

# Hetzner Cloud CLI
brew install hcloud

Benefits of Remote Development

Consistent Environments: Docker ensures the same environment everywhere
Scalable Resources: Develop on powerful remote machines when needed
GitOps Workflows: Flux and other tools enable declarative infrastructure
Cloud-Native Development: First-class support for Kubernetes and cloud services

Conclusion

Setting up macOS as a developer machine requires thoughtful configuration, but the investment pays off in productivity and consistency. The key takeaways from my setup are:

Use Homebrew for package management — it’s reliable and comprehensive
Manage dotfiles with MackUp — keeps configurations in sync across machines
Secure your identity with SSH and GPG keys for authenticated commits
Invest in your terminal — a good prompt and shell configuration boosts productivity
Configure your IDE thoroughly — VS Code with the right extensions is incredibly powerful
Embrace remote development — Docker, Kubernetes, and cloud tools are essential for modern development

I hope this guide helps you set up your own macOS developer machine. Feel free to adapt these configurations to your own needs and preferences.

Welcome!

Wed, 24 Jul 2024 00:00:00 GMT

Hello everyone! Welcome to my site 👋🏻

I am Nikolai Emil Damm AKA Devantler. I am a software engineer with a strong passion for open-source, and I believe that working transparently and collaboratively is the best way to create high-quality software. I have been working in the software industry for many years, and I have experience in a wide range of technologies and domains.

I created this site to share my learnings and experiences with the broader community. I will be writing about software development, open-source, cloud computing, and other topics that I find interesting. I hope that you find my posts useful and informative, and I welcome any feedback or suggestions that you may have.

Peace ✌🏻

Nikolai Emil | Devantler | Blog

How I Run KSail Autonomously with GitHub Agentic Workflows

How I Think About Autonomy

The Pipeline: Six Agentic Workflows

How Autonomy Is Obtained

The Guardrails

My Role

What I’ve Learned

Closing

I Built an MCP Server into My Kubernetes CLI

What It Actually Exposes

Connecting It to Claude Desktop

How the Tools Are Generated

KSail Is Now in the MCP Registry

The Practical Trade-Off

Where to Find It

GitOps Without the Git Server: OCI Registries as a Flux Source with KSail

Prerequisites

Setting Up a Cluster with Flux

Pushing Manifests

How Registry and Tag Resolution Works

Extending to GHCR for CI

What About workload watch?

A Note on Secret Management

Storing Sensitive Values in .zshrc with macOS Keychain

Store a Secret

Retrieve a Secret

Use It in .zshrc

Summary

Building an AI Assistant for Kubernetes with GitHub Copilot SDK

See It in Action

Motivation

The Tech Stack

GitHub Copilot SDK for Go

Bubbletea TUI Framework

Glamour for Markdown Rendering

Architecture Overview

Auto-Generated Tools from Cobra Commands

Embedded Documentation Context

Security Boundaries for File Operations

User Experience Polish

Building with AI Assistance

The Image Snapshot Workflow

Iterating on TUI Design

Technical Decisions and Trade-offs

Per-Turn Subscription Pattern

Context Cancellation Challenges

Tool Result Ordering

What’s Next

Creating Kubernetes Clusters on Hetzner with KSail and Talos

Why Hetzner + Talos + KSail?

Step 1: Create a Hetzner Account

Step 2: Create a Hetzner Project

Step 3: Generate an API Token

Step 4: Export the API Token

Step 5: Install KSail

Step 6: Scaffold Your Cluster Project

Step 7: Create the Cluster

Step 8: Working with Your Cluster

Step 9: Deploying Workloads

Option A: Direct kubectl Workflow

Option B: GitOps with External Registry

Cleaning Up

Cost Considerations

What’s Next

Planned: Production-Grade Features

Feedback Welcome

A Note on Cloud Provider Support

AI-Powered GitHub Issues: How I Use Copilot with Claude Opus 4.5 to Create Impactful Issues

The Problem with Traditional Issue Creation

My AI-Assisted Workflow

Step 1: Select the Context

Step 2: Prompt with Intent and Reference Templates

Step 3: Review and Refine

Structured Templates Are Key

Bug Reports

Feature Requests

Improvement Katas

A Real Example: From Prompt to Issue

What I Typed

What About `workload watch`?