remote-agent-hq-startup

name: remote-agent-hq-startup description: Debug and start Agent HQ services (AMS, UI) on remote machines. Use when AMS not responding, port 8041 issues, environment variable errors, vite config failures, or SSE connection lost errors.

Remote Agent HQ Startup & Debug

Troubleshooting guide for starting Agent HQ services on remote machines when they fail or crash.

Trigger Keywords

Use this skill when you see:

• "AMS not responding", "SSE connection lost"
• "port 8041", "port 8037"
• "environment variable", "Missing/invalid AMS port", "Missing/invalid port"
• "vite config", "failed to load config"
• "agent-hq debug", "Agent HQ died"
• "AMS_TMUX_PORT", "AGENT_HQ_UI_PORT", "AGENT_MGMT_PORT"

Quick Reference: Remote Ports

Problem: AMS Not Responding (SSE Connection Lost)

Symptoms

• UI shows "SSE connection lost"
• "Connecting to SSE..." stuck forever
• /api/agent-top/stream returns connection reset

Diagnosis

# Check if AMS is running on remote
ssh -p <PORT> <HOST> "lsof -nP -iTCP:8041 -sTCP:LISTEN"

Fix: Start AMS

# Start AMS in tmux (requires PATH and env vars)
ssh -p <PORT> <HOST> "export PATH=\"/opt/homebrew/bin:\$PATH\" && \
  cd ~/AgenticProjects/agent-box-v1/services/ams-tmux && \
  AMS_TMUX_PORT=8041 ./launchers/run_ams_tmux_server.sh"

If tmux: command not found:

ssh -p <PORT> <HOST> "export PATH=\"/opt/homebrew/bin:\$PATH\" && \
  AMS_TMUX_PORT=8041 \
  ~/AgenticProjects/agent-box-v1/services/ams-tmux/launchers/run_ams_tmux_server.sh"

Problem: Agent HQ UI Not Responding (port 8037)

Symptoms

• http://localhost:28037 shows "This site can't be reached"
• "ERR_CONNECTION_RESET"

Diagnosis

# Check if UI is running on remote
ssh -p <PORT> <HOST> "lsof -nP -iTCP:8037 -sTCP:LISTEN"

Fix: Start Agent HQ UI

⚠️ CRITICAL: Must source .env file first!

The vite config requires these environment variables:

• AMS_TMUX_PORT (or AGENT_MGMT_PORT)
• AGENT_HQ_UI_PORT (or VITE_PORT)

# Start in tmux with proper env (CORRECT WAY)
ssh -p <PORT> <HOST> "export PATH=\"/opt/homebrew/bin:\$PATH\" && \
  tmux new-session -d -s agent-hq-ui-8037 \
  -c ~/AgenticProjects/agent-box-v1/apps/agent-hq-ui \
  'bash -lc \"cd ~/AgenticProjects/agent-box-v1 && set -a && source .env && set +a && \
  cd apps/agent-hq-ui && npm run dev:web -- --port 8037 --host 127.0.0.1; exec bash\"'"

Common Error:

Error: Missing/invalid AMS port: set AMS_TMUX_PORT (preferred) or AGENT_MGMT_PORT
Error: Missing/invalid port: set AGENT_HQ_UI_PORT (preferred) or VITE_PORT

Cause: .env file not sourced before starting vite.

Fix: Use set -a && source .env && set +a pattern shown above.

Problem: SSH Tunnel Not Forwarding

Symptoms

• Local port not listening
• "Connection refused" when accessing localhost:28xxx

Diagnosis

# Check local tunnel ports
lsof -nP -iTCP:28787 -sTCP:LISTEN
lsof -nP -iTCP:28041 -sTCP:LISTEN

# Check tunnel tmux session
tmux list-sessions | grep tunnel
tmux capture-pane -t ssh-tunnel-to-m2 -p -S -30

Fix: Restart Tunnel

cd ~/swe/vscode-shims && python launchers/launch_ssh_tunnel_to_m2_tmux.py --verbose \
  --map 28787:8787,29288:9288,28037:8037,28041:8041

Environment Variables Reference

From ~/AgenticProjects/agent-box-v1/.env:

Complete Startup Sequence (Remote m2)

# 1. Start AMS (port 8041)
ssh -p 11111 m2@113.161.41.101 "export PATH=\"/opt/homebrew/bin:\$PATH\" && \
  cd ~/AgenticProjects/agent-box-v1/services/ams-tmux && \
  AMS_TMUX_PORT=8041 ./launchers/run_ams_tmux_server.sh"

# 2. Start Agent HQ UI (port 8037)
ssh -p 11111 m2@113.161.41.101 "export PATH=\"/opt/homebrew/bin:\$PATH\" && \
  tmux new-session -d -s agent-hq-ui-8037 \
  -c ~/AgenticProjects/agent-box-v1/apps/agent-hq-ui \
  'bash -lc \"cd ~/AgenticProjects/agent-box-v1 && set -a && source .env && set +a && \
  cd apps/agent-hq-ui && npm run dev:web -- --port 8037 --host 127.0.0.1; exec bash\"'"

# 3. Start SSH tunnel (on LOCAL machine)
cd ~/swe/vscode-shims && python launchers/launch_ssh_tunnel_to_m2_tmux.py --verbose \
  --map 28787:8787,29288:9288,28037:8037,28041:8041

# 4. Verify
curl -sS http://127.0.0.1:28041/api/agent-top/stream | head -5  # AMS
curl -sS http://127.0.0.1:28037/ | head -5  # Agent HQ UI

Tmux Session Names

Related Skills

• agentic-ecosystem-remote-deployment - Full deployment guide
• config-transparency-centralized - .env philosophy