From one command to a whole local system.

1.1Install and verify#

Requires macOS 13 or newer. Homebrew installs the signed, notarized app, the launch command, and its local service. Your project still needs its own tools and dependencies: Node for npm/Expo, Python for Python commands, or Xcode and a downloaded Simulator runtime for iOS.

brew install --cask JakeMawson/tap/launchstation
launch --help
launch doctor

Open Launch Station from Applications. launch doctor checks service compatibility and reports the installed service version. This reference covers the current CLI surface, including named endpoints; if a flag is unknown, check your installed version and update.

brew update
brew upgrade --cask JakeMawson/tap/launchstation

1.2Project, launcher, action, session#

Saving a launcher does not run it. Editing a definition does not change an already-running session. Relaunch creates a fresh session using the updated definition.

1.3Your first working launcher#

In Terminal, move into an existing project folder. This self-contained example serves that folder using Python 3; confirm python3 is installed first. It only exposes a loopback address.

cd ~/Projects/my-project
launch init . --project-name "My project"

launch create "My project docs" "Serve this project's files locally" \
  --type process --port auto \
  --url 'http://${HOST}:${PORT}/' \
  --health 'http://${HOST}:${PORT}/' \
  -- python3 -m http.server '${PORT}' --bind '${HOST}'

launch "My project docs" --open
launch status "My project docs"
launch logs "My project docs"
launch close "My project docs"

Choose a globally unique launcher name. Replace the example directory and project name with your own. Serving a directory makes its files available to local browser clients, so choose the directory intentionally.

2.1Read the examples#

Flags use separate tokens: --port auto, not --port=auto. Boolean switches have no following true or false. Put positional names before options where the synopsis shows that order. launch --help, launch -h, and launch help show the top-level help; there is no universal per-command --help or dry-run switch.

2.2The two meanings of --#

launch create "Shop web" "Run the frontend" --type process --port auto \
  -- npm run dev -- --host '${HOST}' --port '${PORT}' --strictPort

The first -- ends Launch Station's definition options. npm is the executable; everything after it is a stored argument. The second -- belongs to npm and forwards subsequent flags to the script. --host, --port, and --strictPort at that position belong to Vite, not Launch Station.

launch "Shop web" -- --mode demo

On run or relaunch, arguments after -- are appended to the primary action's stored arguments for this session. They are not saved back to the definition. On create/action add, a nonempty executable tail replaces any --executable and --arg values, clears the shell command, and converts a shell runner to process. Do not combine the two command forms.

2.3Quoting, substitution & aliases#

Single quotes preserve ${HOST}, ${PORT}, and linked-action placeholders until Launch Station starts the action. Double quotes around a path such as "$PWD" expand it in your current shell at registration time. Direct actions do not interpret pipes, &&, redirects, glob patterns, or $NAME as shell syntax. Use --command when shell syntax is needed.

launch create "Shop shell" "Start via zsh" \
  --port auto --url 'http://${HOST}:${PORT}/' \
  --command 'npm run dev -- --host "$HOST" --port "$PORT" --strictPort'

These are top-level command aliases, not additional flags for every command. --dir aliases --directory only on commands that accept that directory option.

3.1Initialize or rename a project#

launch init [DIRECTORY] [--project-name NAME] [--json]
launch project update --name NAME [--directory PATH] [--if-revision N] [--json]

Launcher creation resolves the exact project or nearest registered ancestor of the supplied directory. Initialize the actual repository/application root deliberately. A conflicting unmanaged launch_details.md is not overwritten; inspect it before deciding how to resolve the conflict. There is no CLI project-move or project-delete command.

launch project update --directory ~/Projects/shop --name "Shop storefront"

3.2List and search#

launch list [QUERY] [--tag TAG] [--state STATE] [--directory PATH] [--json]

launch list "web" --tag local --directory ~/Projects/shop
launch list --state running --json

Launcher names are unique across all projects. Matching ignores case, repeated/surrounding whitespace, accents, and character width. Names allow at most 80 characters and 240 UTF-8 bytes, cannot begin with a hyphen, and cannot contain slashes or control characters. CLI command words such as run, status, project, and help are reserved launcher names.

3.3Details, status & health#

launch details NAME [--json]
launch retrieve NAME [--json]
launch status [NAME] [--json]
launch doctor [DIRECTORY] [--json]

