Borealis Docs

Ports and service previews

A service needs to be listening inside the sandbox before a port binding can make it reachable.

Start the service

Configure your development server to listen on the container interface, usually 0.0.0.0, rather than only on 127.0.0.1. Choose its container port and confirm the server has started successfully.

A running sandbox does not mean every service inside it is ready. Use execution output or application logs to check the service before debugging the preview URL.

Register the port

Use Networking when creating a sandbox, or register a port on an existing sandbox. For a service listening on port 3000:

borealis sandbox port register SANDBOX_ID --body '{"containerPort":3000,"protocol":"tcp"}'

The create request also accepts an exposedPorts array:

{
  "exposedPorts": [
    { "containerPort": 3000, "protocol": "tcp", "expose": true }
  ]
}

This is a request fragment, not a complete sandbox creation request. Read the returned binding and use the gateway URL provided by Borealis when one is available. Do not construct a URL from an internal host address.

Control access to your application

Treat any reachable preview as an exposed service. Do not assume the sandbox’s API permissions also authenticate visitors to your application. Apply appropriate application authentication and avoid exposing administrative endpoints or development secrets.

Browser integrations can have additional networking requirements. A normal HTTP preview is not proof that a browser streaming session or another protocol will work.

Diagnose a connection problem

Check the service process, its bind address, and the container port first. Then check the registered protocol, returned gateway address, sandbox status, and host connectivity.

If a service fails after a restart, verify that the startup command actually restarts it. A preserved filesystem does not preserve the service’s running process.