Reach a private API without a browser: the CLI agent

Send a request to localhost or a private network through a small program on your own machine.

In short

The CLI agent is a small program you start on a machine that can reach your private API. A request {{brand}} could not send ("Not sent") can then be sent through it, and the answer comes back to the page. It needs no browser, so it also works on a build server.

Before you start

Who: you, signed in, with an access token you made for this agent alone. It serves only you, in your token's workspace.
Plan: an agent run never counts against your allowance. The CLI needs .NET 10 on the machine.
First: a machine that can reach your private API, and the token in KAMOCORE_TOKEN.

Steps

Install the CLI on the machine that can reach your API, with the install line "Run in CI" shows on a suite. It needs .NET 10.
Create an access token in Settings, under Access tokens, for the agent alone: choose "API Tester CLI agent", "Read and write", and nothing else.
Put it in the environment variable KAMOCORE_TOKEN on that machine.
Start the agent and name what it may send to: kamocore agent --allow localhost:5000
Leave it running. Press Ctrl+C to stop it.

Open a request whose address is on your machine or network and press "Send". It is recorded as Not sent.
Check that "Agent connected from" and your machine's name shows under the message.
Press "Send through my agent".

Result: the answer comes back to the page and is recorded as a run marked as sent through your agent.

Keep the agent running on a machine that stays on.
Open Monitors and create or edit a monitor of one request or one suite that runs as you.
In "Sends from", choose "Your agent on" and your machine's name, then save.

Result: every check of that monitor is sent from your machine. Its properties say "Sends from" your agent, and a check made while the agent was not connected is marked Not sent, never failed. When the request signs in with an OAuth profile whose token address is inside your network, the agent fetches that token too.

Good to know

Nothing is allowed until you name it. Repeat --allow for more: a host, a host with a port, every name under a suffix such as *.internal, or a range such as 10.20.0.0/16.
It serves only you, in your token's workspace. Nobody else can send through it.
It opens no port on your machine. It asks {{brand}} for work, one short wait at a time.
It sends only to the hosts you allowed, only to local and private addresses, and never to link-local or cloud metadata addresses.
No secret reaches it: a request that uses a secret variable is not sent. See /help/api-testing/send-to-localhost#secrets.
Up to three agents can be connected at once, and a request and its answer can each be up to 1 MB. With several connected, choose which one sends; "Disconnect" stops one from the web app.
It stops when its token is revoked or expires.
An agent run is your machine's word. It does not change a request's passed or failed state, is never evidence that {{brand}} tested the API, and never counts against your allowance.
A monitor's checks are the exception: they count against the monitor allowance like any check, and turn the monitor up or down. Only the person a monitor runs as chooses its agent; when someone takes the monitor over, it sends from {{brand}} again until they choose their own.
A monitor keeps the agent by its access token, so restarting the agent is fine; a new token needs choosing again.

If something goes wrong

"That agent is not connected. Start it on your machine with kamocore agent, then send again."
"The agent did not send the request: its host is not among those you allowed on that machine. Start the agent with --allow for it."
"The agent did not answer in time, so the request was not sent.": check the agent is running and online.
"The request body is larger than an agent sends: at most 1 MB."
"Too many requests are waiting for that agent. Try again in a moment."
"The agent did not send the request: it only sends to local and private addresses, and never to link-local or cloud platform addresses."
"The request was not sent: you may no longer run this request here.": ask for Run on the project.