Client

The client side is your machine and your folder. Everything you serve lives in one flat directory — on the reference machine that is ~/Developer/LIVE/Port. You author handlers there, test them locally, and the sync client mirrors the whole folder to the server, where the broker turns it into live ports.

The port folder

It is not partitioned by domain or by service — it is one flat script directory. Top-level files with handler names are the entry points; everything else is yours to organise into whatever sub-folders and shared libraries you like.

~/Developer/LIVE/Port/
  echo.tcp.7000.port.js       →  live: TCP :7000
  metrics.udp.9125.port.js    →  live: UDP :9125
  echo.tcp.7000.port.json     →  access manifest for the echo handler
  lib/
    framing.js                →  supporting code — imported, opens no port
  _relay.tcp.4000.port.js     →  local only (leading _)
  .notes.md                   →  local only (dotfile)

What syncs, and what stays

In the folder	Synced?	Opens a port?
Top-level `<name>.tcp.<port>.port.js` / `.udp.`	Yes	Yes — this is an entry point.
Optional `<name>.<proto>.<port>.port.json` sidecar	Yes	No — it configures the handler beside it. See Manifest.
Other files & sub-folders (shared libraries)	Yes	No — imported by handlers, but never a listener.
Anything starting with `_`	No	No — ignored entirely, never uploaded.
Dotfiles (`.git`, `.notes.md`, …)	No	No — ignored entirely.

So the folder is safe to keep under version control and to fill with scratch files: only the files you name as handlers ever become reachable from the internet.

Develop in place

The _ prefix is the develop-locally switch. Name a work-in-progress handler _relay.tcp.4000.port.js and it never leaves your machine — no upload, no port. Run and test it locally however you like. When it is ready, drop the underscore to relay.tcp.4000.port.js; the next sync uploads it and the broker opens :4000. To take a live port offline again, put the underscore back: the next sync withdraws it and the broker closes the port.

The edit loop

Leave the client watching while you work. It re-syncs on every change, so a save on your machine becomes a reload on the server within seconds.

node client/sync.js --config config.json --watch

Use --dry-run first if you want to see what a sync would push without pushing it, and --verbose to watch each file decision. Every flag is in the Commands reference.

How a set of edits goes live

Editing several files at once raises an obvious hazard: what if the sync is halfway through when the server reloads? A handler could import a library the client hasn't uploaded yet. Porthoster avoids this by treating a sync as a transaction — the server keeps serving the last complete generation of your folder until the whole push has landed and been verified, then swaps to the new one. You edit freely; the switch is all-or-nothing.

⚑ Open question · Atomic promotion of changes (Q8)

From the author's side: you may save a batch of edits — a new handler plus the shared library it imports — and the client will push them across several requests. A half-applied set must never go live, or the broker would load a handler whose dependency is missing. The server holds the last complete generation live until the client signals the push is done and the tree hash matches, then promotes the new generation atomically and reloads only the handlers that changed.

Proposed: transactional promotion, so your in-progress saves are never visible to the internet. Open: when a live handler is reloaded, whether its existing connections are dropped or allowed to finish on the old code while new connections use the new code.

Next steps

How the broker serves it → The files reference →