# 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.