DEV Community: Shuaipeng Guo

Debugging an nginx 502 with an AI assistant next to your terminal

Shuaipeng Guo — Tue, 20 Oct 2026 13:07:27 +0000

It's 3 AM, the pager goes off, and the site is answering every request with 502 Bad Gateway. You know the drill: SSH in, read the nginx error log, check the upstream, check the port, check memory. None of it is hard. Doing it half-asleep, without skipping a step, is.

This post walks through that triage the way I now do it in AI-SSH-Pro, an open-source SSH desktop client with an AI assistant docked next to the terminal. The idea is simple: the assistant reads output, proposes the next command and explains it. You decide what actually runs.

Website: https://guoshuaipeng.github.io/ai-ssh-pro/
Download: https://github.com/guoshuaipeng/ai-ssh-pro/releases

Screenshots use the English UI and the built-in demo host, so all data is simulated. Some sample AI replies in the demo are in Chinese.

A quick refresher: what a 502 actually means

nginx returns 502 when it is acting as a reverse proxy and gets no valid response from the upstream. In practice it is almost always one of these:

What you see in `error.log`	Usual cause
`connect() failed (111: Connection refused)`	The upstream process (php-fpm, a Node or Java app) is down, or listening on a different port
`connect() to unix:/run/php/php-fpm.sock failed (2: No such file or directory)`	Socket path in nginx config doesn't match php-fpm's `listen`
`upstream prematurely closed connection`	The app crashed mid-request, often OOM-killed
`upstream sent too big header`	Response headers exceed `proxy_buffer_size`

So the job is: find which line you have, then find why.

Step 1: describe the symptom, get read-only commands back

Connect to the web host, open the AI panel on the right and just type what you see, e.g. "nginx on web-01 returns 502, help me check".

The panel is bound to the terminal tab you're in, so the assistant knows which host it is talking about. A good first answer is a short explanation plus a couple of safe, read-only commands:

systemctl status nginx --no-pager
sudo tail -n 50 /var/log/nginx/error.log

Each suggested command shows up in a compact block with Copy / Run and a risk label (low / medium / high). Both of these are read-only, so they're labelled low.

If the log shows Connection refused, you already know the upstream isn't answering. That one line saves a lot of guessing.

Step 2: follow the thread

Next questions write themselves: is the upstream running, is it listening where nginx expects, did the kernel kill it?

sudo ss -ltnp | grep -E ':(80|443|8080|9000)\b'
systemctl status php-fpm --no-pager      # or your app's unit
sudo journalctl -k --since "1 hour ago" | grep -i -E "oom|killed process"

Instead of reading raw ps output yourself, you can ask "list the top processes by memory". In the screenshot above the assistant proposes:

ps aux --sort=-%mem | head -n 11

It's labelled Risk: low, and because it's read-only it ran right away under the tab's policy ("Ran automatically under the AI execution policy"). The reply then summarizes the output: which process is using the most memory, how much, and whether it's something you should touch.

If you'd rather paste context than describe it, the input row has a button to attach terminal output to your question, so the assistant reads exactly what you're looking at.

Step 3: the fix is a change, so you approve it

Once the cause is clear, the fix usually mutates the host: restart the upstream, correct the socket path, bump a buffer, reload nginx.

sudo nginx -t && sudo systemctl reload nginx
sudo systemctl restart php-fpm

This is where the execution policy matters. AI-SSH-Pro has three levels:

Policy	What happens
Suggest only	Read-only commands run; changes are shown as suggestions only
Confirm before run (default)	Read-only commands run; changes need your confirmation; high-risk needs a second confirmation
Auto run	Low- and medium-risk commands run automatically; high-risk still asks

You set it globally in Settings → AI, per host on the host's Safety card, or for the current tab only from the policy menu in the input row. The tab override is in memory only and resets on disconnect.

For an incident on a real web node, Confirm before run is the sweet spot: diagnostics flow without friction, and nothing restarts until you click.

Guardrails that matter at 3 AM

Tired people make mistakes, so a few safety nets are built in rather than left to discipline:

Production banner. Hosts marked Production show a red banner on the tab, and dangerous commands require typing the host name.
Read-only hosts are enforced in the main process. If a host is marked Read-only, the AI cannot write to its terminal, even if you click approve. The check happens in Electron's main process, not just in the UI.
The effective policy is visible. The host Safety card shows what is actually in effect, e.g. "In effect: Suggest only (limited by read-only guard)".

Step 4: keep the trail for the postmortem

Every terminal tab has its own conversation, and history is grouped per host. Next time web-01 acts up, open the history and the previous investigation is right there: which commands ran, what they returned, what fixed it. + New chat archives the current conversation instead of deleting it.

AI-initiated commands and dangerous operations also land in the audit log, which you can filter by time and export when writing up the incident.

Bring your own model

The assistant talks to any OpenAI-compatible provider (OpenAI, DeepSeek, Qwen, and others). API keys are stored with the OS secure store on your machine and are not uploaded to any product cloud.

