Settings

Settings is where you tell Starship what equipment you have and how you want it to behave. Each tab on the left is one job. The help link beside the tab name at the top of the page opens the help for the tab you are on.

The tabs

Equipment

Safety & Environment

Integrations

System

Buttons that move hardware are on the Console and the Polar Alignment page, not in Settings. The two tests that have no other home (a guide pulse, and the Guardian dry run) are in a closed Tests block at the bottom of the Guiding and Guardian tabs.

A dot beside a tab name means that tab has changes you have not saved yet.

Save, and Save & restart

There are two buttons at the bottom of every tab.

Either button saves the unsaved changes on every tab, not only the one you are looking at. If a value is not allowed, nothing is saved and the page says what to correct.

If the settings were changed from another dashboard after you opened this page, your save is refused and nothing is written. Press Reload settings: what you typed is kept, and you can save again.

The restart badge

A field with a small restart badge beside its name is read only when Starship starts. After a Save that changed one of them, the page lists them by name ("These changes need a restart: ...") and offers Restart now. Until the restart, Starship keeps using the old values. A save that changed none of them takes effect at once.

A restart takes a few seconds and the dashboard reconnects by itself. A restart cuts off a running sequence, schedule or blockscript, so Starship refuses it while one is running: it names what is running and asks you to stop it first, or to confirm that you want to restart anyway.

When the same thing seems to be set twice

A few behaviours have two fields. Each says in its hint what it applies to. In short:

How saving works (technical)

This part is for people who script Starship or edit config.toml by hand. Every tab maps to a [section] block in config.toml, and every field is one key in the typed config tree (starship/core/config/__init__.py).

What a save does

When you Save, the dashboard POSTs the whole config to /api/config. The server:

  1. Rebuilds a StarshipConfig from the JSON (from_dict).
  2. Runs validate() — if anything fails, nothing is written and the errors come back inline.
  3. Backs up the current config.toml to config.toml.bak, then writes the new config.toml.
  4. Swaps the in-memory svc.config pointer to the new config and reports needs_restart: true only when a setting that is read once at startup actually changed (the reply lists those keys in restart_required_keys).

Two dashboards open

Each dashboard remembers which version of the settings it read. If the settings changed somewhere else after that (a save from another dashboard, or a Save as defaults on another page), your save is refused and nothing is written. The page says so and offers Reload settings. What you typed is kept and goes on top of the fresh copy; then save again. This stops an old page from putting back everything that changed since it was opened. A script that posts /api/config without the _version field is saved as before.

That last step is the subtle one: Save updates the config object in RAM, but it does NOT re-initialise any already-running module. Long-lived things (driver poll loops, ASCOM/Alpaca threads, the PHD2 socket, the web server) captured their settings at startup and keep using those values until the service is rebuilt. Settings that are read fresh every time they're used pick up the change immediately; settings read once at startup do not.

What "restart" means here

The restart is in-process, not a reboot and not even a process exit. request_restart() sets a flag and signals the run loop; the runner (scripts/run_starship.py) tears the service down, re-reads config.toml from disk, and builds a brand-new StarshipService from it — all in the same Python process (the command window stays open). This is why "the config in RAM" matters: a plain Save changes RAM but leaves the old threads running against their startup snapshot; only the rebuild on restart re-creates those threads from the freshly loaded file.

Restart takes about 1–2 seconds.

A restart does not resume a run. The sequencer, the scheduler and blockscript are part of the service that is torn down, so a restart cuts a running sequence, schedule or blockscript session off where it stands, and nothing starts it again afterwards. For that reason Save+Restart (and loading a profile, a factory reset, or Shutdown) is refused while a run is active: Starship names what is running and asks you to stop it first, or to confirm that you want to restart anyway. After a restart you start the run again yourself; a sequence that left a checkpoint can be picked up where it stopped with Resume (the /api/sequencer/resume_run route), which skips the frames already taken.

Starship can also carry on by itself with a stand-alone sequence that was cut short when Starship or the PC went down unexpectedly: Settings → Sequencer defaults → Resume a sequence cut short by a restart ([sequencer] auto_resume_after_restart, off by default; new in v23). It never resumes a run you stopped, or a run that was going when you restarted or shut down on purpose. The Windows restarts and crashes topic lists exactly when it will and will not resume.

What's live (no restart)

Changes that take effect on the next use, because the code reads them fresh each time:

Because these are re-read per operation, a plain Save is enough — but Save+Restart is always harmless.

What needs Save+Restart

Anything bound to a long-lived connection, thread, or server captured at startup:

If unsure, use Save+Restart.

Where the newer knobs live

Autofocus ([autofocus])

The autofocus tunables all live in Settings → Autofocus and are live on save (re-read on every Refocus and every Focus Wizard run). The learned calibration is not in Settings; First Light writes the refocus formula — the V's slope, the focuser's backlash and the over-travel that clears it, the last focus — to focus_recipe.json next to config.toml. See the dedicated Autofocus topic for what each knob does, the current Wizard/Refocus model, and the recommended tunings — that page is the source of truth for this section.

Rotator travel limits ([rotator])

Settings → Rotator. min_position_deg and max_position_deg are mechanical degrees (what the rotator itself reports, not sky angle). The allowed arc runs from min up to max and may wrap through zero: min 270 and max 90 allows 90° either side of zero. Blank = no limit. Every rotator move stays on the arc, rotate-to-position-angle included. See the Field rotator topic.

Plate-solve sync limit ([pointing])

Settings → Mount → Do not sync a solve further away than (°) (max_sync_distance_deg, default 10; 0 = no limit). A plate solve further than this from where the mount says it points is not synced to the mount. Blind sync is exempt. See the Plate solving topic.

A failed start-up step asks first ([performance])

start_prompt_timeout_s (default 0 = do not ask). When above 0, a failed on_start action of a stand-alone sequence asks Try again? in the run view and waits this many seconds before it cancels. See the Sequencer topic.

Manual actions and the weather

When you ask for one of these yourself from the dashboard while safety reads UNSAFE or UNKNOWN, Starship refuses and asks you to confirm:

The message names the safety state and its reason. Cancel leaves the rig as it is. OK sends the command again with the safety check overridden; the override is written to the log. Confirm only when you know the rig is protected (the roof is closed, or you are watching the sky).

Nothing is checked in manual mode ([safety] enabled = false). Park, close and cover-close are never held back. The sequencer, blockscript and scheduler do not pass through this check: they follow safety by their own rules.

Fields removed in v23

These were shown in Settings but no code read them. They are gone from the page. An old config.toml that still has the keys loads without error; the keys are dropped the next time the file is saved.

What is in each equipment section

Backups

Every save first copies the current config.toml to config.toml.bak. One level deep — saving twice in a row overwrites the bak. If a backup write fails (e.g. permissions) it's logged but the save still proceeds. For real history, keep config.toml in version control.

Validation

validate() runs before any write. If it returns errors, the save is rejected and nothing is written. Common failures:

Validation errors are displayed inline with the section that triggered them, and Save is blocked until they're fixed.

Environment overrides

A handful of sections (solo, safety, web, audit, phd2, allsky) can be overridden at launch with STARSHIP_<SECTION>_<KEY> environment variables (e.g. STARSHIP_SOLO_HOST=192.168.1.42). These apply on load, on top of whatever is in config.toml. They are not written back to the file, so the Settings page shows the file value, not the override — keep that in mind if a launched value doesn't match what Settings displays.

How it ties into the rest of Starship

Astroworx Starship v23.1.2 · this page is the in-app help of that buildDownload · HTTP API