Rapid Local Debugging with Signadot & Claude Code

Prerequisites

• Signadot CLI v1.4.0+: Required for MCP support. Run signadot version to check.
• Go 1.21+: The demo application (HotROD) requires log/slog. Build will fail on older versions.
• Kubernetes Cluster: You can use any cluster (EKS, GKE, Kind), but this tutorial uses Minikube.
• Signadot Account: An active account at signadot.com.
• Claude Code CLI: Claude Code installed and configured.

Overview

Testing local microservice changes against a shared Kubernetes cluster often involves a mess of kubectl port-forward commands, brittle mocks, or waiting for CI/CD pipelines just to verify a one-line change.

In this tutorial, we will establish a workflow for local debugging using Signadot and Claude Code (the AI-powered CLI). By installing the Signadot MCP (Model Context Protocol) server, you can instruct Claude Code's agent to "spin up a sandbox" that routes traffic from a shared cluster to a service running locally on your personal computer, all via natural language in your terminal.

Baseline Setup (HotROD)

First, we establish the baseline environment. We will use the "HotROD" demo application.

Start the Cluster & Install Operator

Start your local cluster and install the Signadot Operator.

Minikube

minikube start

Follow the install instructions found in your Signadot Dashboard under Clusters → Connect. The dashboard will show you the commands to run.

Other Clusters

Ensure your kubectl context is set to your target cluster:

kubectl config get-contexts  # List available contexts
kubectl config use-context <your-cluster-context>  # Switch to your cluster

Follow the install instructions found in your Signadot Dashboard under Clusters → Connect.

You can verify the cluster connection in the Signadot web dashboard:

Verify Signadot CLI is installed:

signadot --version

Install the HotROD Baseline

Deploy the demo microservices into the hotrod namespace.

kubectl create ns hotrod || true
kubectl -n hotrod apply -k 'https://github.com/signadot/hotrod/k8s/overlays/prod/devmesh'

Verify that the baseline pods are running:

kubectl -n hotrod get pods

⏱️ Wait for pods to be ready: All pods must reach Running status with 1/1 ready before proceeding. This can take 2-5 minutes while images are pulled. Use kubectl -n hotrod get pods -w to watch progress.

Step 1: Local Connect (Required)

To route traffic from the cluster to your laptop, we use signadot local connect. This step must be completed and running before proceeding to Step 3.

Authenticate Signadot CLI

If you haven't already authenticated:

signadot auth login

The CLI will open your browser for authentication.

Configure Local Connect

Create or edit your config file at ~/.signadot/config.yaml:

~/.signadot/config.yaml

local:
  # Use a benchmarking CIDR to avoid conflicts with home/office Wi-Fi
  virtualIPNet: 198.18.0.1/16
  connections:
    - cluster: claude-signadot  # Use your actual cluster name from 'signadot cluster list'
      # Force PortForward for stability on Minikube
      type: PortForward
      kubeContext: minikube

Find Your Cluster Name

Run signadot cluster list to see your registered cluster name. Replace claude-signadot above with your actual cluster name.

Connect to the Cluster

Run this command as your normal user (do not use sudo):

signadot local connect --cluster claude-signadot

The process will run in the background. You'll be prompted for your password when it needs to update /etc/hosts.

Gate Check: Verify Routing

Before proceeding to Step 3, we must prove the tunnel is working. If this check fails, the sandbox will not work.

Run this in your terminal:

curl -I http://frontend.hotrod.svc:8080

• HTTP 200 OK: ✅ Proceed to Step 2.

• Hang/Timeout: ❌ Stop. Your virtualIPNet configuration in Step 1 is likely conflicting. Change the CIDR in ~/.signadot/config.yaml and reconnect.

Keep Local Connect Running

The signadot local connect process must remain running for the duration of your debugging session. Do not interrupt the process.

Step 2: Setup Claude Code MCP

Bridge Claude Code to the Signadot CLI so the AI agent can control Signadot via natural language.

Install Claude Code

If you haven't already installed Claude Code:

curl -fsSL https://claude.ai/install.sh | bash

Add Signadot MCP Server

Configure Claude Code to use the Signadot MCP server:

claude mcp add --transport stdio signadot -- signadot mcp

This command:

• Adds the signadot MCP server to Claude Code's configuration
• Configures it to use stdio transport
• Points to the signadot mcp command

Verify MCP Connection

Verify the Signadot MCP server is connected:

claude mcp list

Launch Claude Code

Start Claude Code for the first time:

claude

First-time authentication flow:

The CLI will open your browser for OAuth authentication:

After authorizing in the browser:

Return to your terminal to see the login confirmation:

Press Enter to continue into Claude Code.

For detailed setup instructions, see the Claude Code Setup Documentation.

Step 3: The Workflow

