> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhoard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hoard Agent Setup

> Run Hoard Agent from the command line on Mac, Windows, or Linux.

This guide covers running Hoard Agent as a standalone command-line program. This is the right path if you're on Linux, want to script Hoard Agent, or just prefer the terminal.

<Info>
  Prefer a point-and-click setup? See the [Hoard Desktop Quick Start](/quickstart) instead. Hoard Desktop handles account connection, downloads, and auto-start for you.
</Info>

## What Hoard Agent does

Hoard Agent is the same binary that Hoard Desktop manages for you, just without the GUI wrapper. It runs in your terminal, syncs your TCGplayer inventory on a schedule, and updates your prices. You manage starting, stopping, and auto-start yourself.

## Requirements

* A computer that stays on during sync times (Mac, Windows, or Linux)
* A TCGplayer seller account (Level 4+)
* A Hoard subscription (Gold, Platinum, or Diamond) with API key

<Note>
  If Chrome isn't installed, Hoard Agent downloads a compatible Chromium automatically on first run (\~200MB, one time).
</Note>

## Download

Get Hoard Agent from the [Hoard setup page](https://www.tryhoard.com/onboarding) — expand **Advanced: manual agent setup (terminal)**. You'll download two things:

* `hoard-agent` (or `hoard-agent.exe` on Windows) — the binary
* `.env` — a configuration file with your API key already filled in

Hoard Agent fetches its automation workflow from Hoard at startup and keeps it current on its own, so there's nothing else to download or manage.

## Configuration

Open the `.env` file. Both required values are already filled in:

```bash theme={null}
# Both required
HOARD_API_KEY=your-api-key-from-dashboard
HOARD_API_URL=https://www.tryhoard.com

# Optional
# HEADED=1                       # Show browser window (useful for debugging)
# DEBUG=1                        # Verbose logging + failure screenshots
# HOARD_AGENT_ADOPT_CHROME=false # Opt out of session preservation across restarts (defaults on)
```

<Note>
  `HOARD_API_URL` tells the agent which server to talk to. The generated `.env` includes it, and the agent defaults to `https://www.tryhoard.com` if it's ever missing — only change it if you're self-hosting.
</Note>

<Tip>
  Session preservation across restarts is on by default. When Hoard Agent restarts (auto-update, crash recovery, manual restart), it attaches to the live browser you logged into earlier instead of killing it and relaunching — so you don't get bounced to the TCGplayer login page. The same behavior is controlled by the **Preserve TCGplayer session across restarts** checkbox in Hoard Desktop. Set `HOARD_AGENT_ADOPT_CHROME=false` to opt out.
</Tip>

<Tip>
  Your `.env` file stays on your machine. Keep it private — it contains your Hoard API key. Hoard Agent does not store your TCGplayer password; you log into TCGplayer in the browser window.
</Tip>

## First run

The first run opens a visible browser window so you can log into TCGplayer. This is needed because TCGplayer shows a CAPTCHA on login that Hoard can't solve for you. After this one-time login, your session is saved and future syncs run in the background.

<Tabs>
  <Tab title="Mac">
    ```bash theme={null}
    # Remove the macOS quarantine flag (one time, same as any app from the internet)
    xattr -d com.apple.quarantine hoard-agent

    # First run — opens a browser so you can log into TCGplayer
    HEADED=1 ./hoard-agent
    ```

    <Tip>
      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**.
    </Tip>
  </Tab>

  <Tab title="Windows">
    ```cmd theme={null}
    set HEADED=1
    hoard-agent.exe
    ```

    <Tip>
      Windows SmartScreen may show "Windows protected your PC." Click **More info**, then **Run anyway**. This only happens on first launch.
    </Tip>
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    chmod +x hoard-agent
    HEADED=1 ./hoard-agent
    ```
  </Tab>
</Tabs>

What happens:

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. Hoard 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

## Running in the background

After the first login, run without `HEADED=1`:

```bash theme={null}
./hoard-agent
```

Hoard Agent polls the Hoard server every 30 seconds, syncs when the server says it's time (based on your sync schedule), and uses saved cookies from the first login.

To keep it running after you close the terminal:

<Tabs>
  <Tab title="Mac (launchd)">
    Create `~/Library/LaunchAgents/com.tryhoard.agent.plist`:

    ```xml theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
      <key>Label</key>
      <string>com.tryhoard.agent</string>
      <key>ProgramArguments</key>
      <array>
        <string>/path/to/hoard-agent</string>
      </array>
      <key>EnvironmentVariables</key>
      <dict>
        <key>HOARD_API_KEY</key>
        <string>your-api-key</string>
        <key>HOARD_API_URL</key>
        <string>https://www.tryhoard.com</string>
      </dict>
      <key>RunAtLoad</key>
      <true/>
      <key>KeepAlive</key>
      <true/>
    </dict>
    </plist>
    ```

    Then load it:

    ```bash theme={null}
    launchctl load ~/Library/LaunchAgents/com.tryhoard.agent.plist
    ```
  </Tab>

  <Tab title="Linux (systemd)">
    Create `~/.config/systemd/user/hoard-agent.service`:

    ```ini theme={null}
    [Unit]
    Description=Hoard Sync Agent

    [Service]
    ExecStart=/path/to/hoard-agent
    Environment=HOARD_API_KEY=your-api-key
    Environment=HOARD_API_URL=https://www.tryhoard.com
    Restart=always
    RestartSec=30

    [Install]
    WantedBy=default.target
    ```

    Then enable and start it:

    ```bash theme={null}
    systemctl --user enable hoard-agent
    systemctl --user start hoard-agent
    ```
  </Tab>

  <Tab title="Windows (Task Scheduler)">
    Open Task Scheduler and create a new task:

    * **Trigger:** At log on
    * **Action:** Start a program
    * **Program:** `C:\path\to\hoard-agent.exe`
    * **Start in:** `C:\path\to\` (the folder containing the binary and your `.env`)

    Add the `HOARD_API_KEY` and `HOARD_API_URL` environment variables to your system or user environment (or keep them in the `.env` file next to the binary).
  </Tab>
</Tabs>

<Tip>
  If you'd rather skip all of this, [Hoard Desktop](/quickstart) handles auto-start for you on Mac and Windows. It's the same binary, just with a wrapper that manages the lifecycle.
</Tip>

## Session expiry

Like any website, TCGplayer sessions expire after a few days. When this happens:

1. You'll see "session expired" in the log output
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 background mode until the next expiry

In practice, sessions last anywhere from 3 to 7 days. Hoard Agent will keep trying to sync and logging "session expired" until you re-login, it won't crash or lose data.

<Warning>
  **Headless Linux servers:** If Hoard Agent runs on a server or a machine without a display, you'll need a way to handle session re-login. A few options:

  * **SSH with X forwarding.** `ssh -X yourserver` then run `HEADED=1 ./hoard-agent`. The browser window appears on your local machine.
  * **VNC or remote desktop.** Connect to the server's desktop, run Hoard Agent headed, log in, then disconnect. The session persists.
  * **Hoard Desktop on a desktop machine.** If re-login friction is a dealbreaker, run Hoard on a Mac or Windows machine where you can interact with the browser directly. Hoard doesn't need much resources, any machine that stays on will do.

  Hoard sends you an email if Hoard Agent has been offline for more than 24 hours, so you'll know when a session expires even if you're not watching the logs.
</Warning>

## Sync schedule

Configure how often Hoard Agent syncs in [Settings → Sync](https://www.tryhoard.com/settings/sync). How often you can sync depends on your plan:

| Schedule              | Best for                                  |
| --------------------- | ----------------------------------------- |
| Every 4 hours         | High-volume stores                        |
| Every 8 hours         | Moderate-volume stores                    |
| Every 12 hours        | Lower-volume stores                       |
| Once daily (24 hours) | Low-volume or just starting out (default) |

Hoard Agent must be running for syncs to happen. If it's off during a scheduled sync, it picks up on the next poll.

Settings > Sync also lets you pin a preferred local hour, set quiet hours, and choose allowed days of week. Those controls affect when the server tells Hoard Agent to run; you do not need to restart the agent after changing them.

## What happens during a sync

```
1. Login check            — verify TCGplayer session is valid
2. Export inventory        — for each product line, download your pricing CSV
3. Upload to Hoard         — for each product line, 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 2 and 3 repeat for each product line enabled in Settings. Inventory-detected games are pinned in Settings, and less common TCGplayer games can be added through search.

Steps 4-8 are non-fatal. If orders or sales reports fail, the inventory sync still completes.

### Cooldown after failures

If a sync fails on a critical step (login, export, or upload), Hoard Agent backs off and waits before retrying. The cooldown escalates: 5 minutes, then 10, then 30 (capped). This keeps it from hammering TCGplayer when something is genuinely wrong. You'll see the cooldown status in your terminal.

## Your data stays on your computer

| What                      | Where                                  | Sent to Hoard?                           |
| ------------------------- | -------------------------------------- | ---------------------------------------- |
| TCGplayer session cookies | Stored locally on your computer        | Never                                    |
| Hoard API key             | Your `.env` file                       | Yes (to authenticate syncs)              |
| Inventory & order data    | Exported from TCGplayer by Hoard Agent | Yes (this is what powers your dashboard) |

## Hoard Desktop vs Hoard Agent — switching later

If you started with Hoard Agent and want to switch to Hoard Desktop, just download the desktop app. It'll detect your existing config at `~/.config/hoard/agent.env` and pick up where you left off.

Going the other way: if you have Hoard Desktop and want to switch to Hoard Agent, grab the standalone binary from the [Hoard setup page](https://www.tryhoard.com/onboarding) (expand **Advanced: manual agent setup (terminal)**), copy your `HOARD_API_KEY` and `HOARD_API_URL` from `~/.config/hoard/agent.env` into the `.env` file next to the binary, and run from your terminal.