Skip to content
Recipes Ecosystem Source Code Docs

Troubleshoot a Remote Server

When a production server misbehaves, you need a diagnosis in minutes, not hours. OpenCode can read the relevant logs, cross-reference them with recent changes, and propose a fix — all while you stay in control of the box.

When to use this recipe

  • A service is up but slow, erroring, or returning 5xx intermittently.
  • Logs are large and you don’t know which subsystem is the source.
  • You need to act on a fix but want a second opinion before restarting anything.

Prerequisites

  • OpenCode installed on your local machine.
  • SSH access to the affected server.
  • Read-only access to the relevant logs and config files.

Steps

  1. Define the symptom precisely

    In one paragraph, state what’s wrong, when it started, and what you’ve already ruled out.

    The checkout service has been returning 504s to about 3% of requests since 14:00 UTC today. Latency p99 went from 800ms to 6s. No deploys in the last 6 hours. CPU and memory on the app nodes are normal. I haven’t restarted anything yet.

  2. Pull the relevant logs

    Ask OpenCode to fetch the right slice of logs and surface anomalies.

    SSH to the prod-app cluster (creds in 1Password). Pull the last 2 hours of the checkout service’s stdout and stderr. Surface any error patterns, stack traces, or unusual latency spikes. Don’t include normal traffic.

  3. Correlate with recent changes

    Even when no deploys happened, infra changes can still matter.

    Check our infra changes in the last 24 hours (Terraform, ingress, DNS). Cross-reference each change with the timing of the latency increase.

  4. Form a hypothesis

    Ask OpenCode to propose the most likely cause and how to verify it.

    Based on the logs and infra changes, give me a ranked list of the top 3 hypotheses for the latency increase. For each, tell me what evidence supports it and what one command I could run to confirm or rule it out.

  5. Verify without disruption

    Use the lowest-impact verification path first. Never jump to a restart.

    # Example: check if a downstream is timing out
curl -w '%{time_total}\n' -o /dev/null -s https://internal.api/ping

  6. Apply the smallest safe fix

    Once verified, make the smallest change that resolves the issue. If the fix is risky, propose it to a teammate first.

    Given that hypothesis #2 is now confirmed, propose the smallest safe change. Tell me the exact command(s), what to monitor in the next 10 minutes, and the rollback plan.

  7. Write a post-incident note

    Even for a small incident, capture what happened, why, and what to change.

    Write a 1-page post-incident note to incidents/2026-06-27-checkout-504.md with: timeline, root cause, mitigation, and one preventive measure (alert, runbook, test, or refactor).

Key prompt

SSH to [host] with the credentials in [vault path]. Pull the last [N hours] of [service] logs and surface error patterns, stack traces, and latency anomalies. Then check our infra changes in the same window. Give me a ranked list of the top 3 hypotheses for [symptom] — for each, the supporting evidence and one verification command. Don’t run anything destructive.

Verify

  • A clear root cause is identified and documented.
  • The fix is applied and metrics return to baseline.
  • A post-incident note is written and shared with the team.
  • If alerts were missing, file a follow-up to add them.

Common pitfalls

  • Restarting first: A restart can hide evidence and cause a second incident. Always diagnose before acting.
  • Single log file: A symptom often spans multiple logs. Pull from all of them, not just the obvious one.
  • Skipping the post-incident: Without a writeup, the same incident will recur in 3 months.

Next up