Prerequisite

Ensure Step 1 (Local Connect) is running and healthy before starting this workflow. The signadot local connect process must be running in the background.

We will now use Claude Code to drive the infrastructure via natural language in the terminal.

Navigate to HotROD Repository

git clone https://github.com/signadot/hotrod
cd hotrod

Launch Claude Code

claude

When launching in a new workspace, you'll see a security prompt:

Choose to trust the workspace. You'll then see the main dashboard:

Prompt 1: Sanity & Cleanup

We want a clean slate to avoid state conflicts from previous sessions.

Prompt:

Check my Signadot setup, then clean up anything from earlier runs.

Claude Code will propose using the Signadot MCP tools:

If no cluster is connected yet, you'll see:

Once your cluster is connected (from Step 1), the status will show:

Prompt 2: Create the Sandbox

We want to debug the route service locally on port 8083.

Prompt:

Create a local-dev sandbox called local-route-dev that maps hotrod/route (Deployment) port 8083 to my localhost:8083, then apply it.

Claude Code will automatically:

1. Read the Signadot workflow documentation

2. Generate the sandbox specification

3. Show you the YAML before applying

4. Create the sandbox via the MCP tool

Prompt 3: Run & Verify

Finally, we run our local code. We need the local process to have access to the cluster's environment variables (database credentials, feature flags, etc.).

Prompt:

Start the local route service with the sandbox env, then show me one curl command that verifies routing using the sandbox routing key.

Claude Code will provide you with commands to:

1. Inject the cluster context into your shell:

eval $(signadot sandbox get-env local-route-dev)

2. Start your local service:

go run ./cmd/hotrod/main.go route

Keep this running in a separate terminal.

3. Verify the local service is listening:

lsof -i :8083

Step 4: Verification

To prove the setup works, let's verify routing to your local service.

Option A: grpcurl Method

Claude Code provides a grpcurl command with the baggage header acting as the routing key:

The response shows your local service is handling requests, with logs confirming traffic went through the local-route-dev sandbox.

Option B: Browser Extension (Visual)

If you prefer a UI flow:

1. Install the Signadot Chrome Extension.

2. Log in and select your sandbox (local-route-dev) from the dropdown.

3. Visit http://frontend.hotrod.svc:8080. The extension will automatically inject the routing headers.

Option C: Modify Code and Re-verify

1. Modify Code: Open cmd/route/main.go and change the ETA calculation from Minutes to Seconds. Save the file.

2. Restart Service: Stop and restart your local go run process.

3. Test Again: Run the grpcurl or curl command again to see the modified response.

Troubleshooting

If you get stuck, check these common issues we identified during testing:

Connection Timed Out on .svc addresses

If curl http://frontend.hotrod.svc:8080 hangs or .svc resolves to an IP but times out, your machine is likely routing the default virtual IP range to your internet gateway. This is more common with Minikube when using VPNs or office Wi-Fi.

Fix: Edit ~/.signadot/config.yaml and change virtualIPNet to 198.18.0.1/16, then restart local connect.

Authentication Failed / Keyring Errors

If you see "Failed to unlock correct collection" or "No authentication found", you likely ran sudo signadot local connect.

Fix: Run signadot local connect as your normal user. Only provide the sudo password when the CLI prompts you for it.

Go Build Failures

If go run fails with package log/slog is not in GOROOT, your Go version is too old.

Fix: Install Go 1.21 or higher and ensure your $PATH lists the new Go version first.

Cluster Not Found Error

If you get Error: no such cluster "hotrod-test", your cluster is registered with a different name.

Fix: Run signadot cluster list to see your actual cluster name, then update ~/.signadot/config.yaml to use that name.

Pods Still Creating After 10 Minutes

If HotROD pods are stuck in ContainerCreating for >10 minutes, there may be image pull issues.

Fix: Check pod events with kubectl -n hotrod describe pod <pod-name> and look for errors in the Events section.

Conclusion

In this tutorial, you have successfully replaced a complex workflow of YAML editing, port-forwarding, and manual config injection with a streamlined setup and natural language prompts via Claude Code's terminal interface. You learned how to:

1. Configure and connect to the cluster with stable PortForwarding configuration.

2. Install Claude Code MCP to bridge the AI agent with Signadot CLI.

3. Clean the environment using Claude Code's AI agent.

4. Create a routing sandbox that maps cluster services to your local machine.

5. Inject cluster context into your local process for seamless debugging.

This workflow enables rapid iteration on microservice changes without the overhead of traditional port-forwarding or waiting for CI/CD pipelines.

See Also

• Signadot MCP Documentation
• Claude Code Setup Documentation
• Claude Code MCP Integration
• Local Development Guide
• Troubleshooting Guide
• Cursor + Signadot Tutorial (GUI alternative)