Temporary connections over HTTP

Not an agent? Read connect a computer.

You are an agent that can make HTTP calls but can't sign in with OAuth. These steps get you a temporary connection: no account, the person approves on their computer, and access ends within 24 hours. Follow them in order. Send a User-Agent naming your agent, such as my-agent/1.0, on every request.

Step 1: Make a secret

Generate 32 random bytes and hex-encode them. This string is your agent token. ezremote never sees it, so store it privately. Hash the exact string with SHA-256 and keep the lowercase hex digest.

Step 2: Create the request

POST https://tunnel.masti.lol/api/connect/request
Content-Type: application/json

{
  "agentName": "Research agent",
  "credentialHash": "<64 lowercase hex characters>",
  "operations": ["files.read", "files.list", "files.search"],
  "durationSeconds": 7200
}

Field	What it's for
`agentName`	Required. Shown to the person as unverified. 1 to 80 characters.
`credentialHash`	Required. The secret's hash. A secret works for one request only.
`operations`	Dotted names of what the task needs. Leave it out to ask for every operation except `mcp.*`.
`durationSeconds`	Access length from the request. Defaults to the maximum.

The server rejects other fields. It answers 201 with requestId, operations, setupUrl, pollToken, expiresAt, statusUrl and exchangeUrl:

setupUrl is for the person. Pass it whole, including #key=, and never post it publicly.
pollToken authorizes status and exchange. Keep it private.
expiresAt is in Unix milliseconds. Approval and exchange must both happen before it.
operations is your list minus what temporary connections can't have.

Save the whole response next to your secret. The server never returns pollToken again.

Step 3: Send the person the link

Ask them to open setupUrl on the computer you will use, choose permissions, run the setup command and approve in the terminal.

Step 4: Wait for approval

GET statusUrl with Authorization: Bearer <pollToken> every 5 seconds and act on state:

`state`	Do
`waiting_for_approval`, `waiting_for_helper`	Keep polling.
`waiting_for_agent`	Go to step 5.
`connected`	Already activated. Use it.
`offline`	Ask the person to wake the computer or check its network.
`expired`, `revoked`	Stop. Start again only if the person asks.

The response also has deviceId, deviceName, online and accessExpiresAt.

Step 5: Activate

POST exchangeUrl with Authorization: Bearer <pollToken> and no body. It returns tokenId, deviceId, expiresAt and mcpUrl, and switches on your secret. Use Authorization: Bearer <secret> at mcpUrl, or with the REST endpoints. Call devices and check that deviceId is online before you start. Exchange returns no new secret, so repeating it is safe.

A temporary connection never gets full Terminal access or MCP servers, and on Windows it gets no Terminal. Reconnecting doesn't extend it.

Keep it: save to an account

The person can choose Sign in and keep it on the setup page. The connection becomes lasting with the same permissions, your secret gets seven days, and accessExpiresAt turns null.

Rotate the secret before it expires with POST https://tunnel.masti.lol/api/agent-tokens/renew and Authorization: Bearer <secret>. The optional body is {"expiresInSeconds": 604800}. The response has a new token. The old secret stops working at once, so save the new one before anything else. If you lose it, the person has to connect you again.

Errors

Status	Error	What to do
400	`invalid_connection_request`	Check the four fields, the operation names and the duration range.
409	`credential_already_used`	Continue with your saved response. If you lost it, make a new secret and a new request.
429	`connection_rate_limited`	Stop. More requests won't help.
503	`guest_connections_unconfigured`	This server is closed to temporary connections. Use MCP with sign-in.
401	`unauthorized`	Wrong `pollToken`. Use the saved one.
409	`local_approval_required`	Not approved yet. Keep polling.
410	`exchange_expired`	You exchanged too late. Start again with a new secret.
409	`connection_unavailable`	The connection stopped or expired. Stop.
403	`lasting_connection_required`	Renewal needs a connection saved to an account.
403	Cloudflare `1010`	Send a `User-Agent`, then check that `GET https://tunnel.masti.lol/health` returns `"ok": true`. If still blocked, report the ray ID and stop.
500 or none		The request may exist. Send the same body once more. A `409 credential_already_used` then means the first try worked, so make a new secret.

Temporary connections over HTTP

Step 1: Make a secretCopy Anchor Link

Step 2: Create the requestCopy Anchor Link

Step 3: Send the person the linkCopy Anchor Link

Step 4: Wait for approvalCopy Anchor Link

Step 5: ActivateCopy Anchor Link

Keep it: save to an accountCopy Anchor Link

ErrorsCopy Anchor Link