All pages
Docs · Right-sidebar surfaces
Ports
Availability: macOS · Linux · Windows · daemon · cloud workspace. All ten ports_* tools run wherever the portable core does; the Ports panel described here is the macOS one, and two behaviours differ off macOS — see Off macOS.
The Ports panel (Conn tab → Containers → Ports) is one table of everything holding a port on this machine: host processes, container publishes, active SSH tunnels, and your own reservations. It exists to answer the two questions that come up when you run several projects at once:
- What's on 3000, and whose is it?
- Where do I put this next service so it stays out of the way?
The table
One row per protocol + port. Each row lists its occupants:
| Badge | Occupant |
|---|---|
| host | A process on this Mac, shown as pid · command |
| docker / orbstack / colima / trmnly | A container publishing that port, shown as container → :containerPort |
| tunnel | A rule from an active port-forward preset |
| reserved | A reservation you saved — nothing is bound yet |
Rows refresh every 12 seconds while the panel is open, and on demand from the refresh button.
Who owns it
Where TRMNLY can work it out, a row names the project that owns the listener:
- Host processes are attributed by working directory. A dev server started from a project folder inherits that folder as its cwd, so the deepest project root containing it wins — a monorepo package beats the repository around it.
- Containers are attributed through Compose. Compose names containers
<project>-<service>-<n>, which identifies the Compose project, whose directory maps back to a TRMNLY project. - SSH tunnels are attributed by the preset. A port-forward preset can name the project its local listeners serve; leave it unset for a machine-wide tunnel.
Attribution is best-effort and says so: a system daemon, or a server launched
from / with an absolute path, shows no owner rather than a guessed one.
Conflicts
A row badges CONFLICT in red when two occupants genuinely contend, and prints who is fighting whom underneath.
These are deliberately not conflicts:
- One process on IPv4 and IPv6. A dual-stack server produces two entries from the operating system's point of view. It isn't fighting itself.
- A container plus its host-side proxy.
docker-proxy, OrbStack, vpnkit and Colima all appear as host listeners for a port their container publishes. One container, one occupant. - Disjoint addresses.
127.0.0.1:3000and192.168.1.10:3000can both be bound at once. A wildcard bind (*,0.0.0.0,::) overlaps everything, so that does conflict. - A project bound to its own reservation. That's the reservation working.
A binding by a different project — or an unattributed one — on a port reserved for someone else is a conflict.
Reservations
A reservation says "this project owns 3000–3010", so suggestions steer around it before anything is running. Reservations persist across launches, and on macOS they are stored encrypted under a key held in the Keychain.
Create one from the + button or the shield icon on any row. A reservation
carries a label, an optional project, a protocol, a single port or a range
(capped at 1024 wide), and free-form notes.
Finding a free port
The suggestion engine considers a port free only when all of these hold:
- Nothing in the last scan holds it — host, container, tunnel, or someone else's reservation. Your own project's reservations don't count against you.
- It isn't privileged (below 1024), which would need root to bind.
- It isn't on the discouraged list: 5000 and 7000 (macOS AirPlay Receiver re-takes these after any kill), 5432 Postgres, 3306 MySQL, 6379 Redis, 27017 MongoDB, 11211 Memcached, 9200 Elasticsearch.
- A live bind probe succeeds. The scan is up to 12 seconds old, so the kernel gets the final say — this is what stops TRMNLY handing you a port that was claimed while you were reading the table.
Both filters can be overridden when you actually want a privileged or conventional port.
Declared ports — planning before anything runs
Everything above is reactive: it can only tell you about a collision once two things are already fighting. Most collisions are knowable much earlier, because projects write their ports down. TRMNLY reads them:
| Source | What it reads |
|---|---|
.env, .env.local, .env.development … |
PORT=, SERVER_PORT=, VITE_PORT=, any *_PORT key |
docker-compose.yml / compose.yaml |
Published host ports, including ${VAR:-3847} resolved against the project's .env, ranges, /udp, and the long published: form |
package.json |
--port, -p, and PORT= inside script bodies |
vite.config.*, next.config.*, and friends |
port: 3000 |
The scan walks the project root and one level below it, skipping node_modules,
.git, build output and the like, with a bounded file budget.
Listen versus connect
SMTP_PORT=587 and EMAIL_PORT=25 are ports the project dials, not ports it
binds. Reserving those would claim something the project never listens on, so
every declaration is tagged listen or connect and only listen ones are
reservation candidates. Connect ones are still reported — they're useful
context — but they never count as a collision, because two projects using the
same mail relay aren't competing.
Cross-project collisions
Two projects that both declare PORT=3000 will collide the first time they run
together, and that's visible before either starts. ports_declared reports
those as collisions, naming each claimant and the file it came from.
ports_import_declared then turns one project's declarations into
reservations, moving any that are already spoken for and reporting the old →
new mapping with the reason. Run it with dry_run:true first to see the plan.
A remap records the intent. The project's own
.envor compose file still has to be updated to match, or the service will keep trying its declared port. The response says so too.
Aliases
Every project has a stable slug, so a port belonging to it can be addressed as
<slug>.<port> — aw3.3000, angelsend.5173. Slugs are assigned at project
creation and survive renames, so an alias you used a month ago still resolves.
Prefix with tcp: or udp: to disambiguate protocol.
Killing a listener
The ✕ on a row SIGTERMs every host process holding the port, waits 1.5 seconds, then SIGKILLs anything still up.
- Container ports are not killed this way — stop the container from the Containers tab instead. TRMNLY suppresses the proxy processes so you can't accidentally take down the runtime's plumbing.
- Processes owned by another user report "permission denied" rather than
claiming a kill that never happened. Use
sudofrom a terminal for those.
Agent tools
| Tool | Approval | Use |
|---|---|---|
ports_check |
no | "Is port N free, and whose is it?" Returns occupants with owning project, any conflict, and the next free port when it's taken. Bind-probed, so it's authoritative. |
ports_list |
no | The whole table. Filter with conflicts_only, project_name, proto; limit defaults to 100 |
ports_suggest_free |
no | Next free port (or contiguous block via count), with skipped explaining what was passed over and why |
ports_claim |
yes | Find a free port and reserve it for a project in one call. preferred_port tries a specific one and reports movedFrom with a reason if it had to move |
ports_reserve |
yes | Save a reservation directly |
ports_release |
yes | Delete a reservation by id, covering port, or alias |
ports_kill_listener |
yes | SIGTERM/SIGKILL the host processes on a port |
ports_declared |
no | What each project's config says it will bind, before anything runs, plus cross-project collisions |
ports_import_declared |
yes | Turn declarations into reservations, remapping ones already taken. dry_run shows the plan |
ports_resolve_alias |
no | Turn aw3.3000 into project + port + current state |
Prefer ports_check over ports_list for a single port — ports_list returns
the whole machine.
The natural conflict-resolution sequence is ports_check → ports_claim:
find out who has it, then take a port that's yours and recorded, so the next
project doesn't ask for the same one.
Off macOS
The scan, the conflict rules, the declared-port reader, aliases and every
ports_* tool are the same code on Linux, Windows, the daemon and the cloud
box. Two things differ, both because the pieces they lean on are macOS-only:
- Container and tunnel rows are host rows. The Docker and port-forward overlays that label a row docker or tunnel, and name the container or preset behind it, come from the macOS app. Elsewhere the port a container publishes, or a tunnel listens on, appears as the plain host process holding it. It is the same port with a less specific name on it.
- Reservations are plain JSON. Encryption needs a key store, and off macOS there is no Keychain to hold one. A key derived from something sitting on the same disk would travel with the file it protects, which is theatre rather than protection — so the file is written as readable JSON instead, and this page says so rather than implying a protection that isn't there.
What lives where
- Reservations:
~/Library/Application Support/TRMNLY/ports.json(encrypted on macOS; plain JSON in the equivalent directory on other hosts) - Scanner and suggestion engine:
Features/Connections/Ports/PortManager.swift - Conflict rules:
Features/Connections/Ports/PortModels.swift - Attribution and the bind probe:
Features/Connections/Ports/PortProjectAttribution.swift - Agent tools:
Features/Agent/AgentToolsPorts.swift