# Request Connectivity

> The connect operation on whisper.agents: pick a tier, read back the proxy connection string or the WireGuard configuration, and use what it returns.

*Source: https://www.whisper.security/docs/control-plane/operations/connect*

---
`connect` hands back everything a client needs to send traffic from an agent's `/128`. It needs `dns:connect`.

## connect

```whisper-call
CALL whisper.agents({op: 'connect', args: {agent: 'checkout-bot', tier: 'socks5'}})
```

### Arguments

| Argument | Contract |
|---|---|
| `agent` | Optional. Names the agent to connect. Accepts an identifier or an address. |
| `tier` | `socks5` is the default. `wireguard` asks for a routed tunnel, `anyip` for a source-bound path. [Connectivity tiers](/docs/network/egress/tiers) says what each one gives you. |
| `public_key` | Your WireGuard public key. Send it with `tier: 'wireguard'`. |

### Returns, on every tier

| Column | Holds |
|---|---|
| `tier` | The tier you were actually given. |
| `address` | The `/128` traffic will leave from. |
| `fqdn` | The canonical name of that address. |

### Returns, on a proxy tier

| Column | Holds |
|---|---|
| `connection_string` | A ready-to-use SOCKS5 URL with the bearer in it. |
| `socks5_endpoint` | Host and port for a SOCKS5 client. |
| `http_proxy` | The same path as an HTTP proxy URL. |
| `dns` | The resolver to use over that path. |
| `doh_url` | The encrypted-DNS URL for the same identity. |

### Returns, on a WireGuard tier

| Column | Holds |
|---|---|
| `wireguard_config` | A complete configuration file. |
| `server_public_key` | The peer's public key. |
| `endpoint` | Host and port of the peer. |
| `client_private_key` | Your side's private key, when Whisper generated the pair. |
| `dns` | The resolver to use inside the tunnel. |

## Use what the answer gives you

Read the endpoint out of `connection_string`, `http_proxy` or `wireguard_config` rather than writing a host name into your own configuration, because the answer is what is current for your account. Where a name has to appear in prose, the proxy path is `connect.whisper.online:443` and the HTTP form is `egress.whisper.online`. The proxy user name is the literal `w`, and the password is the bearer.

## The bearer

The credential in `connection_string` has the form `et_...`. It is bound to the agent's own `/128` and is refused from any other source address, so a leaked bearer does not move. It can also travel as a header:

```text
Proxy-Authorization: Bearer et_...
```

[Egress authentication](/docs/network/egress/auth) covers the header forms and the certificate-based alternative. To prove the path is working end to end, [Send traffic from your address](/docs/network/egress/connect) walks the check.

## Errors

| Code | Status | Meaning |
|---|---|---|
| `BAD_ARGS` | 400 | `tier` is not one of the accepted values, or `public_key` is malformed. |
| `NOT_FOUND` | 404 | No such agent under this account. |
| `AGENT_REVOKED` | 403 | The identity has been cut and cannot be connected. |
| `WG_KEY_IN_USE` | 409 | That public key is already bound to another identity. Generate a new pair. |