remote-agents · git:20261029.b6b1bab · 2026-10-29 · sha256 2c76215f4c42aa5e
remote-agents git:20261029.b6b1babA
Immutable. This exact content never changes and is served at /api/v1/blob/2c76215f4c42aa5e.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_rqkzcdayonq7wcxv/2c76215f4c42aa5e9b9b6a232a10bd755b22452da4a89a02a48795fc27bc72b7.json
Then /plugin install remote-agents@markdownregistry-rqkzcdayonq7wcxv in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: remote-agents
description: Operate dedicated remote Linux/Windows hosts that run coding agents. Use for provisioning and hardening an agent VM, SSH-over-SSM access with no public ingress, host power lifecycle, the WireGuard/SMB work bridge, running agents remotely through porch, a headless Windows desktop with read-only observation, bounded visual QA, durable managed-worker daemons, phone-visible Codex Remote threads, storage audits, and cleanup evidence. Not for running agents on the local machine — use pragmatic-orchestration directly for that.
---
# 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`.
```bash
./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](references/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](references/onboarding.md) + `scripts/onboard.py check` |
| Provision/harden a new host | [provisioning.md](references/provisioning.md) (+ `references/terraform/`, `examples/`) |
| Configure host identity | [configuration.md](references/configuration.md) |
| SSH config, file transfer, SMB mount | [bridge.md](references/bridge.md) |
| Run agents on the host | [porch-remote.md](references/porch-remote.md) |
| Coordinate placement across prepared hosts | Porch's opt-in `fleet` command; see its `references/fleet.md`. Keep one coordinator, explicit host capacity, and isolated workspaces. Cloud provisioning is not implemented yet. |
| Prepare an AgentCore image | Load Porch's `references/agentcore-image.md`; it owns the guest HTTP runner. This host skill retains provisioning/auth/bootstrap ownership. |
| Linux host operations | [linux-host.md](references/linux-host.md) |
| Windows host inventory/recovery | [windows-host.md](references/windows-host.md) |
| Headless interactive desktop | [windows-desktop.md](references/windows-desktop.md) |
| Dev-machine OS support | [local-platforms.md](references/local-platforms.md) |
| GUI/visual QA runs | [visual-qa.md](references/visual-qa.md) |
| Work-root layout and audit | [work-storage.md](references/work-storage.md) |
| Durable worker fleet | [managed-workers.md](references/managed-workers.md) |
| Phone-visible Codex threads | [remote-tui.md](references/remote-tui.md) |
| Threat model | [security.md](references/security.md) |
| Failures | [troubleshooting.md](references/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](references/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.