# ports.io documentation

> Millions of ethically sourced, consented residential proxies from around the world, without the reseller’s markup.

How to use these docs:

- Every page below is a Markdown file. Fetch only the pages the task needs.
- Configure a client from two environment variables: `PORTS_PROXY_URL`, the proxy URL assigned to the account (scheme, hostname and port), and `PORTS_PROXY_KEY`, the full `rp1_...` key. Never invent a proxy hostname or port.
- The proxy username is a routing instruction, such as `v1_rotate` or `v1_sticky_session_job-42_countries_US`. The key is the password.
- SOCKS5 requires username/password authentication and destination hostnames. Use `socks5h://` for remote DNS with curl or Requests; follow the JavaScript guide for its hostname-preserving agent configuration.
- Keep the assigned port. A standard `socks5h://` connection uses plaintext TCP to the proxy and cannot be sent directly to a TLS-only proxy port.
- Rotation picks an exit for each new connection, not for each request sent over a reused one.
- Keep TLS verification on, and keep keys out of prompts, logs and browser code.

## Sections

- [Guides](https://ports.io/docs/guides/llms.txt): only the guides pages
- [Reference](https://ports.io/docs/reference/llms.txt): only the reference pages

## Start here

- [ports.io documentation](https://ports.io/docs.md): Connect your application to ports.io residential proxies: authenticate, choose a location, keep a session, and understand your usage.
- [Make your first request](https://ports.io/docs/guides/quickstart.md): Make your first request with an HTTP proxy or SOCKS5 with remote DNS.

## Connect your application

- [Use curl](https://ports.io/docs/guides/curl.md): Configure HTTP or socks5h proxies and inspect failures with curl.
- [Use Python](https://ports.io/docs/guides/python.md): Use Requests with HTTP proxies or socks5h for remote DNS.
- [Use JavaScript](https://ports.io/docs/guides/javascript.md): Use Undici for HTTP proxies or SOCKS5 with destination DNS at the proxy.

## Routing reference

- [Proxy authentication](https://ports.io/docs/reference/authentication.md): Authenticate HTTP or SOCKS5 with a routing username and your key as the password.
- [Username reference](https://ports.io/docs/reference/username-reference.md): The complete grammar, its clauses, and the validation rules.
- [Geographic targeting](https://ports.io/docs/reference/targeting.md): Filter exits by country or by region.
- [Sessions and rotation](https://ports.io/docs/reference/sessions.md): Rotate exits, or keep related connections on one.

## Account and operations

- [Manage proxy keys](https://ports.io/docs/reference/key-lifecycle.md): Create, rename, replace, and revoke keys.
- [Understand usage measurement](https://ports.io/docs/guides/usage.md): What the console's traffic counters include.
- [Protocols and limits](https://ports.io/docs/reference/protocols-and-limits.md): HTTP and SOCKS5 support, remote DNS, size limits, and deadlines.
- [Errors and troubleshooting](https://ports.io/docs/reference/troubleshooting.md): Diagnose HTTP proxy errors and SOCKS5 handshake or tunnel failures.

## AI resources

- [Use these docs with AI tools](https://ports.io/docs/guides/ai-tools.md): Set up ports.io with Claude Code, Codex, Cursor or another AI assistant.

## Optional

- [All pages in one file](https://ports.io/llms-full.txt)
- [Page manifest](https://ports.io/docs/docs.json): titles, summaries and addresses as JSON