Skip to main content

​
Agent Setup

The Hoard Agent is a small program that runs on your computer. It automates the TCGplayer seller portal using browser automation powered by Brainstorm (brz).

​
Requirements

  • A computer that stays on during sync times (Mac, Windows, or Linux)
  • Chrome or Chromium browser installed (the agent uses it for automation)
  • A TCGplayer seller account
  • A Hoard Pro subscription with API key
If Chrome isn’t installed, the agent downloads a compatible Chromium automatically on first run (~200MB, one time).

​
Download

Download from the Hoard setup page or directly from GitHub Releases. Hoard onboarding page with step-by-step agent setup instructions Each download includes:
  • hoard-agent (or hoard-agent.exe on Windows) — the agent binary
  • workflows/tcgplayer.yaml — the automation workflow
  • .env — configuration file (fill in your values)

​
Configuration

Open the .env file included in the download and fill in your values: 
# Required
HOARD_API_KEY=your-api-key-from-dashboard
TCGPLAYER_EMAIL=your-tcgplayer-email@example.com
TCGPLAYER_PASSWORD=your-tcgplayer-password

# Optional
# HEADED=1     # Show browser window
# DEBUG=1      # Verbose logging + failure screenshots
Your .env file stays on your machine. Keep it private — it contains your TCGplayer password and API key.

​
Your credentials stay on your computer

Your TCGplayer password never leaves your machine. The agent reads it from your local .env file and types it into TCGplayer’s login page in a real browser — exactly the way you would. Hoard’s servers never see it, never store it, and never transmit it.
WhatWhereSent to Hoard?
TCGplayer passwordYour .env fileNever
TCGplayer session cookies~/.config/hoard/chromium-profile/Never
Hoard API keyYour .env fileYes (to authenticate syncs)
Inventory & order dataExported from TCGplayer by the agentYes (this is what powers your dashboard)

​
First Run

The first run opens a visible browser window so you can log into TCGplayer normally. This is needed because TCGplayer shows a CAPTCHA on login — the agent can’t solve that for you, so it lets you handle it yourself. After this one-time login, your session is saved and future syncs run in the background. 
# macOS flags all downloads from the internet with a quarantine attribute.
# This is the same thing you'd do for any app downloaded outside the App Store.
xattr -d com.apple.quarantine hoard-agent

# First run — opens a browser so you can log into TCGplayer
HEADED=1 ./hoard-agent workflows/tcgplayer.yaml
If macOS says the app “can’t be opened because it is from an unidentified developer,” the xattr command above fixes it. You can also go to System Settings > Privacy & Security and click Allow. This happens with any app downloaded outside the App Store.
  1. A Chrome window opens to TCGplayer’s login page
  2. Log in with your seller account — just like you normally would
  3. Complete the CAPTCHA if TCGplayer shows one
  4. The agent detects the login and starts syncing automatically
  5. Your session is saved locally so you won’t need to do this again until it expires

​
Headless Mode

After the first login, run without HEADED=1: 
./hoard-agent workflows/tcgplayer.yaml
The agent:
  • Polls the Hoard server every 30 seconds
  • Syncs when the server says it’s time (based on your sync schedule)
  • Uses saved cookies from the first login (no CAPTCHA needed)

​
Session Expiry

Like any website, TCGplayer sessions expire after a few days. When this happens, the agent will let you know:
  1. You’ll see “session expired” in the terminal
  2. Run again with HEADED=1 — a browser window opens so you can log in
  3. Complete the CAPTCHA if TCGplayer shows one
  4. Done — back to headless mode until the next expiry

​
Sync Schedule

Configure how often the agent syncs in Hoard Settings:
ScheduleBest for
Every 4 hoursMost sellers (default)
Every 2 hoursHigh-volume stores
Every hourCompetitive pricing
Once dailyLow-volume or testing
The agent must be running for syncs to happen. If it’s off during a scheduled sync, it picks up on the next poll.

​
What happens during a sync

1. Login check         — verify TCGplayer session is valid
2. Export inventory     — download your current pricing CSV
3. Upload to Hoard     — send inventory data to the server
4. Export orders        — download recent order history
5. Upload orders        — send order data to the server
6. Sales reports        — download and upload financial data
7. Price updates        — download repricing CSV from Hoard
8. Import prices        — upload new prices to TCGplayer
Steps 4-8 are non-fatal. If orders or sales reports fail, the inventory sync still completes.