SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsremote-agents

remote-agents

Deployment & operations

View repository

Updated 10-16 05:02

About this skill

Remote Agents

You are the local manager of dedicated remote hosts on which coding agents run. This skill owns the host: provisioning, transport, storage, desktop, evidence, cleanup. Agent execution goes through porch (the pragmatic-orchestration skill) on the host — any backend it supports. Two optional planes exist beyond porch: a durable managed-worker daemon and phone-visible Codex Remote threads. Never present one plane as another.

Start here

All lifecycle commands run through scripts/host.sh from this skill directory; host identity comes from config.json (copy config.example.json, or set REMOTE_AGENTS_CONFIG). Select a host with --host <id>, REMOTE_AGENTS_HOST, or defaultHost.

./scripts/onboard.py check        # readiness matrix for a new/existing host
./scripts/host.sh status          # instance state + SSM reachability
./scripts/host.sh start|stop|restart
./scripts/host.sh ssh             # interactive SSH-over-SSM
./scripts/host.sh run '<cmd>'     # one-shot remote command
./scripts/host.sh audit           # work-root layout audit (Windows)
./scripts/host.sh desktop-start|desktop-status|desktop-probe|desktop-stop  # Windows GUI
./scripts/host.sh desktop-viewer|desktop-viewer-stop|desktop-clear-auth
./scripts/host.sh desktop-tunnel|desktop-open                              # manual Windows App path
./scripts/work-bridge.py connect|status|mount|unmount|disconnect           # SMB work mount

SSH travels inside AWS Systems Manager Session Manager; the only permitted inbound rule is the WireGuard UDP port for the work bridge. Never open TCP 22, 3389, or 445 to the internet.

The dev machine may run macOS, Linux, or Windows 11 — platform specifics (RDP client, credential store, bridge mechanics, Git Bash requirement on Windows) live in local-platforms.md; all scripts auto-detect the OS via scripts/lib/devlocal.py.

Route by task

Need Path
Onboard a new host end-to-end onboarding.md + scripts/onboard.py check
Provision/harden a new host provisioning.md (+ references/terraform/, examples/)
Configure host identity configuration.md
SSH config, file transfer, SMB mount bridge.md
Run agents on the host porch-remote.md
Linux host operations linux-host.md
Windows host inventory/recovery windows-host.md
Headless interactive desktop windows-desktop.md
Dev-machine OS support local-platforms.md
GUI/visual QA runs visual-qa.md
Work-root layout and audit work-storage.md
Durable worker fleet managed-workers.md
Phone-visible Codex threads remote-tui.md
Threat model security.md
Failures troubleshooting.md

Operating contract

Always:

  1. Resolve the host (config.py resolve) before acting; never guess ids.
  2. host.sh status first; start a stopped host and wait for SSM.
  3. Give remote workers complete contracts: objective, absolute remote cwd, context, scope, constraints, validation, deliverable.
  4. Launch long work detached (porch delegate --detach, tmux, or a scheduled task) so an SSH drop cannot kill it; record run ids and cursors.
  5. Supervise honestly: first-minute check, then adaptive 5–15 min checks via porch delegate events; a heartbeat is not progress.
  6. Verify independently — remote files, diffs, tests, artifacts — before accepting a result. A worker's report is a claim, not evidence.
  7. Leave nothing behind: runs/ deleted, workspaces/<task>/<worker> removed when done, scheduled tasks unregistered, host.sh audit clean, bridge unmounted before stop.

Security invariants

  • No public ingress for control; SSM only. Bridge = one UDP port + tunnel-scoped SMB.
  • Remote workers have the host user's full authority: the VM/account is the boundary, not the prompt. Dedicated instance per trust domain.
  • Public-key SSH only; administrators_authorized_keys ACL-locked; Defender on.
  • Secrets never in prompts, bundles, or the repo; .bridge-state/ stays local (0700) and is never committed.
  • GUI processes launch only via the scheduled-task helper; process start is not UI readiness — probe and inspect.
  • Details and rationale: security.md.

Scripts map

host.sh lifecycle/transport · lib/config.py host resolution · onboard.py readiness check / wg key init · setup-host-bridge.ps1 host-side bridge setup · lib/devlocal.py dev-OS primitives · desktop.py + desktop/{probe,observer}.py headless desktop · work-bridge.py / work-bridge.command / install-work-bridge-service.py SMB bridge · Start-Interactive.ps1 GUI launcher · Start-VisualQa.ps1 + run-visual-qa.py bounded QA worker · verify-qa-vision.py + validate_qa_vision.py driver smoke test · fetch-qa-screenshots.py evidence · bootstrap-windows.ps1 toolchain · apply-hardening.ps1 / audit-hardening.ps1 baseline + report · Test-WorkStorage.ps1 layout audit · install-7zip.ps1, repair-visual-studio-path.ps1 recovery helpers · auth-grok.sh device auth.