agenTOR

agenTOR gives agents disposable browser sessions with receipts. It routes Chrome through Tor-compatible SOCKS proxies, captures HTML and screenshots, and writes a local artifact trail instead of hand-waving what happened.

Commands

agentor
agentor doctor
agentor fetch <url>
agentor shot <url>
agentor screenshot <url>
agentor research <url> --prompt "research this page"
agentor run <url> --prompt "research this page"
agentor test tor
agentor setup tor --install
agentor demo
agentor profile add tor-local --proxy socks5://127.0.0.1:9050
agentor --version

Common flags:

--out <dir>                 Output directory (default: ./artifacts/<timestamp>-<slug>)
--proxy <url>               Proxy server, default: socks5://127.0.0.1:9050
--no-proxy                  Disable proxy usage
--timeout <ms>              Page timeout, default: 30000
--json                      Print receipt JSON
--profile <name>            Use a saved profile

What it writes

• receipt.json - structured metadata for the run
• page.html - captured DOM HTML
• page.txt - text extraction
• screenshot.png - when using screenshot or run
• report.md - heuristic research output for run

Install

npm install -g @builtbyecho/agentor

Or one-shot:

npx @builtbyecho/agentor fetch https://example.com --json

Bootstrap Tor:

npx @builtbyecho/agentor setup tor
npx @builtbyecho/agentor setup tor --install

Persist a local profile:

npx @builtbyecho/agentor profile add tor-local --proxy socks5://127.0.0.1:9050
npx @builtbyecho/agentor profile use tor-local

Tor notes

Default proxy is socks5://127.0.0.1:9050. If Tor is not running, pass --no-proxy for direct browsing or provide another SOCKS/HTTP proxy with --proxy.

If the default proxy is unavailable, agentor now fails with an actionable message instead of surfacing the raw browser error.

agentor setup tor checks whether Tor is installed and whether SOCKS is actually listening. agentor setup tor --install can run a platform package-manager install when the platform is recognized and the package manager is available.

agentor doctor checks browser availability, Tor binary, SOCKS reachability, and output-dir writability. agentor demo runs a local no-proxy sample so users can see the artifact flow immediately.

This is privacy framing and route control, not a promise of anonymity. DNS leaks, login state, downloaded artifacts, and upstream fingerprinting still matter.

Verification

npm test
node --check src/cli.js
node --check src/index.js
npm pack --json --dry-run
npm publish --dry-run --access public

Release Automation

This package is published from GitHub Actions using npm Trusted Publishing with provenance. Releases are built on GitHub-hosted runners and no long-lived npm publish token is required.