# 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.
