Local debugging — with remote live traffic
This guide covers Remote Debug — a feature that routes real in-cluster traffic to your local machine so you can debug your Extend App without rebuilding or redeploying the image for each code change. For common debugging concepts — VS Code workflow, breakpoints, log reading — see the Extend local debugging guide.
- Enabling or disabling Remote Debug restarts the app.
- Only one pod replica is supported while a debug session is active.
- Only one active debug session is allowed per app at a time.
- When Remote Debug is enabled but no session is connected, in-cluster traffic continues to reach the app as normal. Traffic is only redirected to your local machine while an active session is open.
How it works
When Remote Debug is enabled, a sidecar container is injected into your Extend App's pod. The sidecar transparently intercepts all inbound traffic and forwards it through a secure tunnel to your local machine. Your local app handles the requests and the responses are sent back through the same tunnel.
In addition, the CLI sets up a local TCP listener for the async-messaging service so your local app can publish events the same way it would when running inside the cluster.
Prerequisites
-
extend-helper-cliv0.0.12 or above installed. See the extend-helper-cli README. -
Your Extend App must already be deployed and running.
-
The OAuth Client used must have the following permissions:
For AGS Private Cloud:
ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ, UPDATE]ADMIN:NAMESPACE:{namespace}:EXTEND:TUNNEL [READ]
For AGS Shared Cloud:
- Extend > App Management (Read, Update)
- Extend > TCP Tunneling (Read)
Enabling Remote Debug
Run the following command to enable Remote Debug on your Extend App.
extend-helper-cli remote-debug enable --namespace <my-game-namespace> --app <my-extend-app>
If your app is currently running, you will be prompted to confirm the restart.
app "my-extend-app" is currently running and will be restarted to apply the debug mode change. continue? [y/N]:
To skip the prompt, pass --confirm.
extend-helper-cli remote-debug enable --namespace <my-game-namespace> --app <my-extend-app> --confirm
Enabling Remote Debug restarts the app.
You can also enable Remote Debug from the Admin Portal by navigating to your Extend App settings and toggling on debug mode.
Connecting the debug tunnel
Step 1 — Start your local app
Start your Extend App locally. It should listen on its standard ports.
- gRPC: port
6565 - HTTP: port
8000
If your local app listens on a different port or address, you can specify it using
--local-grpc-port or --local-http-port in the connect command.
Step 2 — Connect
Run the following command to open a tunnel between your local machine and the in-cluster sidecar.
extend-helper-cli remote-debug connect --namespace <my-game-namespace> --app <my-extend-app>
If your local app listens on non-standard ports, specify them explicitly.
extend-helper-cli remote-debug connect --namespace <my-game-namespace> --app <my-extend-app> \
--local-grpc-port localhost:6565 \
--local-http-port localhost:8000
The output will look like the following when the session is established.
INFO[0001] target pod: my-extend-app-xxxxx-xxxxx port: 30001
INFO[0001] connecting to extend app debug sidecar...
INFO[0002] connected to extend app debug sidecar, session established
INFO[0002] starting extend services
Keep this command running for the duration of your debug session. In-cluster traffic will not reach your local app if the tunnel is not connected.
If the tunnel drops, the CLI will automatically attempt to reconnect. To stop the session,
press Ctrl+C.
Debugging with real traffic
Your local app is now receiving real in-cluster traffic. Use breakpoints, log statements, or any IDE debugging workflow as you normally would.
The async-messaging service is available on localhost:7575, mirroring the address your app
would use when running inside the cluster. In all scenarios below, your local app can publish
async-messaging events using this address.
Event Handler
Your local app process receives events published inside the cluster. You can inspect payloads and step through event-handling logic with a debugger.
Service Extension
Your local app process receives actual HTTP requests from in-cluster callers. You can debug request handling end-to-end, including authentication, routing, and response logic, with real traffic instead of mocked data.
Function Override
Your local app process receives gRPC calls from the cluster. You can step through function override logic using your IDE debugger.
Disabling Remote Debug
When you are done debugging, disable Remote Debug to restore normal operation.
extend-helper-cli remote-debug disable --namespace <my-game-namespace> --app <my-extend-app>
If your app is currently running, you will be prompted to confirm the restart.
app "my-extend-app" is currently running and will be restarted to apply the debug mode change. continue? [y/N]:
To skip the prompt, pass --confirm.
extend-helper-cli remote-debug disable --namespace <my-game-namespace> --app <my-extend-app> --confirm
Disabling Remote Debug restarts the app.
Common issues
The connect command fails with "app is not running"
Cause: The app must be in running status before you can connect.
Fix: Start the app if it is not running, or wait for it to finish starting.
The connect command fails with "debug mode is not enabled"
Cause: Remote Debug has not been enabled for this app.
Fix: Enable Remote Debug first using the enable command or from the Admin Portal.
See Enabling Remote Debug.
The connect command fails with "debug session is still active"
Symptom: The connect command exits immediately with an error about an active session.
Cause: Another debug session is already connected to this app. Only one session is allowed at a time.
Fix: If this was a previous session that did not disconnect cleanly, wait a few seconds and try again.
The tunnel connects but the local app does not receive traffic
Cause: The local app is not running or is listening on a different port than expected.
Fix: Make sure your local app is running and listening on the correct port before running
remote-debug connect. If you changed the default port, pass the correct address with
--local-grpc-port or --local-http-port.
Debug mode was enabled or disabled while the app was stopped
Cause: When the app is not running, the configuration change is saved but not yet applied to the running pod.
Fix: Deploy the app to apply the change.
extend-helper-cli deploy-app --namespace <my-game-namespace> --app <my-extend-app> --image-tag <current-image-tag>