All pages

Lesson 5.2 · Reach other machines · 8 min

Ports

See who holds a port, reserve one, find a free one.

Listen

When several projects run at once, ports collide. This lesson shows you how to see every listener on your Mac in one table, find out which project owns a port, reserve ports ahead of time, and get a free port that is guaranteed to bind.

Time: 8 minutes · Works on: macOS app (the agent's ports_* tools also run on Linux, Windows and the cloud workspace)

Open the Ports table

The table is the fourth sub-tab of the container panel. You can reach it two ways:

  • Right sidebar → More → Conn → Containers → Ports.
  • Right sidebar → More → Docker → Ports.

Both show the same table. Its header reads Master ports view.

  1. Open the table.
  2. Start a dev server in one of your projects, for example npm run dev.
  3. Click the Rescan button, or wait. The table rescans every 12 seconds while it is open.
  4. Find your server's port. The row shows the process as pid · command.

Read a row

Each row is one protocol and port, with everything holding it:

Badge Occupant
host A process on your Mac
docker, orbstack, colima, trmnly A container publishing the port
tunnel A rule from an active port-forward preset
reserved A reservation you saved. Nothing is bound yet

Where TRMNLY can tell, the row names the owning project:

  • A host process is matched by its working directory. A server started inside a project folder belongs to that project.
  • A container is matched through its Compose project.
  • A tunnel is matched by the project set on its preset.

If ownership can't be worked out, the row shows no owner instead of guessing.

Use the chips at the top to narrow the list: TCP, UDP, and Hide >49152 to drop high ephemeral ports.

Spot a conflict

A row turns red and shows CONFLICT when two occupants really compete for the port. TRMNLY ignores the usual false alarms. A server listening on both IPv4 and IPv6 is one occupant. So is a container and its runtime's proxy process.

A process from one project bound to a port reserved for another project is a conflict.

Reserve ports for a project

A reservation tells TRMNLY "this project owns these ports" before anything runs, so suggestions steer around them.

  1. Click the + button. Its tooltip reads Reserve a port (range) for a project. You can also click the shield icon on any row to reserve that port.
  2. Enter a Label, for example App A web.
  3. Pick a Protocol.
  4. Turn on Range to reserve a span, then fill in Start and End. A range can be up to 1,024 ports wide.
  5. Pick the Project and add notes if you want.
  6. Click Save.

The row now shows RESERVED, and the count under the table goes up by one. Reservations survive relaunches and are stored encrypted on macOS.

Free up a port

  1. Click the stop button on a host row. Its tooltip reads Kill the host process holding this port.
  2. Confirm in the Kill listener on … dialog.

TRMNLY sends the process a polite stop signal, waits 1.5 seconds, then forces it. Container ports can't be killed this way. Stop the container from the Containers tab instead. A process owned by another user reports "permission denied". Use sudo from a terminal for those.

Ask the agent for a free port

The agent has a set of ports_* tools. The useful pattern is "check, then claim":

  1. Ask: "Is port 3000 free?" The agent calls ports_check, which says who holds the port and suggests the next free one.
  2. Ask: "Claim a port for this project's API server." The agent calls ports_claim. It picks a free port and saves a reservation for the project in one step. Claiming needs your approval.

A port counts as free only if nothing holds it, it isn't below 1024, it isn't on a list of ports other software tends to grab (5000 and 7000 are used by AirPlay on macOS), and a live test bind succeeds.

Plan before anything runs

Projects usually write their ports down in .env files, docker-compose.yml, package.json scripts and framework config files. TRMNLY reads those.

  • Ask the agent: "Which projects declare the same port?" It calls ports_declared and lists collisions with the file each one came from.
  • Ask it to reserve a project's declared ports. It calls ports_import_declared, moving any port that is already taken. Ask for a dry run first to see the plan.

A remapped reservation is only a record. You still have to change the port in the project's own config.

Port aliases

Every project has a short, stable name, so its ports can be written as <project>.<port>, for example shop.3000. The agent's port tools accept an alias anywhere they take a port. Hover a project's alias in the table to see it.

Check yourself

  • Your dev server's port appears with your project's name on the row.
  • A reservation you made shows RESERVED and survives a relaunch.
  • The agent answers "is port 3000 free?" with the current holder or a free alternative.

Go further