Skip to main content
The Remote Tunnels API enables you to programmatically create secure tunnels that expose local ports via Cloudflare. This allows QA.tech to access locally-running applications for testing without deploying them to a public server.

​
Prerequisites

Before using the Remote Tunnels API, you need:
  1. cloudflared – Cloudflare’s tunnel client must be installed on your machine or CI runner 
    # macOS
brew install cloudflared

# Linux (Debian/Ubuntu)
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

# See https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/
  2. Your application running locally – The tunnel exposes local ports, so your app must be running

​
Tunnel Expiration

Tunnels expire 4 hours after creation. The expiresAt field in the response indicates when the tunnel will be automatically torn down. For long-running development, you’ll need to create a new tunnel when the current one expires.

​
When to Use Remote Tunnels

  • Local development testing – Test your local environment without deploying
  • CI/CD pipelines – Expose ephemeral test servers during build processes
  • Preview environments – Create temporary public URLs for testing
  • Firewall-protected environments – Access applications behind corporate firewalls
For CLI-based tunnel management, see the tunnel command documentation. The CLI provides a simpler interface for common tunnel operations.

​
Authentication

All endpoints require Bearer token authentication. Create your API key in the QA.tech dashboard: Organization Settings → API Keys. The key is shown only once, at creation. See the API Introduction for details.

​
Endpoints

For full request, response, and error details, see the generated reference pages:

​
Tunnel Lifecycle

  1. Create the tunnel via Create Remote Tunnel, specifying the local ports to expose. The response contains the public hostnames mapped to each port, a tunnelToken, and the runnerId used in subsequent calls.
  2. Start the cloudflared daemon with the returned token: 
    cloudflared tunnel run --token YOUR_TUNNEL_TOKEN
    The tunnel remains active as long as cloudflared is running and the tunnel has not expired (4-hour maximum lifetime).
  3. Check health with Get Remote Tunnel Status before pointing tests at the tunnel.
  4. Use the public URLs as environment overrides when starting a run or creating a chat conversation.
  5. Clean up with Delete Remote Tunnel when you’re done.
For simpler tunnel management, consider using the CLI tunnel command which handles cloudflared automatically: qatech tunnel start --port 3000

​
Hostname Format

Each exposed port gets a public HTTPS hostname based on the tunnel’s runnerId:
  • Single port without subdomain: r-{runnerId}.quack.run
  • Multiple ports without subdomain: r-{runnerId}-p{localPort}.quack.run
  • With subdomain: r-{runnerId}-{subdomain}.quack.run