Try it without touching a server

Grab the installer for Windows, macOS or Linux from GitHub Releases.
Open the built-in demo host. Everything is simulated, so you can click Run freely.
Add your model provider in Settings → AI, then try it on a real box with Confirm before run.

More details are on the project site. AI-SSH-Pro is MIT-licensed; stars, feedback and issues are very welcome.

How do you triage 502s today? I'd love to hear which checks you run first.

AI-SSH-Pro: a multi-session SSH client with an AI ops assistant you stay in control of

Shuaipeng Guo — Tue, 20 Oct 2026 01:43:48 +0000

AI-SSH-Pro is a local, multi-session SSH desktop client with a built-in, Cursor-style AI ops assistant. The AI proposes commands; you decide how they run: Suggest only, Confirm before run, or Auto run.

Website: https://guoshuaipeng.github.io/ai-ssh-pro/
Download: https://github.com/guoshuaipeng/ai-ssh-pro/releases
Source (MIT): https://github.com/guoshuaipeng/ai-ssh-pro

The UI ships in both English and Chinese — switch the language in Settings. Screenshots below use the English UI with the built-in demo host (simulated data; some sample AI replies are in Chinese).

Who it's for

Ops / SRE engineers watching several machines at once who want one place to see everything.
Backend developers who regularly SSH in to read logs or restart services, and want help structuring the troubleshooting.
Small-team leads who want AI in the loop, with per-host control over what it may execute.
Xshell / FinalShell users looking for familiar tabs and a session tree.

Ops home: every host at a glance

The app opens on an ops dashboard:

Online hosts and open alerts at the top.
One card per host with live CPU, memory and disk.
One click into Terminal, SFTP or Monitor.
Quick actions for common playbooks, such as a rolling nginx restart or disk cleanup.

Multi-session SSH, done properly

Tabs, split panes and session groups, with search and #tag filtering.
Jump hosts (multi-level ProxyJump), port forwarding and host-key verification.
Import from ~/.ssh/config; reconnect to recent sessions in one click.
Production tabs carry a prominent banner, so you always know where you are.

The AI panel

The assistant lives in a panel to the right of the terminal, so you never switch windows mid-incident.

Suggested commands are grouped into one compact block with Copy / Run and a risk label (low / medium / high).
Each reply shows how long it took and can be copied in one click.
The input row holds everything: model, execution policy, attach terminal output, send.
Connect any OpenAI-compatible provider (OpenAI, DeepSeek, Qwen, …). Your API keys stay on your machine.

Three execution policies

Pick one in Settings → AI:

Policy	Behavior
Suggest only	Runs read-only commands; changes are shown as suggestions only
Confirm before run (default)	Read-only commands run; changes need confirmation; high-risk needs a second confirmation
Auto run	Low- and medium-risk commands run automatically; high-risk still asks

Under Auto run you can additionally allow high-risk commands to run automatically. It's off by default.
The policy menu in the input row can override the policy for the current tab only.

Per-host safety

Every host profile has a Safety card:

Protection level: Normal / Production / Read-only.
AI policy for this host: follow the global setting, or pick one.
The card shows the policy actually in effect, e.g. "In effect: Suggest only (limited by read-only guard)".

Production hosts are not capped: your chosen policy applies as-is, and the banner reminds you of the environment. Only read-only hosts block AI writes.

Conversations bound to tabs

Each terminal tab is its own conversation; two tabs on the same host give you #1 and #2.
+ New chat archives the current conversation instead of deleting it.
History is grouped by host — click to restore.
With no terminal bound, the assistant is plain Q&A and never runs anything.

SFTP and the rest of the toolbox

Dual-pane SFTP: local and remote side by side, drag-and-drop, transfer queue.
Monitoring: resource charts, multi-host dashboard, alert rules and an alert workbench.
Toolbox: processes, ports, services, logs, Docker containers and Compose.
Productivity: snippets, playbooks, batch execution, broadcast input, session recording and replay.
Audit: sensitive operations are logged, filterable by time and exportable.

Security by design

Safety is layered, not a single switch:

Main-process enforcement: before the AI writes to a terminal, the main process re-checks host protection. On a read-only host, the AI cannot write even if you click approve.
One rule everywhere: settings, host card, AI input and background execution all compute the effective policy the same way — no "UI says confirm, backend just runs".
Bounded overrides: per-tab overrides live in memory only, reset on close or disconnect, and still respect read-only.
Credentials stay local: passwords, key passphrases and API keys are encrypted with the OS secure store and never uploaded to any product cloud.
Traceable: AI-initiated commands and dangerous operations are recorded in the audit log.

Get started

Download the latest installer from GitHub Releases.
Launch it and try the built-in demo host — all data is simulated, nothing touches a real server.
Add your own model provider in Settings → AI.

If you want a comfortable multi-session SSH client where the AI proposes and you decide how it executes, give AI-SSH-Pro a try. Stars and issues are very welcome.