Getting Started Guide

From invite link to your first automated PR.

PodPulse detects Kubernetes incidents, analyzes root causes with AI, and opens pull requests with proposed fixes — automatically.

Time to complete
~15 minutes
Access required
Read-only on cluster
Prerequisites
Kubernetes + GitHub repo
What you will do
1 Create your account from your invitation link 2 Connect your GitHub repository 3 Copy your API key 4 Deploy the PodPulse agent in your Kubernetes cluster 5 Watch incidents get detected and pull requests get opened
1

Create your account

You received an invitation link. Open it in your browser:

Invitation URL
https://app.podpulse.io/register?token=<your-invitation-token>

The link pre-validates your invitation and takes you directly to the account creation form. Enter your email address and choose a password (minimum 8 characters). Once you click Create account, you are automatically signed in and redirected to your dashboard.

Account creation form — pre-filled with your invitation token
Account creation form — pre-filled with your invitation token.

Your personal dashboard is empty at this point — incidents will appear here once the agent is running.

2

Connect your GitHub repository

Navigate to Settings using the profile icon in the top-right corner. In the GitHub Integration section, click Connect GitHub App.

Settings before GitHub connection
Settings before GitHub connection — click Connect GitHub App to proceed.

GitHub will ask you to:

1.
Select the organization or personal account where your Kubernetes manifests live
2.
Choose the repository PodPulse should open pull requests against
3.
Confirm the installation — GitHub redirects you back to Settings automatically

After the redirect, Settings shows your connected repository with a green status indicator.

Settings after GitHub connection
Settings after GitHub connection — repository shown as connected, API key active.
3

Copy your API key

When GitHub redirects you back to Settings, a green banner displays your API key in full — this is the only time it will ever be shown. Copy it immediately and store it securely (password manager or secrets vault).

Your API key is shown exactly once. If you lose it, go to Settings → API Key → Regenerate. The old key is immediately revoked and your agent will stop sending data until reconfigured.

Your API key looks like this:

API key format
pp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
4

Deploy the PodPulse agent in your cluster

The PodPulse agent is an open-source Go binary that runs inside your cluster. It requires read-only Kubernetes permissions only — it never modifies any cluster resource. Install it via Helm in two commands:

Add the PodPulse Helm repository

Shell
helm repo add podpulse https://charts.podpulse.io

Install the agent

Shell
helm install podpulse-agent podpulse/podpulse-agent \ --set config.apiKey=pp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \ --namespace podpulse --create-namespace

Permissions granted to the agent

Resource Permissions Purpose
pods, pods/log get, list, watch Detect incidents, collect logs
events get, list, watch Capture Kubernetes events
nodes get, list, watch Identify affected node
deployments, replicasets get, list, watch Resolve workload context
secrets none Never accessed

The agent communicates outbound only — to the PodPulse backend via gRPC. No inbound ports are opened. No Kubernetes Secrets are ever read or transmitted.

Verify the agent is running

Shell
kubectl get pods -n podpulse
Expected output
podpulse-agent-xxxx 1/1 Running 0 <age>
5

Watch incidents get detected and pull requests get opened

Once the agent is running, it immediately starts monitoring your cluster. When a pod fails — OOMKilled, CrashLoopBackOff, or other supported patterns — the full pipeline runs automatically within seconds:

→
Agent detects
Pod lifecycle event observed in real time
→
Context built
Logs, events, and pod state assembled — no secrets included
→
AI diagnoses
Claude analyzes root cause and generates a proposed fix with a confidence score
→
PR opened
If confidence exceeds the threshold, a pull request is opened on your repository
→
Dashboard updated
Incident appears in your dashboard in real time via live push
Live diagnostics queue
Live diagnostics queue — incidents detected, diagnosed, and promoted to pull requests in real time.
AI diagnostic — incident detail
Structured AI diagnostic with detection summary, root cause hypothesis, and proposed fix.
Automated pull request on GitHub
Pull request opened automatically by podpulse[bot] — review and merge when ready.
PodPulse never applies changes directly to your cluster. Every fix is a pull request. Your team decides what gets merged.
?

Troubleshooting

Agent pod is not Running

Check the API key is correctly set:

kubectl describe pod -n podpulse

Look for authentication errors in the logs:

kubectl logs -n podpulse -l app=podpulse-agent
No incidents appear in the dashboard

The agent only reports incidents matching supported patterns (OOMKilled, CrashLoopBackOff). Verify your pods are actually failing and that the agent pod is in Running state.

Pull requests are not opened

Check the GitHub integration in Settings. The GitHub App must be connected before any PR can be created. Low-confidence detections surface as insights only — no PR is opened below the threshold.

Need to regenerate your API key

Go to Settings → API Key → Regenerate. Your old key is immediately revoked. Update the agent:

helm upgrade podpulse-agent podpulse/podpulse-agent \ --set config.apiKey=pp_live_new_key \ -n podpulse
podpulse.io app.podpulse.io GitHub ↗