Companion rt agent
The web app runs the RequestTailor core in the browser – so the browser’s rules apply: no request to a server without CORS headers, none of the forbidden headers, no client certificates, no gRPC. The rt agent companion runs on your machine and sends such requests for the web app, with the same native transport as rt send.1 It listens on 127.0.0.1 only, checks every request and pairs through a single-use code.
- Start
rt agentin a terminal- Address
127.0.0.1:47812(default)- Pairing
- single-use code, valid for 10 minutes
- Tokens
- in memory only; a restart revokes all
What the companion is for
The Mac app and rt send natively and know none of these limits. Only the web app needs the companion, and only for:
- Requests the browser blocks – usually a server without CORS headers or a header the browser does not allow. The web app then asks “The browser blocked this request. Send it through the RequestTailor companion?” and offers Send through companion.
- Sessions: gRPC, WebSocket and server-sent events always run through the companion in the web app (see gRPC, WebSocket, SSE and GraphQL).
- Git networking: the web app’s pull and push go through the companion.
- External secrets from 1Password, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault and Google Secret Manager, if you allow it (below).
Client certificates exist only natively, that is in the Mac app and in rt; the browser and the companion refuse them with a clear TLS error.
Start and pair
- Install
rt(see Download) and startrt agentin a terminal. - The companion prints a pairing code and a pairing link for each allowed origin, such as
Pairing code: 7KQ2-M9XD (single use, valid for 10 minutes). - Open the link in the browser or type the code where the web app asks for it (Pairing code).
- The web app exchanges the code for a token and uses the companion from then on whenever you choose it. Stop it with Ctrl+C; a restart revokes every pairing.
| Option | Meaning |
|---|---|
--port PORT | Listen on 127.0.0.1:PORT (default 47812, where the web app looks) |
--allow-origin ORIGIN | A web app origin (scheme://host[:port]) that may pair and send; repeatable. Replaces the default list (the web app’s local dev server on port 5173) |
--allow-secrets | Also read external secrets for the web app. Default: off |
External secrets in the web app
The browser cannot start op, vault and similar programs. With rt agent --allow-secrets, a paired web app sends the references of an environment’s external secrets to the companion, which reads them with the providers’ command lines – with your existing logins, without a shell, with a 60-second timeout. The web app keeps the values in memory for the session only, only to send; they are masked in reports and never stored, not in the companion either.
Security model
The companion is a local server that sends requests with your machine’s network access, internal hosts included. That is why these rules apply, each with tests in the core repository:
- Loopback only. It binds
127.0.0.1, never0.0.0.0; other machines cannot reach it. - Host check against DNS rebinding: every request needs
Host: 127.0.0.1:<port>orlocalhost:<port>, otherwise403. - Allowed origins (CORS): a request with a foreign
Origingets403without CORS headers, never*. - Pairing: the code has 40 random bits, is valid once and for 10 minutes; after 5 wrong attempts it is replaced. The token has 256 bits and is bound to the origin.
- Tokens in memory only, compared in constant time; nothing is written to disk.
- Secrets only when asked for, with
--allow-secrets, without caching, withCache-Control: no-store. - Nothing else: five endpoints, no file access, no configuration over HTTP; it refuses requests to itself.
- Logging: one line per request with method and host, never paths, headers or bodies; for secrets only provider, count and origin.
What it does not protect against: other programs running as your user can reach 127.0.0.1 too – but they can pair only with the code from your terminal. A compromised page on an allowed origin can use that origin’s token like the web app itself; allow only origins you trust.
Typical problems
| Message or situation | What helps |
|---|---|
| “The companion did not accept this code. Use the newest code `rt agent` printed.” | Every used, expired or replaced code is followed by a new one in the terminal. Type the newest. |
| The web app does not find the companion | Is rt agent running? With a custom port, the web app must know the same one; the default is 47812. |
| Pairing from a hosted web app fails | Allow its origin with --allow-origin https://…; the default list contains only the local dev server. |
| External secrets are not read | Restart rt agent with --allow-secrets and pair again; the provider’s command line must be installed and signed in. |
See also
- Docs gRPC, WebSocket, SSE and GraphQL
- Docs rt command line
- Docs Secrets and privacy
- Docs Environments and variables
- Sources rt-cli/README.md1 · rt-cli/README.md2