# Proxy Configuration

All outbound HTTP traffic from the Web Search tool -- both search engine API calls and crawler requests to target websites -- can be routed through a corporate proxy. This is a shared platform-level configuration that applies to every search engine and every crawler.

---

## When to Use

Configure a proxy when:

- The `assistants-core` pod runs in a network that does not allow direct outbound internet access.
- Corporate security policies require all external traffic to pass through an inspection proxy.
- You need to control or log which external domains the tool communicates with.

When no proxy variables are set (`PROXY_AUTH_MODE` is `none` and `PROXY_HOST` is empty), all outbound requests go directly to the target without any proxy.

---

## Authentication Modes

The `PROXY_AUTH_MODE` variable determines how the tool authenticates with the proxy:

| Mode                  | Description                                                   |
|-----------------------|---------------------------------------------------------------|
| `none`                | No authentication. The proxy accepts unauthenticated connections. |
| `username_password`   | HTTP Basic authentication. Requires `PROXY_USERNAME` and `PROXY_PASSWORD`. |
| `ssl_tls`            | Mutual TLS (mTLS) authentication. Requires `PROXY_SSL_CERT_PATH` and `PROXY_SSL_KEY_PATH` for the client certificate and key. |

---

## Environment Variables

All proxy variables must be set on the `assistants-core` pod.

### Connection

| Variable        | Type              | Default  | Description                                        |
|------------------|-------------------|----------|----------------------------------------------------|
| `PROXY_PROTOCOL` | `http` / `https`  | `http`   | Protocol used to connect to the proxy.             |
| `PROXY_HOST`    | string            | `null`   | Proxy hostname or IP address.                       |
| `PROXY_PORT`    | integer           | `null`   | Proxy port number.                                  |
| `PROXY_HEADERS`  | JSON dict         | `{}`     | Additional HTTP headers to include on every proxied request. |

### Authentication -- Username / Password

| Variable          | Type      | Default | Description                                     |
|-------------------|-----------|---------|-------------------------------------------------|
| `PROXY_AUTH_MODE` | string    | `none`  | Set to `username_password` to enable.            |
| `PROXY_USERNAME`  | string    | `null`  | Proxy username.                                 |
| `PROXY_PASSWORD`  | string    | `null`  | Proxy password.                                 |

### Authentication -- SSL / TLS (mTLS)

| Variable                      | Type      | Default | Description                                         |
|-------------------------------|-----------|---------|-----------------------------------------------------|
| `PROXY_AUTH_MODE`             | string    | `none`  | Set to `ssl_tls` to enable.                          |
| `PROXY_SSL_CERT_PATH`        | string    | `null`  | Path to the client certificate file (PEM) on the pod filesystem. |
| `PROXY_SSL_KEY_PATH`         | string    | `null`  | Path to the client private key file (PEM) on the pod filesystem. |

### SSL Verification

| Variable                         | Type      | Default | Description                                           |
|----------------------------------|-----------|---------|-------------------------------------------------------|
| `PROXY_SSL_CA_BUNDLE_PATH`      | string    | `null`  | Path to a custom CA bundle for verifying the proxy's TLS certificate. Use when the proxy presents a certificate signed by an internal CA. |

---

## Examples

### No-auth proxy

```
PROXY_PROTOCOL=http
PROXY_HOST=proxy.corp.example.com
PROXY_PORT=8080
```

### Username / password proxy

```
PROXY_AUTH_MODE=username_password
PROXY_PROTOCOL=http
PROXY_HOST=proxy.corp.example.com
PROXY_PORT=8080
PROXY_USERNAME=svc-websearch
PROXY_PASSWORD=<secret>
```

### mTLS proxy with custom CA

```
PROXY_AUTH_MODE=ssl_tls
PROXY_PROTOCOL=https
PROXY_HOST=proxy.corp.example.com
PROXY_PORT=8443
PROXY_SSL_CERT_PATH=/etc/ssl/proxy/client.pem
PROXY_SSL_KEY_PATH=/etc/ssl/proxy/client-key.pem
PROXY_SSL_CA_BUNDLE_PATH=/etc/ssl/proxy/ca-bundle.pem
```