Using Port Forwarding for Extend Apps Local Hosted

Last updated on January 8, 2026

Overview

Extend apps (Override, Service Extension, and Event Handler) run locally on your development machine. To test with AccelByte Gaming Services (AGS), your local app must be accessible over the internet. Port forwarding creates a public URL that tunnels to your local server.

VS Code port forwarding is a built-in feature that exposes local TCP ports over public HTTPS URLs via Microsoft dev tunnels; no extensions or firewall changes required. This guide shows how to use it for Extend app local hosted testing.

info

You can also use other tunnel services like ngrok or pinggy. VS Code port forwarding is recommended for developers already using VS Code or Cursor, as it requires no additional tools.

Why Port Forwarding for Extend Apps?

When developing Extend apps locally, your app runs on localhost, which AGS in the cloud cannot access directly. Port forwarding creates a public URL that tunnels to your local server, enabling external services like AGS or testing tools to communicate with your app during development. This forwarded URL can be used for testing with AGS, registered in the Admin Portal for local hosted testing, or accessed directly by other tools and services.

Prerequisites

• VS Code or Cursor (with port forwarding support)
• Running Extend app locally
• GitHub or Microsoft account (for VS Code tunnel authentication)
• Access to AGS Admin Portal (optional; to register the forwarded URL for local hosted testing)

Step-by-Step Guide

1. Start your Extend app locally

Run your Extend app using Docker Compose (recommended) or directly:

# Using Docker Compose (most common)
docker compose up --build

# Or run directly (varies by language)
go run main.go
python main.py
dotnet run

Check the app logs or docker-compose.yaml to confirm the port number, typically ports 6565, 8000.

2. Forward the app port in VS Code

1. Open the Ports view in VS Code:

   • Open Panel (Ctrl+` / Cmd+`) → Ports tab
   • Or use command palette: Ports: Focus on Ports View

2. Click Forward a Port

3. Enter your app's port number

4. Press Enter

5. Sign in with GitHub or Microsoft account if prompted (required for tunnel creation)

The Ports view will display:

