> ## Documentation Index
> Fetch the complete documentation index at: https://proxy-hopper.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Install Proxy Hopper, write a config file, and send your first proxied request.

## Run with Docker

```bash theme={}
docker pull ghcr.io/cams-data/proxy-hopper:latest
```

For the Redis backend (multi-instance HA):

```bash theme={}
docker pull ghcr.io/cams-data/proxy-hopper:latest-redis
```

<Note>
  PyPI packages are not yet published. Docker is the recommended installation method. See [Simple Docker Deployment](/admin/deployment/docker/simple) for full examples.
</Note>

## Write a config file

Create a `config.yaml`. Every config follows a three-tier model:

* **`proxyProviders`** — your proxy supplier's IPs and credentials
* **`ipPools`** — named collections that draw IPs from one or more providers
* **`targets`** — URL routing rules that reference a pool

```yaml theme={}
proxyProviders:
  - name: my-provider
    auth:
      type: basic
      username: user
      password: secret
    ipList:
      - "10.0.0.1:3128"
      - "10.0.0.2:3128"
      - "10.0.0.3:3128"
    regionTag: US-East

ipPools:
  - name: my-pool
    ipRequests:
      - provider: my-provider
        count: 3

targets:
  - name: general
    regex: '.*'
    ipPool: my-pool
    minRequestInterval: 1s
    maxQueueWait: 30s
    numRetries: 3
    ipFailuresUntilQuarantine: 5
    quarantineTime: 2m
```

## Start the server

```bash theme={}
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/etc/proxy-hopper/config.yaml:ro \
  ghcr.io/cams-data/proxy-hopper:latest
```

## Send a request

Add `X-Proxy-Hopper-Target` to your request headers with the destination URL and send it to Proxy Hopper:

<CodeGroup>
  ```bash curl theme={}
  curl -H "X-Proxy-Hopper-Target: https://httpbin.org" \
       http://localhost:8080/get
  ```

  ```python requests theme={}
  import requests

  session = requests.Session()
  session.headers["X-Proxy-Hopper-Target"] = "https://httpbin.org"

  resp = session.get("http://localhost:8080/get")
  print(resp.json())
  ```

  ```python httpx theme={}
  import httpx

  with httpx.Client(
      base_url="http://localhost:8080",
      headers={"X-Proxy-Hopper-Target": "https://httpbin.org"},
  ) as client:
      resp = client.get("/get")
      print(resp.json())
  ```

  ```python aiohttp theme={}
  import aiohttp

  async with aiohttp.ClientSession(
      headers={"X-Proxy-Hopper-Target": "https://httpbin.org"}
  ) as session:
      async with session.get("http://localhost:8080/get") as resp:
          print(await resp.json())
  ```
</CodeGroup>

## Validate a config file

Check your config file without starting the server:

```bash theme={}
docker run --rm \
  -v $(pwd)/config.yaml:/etc/proxy-hopper/config.yaml:ro \
  ghcr.io/cams-data/proxy-hopper:latest \
  proxy-hopper validate --config /etc/proxy-hopper/config.yaml
# Config OK — 1 target(s) defined.
#   'general': 3 IP(s), regex='.*'
# Server defaults: host=0.0.0.0, port=8080, backend=memory
```

## Next steps

<CardGroup cols={2}>
  <Card title="Sending Requests" icon="paper-plane" href="/concepts/sending-requests">
    All control headers and request behaviour.
  </Card>

  <Card title="Config Reference" icon="sliders" href="/admin/configuration/reference">
    Full reference for all configuration fields.
  </Card>

  <Card title="Docker deployment" icon="docker" href="/admin/deployment/docker/simple">
    Production-ready Docker and Compose setups.
  </Card>

  <Card title="Authentication" icon="key" href="/admin/authentication/overview">
    Secure Proxy Hopper with API keys or SSO.
  </Card>
</CardGroup>