These commands inspect the catalog and service; they do not launch your project. JSON is useful for copying exact session IDs and revisions. External listeners are a separate observation surface.

4.1Required inputs and command forms#

launch create NAME DESCRIPTION [RUN_DETAILS] [OPTIONS] -- EXECUTABLE ARG...
launch create NAME DESCRIPTION [RUN_DETAILS] --command COMMAND [OPTIONS]

NAME and DESCRIPTION are required nonempty strings. The project must already be initialized. Supply a runnable command or target: a direct executable tail, --command, or an explicit runner with --executable. Creation saves a definition only. RUN_DETAILS is optional descriptive prose and is never executed.

4.2Runner, executable & action fields#

Changing --type to shell clears executable; changing to a non-shell runner clears the shell command. Choosing url also clears arguments and disables runtime arguments. Put the type before its command fields, and finish with a valid combination. A bare --executable does not itself switch the default shell runner.

4.3Port, health & opening flags#

4.4Environment flags#

Do not put secrets in any saved field. Names, commands, arguments, environment values, descriptions, tags, and notes are visible in the app, JSON, database, and generated project summary. Have the launched program read credentials from an appropriate secret store.

When a managed port is enabled, its configured port and host aliases cannot also appear in --env or --inherit-env. Baseline PATH includes ~/bin, Apple system paths, /opt/homebrew/bin, and /usr/local/bin. A daemon is not your interactive shell: use a known executable or absolute virtual-environment path rather than relying on aliases, nvm activation, or .zshrc.

5.1Vite and Next.js#

launch create "Shop Vite" "Run the Vite frontend" \
  --directory ~/Projects/shop --tag web \
  --type process --port auto \
  --url 'http://${HOST}:${PORT}/' --health 'http://${HOST}:${PORT}/' \
  -- npm run dev -- --host '${HOST}' --port '${PORT}' --strictPort

Vite's --strictPort stops it from silently moving to another port. Launch Station must know the actual listener it owns.

launch create "Shop Next" "Run the Next.js frontend" \
  --directory ~/Projects/shop-next --type process --port auto \
  --url 'http://${HOST}:${PORT}/' --health 'http://${HOST}:${PORT}/' \
  --ready-timeout 90 \
  -- npm run dev -- --hostname '${HOST}' --port '${PORT}'

Next.js uses --hostname, not Vite's --host. Do not add Vite's --strictPort to a different CLI. If your dev script invokes another framework, use that framework's actual host/port syntax.

5.2Python, virtual environments & custom services#

launch create "Research files" "Serve the local public directory" \
  --directory ~/Projects/research --cwd public \
  --type process --port auto \
  --health 'http://${HOST}:${PORT}/' --url 'http://${HOST}:${PORT}/' \
  -- python3 -m http.server '${PORT}' --bind '${HOST}'

launch create "Research API" "Run the ASGI API" \
  --directory ~/Projects/research --type process --port auto \
  --health 'http://${HOST}:${PORT}/health' --url 'http://${HOST}:${PORT}/docs' \
  -- ./.venv/bin/uvicorn app:app --host '${HOST}' --port '${PORT}'

This assumes .venv contains Uvicorn, app:app exists, and the API implements /health. Replace those values to match your code. Slash-containing relative executables resolve from the action's working directory.

launch create "Custom API" "Run the project server" \
  --directory ~/Projects/custom-api --type process --port auto \
  --port-env APP_PORT --host-env APP_HOST \
  --url 'http://${HOST}:${PORT}/' --health 'http://${HOST}:${PORT}/health' \
  -- node server.mjs --host '${APP_HOST}' --port '${APP_PORT}'

The last recipe assumes your server supports those two flags. --port-env changes the process variable alias, not the ${PORT} spelling used in endpoint templates.

5.3Non-server commands and shell workflows#

launch create "Shop worker" "Run the background worker" \
  --directory ~/Projects/shop --type process --port none \
  --env APP_MODE=development -- node worker.mjs

launch create "Shop pipeline" "Transform local input" \
  --directory ~/Projects/shop --type shell \
  --command './scripts/read-input | ./scripts/transform-output'

Use process for exact argument boundaries; use shell when the shell must interpret a pipeline or redirect. Required executables/scripts must already exist. A finite command transitions to exited when it finishes; Launch Station does not keep it running or invent a server endpoint.

