Docs / Start scripts and ports
Start scripts and ports
Appling starts an app by running one small script. Knowing that explains most of what you'll see.
How an appling starts
An app appling points to a start script: a small file ending in .command that contains the command to run, such as npm run dev. Clicking Start runs that file under Appling, without opening a terminal window.
Appling never stores a raw command in its list. The command always lives in a file you can open, read and edit.
Where the script lives
When Appling or your AI tool creates a start script, you choose between:
- In the project folder, as
Start <Name>.command. Easy to find and edit. - In Appling’s own folder, so nothing new appears in your project. Useful when you don’t want an untracked file in a git repository.
You can move a script into Appling later from Edit Appling.
How ports are found
Appling asks macOS which ports the app’s processes are listening on. It does not guess from what the app prints. That is why the address button shows the port that works, even when the output mentions other addresses.
When a port is taken
Before starting, Appling checks the port the app used last time. If something else is listening on it, Appling tells you what it is (another appling, or a process by name and ID) and offers to stop it first.
The Ports page in the sidebar lists everything listening on your Mac, with each process and its folder.
Changing a port
Open the appling, click the Port box, and choose a port. Appling suggests the next free one. It then starts the app with the PORT variable set to your number.
This works when the start script or the framework reads PORT. Many do; some, such as Vite, use their own setting instead. If the app ignores it, the Port box shows the port it actually took. To make such an app follow PORT, edit its start script, or ask Claude Code or Codex to.
Stopping
Stop ends the app and everything it started. Quitting Appling asks first, then stops every running appling.
Last updated November 15, 2026