Request Connectivity
Ask for the credentials and configuration that make traffic leave from an agent's own address.
On this page (8)
Request Connectivity Documentation
connect hands back everything a client needs to send traffic from an agent's /128. It needs dns:connect.
connect
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 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:
Proxy-Authorization: Bearer et_...
Egress authentication covers the header forms and the certificate-based alternative. To prove the path is working end to end, Send traffic from your address 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. |