Skip to main content

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

1. 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.

Loading…

2. Reserve a domain​

Navigate to the Domains section of the ngrok dashboard to use your free dev domain, click New + to reserve a custom domain like https://your-service.ngrok.app, or use a custom domain you already own.

We'll refer to this domain as $NGROK_DOMAIN from here on out.

tip

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

3. 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.

4. Apply Traffic Policy for development gateway​

While still viewing your new cloud endpoint in the dashboard, copy and paste the policy below into the 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
Loading…

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.

5. 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:

Loading…

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

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

What's next?​

← Back to other examples

Want to contribute to the examples gallery?