<!-- Source: https://ports.io/docs/guides/quickstart.md -->

# Make your first request

> Make your first request with an HTTP proxy or SOCKS5 with remote DNS.
>
> Web page: https://ports.io/docs/guides/quickstart/
> Documentation index: https://ports.io/llms.txt

Connect your client to an HTTP proxy or authenticated SOCKS5 endpoint with a routing username and your workspace's secret key. This guide makes one HTTPS request using a rotating route.

## Before you begin

You need access to a workspace, permission to create an API key, and the proxy endpoint assigned to your account. An owner or admin can create a key.

Set `PORTS_PROXY_URL` to your assigned proxy URL, including its scheme, hostname, and port. Obtain this URL before running the examples. It is separate from the console URL and from the destination website's URL.

| Proxy type | URL format for curl |
| --- | --- |
| HTTP proxy | `http://HOST:PORT` |
| HTTP proxy over TLS | `https://HOST:PORT` |
| SOCKS5 with remote DNS | `socks5h://HOST:PORT` |

These are formats, not real endpoints. For SOCKS5, use the assigned SOCKS port and `socks5h://` so the destination hostname reaches the proxy. curl's `socks5://` mode resolves locally and sends an IP address, which the gateway rejects. Destination URLs must use hostnames, even with remote DNS enabled.

