Settings

The Settings page is the configuration surface for everything. Every section maps to a [section] block in config.toml, and every field you see is one key in the typed config tree (starship/core/config/__init__.py). Saving writes that file; the web server validates and persists it, and updates the in-memory config.

How a save actually works

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 returns needs_restart: true.

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.

Save vs. Save+Restart

Two save buttons at the bottom of every section:

Save — writes config.toml (after backing up to config.toml.bak) and updates the in-memory config. Some settings take effect immediately (see "What's live"); others need a restart.

Save+Restart — saves as above, then triggers a graceful service restart (POST /api/config/restart → request_restart()). Use this for any setting where you're not sure.

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. It won't lose a running sequence — the sequencer is part of the same service and resumes from its journal after the rebuild.

What's live (no restart)

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

• Console default object name (read when a capture starts without a name).
• FITS watch directory / options (the watcher rescans).
• Cooling parameters (read on every cooling action).
• Autofocus parameters (read on every AF run; the learned Refocus recipe lives in a separate focus_recipe.json, not in Settings).

• Plate solver (ASTAP) path / radius / timeout / downsample (the -z factor: 0 = auto, force 2–4 to solve noisier OSC/short frames).
• Site coordinates, mount slew/flip defaults, pointing/rotator/polar parameters (read at the start of each operation).
• Auto Flat planner parameters, Frame acceptance gates, and the Guiding watchdog — read when the relevant step runs.
• Filter library (Settings → Filters) — the named filters, per-filter refocus exposure, and focuser offset are read on each filter change / refocus.
• Scheduler loop knobs, score weights, moon-avoidance and roof-management settings (read as the dispatch loop runs).
• Alerts routing (the AlertsManager re-reads on save; the alerts section has its own Save endpoint).
• Audit retain/exclude settings (applied as the log rolls).
• Memory response knobs (gc_on_warning, drop_preview_cache_on_warning) — read when the health monitor hits a memory warning.

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:

• Solo host / poll interval / timeout (driver re-binds its poll loop).
• All-sky URL / refresh (poll loop re-creates).
• CCTV RTSP/snapshot URL (capture pipeline re-spawns).
• PHD2 host / port (JSON-RPC connection re-opens).
• Planetarium (Cartes du Ciel) host / port (TCP socket re-opens).
• Web server host / port, and the dashboard auto-open mode (only a restart re-binds the listener).
• Health monitor poll interval / thresholds / restart policy (the monitor thread reads these at start).
• Diagnostics ring-buffer size (installed once at startup).
• Any ASCOM prog_id or Alpaca host/port/device change, for any of the nine device roles (mount, camera, guide camera, rotator, focuser, filter wheel, observatory, power switch, flat device). The Chooser/Pick buttons re-save and trigger a reconnect, but a restart is the clean way to fully re-init a transport. The ASCOM/Alpaca poll interval and the ASCOM liveness-watchdog timeout are also captured at start.

• Scripts / Plugins — the external-script sandbox and the plugin loader initialise at startup; enabling either, or changing the allowed/plugins directory, needs a restart.
• Sequencer plans directory and journal size.
• Blockscript engine settings.

• Observatory enclosure type — set in Settings → Observatory, roll_off (default) or dome. A roll-off roof needs no azimuth tracking; switching to dome unlocks ASDM slit slaving and the Dome page (see the Dome topic). Restart after changing it so the dome subsystem binds cleanly.

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; the Wizard writes a Refocus recipe — focus position, step, half-range, points-per-arm, backlash — 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. A few AutofocusConfig fields are schema-committed but PENDING (not yet wired); the Autofocus topic flags them, and the refocus-trigger fields here have live equivalents in [sequencer].

Sections that are mostly schema-only (PENDING)

Some sections render in Settings but several of their fields are schema-committed, not yet read by any code — they exist so future versions don't need a config migration. Saving them is harmless; they simply do nothing until the feature ships. The largest are:

• Camera ([camera]) — sensor type, image scale (focal length / pixel size), default capture params: nearly all PENDING. Exceptions are updated automatically (e.g. camera_position_angle_deg from the last plate solve).
• Focuser ([focuser]) — mechanical limits, jog step, and general (non-AF) backlash: PENDING. AF backlash lives in [autofocus]. The measured_backlash_ / characterization_ fields are not user knobs — Adaptive First Light writes them here (with the full curve report as JSON) so the measured characterisation is visible in Settings and travels with saved profiles.
• Mount ([mount]) — the slew, tracking-on-connect, and meridian-flip defaults (including flip_pier_side_check and the recenter-after-flip options) are LIVE; precess_targets (v22.2.0, J2000 targets converted to the mount's frame) is LIVE and config-file only; park_on_disconnect and the custom-park/slew-rate fields are PENDING.
• Cooling ([cooling]) — the core setpoint/settle/warm-up fields are LIVE; the ramp fields (ramp_minutes / ramp_step_s / no_cooldown_for_delta_c), the legacy cool_down_ramp_min, and auto_setpoint_scaling_fallback are PENDING.
• Polar ([polar]) — the motorized_* fields are PENDING hooks for a future powered adjuster.
• Rotator ([rotator]) — min_position_deg / max_position_deg travel limits are PENDING.

Where a field is PENDING the field tooltip/spec says so; this page and the per-feature topics call it out honestly rather than implying it works.

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:

• Port outside 1..65535 (web / PHD2).
• Required field missing (e.g. solo.host, an all-sky URL when all-sky is enabled, a CCTV camera with neither RTSP nor snapshot URL).
• Web Basic Auth enabled without a username or a valid pbkdf2_sha256$… password hash (fails closed rather than shipping broken auth).
• Inconsistent values, e.g. solo.timeout_s >= solo.poll_interval_s; cooling.cool_down_ramp_min + settle_dwell ≥ timeout_settling_min; autofocus.max_hfd_allowed < near_focus_hfd; autofocus.vcurve_limit_hfd <= near_focus_hfd; an out-of-range autofocus.binning (must be 1–4) or central_region_pct.
• Auto Flat out of range: an unrecognised flat.flat_type (must be panel, manual, sky_dusk, or sky_dawn), a non-positive target_adu, a max_err_pct outside (0, 100], max_exposure_s < min_exposure_s, or a calc_roi_pct outside 1–100.
• Frame acceptance gates below 0 (each gate is 0 = off), or a central_region_pct outside 1–100. Guiding watchdog rms_max_px/recover_timeout_s below 0 or a non-positive poll_interval_s.

• A config_version newer than this build supports. The current schema version is 2.

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.

The Licence tab

Not everything in Settings maps to config.toml. Settings → Licence is a self-contained tab that shows your edition and supporter-licence status, this computer's licence ID, and an activation-key field with Activate / Refresh now. It talks to the licence server and the local ~/.starship/license.key, not to your config file — saving config never touches it and it never needs a restart. See the dedicated Licence & editions topic for how the gate, the two editions, and the daily offline-safe refresh work.

How it ties into the rest of Starship

• The same config.toml is read at process start by the runner and rebuilt on every in-process restart, so Settings is the single source of truth for the whole service.
• Equipment profiles (Settings → equipment) are saved/loaded copies of config.toml; activating a profile copies it over the active file and triggers the same restart path.
• Alerts have their own save endpoint (/api/alerts/config) so the SMTP password is never echoed back to the browser; a blank password field keeps the stored one.