Shell stored arguments and runtime arguments are quoted and appended once. Direct executable, argument, and environment strings support ${NAME} substitution from the action environment. Undefined values cannot stand in for required configuration; inspect your command and output.

5.4Native apps, URLs and files#

launch create "Shop Xcode" "Open Xcode for this project" \
  --directory ~/Projects/shop --type app --open application \
  --app-bundle-id com.apple.dt.Xcode \
  -- /Applications/Xcode.app

Application arguments are passed through LaunchServices as app arguments. They are not shell commands or guaranteed document-opening instructions. Launch Station only closes an exact newly owned instance; if LaunchServices reuses an existing app, it leaves that instance alone.

launch create "Shop readme" "Open the project README" \
  --directory ~/Projects/shop --type url \
  -- "$HOME/Projects/shop/README.md"

A URL runner accepts one absolute URL or existing absolute file path, stores no arguments, and completes after opening it. It does not own or close the receiving browser/editor. Use this form for a workspace/document when you only want it opened.

6.1Expo in Simulator#

launch create "Mobile Expo" "Start Expo in iOS Simulator" \
  --directory ~/Projects/mobile --tag expo --tag ios \
  --action-name metro --action-description "Expo Metro bundler" \
  --type ios --port auto --open simulator \
  --ready-timeout 120 \
  -- npx expo start --ios --go

Requires a working Expo project and Xcode with an available iOS Simulator runtime. Launch Station recognizes expo, npx expo, and supported shell forms. It adds a missing localhost host mode and managed port, and adds --ios when simulator opening is configured. Explicit host modes, ports, --ios, and -i are not duplicated.

Expo's --go selects Expo Go. Replace it with --dev-client when you already have a compatible development build installed. Without either override, Expo chooses according to the project's development-client setup. These are Expo flags, not Launch Station definition options.

6.2Metro without opening Simulator#

launch create "Mobile Metro" "Start Metro without opening a device" \
  --directory ~/Projects/mobile --type process \
  --port auto --open none \
  -- npx expo start --localhost --port '${PORT}'

Use process, --open none, no --ios/-i, and no Simulator-specific environment when you want no device interaction. An ios runner can still select/boot a Simulator as part of preparation. The managed process has no attached interactive Terminal UI; use saved flags and session open choices rather than expecting to press Expo's interactive keys.

Expo web differs across bundlers/SDKs. Check npx expo start --help for the project's installed version before storing --web; confirm that the web server actually consumes the allocated port. Do not assume Metro and a separate web listener share a port. Give each persistent listener its own managed action. For exported static web files, use the Python static-server recipe.

6.3Device and app configuration#

launch update "Mobile Expo" \
  --env 'CODEX_SIMULATOR_DEVICE=iPhone 16 Pro'

The device name must exist on your Mac. Use xcrun simctl list devices available to see available names/UDIDs. Exact device IDs are less ambiguous when names repeat.

6.4Custom Simulator commands and close behavior#

launch create "Demo Simulator" "Run the installed simulator app" \
  --directory ~/Projects/demo --type ios --open simulator \
  --env CODEX_SIMULATOR_DEVICE=booted \
  -- xcrun simctl launch --console '${CODEX_SIMULATOR_UDID}' com.example.DemoApp

Replace the bundle identifier with your app's installed identifier. A built app can be prepared using the APP_PATH/BUNDLE_ID/APP_ARGUMENTS environment fields above; it must be a Simulator-compatible build.

7.1Managed allocation and readiness#

--port auto asks codex-port for a verified loopback allocation. --port N requests a fixed port and refuses an unrelated listener. --port none uses the process-group runner without a managed TCP port. A URL field alone does not turn an unmanaged listener into a managed one.

The launched command must consume the allocated host/port, through environment variables or arguments. A framework that silently switches ports can invalidate the expected endpoint, so use its strict binding option when available. Managed host defaults to 127.0.0.1; detected Expo uses localhost.

HTTP health readiness succeeds on status 200–399 within the ready timeout. Without an HTTP health URL, successful process start is not proof that your application is usable. A required failure closes earlier owned actions; an optional failure may produce a partial session.

The port lease defaults to eight hours. The daemon renews active managed ownership before expiry while it remains healthy. A fresh lifecycle may reuse the same numeric port after the old listener has fully stopped; fresh means a new verified owner, not necessarily a different number.