• Local Address: localhost:<your-port>
• Forwarded Address: Public HTTPS URL (e.g., https://xxxxx-xxxxx.tunnel.app.dev)
• Visibility: Private or Public

3. Set port visibility for AGS access

When using or registering the forwarded URL with AGS, set port visibility to Public:

• Right-click the port → Port Visibility > Public
• AGS requires Public visibility to access your forwarded URL
• Anyone with the URL can access (no sign-in required)

warning

Public ports are accessible to anyone with the URL. Ensure your Extend app has proper authentication enabled (e.g., PLUGIN_GRPC_SERVER_AUTH_ENABLED=true)

4. Copy the forwarded URL

From the Ports view, copy the Forwarded Address. This is the public URL you can use for testing or register in the Admin Portal.

The forwarded URL format is typically:

• https://xxxxx-xxxxx.tunnel.app.dev or similar
• VS Code provides an HTTPS URL that tunnels to your local service, handling both TCP and HTTP protocols automatically

5. Register the forwarded URL in Admin Portal

info

Registration is only required for Extend Override apps. Extend Service Extension and Extend Event Handler do not require Admin Portal registration; see their sections below.

The registration location varies by Extend Override type:

Extend Override:

• Challenge Goals Assignment: Engagement > Challenges > Customization > Locally Hosted for Testing Purpose
• Cloud Save Validator: Progression & Inventory > Cloud Save > Customization > Locally Hosted for Testing Purpose
• Entitlement Revocation: Commerce > Customization > Revocation > Locally Hosted for Testing Purpose
• Loot Box Roll: Commerce > Customization > Loot Box Roll > Locally Hosted for Testing Purpose
• Matchmaking: Game Management > New Matchmaking > Custom Function > Register Function > Locally Hosted for Testing Purpose
• Profanity Filter: Multiplayer > Chat > Configuration > Chat Filter Database > Custom > Locally Hosted for Testing Purpose
• Rotating Shop Items: Commerce > Customization > Item Rotation > Locally Hosted for Testing Purpose
• Session Dedicated Server: Multiplayer > Matchmaking > Session Configurations > Add Session Template > Server > DS - Custom > Custom URL
• Session Manager: Multiplayer > Matchmaking > Session Configurations > Add Session Template > Main Configuration > Use Custom Session Function > Custom URL

General steps for Extend Override:

1. Find Configurations
2. Find Custom
3. Select Locally Hosted for Testing Purpose (or similar option, e.g., Custom URL)
4. Paste the forwarded URL from VS Code into the configuration field
5. Click Register, Save, or Create (varies by service)

Extend Service Extension

Admin Portal registration is not required for Extend Service Extension apps. You can use the forwarded URL directly in your browser, curl, or integrate it into your game code to call your custom REST endpoints.

Extend Event Handler

Admin Portal registration is not applicable for Extend Event Handler apps, as AGS cannot call your local event handler directly. To test your event handler locally, use the forwarded URL to mock incoming events yourself (e.g., using grpcurl to simulate event payloads).

6. Test the integration

note

For Extend Override apps, complete Step 5 (Admin Portal registration) before testing. For Extend Service Extension and Extend Event Handler, you can test directly using the forwarded URL.

To test your forwarded Extend app:

1. Trigger requests or events:

   • Extend Override: Trigger the Extend override function through AGS (e.g., via /apidocs, curl, or from your game code)
   • Extend Service Extension: Call your custom REST endpoints directly using the forwarded URL (e.g., in your browser, curl, or from your game code)
   • Extend Event Handler: Mock incoming events by sending test payloads to your forwarded URL (e.g., using grpcurl)

2. Monitor your local app logs for incoming requests or event notifications

3. Verify your app processes the requests/events correctly

Considerations

• Protocol Support: VS Code port forwarding handles both TCP and HTTP protocols. For TCP-based services (e.g., gRPC), VS Code automatically tunnels TCP through HTTPS.
• Port Configuration: Check your docker-compose.yaml or app configuration to identify which port your app listens on. Common ports include 6565, 8000, but your app may use a different port.
• Envoy Proxy: If using grpc-plugin-dependencies with Envoy, forward the port that Envoy exposes (typically 10000) rather than the app's direct port.
• Base Path: For RESTful services, ensure the forwarded URL points to the correct base path if your app uses one (e.g., /guild).
• Connection Stability: Keep VS Code and the forwarded port active while testing. Closing VS Code stops the tunnel.
• Multiple Ports: Some Extend apps expose multiple ports (e.g., main service on one port and metrics on another). Forward the port that external services need to access.

Alternative Tunnel Services

If VS Code port forwarding doesn't work for your setup, alternatives include:

• ngrok: ngrok tcp <your-port> (requires account and authtoken)
• pinggy: ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:<your-port> tcp@a.pinggy.io

These provide similar forwarding capabilities. The forwarded URL format is the same. For Extend Override apps that require Admin Portal registration, the registration process remains the same.

Best Practices

• Keep VS Code running: The tunnel is active only while VS Code is open with the port forwarded
• Use Public visibility when using with AGS
• Stop forwarding when done: Right-click the port → Stop Forwarding to free resources
• Monitor tunnel usage: VS Code has usage limits (see limitations below)
• Verify app authentication: Ensure your app has proper authentication enabled for production-like testing (e.g., PLUGIN_GRPC_SERVER_AUTH_ENABLED=true)
• Check app logs: Verify requests/calls are reaching your local server

Limitations

VS Code Tunnel Usage Limits

VS Code port forwarding has usage limits (see tunneling service usage limits):

• Bandwidth quotas on tunnel traffic
• Limits on number of active machines
• Maximum 10 tunnels per user (creating an 11th may delete a random unused tunnel)

For heavy testing, consider alternative tunnel services with higher limits.

Organizational Policies

Organizations may block VS Code tunnels by blocking domain global.rel.tunnels.api.visualstudio.com or configuring Group Policy. In this case, use alternative tunnel services like ngrok or pinggy.

Remote Development

Port forwarding only works for locally-running services. For SSH or remote development, use VS Code Remote - Tunnels to connect first, then forward ports from the remote environment.

Troubleshooting

Port forwarding not starting:

• Sign in with GitHub/Microsoft account
• Verify your app is listening on the expected port
• Check firewall allows outbound connections to Microsoft services
• Restart VS Code

AGS cannot reach your forwarded URL:

• Ensure port visibility is set to Public
• Verify the forwarded URL is correct in Admin Portal
• Ensure VS Code is running and port forwarding is active
• Check that your local app is running and responsive

Requests/calls not reaching your app:

• Verify port number matches your app configuration
• Check app logs for connection attempts
• Ensure authentication settings match your testing setup (e.g., PLUGIN_GRPC_SERVER_AUTH_ENABLED)
• For RESTful services, verify the base path is correctly configured
• Test locally first (e.g., with curl, grpcurl, or gRPC client) before forwarding

Port already in use:

• Check for other processes using the port
• Stop existing port forwarding in VS Code
• Change your app to use a different port and forward that instead

Performance issues:

• Expect additional latency vs. localhost (tunnel overhead)
• Monitor tunnel bandwidth usage
• For production testing, deploy to AGS instead of using local hosted