Request a temporary connection

Use this flow when you need access without an account. The person approves on their computer. Access ends within 24 hours of request creation.

1. Check availability

Fetch https://tunnel.masti.lol/agent.json and check onboarding.selfServiceRequests. If false, use computer setup.

Start when the person can use the computer within 10 minutes. Send an identifying header such as User-Agent: ezremote-agent/0.1. If requests are blocked before reaching the API, check GET /health with that header; it should return JSON with ok: true.

2. Create and save the request

Generate 32 random bytes and encode them as a token string. Save that token privately. Hash the exact token string with SHA-256 and send its lowercase hex digest:

POST /api/connect/request
Content-Type: application/json
Accept: application/json
User-Agent: ezremote-agent/0.1

{
  "agentName": "My agent",
  "credentialHash": "<SHA256_OF_PRIVATE_AGENT_TOKEN>",
  "operations": ["files.read", "transfer.pull"],
  "durationSeconds": 86400
}

These are the only accepted fields. operations and durationSeconds are optional. Omitting operations requests every supported operation, so specify what the task needs. Duration must be an integer from 60 to 86400 seconds. The requester name is an unverified label.

Save the successful response beside the original token. It contains requestId, setupUrl, pollToken, statusUrl, exchangeUrl, and expiresAt.

Share only setupUrl with the person. Keep the full URL intact, including its fragment key. That URL controls their connection; do not publish it. Keep the polling and agent tokens private on the agent host.

3. Wait for local approval

The person opens the link, runs its command, and approves in their terminal. Poll statusUrl with Authorization: Bearer <POLL_TOKEN> and read the response's state field.

• waiting_for_approval: Wait for the person to run setup and approve.
• waiting_for_helper: Keep polling while the approved helper starts.
• waiting_for_agent: Activate your token.
• connected: Use the connection, or recover activation details if needed.
• offline: Ask the person to wake the computer and check its network.
• revoked or expired: Stop using this connection.

4. Activate and verify

When state is waiting_for_agent, POST to exchangeUrl with the polling token as bearer authorization. You can also exchange again in connected state to recover details. The response contains deviceId, mcpUrl, tokenId, and expiresAt, a Unix timestamp in milliseconds.

Exchange activates the original token. It does not return a new raw token and is safe to retry if its response is lost.

Configure the returned MCP URL with the original agent token, or use it through REST or the SDK. List devices and verify the returned UUID. Continue with the task when the computer is online. Temporary connections include sandboxed shell.exec when the person approves it. MCP forwarding and full Terminal access are unavailable. On Windows temporary Terminal starts off.

Reconnecting uses the same token and does not extend expiry. File and shell operations have different retry rules: never automatically repeat outcome_unknown.

Recover from an error

• 409 credential_already_used: Continue with the saved response. The server will not return the old keys again or update that request's scope. If the response is lost, deliberately create a new request with a fresh token; cancel the old connection through its setup page when available.
• 400 invalid_connection_request: Check the four fields, dotted operation names, and duration range.
• 429 connection_rate_limited: Wait. Creating more requests will not help.
• HTTP 403 with Cloudflare 1010: Check /health with an identifying user agent. If still blocked, report the ray ID and stop.
• Network failure or HTTP 500: Creation may have succeeded. Check saved state before retrying. Do not repeatedly rotate tokens. A deliberate retry returning 409 follows the recovery above.

The SDK's requestConnection and waitForConnection handle token generation, polling, and activation. Persist the returned pending state yourself. To keep the computer in an account later, follow account setup.