7.2Substitution rules#

A port placeholder in a URL or health template requires auto/fixed mode. For a no-port static endpoint, HOST aliases resolve to loopback. Browser opening uses the action URL, then health URL; a managed port can otherwise supply a default HTTP endpoint.

7.3Named in-app destinations#

launch update "Shop Vite" \
  --endpoint 'Dashboard: /dashboard' \
  --endpoint 'Settings: /settings' \
  --endpoint 'Documentation: /docs'

launch update "Shop Vite" --clear-endpoints

These are navigation shortcuts under the primary action's exact running HTTP(S) origin. They do not create server routes, add services, or perform health checks. The app offers them only when the selected session has a usable browser origin. Configure them after creating the launcher and relaunch to give a new session the updated endpoint snapshot.

8.1Add, update and remove an action#

launch action add LAUNCHER ACTION DESCRIPTION [DEFINITION OPTIONS] -- EXECUTABLE ARG...
launch action update LAUNCHER ACTION [MUTATION OPTIONS] [--if-revision N] [--json]
launch action delete LAUNCHER ACTION [--yes --if-revision N] [--json]

Action add requires the launcher name, action name, and nonempty action description. It supports the action-definition flags in section 04, but not launcher-level --directory, --run-details, --tag, or --tags. It fetches and binds the current launcher revision internally; action add does not accept --if-revision.

Action update accepts --name / --description as aliases for action name/description, plus the mutation flags in section 10. It edits that action without changing which action is primary. Action delete follows the confirmation rules in section 10. The sole remaining action cannot be deleted; deleting the primary in a multi-action launcher selects the first remaining ordered action.

8.2API plus frontend, end to end#

Assumes a project with server/server.mjs accepting host/port arguments and a frontend directory containing a Vite dev script. Install both projects' dependencies first.

launch init ~/Projects/shop --project-name "Shop"

launch create "Shop stack" "Start API and frontend together" \
  --directory ~/Projects/shop --tag compound \
  --action-name api --action-description "Local API server" \
  --cwd server --order 10 --type process --port auto --port-name api \
  --url 'http://${HOST}:${PORT}/' --health 'http://${HOST}:${PORT}/health' \
  -- node server.mjs --host '${HOST}' --port '${PORT}'

launch action add "Shop stack" frontend "Vite frontend" \
  --cwd frontend --order 20 --type process --port auto --port-name frontend \
  --url 'http://${HOST}:${PORT}/' --health 'http://${HOST}:${PORT}/' \
  --env 'VITE_API_URL=${LAUNCH_STATION_ACTION_API_URL}' \
  -- npm run dev -- --host '${HOST}' --port '${PORT}' --strictPort

launch update "Shop stack" --primary-action frontend
launch details "Shop stack"
launch "Shop stack" --open
launch close "Shop stack"

API starts and becomes ready first, then frontend. The frontend receives the actual API URL. Closing reverses the order. Runtime arguments and bare --open apply to frontend because it is primary.

For a database or worker, add another action with a unique earlier order and the project's real start command. If it opens a TCP listener, configure that listener's own managed port and explicit binding. A placeholder script does not automatically make database readiness or port management work.

8.3Dependency constraints and failure handling#

Token generation uppercases the normalized action name and replaces punctuation with underscores. Prefer simple ASCII action names such as api and frontend. Names without an ASCII alphanumeric token use an ID-derived fallback; inspect the returned definition instead of guessing it.

9.1Run and relaunch#

launch NAME [--new] [--open] [--json] [-- RUNTIME_ARG...]
launch run NAME [--new] [--open] [--json] [-- RUNTIME_ARG...]
launch relaunch NAME [--session UUID] [--open] [--json] [-- RUNTIME_ARG...]

Ordinary run returns an existing active primary unchanged. New runtime arguments and --open do not modify or re-open that reused instance. Use relaunch to apply new arguments, or launch open to select an existing target.

Relaunch is one daemon operation: reserve the exact selection, close it, then start a distinct replacement. It preserves primary/additional role and leaves other sessions alone. From idle it starts a new primary. It refuses an overlapping replacement if close loses ownership or the definition/selection changes during the operation.

9.2Open a specific target#

launch open NAME [--session UUID] [--json]
launch open NAME --option OPTION_ID [--session UUID] [--probe] [--json]

