Scout Quickstart - Local-first web acquisition

Path 01

Install from the verified private-beta branch.

python3 -m venv .venv
source .venv/bin/activate
pip install "git+https://github.com/arijitchowdhury80/scout.git@codex/scout-platform-foundation"
playwright install chromium
export SCOUT_WORKDIR="$PWD/scout-runs"
scout serve

Workdir

`SCOUT_WORKDIR` is where Scout writes run artifacts: records, source pages, blocked pages, validation, reports, raw evidence, and screenshots.

Health check

Open `http://127.0.0.1:8421/health` after `scout serve` starts. The launch website is served from `/`. Local Swagger API docs remain at `/docs`; hosted deployments keep Swagger private.

Package release

`pip install scout-web` comes after the registry publishing and license gates close. Until then, beta installs use the verified launch branch.

Path 02

Run with Docker when you want a clean service boundary.

docker compose -f docker/docker-compose.yml up -d
curl http://127.0.0.1:8421/health

Persistence

Mount a host volume for Scout runs so artifacts survive container restarts.

Browser capture

Docker is best for service-style scraping. User-browser capture remains a local-machine workflow because it can touch your active session.

First useful run

Make one artifact folder, then inspect it.

1. Pick a target

Start with a public page you are allowed to access.

2. Run Scout

Use CLI or HTTP API. Keep live hard-site testing small and intentional.

3. Inspect evidence

Open `records.json`, `source_pages.json`, `blocked_pages.json`, and `extraction_report.md`.

Readiness check

Verify the same launch gate CI runs.

The readiness checker summarizes the current truth: private beta is ready with limits, while public launch remains blocked until license, Stripe, dependency, registry, and legal gates close.

scout launch-readiness
scout launch-readiness --json
scout launch-readiness --require-public

Beta gate

The default command should report `Private beta: ready_with_limits` when the repo evidence is intact.

Public gate

`--require-public` is expected to fail until the public launch blockers are closed.

Hosted beta

Use hosted Scout only after you receive an API key.

Hosted beta is a convenience API with finite credits. It is not unlimited crawling, and local Scout remains the primary beta path. Hosted beta remains invite-only and metered while pricing is derived from unit economics. Final credits, retention, and overage rules are not approved yet.

export SCOUT_HOSTED_BASE_URL="https://scout.chowmes.com"
export SCOUT_HOSTED_API_KEY="paste-your-delivered-key"

curl "$SCOUT_HOSTED_BASE_URL/v1/hosted/me" \
  -H "Authorization: Bearer $SCOUT_HOSTED_API_KEY"

curl -X POST "$SCOUT_HOSTED_BASE_URL/v1/hosted/scrape" \
  -H "Authorization: Bearer $SCOUT_HOSTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["markdown"],"timeout_ms":30000}'

Credits

`/v1/hosted/me` shows your plan, credit balance, and current limits. A basic hosted scrape consumes one standard credit.

Bearer auth

Hosted endpoints use `Authorization: Bearer ...`. Do not put hosted keys in frontend code, public repos, screenshots, or shared logs.

Artifacts

High-level hosted runs write records and source evidence into hosted artifact storage with limited beta retention.

Local install is the primary beta path.