The SOCKS port can differ from the HTTPS proxy port. `socks5h://` does not add TLS to the proxy connection; changing the scheme of an HTTPS proxy URL while retaining its TLS-only port will not work. See [Protocols and limits](https://ports.io/docs/reference/protocols-and-limits.md) for transport details.

## Create a key

1. Sign in to the console and select your workspace.
2. Open **API keys** and select **Create key**.
3. Give the key a recognizable name, such as `Integration development`, and choose when it expires.
4. Copy the full `rp1_...` secret when it appears. The console shows it only once.
5. Store the secret in your application's secret store. Supply it to the examples as the `PORTS_PROXY_KEY` environment variable.

The full secret is the proxy password. A key name, key ID, or masked suffix cannot authenticate a request.

## Send an HTTPS request

Use `v1_rotate` as the username. The username selects the route; the password authenticates your workspace's key.

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

On Windows PowerShell, use the environment-variable syntax below and call `curl.exe` explicitly.

```powershell
curl.exe --proxy "$env:PORTS_PROXY_URL" --proxy-user "v1_rotate:$env:PORTS_PROXY_KEY" --connect-timeout 10 --max-time 30 https://example.com/
```

The command works with any of the proxy URL formats above. `--proxy-user` supplies the routing username and full key for either HTTP Basic authentication or SOCKS5 username/password authentication. The client establishes the corresponding tunnel, then performs TLS with the HTTPS destination. An `https://` HTTP proxy URL additionally protects the connection to the proxy with TLS. Keep certificate verification enabled.

These timeouts are client settings for the example. Adjust them to your application.

## Recognize success

A successful request returns the destination's response body. Successful HTTP or SOCKS5 tunnel setup by itself only means the tunnel opened; inspect the destination response to confirm the request succeeded.

If HTTP authentication fails with `407`, or SOCKS5 reports authentication failure, check the full secret, key expiration, routing username, and workspace status. If SOCKS5 reports a connection-not-allowed reply, check that remote DNS is enabled and the destination is a hostname. See [errors and troubleshooting](https://ports.io/docs/reference/troubleshooting.md).

## Choose your next step

- Use [curl](https://ports.io/docs/guides/curl.md), [Python](https://ports.io/docs/guides/python.md), or [JavaScript](https://ports.io/docs/guides/javascript.md) in your application.
- Add [country and region targeting](https://ports.io/docs/reference/username-reference.md).
- Keep related connections together with a [sticky or fixed session](https://ports.io/docs/reference/sessions.md).
- Read [usage measurement](https://ports.io/docs/guides/usage.md) before comparing proxy traffic with application payload sizes.

---

<!-- Source: https://ports.io/docs/guides/curl.md -->

# Use curl

> Configure HTTP or socks5h proxies and inspect failures with curl.
>
> Web page: https://ports.io/docs/guides/curl/
> Documentation index: https://ports.io/llms.txt

Use curl to make a request through an HTTP or SOCKS5 proxy and inspect a connection before configuring a larger application. Set `PORTS_PROXY_URL` to your assigned proxy URL, including its scheme, hostname, and port. Supply the full `rp1_...` key as `PORTS_PROXY_KEY`.

## Configure the proxy transport

| Proxy URL format | Behavior |
| --- | --- |
| `http://HOST:PORT` | HTTP proxy over plaintext TCP |
| `https://HOST:PORT` | HTTP proxy with TLS to the proxy |
| `socks5h://HOST:PORT` | SOCKS5 with the destination hostname resolved by the exit |

These show formats only. Use your assigned endpoint, without embedded credentials, and keep the assigned port. A standard `socks5h://` connection uses plaintext TCP to the proxy, so it cannot be pointed directly at an HTTPS proxy's TLS-only port.

For SOCKS5, use `socks5h://` rather than curl's locally resolving `socks5://` mode. The gateway requires a hostname and rejects destination IP addresses. `--socks5-hostname HOST:PORT` is curl's equivalent remote-DNS option. See the [curl options reference](https://curl.se/docs/manpage.html#--socks5-hostname).

## Request an HTTPS URL

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

`--proxy` identifies the proxy; `--proxy-user` supplies the routing username and full key for HTTP Basic or SOCKS5 username/password authentication. The final URL is the destination and must contain a hostname. curl opens an HTTP CONNECT or SOCKS5 tunnel, then negotiates TLS with the HTTPS destination. Keep certificate verification enabled. The timeouts here are example client settings. [curl options reference](https://curl.se/docs/manpage.html).

The password is the complete secret shown when you created a key. Keep it out of source control, shared logs, and pasted diagnostics. Command arguments can be visible to other processes; use your environment's protected credential-loading method for unattended execution.

## Select a country

Change the username while keeping the same endpoint and password.

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate_countries_US:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

The route requires an eligible United States exit. A valid country code is a filter, not a guarantee that an exit is currently available. See [routing](https://ports.io/docs/reference/username-reference.md).

## Reuse a sticky route

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_sticky_session_checkout-42:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

Use the same session ID for connections that belong together. Sticky sessions permit failover when the selected exit becomes unavailable. `v1_fixed_session_checkout-42` requests a route that does not fail over. See [sessions](https://ports.io/docs/reference/sessions.md) before choosing between them.

## Inspect a failure

For a local investigation, add `--verbose` to see connection stages. Redact proxy credentials and any destination credentials before sharing output. An error during proxy negotiation, authentication, or tunnel setup happens before the destination response; an HTTP error after tunnel establishment can come from the destination. SOCKS5 setup errors are not HTTP statuses or JSON error codes. See [errors and troubleshooting](https://ports.io/docs/reference/troubleshooting.md).

On Windows PowerShell, use `curl.exe`, read variables as `$env:PORTS_PROXY_URL` and `$env:PORTS_PROXY_KEY`, and put the command on one line.

---

<!-- Source: https://ports.io/docs/guides/python.md -->

# Use Python

> Use Requests with HTTP proxies or socks5h for remote DNS.
>
> Web page: https://ports.io/docs/guides/python/
> Documentation index: https://ports.io/llms.txt

Configure Python Requests with the same proxy for HTTP and HTTPS destinations. The proxy can be HTTP, HTTPS, or SOCKS5 with remote DNS. You need your assigned proxy URL supplied as `PORTS_PROXY_URL` and the full `rp1_...` key supplied as `PORTS_PROXY_KEY`.

## Install Requests

```sh
python -m pip install "requests[socks]"
```

The `socks` extra installs the optional SOCKS dependencies. It also supports the HTTP proxy example below. [Requests SOCKS documentation](https://requests.readthedocs.io/en/latest/user/advanced/#socks).

## Make a request

Set `PORTS_PROXY_URL` to your assigned proxy URL without embedded credentials. Use `http://` or `https://` for an HTTP proxy, or `socks5h://` with the assigned SOCKS hostname and port. Requests' `socks5://` mode resolves destinations locally and sends IP addresses, which this gateway rejects.

The SOCKS port can differ from the HTTPS proxy port. `socks5h://` does not establish TLS to the proxy, so do not reuse a TLS-only proxy port by changing the scheme alone. The destination URL must contain a hostname. This example reads credentials at runtime and encodes them for use inside a proxy URL.

```python
import os
from urllib.parse import quote, urlsplit

import requests

endpoint = urlsplit(os.environ["PORTS_PROXY_URL"])
if endpoint.scheme not in {"http", "https", "socks5h"} or not endpoint.hostname:
    raise ValueError("PORTS_PROXY_URL must use http://, https://, or socks5h://")
if endpoint.scheme == "socks5h" and endpoint.port is None:
    raise ValueError("Include the assigned SOCKS proxy port in PORTS_PROXY_URL")
password = quote(os.environ["PORTS_PROXY_KEY"], safe="")
username = "v1_rotate"
proxy = f"{endpoint.scheme}://{quote(username, safe='')}:{password}@{endpoint.netloc}"

response = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    timeout=(10, 30),
)
response.raise_for_status()
print(response.status_code)
print(response.text)
```

The dictionary keys identify destination URL schemes, so they remain `http` and `https` when both values contain a `socks5h://` proxy URL. For SOCKS5, Requests sends the hostname for the exit to resolve; for an HTTP proxy and HTTPS destination, it establishes an HTTP CONNECT tunnel. TLS to the HTTPS destination is then negotiated through either tunnel. An `https://` HTTP proxy URL also encrypts the connection to the proxy. Passing `proxies` per request makes the intended configuration explicit. [Requests proxy documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).

`timeout=(10, 30)` sets connect and read timeouts in seconds; it is not a total download deadline. `raise_for_status()` raises for an unsuccessful destination HTTP status. [Requests API](https://requests.readthedocs.io/en/latest/api/#requests.request).

Keep TLS verification enabled and avoid logging the proxy URL.

## Target a country or reuse a route

Replace the username in the example with a routing policy:

```python
# Eligible United States exits.
username = "v1_rotate_countries_US"

# Related connections use the same sticky session.
username = "v1_sticky_session_job-42_countries_US"

# The session does not fail over to another exit.
username = "v1_fixed_session_job-42_countries_US"
```

Rebuild the proxy URL after changing the username. See [routing](https://ports.io/docs/reference/username-reference.md) and [sessions](https://ports.io/docs/reference/sessions.md) for filter and failover behavior.

## Understand connection reuse

A Requests `Session` can reuse established connections through HTTP or SOCKS5 proxies. `v1_rotate` selects an exit when a new tunnel opens, so several requests sent through one existing tunnel do not trigger a new exit selection. A rotation can also select the same eligible exit again. [Requests session documentation](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects).

Treat a Requests session, a proxy routing session ID, and destination cookies as separate concepts. A routing session controls exit selection; it does not manage your application's cookies.

---

<!-- Source: https://ports.io/docs/guides/javascript.md -->

# Use JavaScript

> Use Undici for HTTP proxies or SOCKS5 with destination DNS at the proxy.
>
> Web page: https://ports.io/docs/guides/javascript/
> Documentation index: https://ports.io/llms.txt

Use an HTTP client with explicit proxy support for server-side JavaScript. This example uses Undici's `ProxyAgent` for HTTP proxies and `Socks5ProxyAgent` for SOCKS5. You need your assigned proxy URL supplied as `PORTS_PROXY_URL` and the full `rp1_...` key supplied as `PORTS_PROXY_KEY`.

## Install the client

This example uses Undici 8.11.2, which requires Node.js 22.19.0 or later. Its SOCKS5 agent is marked experimental. Check the [Undici installation and compatibility table](https://github.com/nodejs/undici#install) when selecting a version for another runtime.

```sh
npm install undici@8.11.2
```

## Make a request

Save this example as `proxy-request.mjs`. Set `PORTS_PROXY_URL` to your assigned `http://`, `https://`, or `socks5h://` proxy URL, including its hostname and port, without embedded credentials. Supply the secret through `PORTS_PROXY_KEY`. The destination URL must contain a hostname.

```javascript
import { fetch, ProxyAgent, Socks5ProxyAgent } from "undici";

const endpoint = process.env.PORTS_PROXY_URL;
const password = process.env.PORTS_PROXY_KEY;
if (!endpoint || !password) {
  throw new Error("Set PORTS_PROXY_URL and PORTS_PROXY_KEY");
}

const username = "v1_rotate";
const uri = new URL(endpoint);
let proxy;
if (uri.protocol === "socks5h:") {
  if (!uri.port) {
    throw new Error("Include the assigned SOCKS proxy port in PORTS_PROXY_URL");
  }
  // This agent sends hostnames to the proxy but accepts socks5: URLs.
  uri.protocol = "socks5:";
  proxy = new Socks5ProxyAgent(uri, {
    username,
    password,
    connectTimeout: 10_000,
  });
} else if (uri.protocol === "http:" || uri.protocol === "https:") {
  const credentials = Buffer.from(`${username}:${password}`).toString("base64");
  proxy = new ProxyAgent({
    uri,
    token: `Basic ${credentials}`,
  });
} else {
  throw new Error("PORTS_PROXY_URL must use http://, https://, or socks5h://");
}

try {
  const response = await fetch("https://example.com/", {
    dispatcher: proxy,
    signal: AbortSignal.timeout(30_000),
  });
  const body = await response.text();
  if (!response.ok) {
    throw new Error(`Destination returned HTTP ${response.status}`);
  }
  console.log(response.status);
  console.log(body);
} finally {
  await proxy.close();
}
```

The agent is passed as the request's dispatcher. The HTTP branch attaches Basic credentials and uses HTTP CONNECT for the HTTPS destination. The SOCKS5 branch sends the routing username and full key in the SOCKS authentication handshake, then requests a tunnel to the destination hostname. Consume the response body and close the agent when it is no longer needed. [Undici ProxyAgent documentation](https://github.com/nodejs/undici/blob/v8.11.2/docs/docs/api/ProxyAgent.md).

## SOCKS5 and remote DNS

Undici's `Socks5ProxyAgent` always sends destination hostnames to the proxy for resolution, but accepts `socks5:` or `socks:` URLs rather than `socks5h:`. The example adapts the configured `socks5h:` scheme for that agent while preserving the hostname, port, and remote-DNS behavior. It rejects plain `socks5://` in the shared application configuration so that the same value remains safe to use with curl or Requests.

Keep the assigned SOCKS port: a standard SOCKS connection does not establish TLS to the proxy. SOCKS5 over TLS requires the assigned TLS endpoint and explicit `proxyTls` options; the example's SOCKS branch uses plaintext TCP to the proxy. TLS verification remains enabled for the HTTPS destination. [Undici Socks5ProxyAgent documentation](https://github.com/nodejs/undici/blob/v8.11.2/docs/docs/api/Socks5ProxyAgent.md).

`AbortSignal.timeout(30_000)` requests cancellation after 30 seconds. Adjust this client setting to your application's needs. [Node.js AbortSignal documentation](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay).

Keep proxy authentication in the agent configuration. Do not put the proxy secret into a destination `Authorization` header or log the proxy URL or credentials; Base64 encoding in the HTTP branch is reversible.

## Select the route

Change the username before constructing the agent:

```javascript
const username = "v1_rotate_countries_US";
// Or: "v1_sticky_session_job-42_countries_US"
// Or: "v1_fixed_session_job-42_countries_US"
```

See [routing](https://ports.io/docs/reference/username-reference.md) and [sessions](https://ports.io/docs/reference/sessions.md) for the meaning of these policies.

## Understand connection reuse

An HTTP or SOCKS5 agent can reuse its connection to a destination. The proxy selects an exit when a new tunnel opens. Reusing one tunnel with `v1_rotate` does not rotate the exit for every application request. [Undici connection behavior](https://github.com/nodejs/undici/blob/v8.11.2/docs/docs/api/ProxyAgent.md).

Browser JavaScript does not accept an Undici dispatcher. Keep the proxy secret in your application's server-side configuration.

---

<!-- Source: https://ports.io/docs/guides/usage.md -->

# Understand usage measurement

> What the console's traffic counters include.
>
> Web page: https://ports.io/docs/guides/usage/
> Documentation index: https://ports.io/llms.txt

The console reports traffic by API key and shows a workspace usage chart. Use these measurements to understand traffic direction and trends; the bytes can differ from the payload sizes your application records.

## What the counters mean

| Counter | Meaning |
| --- | --- |
| Uploaded | Bytes sent toward the destination through the upstream connection. |
| Downloaded | Bytes received from the destination through the upstream connection. |
| Total | Uploaded bytes plus downloaded bytes. |

The counters include bytes carried by the upstream connection, such as forwarded HTTP headers. For HTTPS destinations reached through HTTP CONNECT or SOCKS5, the encrypted TLS traffic is carried on that connection. HTTP proxy setup messages and SOCKS5 negotiation, authentication, and CONNECT messages between your client and the proxy are excluded.

HTTP and SOCKS5 use the same per-key usage measurements. Application bytes sent alongside a SOCKS5 handshake are counted when they pass through the established upstream tunnel; sending them early does not exclude them from usage.

```text
uploaded bytes + downloaded bytes = total bytes
```

The totals count bytes, not requests. One tunnel can carry more than one HTTPS request.

## Read the console

Open **Usage** in the console. Its **Usage by API key** table shows recorded totals for each key and retains entries for revoked keys. Revoking a key does not remove its prior usage history. The per-key table is shown to workspace owners and admins; every member sees the workspace chart.

The workspace chart supports these ranges:

| Range | Chart grouping |
| --- | --- |
| 24 hours | Hourly buckets |
| 7 days | Daily buckets |
| 30 days | Daily buckets |

The chart range selects its time-series window, and its buckets are aligned to UTC. The per-key totals are recorded cumulative totals; they do not change to the chart's selected date range.

The console formats byte values using binary units: `1 KiB = 1,024 bytes`, `1 MiB = 1,048,576 bytes`, and `1 GiB = 1,073,741,824 bytes`.

## Allow for reporting delay

Usage arrives asynchronously. Select **Refresh** to retrieve currently available totals. During an outage, usage may appear later; an unchanged counter immediately after a request is not proof that no traffic passed through the proxy.

Compare the same key and time window when investigating a discrepancy. Include the key's non-secret ID or name, approximate request times, and the client behavior. Keep the secret password out of diagnostics.

## Separate usage from pricing

This page defines the current traffic measurements. It does not specify prices, free allowances, charging increments, invoice timing, or a billing accuracy guarantee. Refer to the commercial terms provided for your account when interpreting a charge.

---

<!-- Source: https://ports.io/docs/guides/ai-tools.md -->

# Use these docs with AI tools

> Set up ports.io with Claude Code, Codex, Cursor or another AI assistant.
>
> Web page: https://ports.io/docs/guides/ai-tools/
> Documentation index: https://ports.io/llms.txt

Claude Code, Codex, Cursor and other coding assistants can configure your client from these pages. Give the assistant the pages your task needs, add a few standing instructions to your project, then review what it writes. Every documentation page is also published as a static Markdown file.

## Copy or open a page as Markdown

Under the title of every page:

- **Copy page** copies the page's complete Markdown, including every code example, ready to paste into an assistant.
- **View as Markdown** opens the same text as a plain file.
- **Download** saves that file so you can attach it to your assistant.

The Markdown files work without browser JavaScript. Copying uses your browser's clipboard access.

## Fetch Markdown directly

Every page's Markdown sits at its address with `.md` in place of the final slash. For the page at `https://ports.io/docs/reference/authentication/`, fetch `https://ports.io/docs/reference/authentication.md`. The overview is at `https://ports.io/docs.md`.

```sh
curl --fail --show-error --location \
  https://ports.io/docs/reference/authentication.md \
  --output ports-authentication.md
```

Each file starts with the page's title and summary, then a line linking the documentation index. Its links point at other pages' Markdown files, so an assistant can follow them without loading the website.

## Discover only the pages you need

| File | Use it for |
| --- | --- |
| [llms.txt](https://ports.io/llms.txt) | An index of every page, with a summary and its Markdown address. Start here. |
| [Guides index](https://ports.io/docs/guides/llms.txt) | Getting started and the language guides only. |
| [Reference index](https://ports.io/docs/reference/llms.txt) | Routing rules, keys, limits, and errors only. |
| [Guides bundle](https://ports.io/docs/guides/llms-full.txt) | Every guide in one file. |
| [Reference bundle](https://ports.io/docs/reference/llms-full.txt) | The whole reference in one file. |
| [llms-full.txt](https://ports.io/llms-full.txt) | All the documentation in one file, for offline indexing or a task that needs everything. |
| [Page manifest](https://ports.io/docs/docs.json) | Titles, summaries, and addresses as JSON, for tools that list pages programmatically. |

Start with `llms.txt`, then fetch the pages the task needs. Use a section bundle before the complete bundle when the task has a narrow scope. A tool must fetch or receive the text to use it; the files do not configure an assistant by themselves.

## Save the pages in your project

Saved Markdown files give an assistant the complete text in every session, without a network request. Download the pages a client integration needs into a folder in your project:

```sh
mkdir -p ports-io-docs
for page in guides/quickstart reference/authentication \
  reference/username-reference reference/sessions \
  reference/troubleshooting guides/python; do
  curl --fail --show-error --location \
    "https://ports.io/docs/$page.md" \
    --output "ports-io-docs/${page#*/}.md"
done
```

Replace `guides/python` with `guides/javascript` or `guides/curl` for another client, and add `reference/targeting` if you filter by location. The pages contain no secrets.

## Add standing instructions

Coding assistants read a project instructions file at the start of each session. Add a short ports.io section so every session follows the same rules:

```markdown
## ports.io proxy

- Before changing proxy code, read the ports.io pages in ports-io-docs/.
  The index of every page is https://ports.io/llms.txt.
- Read PORTS_PROXY_URL and PORTS_PROXY_KEY from the environment.
  Never print, log, or commit the key.
- The proxy username is a routing rule such as v1_rotate.
  The full key is the password.
- For SOCKS5 with curl or Requests, use socks5h:// so the proxy resolves hostnames.
- Keep TLS verification on. Never invent a proxy hostname or port.
```

Each assistant reads this section from its own file, described below. One `AGENTS.md` at your project root can serve Claude Code, Codex, and Cursor together.

## Claude Code

Put the section in `CLAUDE.md` at your project root. Claude Code reads it at the start of every session. Claude Code v2.1.277 and later also read `AGENTS.md` when the project has no `CLAUDE.md`. If your project has both, add the line `@AGENTS.md` to `CLAUDE.md` so Claude Code reads both.

A line such as `@ports-io-docs/authentication.md` in `CLAUDE.md` loads that page into every session. Import only the pages most tasks need, since each import takes up context.

Claude Code can also read the online pages when your prompt includes their addresses. Its web fetch can ask for permission first, and it gives Claude an extract of the page rather than the whole file. For exact code examples, use the saved pages or ask Claude Code to download the Markdown with `curl`. [Claude Code memory documentation](https://code.claude.com/docs/en/memory).

## Codex

Put the section in `AGENTS.md` at your project root. Codex reads `AGENTS.md` files from the project root down to your working directory, and your personal instructions from `~/.codex/AGENTS.md`.

By default, Codex runs commands without network access and asks before a command needs the network. Its default web search answers from a cached index rather than fetching live pages. Save the pages before you start Codex, or approve the download when it asks. [Codex AGENTS.md documentation](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

## Cursor

Put the section in `AGENTS.md` at your project root, and Cursor applies it automatically. For more control over when the instructions apply, use a project rule in `.cursor/rules` instead.

In a chat, @-mention a saved page such as `ports-io-docs/authentication.md`, or paste a page's address into your prompt so the agent reads that page. [Cursor rules documentation](https://cursor.com/docs/rules).

## Ask for the integration

For a client integration, supply the quickstart, authentication reference, your language guide, and any required targeting or session pages. Then ask for the change:

```text
Use the ports.io documentation to configure my Python HTTP client.
Read the saved pages in ports-io-docs/ first: the quickstart,
authentication, username, and Python pages. If a page you need
is missing, find it from https://ports.io/llms.txt.

Requirements:
- Read PORTS_PROXY_URL and PORTS_PROXY_KEY from the environment.
- Preserve the supplied proxy transport, hostname, and port.
- For SOCKS5, use remote DNS: socks5h with curl or Requests,
  or the documented hostname-preserving agent configuration for JavaScript.
- Use a destination hostname, not an IP address.
- Use v1_rotate_countries_US as the proxy username.
- Keep TLS certificate verification enabled.
- Set explicit connect and read timeouts.
- Do not log secrets or invent an endpoint.
- Explain how connection reuse affects rotating routes.

If a required detail is absent, identify it explicitly.
Show a complete example and cite the documentation pages you used.
```

Supply the real key directly to your application's secret configuration, not to the prompt. Keep `PORTS_PROXY_URL` in runtime configuration.

## Review the generated configuration

Check that the complete `rp1_...` key is the proxy password, the routing username follows the [username reference](https://ports.io/docs/reference/username-reference.md), and the proxy URL is separate from the destination URL.

For SOCKS5, check remote DNS and username/password authentication. curl and Requests use `socks5h://`; the JavaScript guide adapts that scheme for an agent that sends hostnames by default. Keep the assigned port and distinguish plaintext SOCKS transport from TLS to the destination. The proxy rejects destination IP addresses.

The assistant should preserve TLS verification, distinguish proxy setup errors from destination responses, and explain that rotation occurs when a new tunnel opens. It should not invent an available location, a session duration, a price, or a service guarantee.

## Keep context current

Download the saved pages again after documentation changes, and re-fetch any page an assistant read online. Ask your assistant to cite the pages that support its behavior claims. Use per-page files for small tasks so unrelated documentation does not take up the context window.