Option IDs are opaque and session-specific. Browser URLs, native app focus targets, named endpoints, or Simulator choices come from the daemon; do not substitute a raw URL, PID, or invented option ID. An expired or unavailable target must be refreshed from the current session.

9.3Logs and durable history#

launch logs NAME [--session UUID]
launch history [NAME] [--state STATE] [--role primary|additional] [--limit N] [--cursor TOKEN] [--json]

History is newest first and records managed runs, including their original revisions and action definitions. It is not a list of every process on your Mac. External listener observations never become managed history automatically.

launch history "Shop stack" --role additional --state running --limit 20 --json

9.4Close and interpret state#

launch close NAME [--session UUID] [--json]

Without --session, close targets the active primary only; if none exists, it reports a conflict instead of picking an additional instance. With a UUID, it verifies membership and that the session is active. Closing a multi-action session reverses startup order.

Process-group close escalates SIGINT → SIGTERM → SIGKILL within the recorded budget only while exact identity holds. Managed-port close delegates to the recorded manager ID. App close excludes reused instances; URL close does not close a receiving app; iOS close never shuts down Simulator.

10.1Launcher metadata and primary selection#

launch update NAME [LAUNCHER FIELDS] [ACTION MUTATIONS] [--if-revision N] [--json]

--tag is a creation flag; use --add-tag or --tags when updating. Project directory is not changed through launcher update. Action edits in this command target the current primary unless --primary-action selects another first.

launch update "Shop stack" --description "API and frontend for local work" --primary-action frontend

10.2Every action mutation#

All action fields from section 04 can be changed using launch update or launch action update. In addition to those setters, the following flags alter or clear existing values. The command is validated as a complete action before saving.

Mutation flags are applied in order. For example, --clear-args --arg a --arg b produces ["a","b"]. Prefer an atomic --args-json replacement when changing an entire command. Switching to URL clears arguments and denies runtime arguments.

10.3Safe command replacement examples#

launch details "Shop Vite" --json
launch update "Shop Vite" \
  --type process --executable npm \
  --args-json '["run","dev","--","--host","${HOST}","--port","${PORT}","--strictPort"]'
launch relaunch "Shop Vite" --open

launch action update "Shop stack" api \
  --ready-timeout 90 --env LOG_LEVEL=debug
launch action update "Shop stack" api --remove-env LOG_LEVEL

An explicit --if-revision refers to the launcher revision, even for action mutations. On conflict, retrieve fresh details and review the concurrent change before retrying. Do not blindly repeat a mutation after a lost response; it may already have succeeded.

10.4Delete a saved shortcut or action#

launch delete NAME
launch action delete LAUNCHER ACTION

launch delete NAME --yes --if-revision N [--json]
launch action delete LAUNCHER ACTION --yes --if-revision N [--json]

Interactive deletion requires a Terminal/TTY and the exact displayed launcher/action name. --yes skips the typed prompt only when accompanied by --if-revision N; it is not an unrestricted force option. Supply the revision you just inspected.

Deleting a launcher is refused while managed sessions are active, when confirmation expires, or when its revision changes. The shortcut is removed from the catalog; project source files and durable history are not deleted. An action cannot be removed if it would leave the launcher empty. Do not delete and recreate a launcher merely to change its command.

11.1Find and review an outside listener#

launch external list [--refresh] [--json]
launch external draft OBSERVATION_UUID [--json]

List returns the daemon's cached listener inventory; --refresh requests a current scan. Each observation has an ephemeral UUID, PID identity, endpoints, ownership classification, and available command information. Bare launch external defaults to list.

Draft refreshes the observation and returns a proposal only. It neither saves a launcher nor adopts the process. Review directory, runner, command, arguments, and port policy, then create a launcher through the normal flow if appropriate. Use the real command rather than a redacted placeholder.

11.2Confirmation-bound external close#

launch external close OBSERVATION_UUID

Requires a TTY and the exact freshly displayed confirmation text. It accepts no --json, --yes, arbitrary PID, or port argument. The daemon rechecks identity and closability before signaling.

Stale, already-managed, unverified, or unsafe observations are refused. Observation IDs and close intents are transient and do not survive daemon restart. After saving a reviewed launcher, future managed sessions have their own identities; the previously outside process does not become one of them.

