Agent Workstation Bootstrap

Portable setup pack for a Hermes-class agent workstation on a small company machine.

Goal: after clone + one install pass, an agent can:

1. Search many websites in parallel and gather sources
2. Handle Cloudflare-protected public pages via real browser / stealth fetchers (authorized use only)
3. Convert pages into clean Markdown / plain text for LLM context

This repo intentionally contains only generic tooling. No company SOPs, customer data, wallets, OAuth tokens, internal pricing, or private skills.

---

Quick start (human)

Windows (PowerShell)

git clone https://github.com/jacksoncoin0202-ops/agent-workstation-bootstrap.git $HOME\agent-workstation-bootstrap
cd $HOME\agent-workstation-bootstrap
pwsh -File .\install\windows.ps1

Linux / WSL

git clone https://github.com/jacksoncoin0202-ops/agent-workstation-bootstrap.git ~/agent-workstation-bootstrap
cd ~/agent-workstation-bootstrap
bash install/wsl.sh

Then complete secrets (optional but recommended):

cp .env.example .env
# edit .env — put FIRECRAWL_API_KEY etc. Never commit .env

Finally run the verification checklist:

pwsh -File .\scripts\verify.ps1   # Windows
# or
bash scripts/verify.sh            # Linux/WSL

---

Quick start (agent) — single prompt

Paste this into any coding agent (Claude Code / Codex / Cursor / Hermes):

You are installing a portable agent workstation from this repo.

Repo: https://github.com/jacksoncoin0202-ops/agent-workstation-bootstrap

Do ALL of the following, in order, without skipping:

1. Clone (or git pull) this repo to ~/agent-workstation-bootstrap (Windows: %USERPROFILE%\agent-workstation-bootstrap).
2. Read README.md, docs/TOOLING.md, docs/SKILLS.md, docs/SECURITY.md, CHECKLIST.md, MANIFEST.yml.
3. Run the OS-appropriate installer:
   - Windows: pwsh -File install/windows.ps1
   - Linux/WSL: bash install/wsl.sh
4. Install the generic skills listed in docs/SKILLS.md (public sources only).
5. Configure optional API keys from .env.example → .env (never print secret values).
6. Run scripts/verify.ps1 or scripts/verify.sh and fix anything red.
7. Work through CHECKLIST.md until every required box is [x].
8. Report a final summary table: component | installed | version | smoke test | notes.
9. Do NOT install company-private skills, wallets, customer dumps, or copy secrets from other machines.

Stop only when CHECKLIST.md required items are all complete, or when blocked on an explicit human-only step (browser OAuth login, paid API key).

A copy of this prompt also lives in AGENT_PROMPT.md.

---

What this pack installs

Layer	Components	Why it exists
Core runtimes	Python 3.10+, Node.js 20+, Git, GitHub CLI, ripgrep, ffmpeg	Agent scripts and CLIs
Parallel web research	firecrawl-cli, optional firecrawl-mcp	Multi-URL search + scrape to Markdown
Hard pages / CF	scrapling (StealthyFetcher), agent-browser, Playwright Chromium	Public pages behind bot challenges; real browser session when needed
Page → Markdown/txt	Firecrawl scrape, Scrapling extract, trafilatura, defuddle, markdownify	Clean LLM-readable text
Agent shell (optional)	Hermes Agent (hermes)	Long-running agent + gateway on Linux/WSL
Generic skills	See docs/SKILLS.md	Coding, QA, research, safety — no business IP

Full dependency map: MANIFEST.yml · details: docs/TOOLING.md

---

Tool routing (how the agent should pick tools)

Use the smallest tool that works:

1. Public article / docs page
   → firecrawl scrape URL   OR   trafilatura URL   OR   defuddle URL

2. Need search across the web first
   → firecrawl search "query" --scrape

3. Many URLs in parallel
   → firecrawl batch / multiple firecrawl scrape jobs
   → or Python asyncio + httpx for simple HTML sites

4. Page is JS-heavy or shows Cloudflare interstitial
   → scrapling extract stealthy-fetch URL
   → or agent-browser / Playwright with a real profile
   → last resort: human handoff for CAPTCHA/login

5. Need interactive QA / click paths
   → agent-browser or gstack browse / Playwright

Safety framing: do not describe browser-profile use as “hacking Cloudflare.”
Prefer: authorized observation through the operator’s own browser state, or stealth public fetch for sites you have rights to collect.

---

Repo layout

.
├── README.md                 # this file
├── AGENT_PROMPT.md           # paste-ready agent install prompt
├── CHECKLIST.md              # done-definition for agents
├── MANIFEST.yml              # machine-readable dependency list
├── .env.example              # secret placeholders only
├── install/
│   ├── windows.ps1           # Windows installer
│   └── wsl.sh                # Linux/WSL installer
├── scripts/
│   ├── verify.ps1
│   └── verify.sh
├── skills/
│   └── ROUTER.md             # generic skill router (no private routes)
└── docs/
    ├── TOOLING.md
    ├── SKILLS.md
    └── SECURITY.md

---

Optional: Hermes Agent

On Linux/WSL, after base install:

# Official Hermes install path varies by release — prefer:
# https://github.com/NousResearch/hermes-agent  (or your org's pinned fork)
# Then:
hermes postinstall
hermes doctor
hermes status

Windows primary coding agents (Claude Code / Codex / Grok) do not require Hermes. Hermes is the optional long-running gateway layer used on WSL.

---

What is deliberately excluded

Excluded	Reason
Company Brain / internal SOPs	Private ops knowledge
YAICHI / PTCG / product listing skills	Business-specific
Wallet / Telegram bot tokens / OAuth cookies	Secrets
Customer CSVs, CRM dumps, browser password DBs	PII / regulated
Machine-hardcoded absolute paths from one laptop	Not portable

See docs/SECURITY.md.

---

Verify completion

An install is complete only when:

1. CHECKLIST.md required items are all [x]
2. scripts/verify.* exits 0
3. Smoke tests pass:
   • firecrawl --version (or documented offline fallback)
   • scrapling --help
   • trafilatura --version or python -c "import trafilatura"
   • agent-browser --help or playwright --version
   • At least one page → markdown conversion works on https://example.com

---

License

MIT — tooling references only. Third-party CLIs keep their own licenses.