Get started

You’ll run 3 local processes: a gateway (GraphQL API), a worker (does the fetching/extracting), and a validator (optional). Then you’ll run a query in the GraphQL playground.

Use the TUI Use 3 terminals Run a first query

Option A: Textual TUI (recommended)

Runs gateway/worker/validator and helps with mesh allowlists + approvals.

python3 -m venv .venv
source .venv/bin/activate
pip install -e tools/wq-tui
wq-tui

Tip: the TUI can detect the gateway’s endpoint_id_hex from logs and wire up peers automatically.

Option B: three terminals

Start the gateway first and copy the printed endpoint_id_hex=... (call it GW_ID). Then start worker/validator with --static-peer "${GW_ID}@127.0.0.1:4242".

mkdir -p .local

# Terminal A (gateway)
cargo run -p wq-gatewayd -- \
  --http-listen 127.0.0.1:8080 \
  --p2p-bind 127.0.0.1:4242 \
  --identity-key-file .local/gateway.key \
  --network-id local \
  --state-dir .local/state

# Terminal B (worker)
cargo run -p wq-workerd -- \
  --p2p-bind 127.0.0.1:4243 \
  --identity-key-file .local/worker.key \
  --network-id local \
  --static-peer "${GW_ID}@127.0.0.1:4242"

# Terminal C (validator)
cargo run -p wq-validatord -- \
  --p2p-bind 127.0.0.1:4244 \
  --identity-key-file .local/validator.key \
  --network-id local \
  --static-peer "${GW_ID}@127.0.0.1:4242"

Run a first query

Open the GraphQL playground at http://127.0.0.1:8080/ and try a minimal extraction:

query Demo {
  web(
    url: "https://example.com/"
    wql: "{ title: { css: \"h1\" } }"
  ) {
    extract
    proofInfo { offerId }
  }
}

Notes: WebGraphQL is cache-first. Add @fresh(ttlSeconds: ...) only when you want to refetch.

Optional: enable offer approval (human review)

When enabled, higher-risk @fresh jobs pause and wait for human approval before they run.

# start gateway with approval enabled
cargo run -p wq-gatewayd -- \
  --network-id coop \
  --require-offer-approval \
  --offer-approval-mode risky \
  --offer-approval-dir .local/approvals

# list / inspect / approve
cargo run -p wq-offerctl -- list-pending --approval-dir .local/approvals
cargo run -p wq-offerctl -- show <offer_id> --approval-dir .local/approvals
cargo run -p wq-offerctl -- approve <offer_id> --approval-dir .local/approvals