# Debug Grpc Connection

Diagnose gRPC connection issues between the Bindu core and a language SDK.

- Repository: https://github.com/GetBindu/Bindu (10015 stars)
- Category: AI and agents
- License: see repository
- Last updated: 2026-09-06
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add GetBindu/Bindu --skill debug-grpc-connection -g -a claude-code -y`
Codex: `npx skills add GetBindu/Bindu --skill debug-grpc-connection -g -a codex -y`
Cursor: `npx skills add GetBindu/Bindu --skill debug-grpc-connection -g -a cursor -y`
Gemini CLI: `npx skills add GetBindu/Bindu --skill debug-grpc-connection -g -a gemini-cli -y`

## Description

Diagnose gRPC connection issues between the Bindu core and a language SDK. Use when an SDK fails to register, HandleMessages calls time out, "connection refused" on :3774, heartbeats stop arriving, or the core logs "agent silently died".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debug gRPC Connection

## Overview

The Bindu core (Python) runs a gRPC server on port `3774` that SDKs connect to via `RegisterAgent` and `Heartbeat`. After registration, the core calls back into the SDK's own gRPC server (ephemeral port) via `HandleMessages`. Most connection bugs are in that handshake.

See [docs/grpc/overview.md](../../../docs/grpc/overview.md) for the full message flow and [docs/grpc/limitations.md](../../../docs/grpc/limitations.md) for known unimplemented behaviors.

## Inputs

- Which end is reporting the failure: core logs vs. SDK logs.
- The exact error message and/or symptom.
- Recent commits touching `proto/`, `bindu/grpc/`, or `sdks/typescript/src/`.

## Safety

- Do not modify files under `bindu/grpc/generated/` or `sdks/typescript/src/generated/` to "make the error go away". Proto drift is the underlying problem, fix it with the `regenerate-grpc-stubs` skill.
- Do not bypass the heartbeat mechanism. The core relies on heartbeats to clean up dead-agent registrations.
- Do not assume the SDK is at fault before inspecting core logs, the core is the ground truth for registration state.

## Execution Contract

1. Confirm both processes are alive and bound to expected ports.
2. Inspect core logs for the registration handshake.
3. Probe the core directly with `grpcurl`.
4. Check for proto drift.
5. Verify SDK heartbeat timing.
6. Consult limitations doc before filing a bug.

## Steps

### 1. Confirm both processes and ports

```bash
lsof -ti:3773 -ti:3774
ps aux | grep -E '(bindu|node.*agent|python.*bindu)' | grep -v grep
```

- `3773` missing → HTTP/A2A server never started. Check for port clash (`lsof -i:3773`).
- `3774` missing → core started without `--grpc`. Restart with `bindu serve --grpc`.
- SDK process missing → it crashed. Check its own logs for a stacktrace.

### 2. Inspect core logs

Filter for the `[bindu-core]` prefix. Meaningful signals:

The rest: https://github.com/GetBindu/Bindu/blob/HEAD/.agents/skills/debug-grpc-connection/SKILL.md