Agent-Assisted Gateway

An agent-assisted gateway bridges your localhost development environment with the public internet, enabling AI coding tools, webhook testing, and real authentication flows without waiting for production deployment. Instead of port forwarding and localhost limitations, you get a production-like environment for testing traffic patterns, auth flows, and integrations. With this setup, you can:

Expose local services securely to AI coding assistants and external tools
Test real OAuth flows, webhooks, and API integrations during development
Apply traffic transformations and header manipulation in your dev environment
Debug production-like traffic patterns before deploying
Share work-in-progress with teammates and stakeholders securely

Create internal endpoints for your local services

Start Agent Endpoints for your local development services using internal URLs. Replace $PORT with your actual service ports.

# Backend API (for example, Express, Flask, FastAPI)
ngrok http $BACKEND_PORT --url https://api-dev.internal

# Frontend development server (for example, React, Vue, Next.js)
ngrok http $FRONTEND_PORT --url https://app-dev.internal

Reserve a domain

Navigate to the Domains section of the ngrok dashboard and click New + to reserve a free static domain like or a custom domain you already own.This guide refers to this domain as $NGROK_DOMAIN from here on out.

Consider using a subdomain like dev.yourcompany.com or staging.yourproject.com to clearly distinguish from production.

Create a Cloud Endpoint

Navigate to the Endpoints section of the ngrok dashboard, then click New + and Cloud Endpoint.In the URL field, enter the domain you just reserved to finish creating your Cloud Endpoint.

Apply Traffic Policy for development gateway

While viewing your new Cloud Endpoint in the dashboard, copy the policy below and paste it into the Traffic Policy editor. Make sure you change each of the following values:

$GITHUB_OAUTH_CLIENT_ID: Replace with your GitHub OAuth app client ID for development
$GIBHUB_OAUTH_CLIENT_SECRET: Replace with your GitHub OAuth app secret for development
$YOUR_DEV_API_KEY: Replace with an API key for development access
Internal service URLs: Replace with your actual internal endpoint URLs

on_http_request:
  # Development environment identification
  - actions:
      - type: add-headers
        config:
          headers:
            x-environment: "development"
            x-client-ip: "${conn.client_ip}"
            x-client-location: "${conn.geo.city}, ${conn.geo.country}"
            x-forwarded-host: "${req.host}"

  # OAuth authentication for protected development routes
  - expressions:
      - "req.url.path.startsWith('/admin') || req.url.path.startsWith('/dashboard')"
    actions:
      - type: oauth
        config:
          provider: google
          client_id: "$GITHUB_OAUTH_CLIENT_ID"
          client_secret: "$GITHUB_OAUTH_CLIENT_SECRET"
          scopes:
            - https://www.googleapis.com/auth/userinfo.email

  # API key authentication for external tools and AI assistants
  - expressions:
      - "req.url.path.startsWith('/api')"
      - "!hasReqHeader('authorization')"
    actions:
      - type: basic-auth
        config:
          credentials:
            - "dev-user:$YOUR_DEV_API_KEY"

  # Allow webhook testing without auth (for development only)
  - expressions:
      - "req.url.path.startsWith('/webhooks')"
    actions:
      - type: add-headers
        config:
          headers:
            x-webhook-source: "${req.user_agent}"
            x-webhook-timestamp: "${timestamp(time.now)}"
            x-webhook-signature: "${getReqHeader('x-signature')[0]}"

  # Route API requests to backend
  - expressions:
      - "req.url.path.startsWith('/api')"
    actions:
      - type: forward-internal
        config:
          url: https://api-dev.internal

  # Route webhook requests to backend
  - expressions:
      - "req.url.path.startsWith('/webhooks')"
    actions:
      - type: forward-internal
        config:
          url: https://api-dev.internal

  # Route admin/dashboard to backend with auth headers
  - expressions:
      - "req.url.path.startsWith('/admin') || req.url.path.startsWith('/dashboard')"
    actions:
      - type: add-headers
        config:
          headers:
            x-authenticated-user: "${actions.ngrok.oauth.identity.email}"
            x-auth-provider: "github"
      - type: forward-internal
        config:
          url: https://app-dev.internal

  # Default route everything else to frontend
  - actions:
      - type: forward-internal
        config:
          url: https://app-dev.internal

on_http_response:
  # Add development debugging headers
  - actions:
      - type: add-headers
        config:
          headers:
            x-served-by: "ngrok-dev-gateway"
            x-processing-timestamp: "${time.now}"

  # Enable CORS for development (be more restrictive in production)
  - actions:
      - type: add-headers
        config:
          headers:
            access-control-allow-origin: "*"
            access-control-allow-methods: "GET, POST, PUT, DELETE, OPTIONS, PATCH"
            access-control-allow-headers: "Content-Type, Authorization, X-API-Key"
            access-control-expose-headers: "X-Processing-Timestamp"

What’s happening here? On every HTTP request, the policy adds environment identification headers for tracing, enforces OAuth authentication for admin/dashboard routes, requires API key authentication for API routes accessed by external tools and AI assistants, and allows webhook testing without authentication for easy debugging.The gateway routes traffic based on URL paths—API requests go to your backend service, admin routes go to the backend with authentication headers, and everything else goes to your frontend. On responses, it adds development-specific headers for debugging, enables permissive CORS for local development, and timestamps responses for request tracking.

Try out your development gateway

Visit the domain you reserved either in the browser or in the terminal using a tool like curl. You should see the app or service at the port connected to your internal Agent Endpoint.Test different aspects of your development setup:

# Test your frontend application
curl "https://$NGROK_DOMAIN/"

# Test API with authentication (basic auth with base64 encoded API key)
# First, base64 encode the dev-user:$YOUR_DEV_API_KEY pair
# Example: dev-user:my-api-key becomes ZGV2LXVzZXI6bXktYXBpLWtleQ==
curl -H "Authorization: Basic ZGV2LXVzZXI6bXktYXBpLWtleQ==" \
 "https://$NGROK_DOMAIN/api/users"

# Test OAuth protected admin route (will redirect to GitHub)
curl "https://$NGROK_DOMAIN/admin/dashboard"

When using tools like Lovable, Cursor, or other AI coding assistants:

They can access your API schema: https://$NGROK_DOMAIN/api/schema
Test frontend builds against your real backend: https://$NGROK_DOMAIN/api/*
Receive webhooks for real-time collaboration: https://$NGROK_DOMAIN/webhooks/ai-assist

What’s next?

Read about other gateway shapes you can build with ngrok
Learn about securing developer environments for team-wide development workflows
Explore webhook integrations for testing with real services during development
Set up Traffic Inspector to debug request flows and authentication issues
Configure custom domains for more professional development URLs

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Create internal endpoints for your local services

Reserve a domain

Create a Cloud Endpoint

Apply Traffic Policy for development gateway

Try out your development gateway

What’s next?

Create internal endpoints for your local services

Reserve a domain

Create a Cloud Endpoint

Apply Traffic Policy for development gateway

Try out your development gateway

​What’s next?

What’s next?