Install byteport-agent
on your infra.

Pick your install method. Helm is recommended for Kubernetes clusters. npm is for Node.js environments or local testing.

curl -fsSL https://byteport.polsia.app/install.sh | sh

# Add repo and fetch latest index
helm repo add byteport https://byteport.polsia.app/charts
helm repo update

# Install into its own namespace (dry-run on by default)
helm install byteport byteport/byteport-agent \
  --namespace byteport-agent \
  --create-namespace

kubectl get pods -n byteport-agent -w
kubectl logs -n byteport-agent \
  -l app.kubernetes.io/name=byteport-agent \
  --tail=30 -f

# Install globally
npm install -g byteport-agent@v0.1.30

# Or add to your project
npm install byteport-agent@v0.1.30

# Dry-run on by default; set env vars before starting
BYTEPORT_DRY_RUN=true byteport-agent start

Pick the monitoring backend you already have. Click a card to see the wiring snippet. One adapter is enough to start — add more later.

BYTEPORT_ADAPTER=sentry
SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

helm upgrade byteport byteport/byteport-agent \
  --set adapter=sentry \
  --set sentry.authToken=<your-sentry-auth-token> \
  --set sentry.org=your-org \
  --set sentry.project=your-project

BYTEPORT_ADAPTER=cloudwatch
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...      # or instance profile / IRSA
AWS_SECRET_ACCESS_KEY=...

helm upgrade byteport byteport/byteport-agent \
  --set adapter=cloudwatch \
  --set cloudwatch.region=us-east-1

BYTEPORT_ADAPTER=prometheus
PROMETHEUS_URL=http://localhost:9090

helm upgrade byteport byteport/byteport-agent \
  --set adapter=prometheus \
  --set prometheus.url=http://prometheus-operated.monitoring.svc:9090

BYTEPORT_ADAPTER=github-actions
GITHUB_TOKEN=ghp_...
GITHUB_REPO=yourorg/infra

helm upgrade byteport byteport/byteport-agent \
  --set adapter=github-actions \
  --set githubActions.repo=yourorg/infra \
  --set githubActions.token=<github-pat-or-app-token>

BYTEPORT_ADAPTER=pagerduty
PAGERDUTY_API_TOKEN=u+abcXYZ...
PAGERDUTY_SERVICE_IDS=SVC001,SVC002  # optional

helm upgrade byteport byteport/byteport-agent \
  --set adapter=pagerduty \
  --set pagerduty.apiToken=<your-pd-api-token> \
  --set pagerduty.subdomain=your-subdomain \
  --set pagerduty.fromEmail=ops@yourcompany.com

BYTEPORT_ADAPTER=datadog-monitors
DD_API_KEY=your-datadog-api-key
DD_APP_KEY=your-datadog-app-key
DD_SITE=api.datadoghq.com

helm upgrade byteport byteport/byteport-agent \
  --set adapter=datadog-monitors \
  --set datadogMonitors.site=api.datadoghq.com \
  --set datadogMonitors.apiKeySecretRef.name=byteport-datadog-monitors-secret \
  --set datadogMonitors.apiKeySecretRef.key=DD_API_KEY \
  --set datadogMonitors.appKeySecretRef.name=byteport-datadog-monitors-secret \
  --set datadogMonitors.appKeySecretRef.key=DD_APP_KEY

BYTEPORT_ADAPTER=grafana-alerting
GRAFANA_URL=http://grafana.monitoring.svc:3000
GRAFANA_API_TOKEN=glsa_...
GRAFANA_WEBHOOK_SECRET=your-hmac-secret  # optional

helm upgrade byteport byteport/byteport-agent \
  --set adapter=grafana-alerting \
  --set grafanaAlerting.url=http://grafana.monitoring.svc:3000 \
  --set grafanaAlerting.apiToken=<your-grafana-api-token>

View all 12 integrations →  ·  Don't see your tool? Request an integration →

Where should BytePort notify you when a runbook fires? Enter one or both, or skip for now — logs are always written to stdout.

Fire a synthetic disk_pressure signal and watch the runbook in the agent log. No mutations will happen — dry-run is still on. Link: full runbook library →

# If you installed via npm globally:
byteport test --signal disk_pressure

# Or trigger via HTTP if running as a service:
curl -X POST http://localhost:3001/api/test-signal \
  -H 'Content-Type: application/json' \
  -d '{"type":"disk_pressure","value":91.2,"host":"verify-test"}'

[byteport] signal=disk_pressure host=verify-test value=91.2% threshold=85% severity=warning
[byteport] runbook=disk_pressure action=PROPOSED steps=3 confidence=0.94
[byteport] dry_run=true action=SKIPPED reason=dry_run_enabled
[byteport] notifier=slack status=sent event=escalation.required
[byteport] escalation=github status=opened issue_url=https://github.com/your-org/infra/issues/42

What you'll see in 60 seconds

Within 30 seconds of the pod reaching Running, heartbeat logs appear. If there's active pressure in your cluster, detections show up too.

[byteport] adapter=prometheus dry_run=true status=watching
[byteport] cycle=1 signals_checked=4 detections=0 duration_ms=142
[byteport] cycle=2 signals_checked=4 detections=0 duration_ms=138

Promote to production

Run through this checklist before setting dryRun: false. Enable one runbook at a time and let it run cleanly for 48 hours before adding the next.

• Pick your adapter and verify signal data appears in logs (detections=N)
• Review a dry-run detection — open the GitHub Issue it filed and confirm the proposed action makes sense for your cluster
• Scope RBAC — annotate only the namespaces you want the agent to touch:
  bashCopy

  kubectl annotate namespace production \
    byteport.io/allow-remediation=true \
    byteport.io/allow-rollback=true

• Enable runbooks one at a time — start with the safest (disk_pressure won't delete pods):
  bashCopy

  helm upgrade byteport byteport/byteport-agent \
    --set dryRun=false \
    --set runbooks.allow[0]=disk_pressure

• Wire Postmark for email on escalation:
  bashCopy

  kubectl create secret generic byteport-postmark \
    -n byteport-agent \
    --from-literal=POSTMARK_SERVER_TOKEN=<your-token>
  
  helm upgrade byteport byteport/byteport-agent \
    --set escalation.postmark.enabled=true \
    --set escalation.postmark.serverTokenSecretRef.name=byteport-postmark \
    --set escalation.postmark.to=oncall@yourcompany.com

• Tune thresholds if the defaults (85% disk / 90% memory) don't match your SLOs:
  bashCopy

  helm upgrade byteport byteport/byteport-agent \
    --set thresholds.diskUsagePct=80 \
    --set thresholds.memoryPressurePct=88

• Add a second runbook after the first has run cleanly for 48 hours. pod_crashloop is a good second choice.

Available runbooks

All 8 runbooks ship with the chart. Enable them one at a time via runbooks.allow.

Troubleshooting

Most issues fall into one of these buckets. Click to expand.

Uninstall

RBAC (ClusterRole + ClusterRoleBinding) is removed automatically with the release.

helm uninstall byteport -n byteport-agent
kubectl delete namespace byteport-agent