// workspaces

Ports & preview

A workspace is a real Linux machine, so you can run a dev server, an API, or a database on any port you like. The only question is how to reach what you started. You have two ways to do it: open it in the browser IDE, or pull it down to your own laptop. Neither one puts it on the public internet.

Two ways to reach a port

Start your server however you normally would. That could be npm run dev, flask run, or anything else that listens on a port. Then open it one of two ways.

In the browser IDE

When a server starts, the VS Code Ports panel notices it and forwards the port for you. Click the forwarded address and your app opens in a new tab. Nothing to set up, and it stays inside your signed-in IDE session.

From your own machine

Run runcode forward <port> and the CLI tunnels that workspace port to the same port on your laptop, over the SSH gateway. Your browser, curl, or test runner then hits http://localhost:<port> as if the server were running locally.

Forward a port to your laptop

Once a workspace is attached over the SSH gateway, runcode forward maps a port on the box to the same port on your machine. The tunnel is encrypted, and your short-lived key is what authenticates it.

terminal
# with a workspace attached, tunnel one of its ports to your laptop:
runcode forward 5173            # box :5173  ->  http://localhost:5173

# then just open it locally:
open http://localhost:5173      # macOS  (xdg-open on Linux)

If your server won’t show up

Nine times out of ten it is a server that only listens on the loopback address. Bind it to 0.0.0.0 instead, so both the Ports panel and runcode forward can see it.

terminal
# many dev servers listen on 127.0.0.1 only. bind to all interfaces so the
# forwarder and the browser IDE can reach them:
npm run dev -- --host 0.0.0.0          # vite
python -m http.server 8000 --bind 0.0.0.0
flask run --host 0.0.0.0 --port 5000

Good to know

  • Nothing is public by default

    You reach a port through your authenticated IDE session or the SSH tunnel. There is no public URL pointing at it unless you make one. Stop the workspace and every forward goes away with it.

  • Forwarding needs a running workspace

    A tunnel only lives while the box is on. If it idles out and auto-stops, the forward drops. Start the workspace again and re-open it.

  • Bind to the right host

    A server that listens only on 127.0.0.1 is hard to reach from anything else. Bind it to 0.0.0.0 instead. That works for both the Ports panel and runcode forward.

  • Bring it back with onStart

    Stopping the box shuts every process down. Put your server’s start command in onStart and it comes back on its own after each boot.

Want a server to come back on every boot? Start it from onStart in .runcode.yaml. Driving the box from your own editor instead? Have a look at Connect over SSH.