12.1Find and operate a launcher#

Open Launch Station from Applications. Search by launcher name, project, directory or tags. Select a launcher to inspect its working directory, run details, saved actions, endpoint configuration and active sessions.

12.2Edit, add and inspect#

To create a launcher without Terminal, click Add Launcher below the catalog. Enter a name, description, and existing project directory (Browse can select it). Choose Process for a direct executable and arguments, or Shell for an intentional shell command. Review the working directory, port mode and opening behavior; the form marks uncertain fields as Review required. Confirm that you have reviewed the command, directory, and port settings, then save. Saving defines the launcher; it does not start it.

For a managed web server, choose an automatic port and pass its HOST/PORT placeholders to your server command. Enable the HTTP open target only when the action actually serves HTTP. Command arguments are separate values, not arbitrary shell source. The form's validation must pass before Save is available.

Edit Launcher exposes saved metadata, actions, runner/command, ports, opening behavior, named endpoints, and advanced action controls. Save commits a revised definition; running sessions retain the definition they started with. Use the CLI's full flag surface when a specialized property is not exposed in the editor.

Entries marked STARTED SEPARATELY are observed listeners, not managed sessions. Add Launcher opens a reviewable proposal. Saving that proposal does not take over the already-running process. External Close has its own exact confirmation.

The history view can inspect one launcher or all managed launchers. Session rows distinguish primary/additional role, start/end times, state and logs. The app supports light/dark appearance and reduced motion.

12.3Settings and app updates#

Settings → Agent integration can install/reinstall a managed skill, inspect its state, or export the standalone SKILL.md. These integrations are optional and are not required for using the app or CLI.

Application updates shows current availability and a Check for Launch Station updates control. Automatically prepare updates can download/prepare an update but does not restart the app or interrupt a launcher by itself. Apply a prepared update through the app's restart flow once safe.

Closing the app window is not the same as closing managed sessions. Use the session's Close control to stop its owned work. The local service is responsible for session lifecycle and recovery.

13.1Optional coding-agent integration#

launch skill status [--json]
launch skill source [--json]
launch skill install codex|claude-code [--json]
launch skill uninstall codex|claude-code

Bare launch skill defaults to status. status reports product detection and managed file/version state. source prints the canonical standalone SKILL.md; with JSON it returns the source object. install installs or refreshes only the chosen supported product's managed files.

Installation refuses unsafe destinations and unavailable supported hosts. Reinstalling preserves sibling skills. Product detection is not the same as file verification: a product may be available while its skill is missing, outdated, or blocked. None of these integrations is a prerequisite for this manual.

13.2Check or repair the generated summary#

launch sync [DIRECTORY] [--check | --repair] [--json]

DIRECTORY defaults to the current directory. Check is the default and compares generated content and read-only permissions. Drift returns exit code 4. Repair regenerates the daemon-owned launch_details.md; it does not import handwritten changes into the catalog. If both switches are supplied, the last one wins—prefer one.

The mirror is generated from SQLite after catalog edits. Never hand-edit or chmod it as a configuration workflow. If the project is offline or unwritable, the catalog can report pending/drifted/failed synchronization until the directory becomes available.

launch sync ~/Projects/shop --check
launch sync ~/Projects/shop --repair

13.3Installer-only upgrade reservation#

launch maintenance prepare-upgrade [--json]
launch maintenance cancel-upgrade RESERVATION_TOKEN [--json]

These commands exist for the signed app upgrader, not ordinary project startup. Preparation requires a completely idle daemon and places a temporary mutation reservation. It rejects mutations until cancelled, expired after 120 seconds, or the daemon restarts.

JSON preparation returns a short-lived cancellation capability. Keep it private in installer memory and cancel the exact reservation if installation fails. The non-JSON preparation message does not expose the token. A reservation does not itself install an update or authorize changing app files.

14.1Connect, authenticate and handle errors#

launch api endpoint [--json]

The daemon listens on a dynamic loopback port. launch api endpoint prints the current base URL; with JSON it returns an endpoint field. Do not hard-code the port. Every route, including health, requires the current bearer token held in private service metadata.

A purpose-built client may load ~/Library/Application Support/Launch Station/service.json into private process memory, use its endpoint/token for the request, and avoid printing or logging credentials. Reload metadata after restart/401. Never expose this API to the network: it can run commands as your macOS user.

