Hi! I started using cloud agents with Cursor 3/Glass and it seems like ports are being forwarded from the cloud agent to my machine?
Do you have any documentation on how this works? Or a guide? It seems to be working but I really can’t tell how it’s deciding which ports to map or how.
There also seems to be a bug: I run my server on the same port P on every cloud agent, and it looks like Cursor tries to forward port P from each agent onto P on my machine, so they seem to be conflicting? Ideally Cursor would see a port is in use and try another one.
I do run multiple services in each cloud agent (database, background worker, server, etc), and it seems like for the ones that run in Docker, it does try to map different random ports on my machine. But the main web service in each cloud agents always gets mapped to the same port.
Thanks for raising this. Agreed that the docs are a bit lacking here. Will follow up on that, but here’s what I can tell you.
When you use a cloud agent with the Agents Window and Cursor detects a process listening on a port, Cursor automatically forwards it to your local machine so you can access it at localhost. By default, it tries to map remote port P to local port P. If that local port is already taken, it falls back to a random available port.
Any port the cloud agent listens on is a candidate, except for internal infrastructure ports (26000-26999). If “Auto-Forward Ports” is enabled (the default), all detected candidate ports are forwarded automatically.
There’s a plug icon in the top-right of the editor panel when connected to a cloud agent (see screenshot). Click it to see forwarded ports, manually forward or close ports, open a forwarded port in the built-in browser, and toggle auto-forwarding.
When multiple cloud agents listen on the same port, Cursor manages forwarding based on which agent tab is active. The active agent gets the preferred localhost:P mapping, and when you switch tabs, Cursor releases it from the previous agent and re-establishes it for the newly active one. In most cases this handoff is seamless, but if a forward was already established on a different local port (e.g. via the plug menu), it won’t be automatically upgraded to localhost:P .
You can use the plug menu to manually close stale forwards when switching between agents.
