Rapid Local Debugging with Signadot & Cursor

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.
• Cursor IDE: Cursor installed with MCP support enabled.

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 Cursor (the AI IDE). By installing the Signadot MCP (Model Context Protocol) server, you can instruct Cursor'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.

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:

After running the commands, you should see success in your terminal:

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. The dashboard will show you the commands to run:

After running the commands, you should see success in your terminal:

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

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.

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: hotrod-test
      # Force PortForward for stability on Minikube
      type: PortForward
      kubeContext: minikube

Confirm your cluster is registered by running signadot cluster list and checking for 'hotrod-test'.

Authenticate your CLI:

signadot auth login

The CLI will open your browser for authentication. You'll see a waiting state in the terminal:

Complete the authentication in your browser:

Once authentication completes in the browser, the CLI receives the callback and shows success:

Connect to the Cluster

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

signadot local connect --cluster hotrod-test

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 3.

• Hang/Timeout: ❌ Stop. This may be due to a virtualIPNet CIDR conflict with your VPN or network configuration. See advanced configuration options to adjust your network settings.

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 Cursor MCP

Bridge the IDE to the CLI so the AI Agent can control Signadot.

1. Click the button below to automatically install the Signadot MCP server in Cursor:

Install in Cursor

Alternatively, you can visit the Signadot MCP Cursor documentation page.

2. Fallback: If the link doesn't work, manually edit ~/.cursor/mcp.json:

~/.cursor/mcp.json

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

Verify the installation in Cursor Settings > Features > MCP.

For detailed setup instructions, see the Signadot MCP Cursor guide.

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 Cursor to drive the infrastructure.

1. Open the HotROD repository in Cursor: git clone https://github.com/signadot/hotrod

2. Open Cursor Chat (Cmd+L or Ctrl+L).

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."

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."

Cursor will automatically generate the correct YAML schema for the sandbox and apply it to the cluster 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."

Cursor will show you the commands to run:

1. eval $(signadot sandbox get-env ...) to inject the cluster context into your shell.

2. go run ./cmd/hotrod/main.go route (or equivalent) to start your local service.

3. A grpcurl command with the baggage header to verify routing to your local service.

Step 4: Verification

To prove the setup works, let's modify the code and see the result instantly.

1. Modify Code: Open cmd/route/main.go (or the relevant service logic) and change the ETA calculation from Minutes to Seconds. Save the file.

2. Verify: Use the header method to route a request specifically to your local machine.

Option A: The Header Method (Programmatic)

Since the route service uses gRPC, Cursor will provide a grpcurl command (not curl) to test the sandbox routing. The baggage header acts as the routing key. This is the most reliable method for local verification.

Example command Cursor might provide:

grpcurl -plaintext -H 'baggage: sd-routing-key=<YOUR_KEY>' \
  route.hotrod.svc:8083 route.RouteService/GetRoute \
  -d '{"from": "37.7749, -122.4194", "to": "37.7849, -122.4094"}'

You should see a successful response, proving the request hit your local service.

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.

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.

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. You learned how to:

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

2. Clean the environment using Cursor's AI agent.

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

4. 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
• Cursor Model Context Protocol
• Local Development Guide
• Troubleshooting Guide