Listing your local platforms

Summary#

Shows every local platform this machine has, and which of them are running right now. Each project gets its own — the loop commands start one on demand (Running a local platform) — and Stopping the local platform stops exactly one, the project you are standing in. This is the other half: seeing what is up before deciding what to stop.

Signature#

osy instances [--running] [--all] [--stale] [--json]

Description#

Running platforms are listed first, each with its URL, the process behind it, and how long it has been up. A platform counts as running only when the process it recorded is verified to still be that process — a recorded process id on its own is not proof, because the system reuses ids, so anything unproven is reported as such rather than guessed at.

A platform that has not finished starting is listed as starting, with the step its start is on and how long it has been on it. It counts as running — --running includes it and osy stop can stop it — because it is already a live process holding its project's database, even before it answers. A start that stays on the same step for minutes is stuck rather than slow: its log says so as it happens, and stopping it and starting again is the remedy.

• --running lists only the platforms with a verified live server, including one that is still starting.
• --all also lists directories that have never run a server. Working in a throwaway project leaves one behind, so these accumulate; they are counted in the summary line by default and printed in full with this flag.
• --stale lists only the platforms whose project directory no longer exists.
• --json emits the list for tools and agents.

The summary line reports the total disk all of them occupy. Each carries a database of its own, so the figure grows faster than the count suggests — Reclaiming the disk your local platforms use deletes the ones you have finished with.

They are this computer's, wherever OSY_HOME points. OSY_HOME moves the toolchain's own files — the package cache, its search and font caches, config.json and its logs — and not the local platforms: instances are always under ~/.osy/instances, beside the PostgreSQL the platform downloaded (~/.osy/pg, or OSY_PG_DIR) and the browser for screenshots (~/.osy/browser, or OSY_BROWSER_HOME). One platform per checkout, the ports they take and the clean-up of unused ones all read that one list, so a command run under a private OSY_HOME still starts, lists and stops the same platforms as one run without it.

Listing never signals anything — it only reads. To stop one, go to its project and run osy stop, or name it directly with osy stop --devname <name>. Stopping a platform by killing processes by name is never the right move: another project's platform, or a test run, can be caught in the same sweep.

Examples#

osy instances --running     # just what is still up

osy instances --json        # the same list, for a tool to read

See also#

Reclaiming the disk your local platforms use — delete the ones you are no longer using.

Stopping the local platform — stop one of the platforms this lists.

Running a local platform — what a local platform is, and how the loop starts one per project.

Launching your app — compile and open your app, starting a platform if there isn't one.