# Cursor IDE — работа из РФ и обход PING timeout

> **Проблема:** из России Cursor показывает `PING timed out`, Agent не отвечает.  
> **Временный обход:** Disable Http2 в настройках — помогает, но всё сильно замедляется.  
> **Рекомендуемое решение:** SOCKS-прокси через SSH-туннель на сервер с нормальным доступом (DO / RU VPS), без отключения HTTP/2.

**Связанные гайды:** [PROXY_GUIDE.md](../../connectivity/PROXY_GUIDE.md), [BUILD_AAB_FROM_RUSSIA_GUIDE.md](../../connectivity/BUILD_AAB_FROM_RUSSIA_GUIDE.md) — тот же паттерн «туннель через прокси-сервер».

---

## Содержание

1. [Симптомы и причина](#-симптомы-и-причина)
2. [Обход 1: Disable Http2 (простой, но медленный)](#-обход-1-disable-http2-простой-но-медленный)
3. [Обход 2: SOCKS через SSH-туннель (рекомендуется)](#-обход-2-socks-через-ssh-туннель-рекомендуется)
4. [Проверка и диагностика](#-проверка-и-диагностика)
5. [Troubleshooting](#-troubleshooting)
6. [Ссылки](#-ссылки)

---

## Симптомы и причина

### Что видно в Cursor

- В чате с Agent: **Request ID: … [unavailable] PING timed out**, `_he: [unavailable] PING timed out`.
- Стек указывает на `workbench.desktop.main.js`, `streamFromAgentBackend` / `getAgentStreamResponse` — обрыв связи с бэкендом агента.

### Почему так происходит

1. **HTTP/2 и маршрутизация**  
   Cursor использует HTTP/2 для стриминга к `*.cursor.sh` (в т.ч. `agent.api5.cursor.sh`). В части сетей (в т.ч. из РФ) запросы уходят в CDN (например Cloudflare) с неудачной конфигурацией SSL/HTTP2 или блокировкой по DPI, из‑за чего соединение обрывается или уходит в таймаут.

2. **Disable Http2**  
   Отключение HTTP/2 переводит трафик на HTTP/1.1 и часто убирает обрывы, но увеличивает нагрузку и задержки — «всё становится медленным», возможны дополнительные таймауты агента.

3. **Идея нормального обхода**  
   Пропускать только трафик Cursor через сервер с хорошим доступом к Cursor API (VPS в DO, РФ и т.п.). До этого сервера — SSH (обычно не режется). От сервера до `*.cursor.sh` — уже «нормальный» канал, HTTP/2 работает без костылей.

---

## Обход 1: Disable Http2 (простой, но медленный)

Если нужно быстро восстановить работу без настройки туннеля:

1. **Cursor → Settings** (Cmd+, / Ctrl+,).
2. Поиск: **HTTP**.
3. Включить **Cursor > General: Disable Http2**.

Минус: выше задержки и нагрузка, возможны таймауты агента при длинных ответах. Для постоянной работы из РФ предпочтительно [Обход 2](#-обход-2-socks-через-ssh-туннель-рекомендуется).

---

## Обход 2: SOCKS через SSH-туннель (рекомендуется)

Трафик Cursor идёт в интернет через ваш VPS. До VPS — SSH (один порт), с VPS — обычный доступ к Cursor API, HTTP/2 остаётся включённым.

### Схема

```
Cursor (macOS)  →  SOCKS 127.0.0.1:10809  →  SSH-туннель  →  VPS (DO/RU)
                                                                  ↓
                                                        HTTPS/HTTP2 → *.cursor.sh
```

На VPS не нужны отдельные прокси-сервисы — достаточно SSH (как в [PROXY_GUIDE](../../connectivity/PROXY_GUIDE.md) и [BUILD_AAB_FROM_RUSSIA_GUIDE](../../connectivity/BUILD_AAB_FROM_RUSSIA_GUIDE.md)).

### Предположения

- Есть VPS с нормальным доступом к интернету (например, тот же, что для ru.hunab.app: **149.154.64.19**, доступ по `ssh hsites-ahau` или аналог).
- Локально свободен порт для SOCKS (ниже — **10809**, чтобы не пересекаться с другими прокси).

### Шаг 1: Поднять SOCKS-туннель

```bash
# Убить старый туннель на порту 10809 (если был)
pkill -f "ssh.*-D 10809" 2>/dev/null

# Запуск SOCKS5 на 127.0.0.1:10809 через ваш VPS
ssh -D 10809 -f -N hsites-ahau
```

Если используете другой хост (например, hunab-prod):

```bash
ssh -D 10809 -f -N hunab-prod
```

Проверка: туннель держится, пока сессия не разорвана; можно проверить доступ через SOCKS (см. [Проверка и диагностика](#-проверка-и-диагностика)).

### Шаг 2: Настроить Cursor на использование SOCKS

1. **Cursor → Settings** (Cmd+, / Ctrl+,), поиск: **proxy**.
2. Заполнить:
   - **Http: Proxy** — `socks5://127.0.0.1:10809`
   - **Http: Proxy Strict SSL** — при необходимости отключить только если заведомо знаете, что за прокси (для одного своего VPS обычно не требуется).

Или в `settings.json` (Cursor: Open User Settings (JSON)):

```json
{
  "http.proxy": "socks5://127.0.0.1:10809",
  "https.proxy": "socks5://127.0.0.1:10809"
}
```

### Шаг 3: Не отключать HTTP/2

**Cursor > General: Disable Http2** — выключить (оставить HTTP/2 включённым). Весь трафик к Cursor API пойдёт с VPS, где HTTP/2 работает нормально.

### Шаг 4: Запуск Cursor при уже поднятом туннеле

Порядок каждый раз:

1. В терминале: `ssh -D 10809 -f -N hsites-ahau` (или ваш хост).
2. Запуск Cursor как обычно.

Чтобы не забывать туннель, можно завести скрипт запуска (см. [Скрипт запуска с туннелем](#скрипт-запуска-с-туннелем)).

---

## Проверка и диагностика

### Туннель поднят

```bash
# Должен слушать 10809
lsof -i :10809
# или
nc -z 127.0.0.1 10809 && echo "OK"
```

### Доступ к Cursor API через SOCKS (curl)

```bash
curl -x socks5h://127.0.0.1:10809 -sI https://agent.api5.cursor.sh 2>&1 | head -5
```

Успех: в ответе есть HTTP/2 или заголовки от сервера. Ошибка соединения или таймаут — туннель не работает или порт занят.

### Логи Cursor

При проблемах с подключением:

- **macOS:** `~/Library/Application Support/Cursor/logs/main.log`
- Искать по `ERROR`, `PING`, `timeout`, `HTTP2`, `ECONNREFUSED`, `ETIMEDOUT`.

---

## Troubleshooting

### После включения прокси Cursor вообще не подключается

- Убедиться, что туннель запущен: `lsof -i :10809`.
- Проверить доступ через SOCKS: `curl -x socks5h://127.0.0.1:10809 -sI https://agent.api5.cursor.sh`.
- Временно в настройках Cursor убрать `http.proxy` / `https.proxy` и проверить без прокси (например, с Disable Http2) — если так работает, проблема в туннеле или порте.

### PING timed out остаётся даже через прокси

- Перезапустить туннель и Cursor (полностью закрыть приложение и открыть снова).
- В настройках Cursor убедиться, что **Disable Http2** выключен (HTTP/2 включён).
- Проверить, что в настройках указан именно `socks5://127.0.0.1:10809` (без опечаток, порт совпадает с `-D 10809`).

### Порт 10809 занят

Выбрать другой порт, например 10810:

```bash
ssh -D 10810 -f -N hsites-ahau
```

И в настройках Cursor указать `socks5://127.0.0.1:10810`.

### Туннель рвётся при долгой неактивности

Поддерживать соединение помогут опции SSH:

```bash
ssh -D 10809 -f -N -o ServerAliveInterval=30 -o ServerAliveCountMax=6 hsites-ahau
```

При необходимости можно вынести эту команду в скрипт или systemd/supervisor на стороне клиента.

---

## Скрипт запуска туннеля

В репозитории есть скрипт для поднятия/остановки SOCKS-туннеля:

```bash
# Из корня репо
./docs/cursor/scripts/cursor-socks-tunnel.sh start   # поднять туннель
./docs/cursor/scripts/cursor-socks-tunnel.sh status   # проверить
./docs/cursor/scripts/cursor-socks-tunnel.sh stop      # остановить
```

Переменные окружения: `CURSOR_SOCKS_PORT` (по умолчанию 10809), `CURSOR_TUNNEL_HOST` (по умолчанию `hsites-ahau`).

**Запуск Cursor после туннеля (macOS):** после `./docs/cursor/scripts/cursor-socks-tunnel.sh start` откройте Cursor как обычно; при настроенных `http.proxy`/`https.proxy` трафик пойдёт через SOCKS.

---

## Ссылки

| Документ | Назначение |
|----------|------------|
| [PROXY_GUIDE.md](../../connectivity/PROXY_GUIDE.md) | Прокси ru.hunab.app, SSH ProxyCommand для scp/ssh на прод |
| [BUILD_AAB_FROM_RUSSIA_GUIDE.md](../../connectivity/BUILD_AAB_FROM_RUSSIA_GUIDE.md) | Сборка AAB из РФ через Maven proxy + SSH-туннель |
| [Cursor Forum — HTTP/2 network error](https://forum.cursor.com/t/http2-network-error-with-cursor-ide-and-cursor-cli/147318) | Обсуждение ошибок HTTP/2 и региональной маршрутизации |
| [Cursor Forum — Agent timeouts when HTTP2 disabled](https://forum.cursor.com/t/agent-timeouts-much-more-when-http2-disabled/76517) | Таймауты агента при отключённом HTTP/2 |

---

*Последнее обновление: 2026-03-08*