Ports and APIs

A web server, an API or a webhook receiver needs a port that other programs can connect to. Pythonator lets a service listen on the ports you list, and only those, and lets you choose who may connect.

Serving a port

Open the service’s Network tab:

Pythonator passes the first port to the program as PORT, and with This computer only also HOST=127.0.0.1, unless you set them yourself. Most frameworks read them, or you can:

# Python (FastAPI with uvicorn)
import os, uvicorn
uvicorn.run("app:app", host=os.environ.get("HOST", "127.0.0.1"), port=int(os.environ["PORT"]))

// Node.js (Express)
app.listen(Number(process.env.PORT), process.env.HOST ?? "127.0.0.1");

// Go
http.ListenAndServe(os.Getenv("HOST")+":"+os.Getenv("PORT"), mux)

When the service runs, the header shows a link to http://127.0.0.1:PORT/ and the list of ports it actually listens on. The Health checks plugin calls it every few seconds and shows whether it answers.

What each mode enforces

On Linux, a sandboxed server reached by other computers is also subject to your firewall (ufw, firewalld).

Windows: Make reachable

Windows keeps every AppContainer unreachable, even from the same computer, until an administrator allows it. So on Windows the Network tab has Make reachable… and Undo. Make reachable asks for administrator rights once, then:

1. adds a loopback exemption for this service’s AppContainer (CheckNetIsolation LoopbackExempt), so programs on this computer can connect;
2. adds a Windows Filtering Platform permit with the same scope (this AppContainer, a loopback connection from 127.0.0.1, the listed ports). Windows’ own block of loopback connections into an AppContainer sits where firewall rules can’t override it, and the loopback exemption alone only lets the container connect out. The permit sits just above that block, for this one container, and stays until Undo. This is what lets your browser open http://127.0.0.1:<port>/;
3. adds an inbound firewall rule for this service only, for TCP from 127.0.0.1, on the listed ports;
4. with Other computers chosen, adds a second rule for the listed ports on private and domain networks (never public Wi-Fi).

Every rule is tied to the service’s own AppContainer, in a Pythonator firewall group, so no other program gains anything. Undo removes the exemption, the permit and both rules. Removing a service deletes its AppContainer, so its rules no longer apply to anything; press Undo first if you’d like them gone from the firewall list as well.

Run it again after you change the ports. Without it, the service runs and listens, but connections time out.

Connecting to other containers

A service in Container mode can join a container network, to reach a database or a cache running in another container by name.

1. Create a network and start the database on it, once:

   docker network create appnet
   docker run -d --name db --network appnet -e POSTGRES_PASSWORD=change-me postgres:17
   

2. In the service’s Isolation tab, choose Container and type appnet under Network.
3. In the program, connect to db:5432. Put the password in the service’s environment or .env file.

The network can be any name except host, which Pythonator refuses because it would remove the isolation.

Inside the container, the program should listen on 0.0.0.0: the port is published to the host on 127.0.0.1 (this computer) or all addresses (other computers) by the engine, according to Who may connect.

Connecting from a sandbox to a container

A sandboxed service with the network on can connect to a container’s published port like any other program, for example a database started with -p 127.0.0.1:5432:5432 is at 127.0.0.1:5432.

Calling Pythonator itself

Pythonator’s own background service isn’t on the network at all. It listens on a local socket that only your account can open, with a token. Scripts of yours can use it: see Background service API.