菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Shadow and version-control another agent's conversation. Use when asked to track an agent, create agent biography, shadow an agent, document agent work, or make agent output more accessible.
Configure Agent HQ Electron crash mitigations + diagnostics via repo .env (added after 2026-01-22 renderer crash).
Start the full agent stack (tmux sessions for Claude Code agents, SQLite ingestors, announcers, watchdog, and mitmproxy) after a fresh Mac reboot. This skill should be used when the user asks to "start everything", "bring up the agent stack", "start after reboot", "launch tmux sessions", or needs to initialize the development environment with all monitoring and agent processes.
Bootstrap the complete agentic ecosystem (Claude Code, Codex, vscode-shims, agent-box) on a remote machine. Use when user asks to install ecosystem, setup remote agent, bootstrap agent box, deploy to remote, or install claude/codex on another machine.
This skill should be used when containerizing a multi-service agentic ecosystem (UI + Agent Management Server, optionally launchers/ingestors) with Docker Compose while preserving localhost-only security, correct in-container networking, centralized log volume mounts, and working Codex/Claude CLIs.
Safe incremental deployment and updates for the agentic ecosystem after initial setup. Focuses on config preservation, safe service restarts, verification, and optional testing. Use after agentic-ecosystem-remote-deployment has completed at least once.
| 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. |
Troubleshooting guide for starting Agent HQ services on remote machines when they fail or crash.
Use this skill when you see:
| Service | Port | Purpose |
|---|---|---|
| AMS (Agent Management Server) | 8041 | /api/agent-top/stream SSE endpoint |
| Agent HQ UI | 8037 | Web UI for viewing agents |
| Claude Shim | 8787 | Claude vscode-shim server |
| Codex Shim | 9288 | Codex vscode-shim server |
/api/agent-top/stream returns connection reset# Check if AMS is running on remote
ssh -p <PORT> <HOST> "lsof -nP -iTCP:8041 -sTCP:LISTEN"
# 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"
http://localhost:28037 shows "This site can't be reached"# Check if UI is running on remote
ssh -p <PORT> <HOST> "lsof -nP -iTCP:8037 -sTCP:LISTEN"
⚠️ 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.
# 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
cd ~/swe/vscode-shims && python launchers/launch_ssh_tunnel_to_m2_tmux.py --verbose \
--map 28787:8787,29288:9288,28037:8037,28041:8041
From ~/AgenticProjects/agent-box-v1/.env:
| Variable | Value | Used By |
|---|---|---|
AMS_TMUX_PORT | 8041 | AMS server, vite config |
AGENT_HQ_UI_PORT | 8037 | Agent HQ UI vite config |
AGENT_MGMT_PORT | (fallback for AMS_TMUX_PORT) | Legacy |
VITE_PORT | (fallback for AGENT_HQ_UI_PORT) | Legacy |
# 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
| Session | Service |
|---|---|
ams_tmux | AMS server (port 8041) |
agent-hq-ui-8037 | Agent HQ UI (port 8037) |
ssh-tunnel-to-m2 | SSH tunnel (local) |