Requests/responses use JSON; logs return a SessionLogResponse with text and structured diagnoses. Responses use Cache-Control: no-store, timestamps use ISO 8601, and IDs are UUID strings. HTTP/1.1 accepts GET/POST/PATCH/DELETE, with a 16 KiB header and 1 MiB body limit. Mutations carrying expectedRevision must also send the same decimal If-Match header.

14.2Catalog routes and bodies#

LauncherPatchRequest contains required expectedRevision plus optional name, description, runDetails, replaceTags, replaceEndpoints, primaryAction and primaryActionID; boolean clearRunDetails and arrays addTags/removeTags express explicit mutation behavior. Omitted optional replacement fields preserve their current values. Endpoints are objects with id, name and path. Use complete model shapes from the public source when implementing a raw client; constructor defaults are not automatically JSON decoding defaults.

14.3Action and session request shapes#

{
  "id": "ACTION-UUID",
  "name": "web",
  "normalizedName": "web",
  "description": "Local web server",
  "order": 0,
  "runner": "process",
  "workingDirectory": ".",
  "executable": "python3",
  "arguments": [
    "-m",
    "http.server",
    "${PORT}",
    "--bind",
    "${HOST}"
  ],
  "environment": {},
  "inheritedEnvironment": [],
  "port": {
    "mode": "automatic",
    "logicalName": "web",
    "environmentVariable": "PORT",
    "hostEnvironmentVariable": "HOST",
    "URLTemplate": "http://${HOST}:${PORT}/",
    "lease": "8h"
  },
  "healthCheckURL": "http://${HOST}:${PORT}/",
  "openTarget": "none",
  "readyTimeoutSeconds": 30,
  "stopTimeoutSeconds": 8,
  "required": true,
  "allowsRuntimeArguments": true
}

Optional action fields include shellCommand, executable, healthCheckURL and appBundleIdentifier; optional port fields include fixedPort and URLTemplate. Supply the required fields shown above when using direct Codable clients. For shell, replace executable with shellCommand; for url, use a target, empty arguments and allowsRuntimeArguments false. The same validation rules as the CLI apply.

{
  "runtimeArguments": [],
  "openRequested": true,
  "expectedLauncherRevision": 4,
  "mode": "reuse-primary"
}

{
  "runtimeArguments": [
    "--mode",
    "demo"
  ],
  "openRequested": true,
  "expectedSessionID": "CONFIRMED-SESSION-UUID",
  "requireIdle": false,
  "expectedLauncherRevision": 4
}

Start mode is reuse-primary or new-instance. Relaunch uses expectedSessionID to bind the confirmed active instance, or requireIdle:true to bind an idle observation; they are mutually exclusive. expectedLauncherRevision binds the displayed definition and is rechecked after close. Relaunch returns previousSession (when one existed) and the new session.

Session JSON contains id, launcherID/name/revision, launchRole, projectSnapshot, primaryActionID, actionSnapshots, endpointSnapshots, runtimeArguments, state, actionRuns, startedAt and optional endedAt/lastError/exitCode. Action runs expose their own ID/action ID/name, state, manager, exact manager/process identity, log path, endpoint/host/port when available, and timestamps/errors. Treat manager and open-option identities as opaque. Read actual launch details --json or history output rather than constructing a runtime record yourself.

14.4Session, external and integration routes#

SessionOpenRequest uses the returned optionID. External and uninstall intent responses include expiry and exact confirmation material; implement the review/confirmation step rather than treating the API as a bypass. A raw request that times out may have succeeded—read the resulting state before repeating it.

15.1CLI exit codes and common failures#

No --version flag is provided by this CLI; use launch doctor to inspect the service version and the app's About/Settings UI for the app version. No generic --force, --dry-run, automatic process restart policy, remote deployment, or session adoption command is provided.

15.2Resolve common problems#

15.3Storage, privacy and boundaries#

Only run trusted commands under your user account. A local bearer token grants command-execution capability; protect it as a credential. Do not save secrets in launcher fields or expose the loopback service. Deleting a shortcut does not erase project files, outside processes, or managed history.

Launch Station coordinates local development; it does not install your project dependencies, create its source code, make missing server routes, replace your secret store, or deploy production. Its ownership guarantees depend on exact recorded identities, not guesses about command names.