Configuration file

Starship's config lives in a single TOML file, typically config.toml in the working directory. The Settings page edits it, but you can also edit it directly with any text editor. This page is the reference for the file format, every top-level section, and the recently added knobs.

Location

When you run python scripts/run_starship.py, the loader looks for config.toml in:

  1. --config <path> argument if given
  2. STARSHIP_CONFIG environment variable if set
  3. ./config.toml in the current working directory

If none of these exist, the loader also tries starship.toml and ~/.starship/config.toml. If nothing is found, Starship runs with built-in defaults and remembers config.toml in the cwd as the default save target. Save once from the Settings page to materialise the file.

How load/save works

Schema

Every section is optional. Top-level sections:

Each section is documented in its own help topic where one exists; this page focuses on the file itself and the newest knobs.

Environment variable overrides

Any field in [solo], [safety], [web], [audit], [phd2], or [allsky] can be overridden via STARSHIP_<SECTION>_<FIELD> (uppercased). For example:

The override is type-aware: booleans accept 1/true/yes, ints and floats are parsed, and a value that won't parse is logged and ignored rather than crashing. Overrides apply after the file is loaded, so they win over the file.

Note: override support currently covers only those six sections. Other sections (e.g. [autofocus]) are not env-overridable — edit the file or the Settings page for those.

TOML quirks

The Sequencer's plan-policy embedding and the Response Engine plans use inline tables — the format is sensitive to TOML rules. Easiest to edit those through their structured editors and let Starship generate the TOML.

Schema version

The config carries a [meta] config_version so future schema changes can migrate old files cleanly. The current build's schema version is 2. A config written by an older Starship (no [meta] section) loads as version 1 — Starship reads it fine and re-saves it at the current version. Every added section has a safe default, so an older file simply gains the new sections at their defaults on the next save; nothing you set is lost. A config newer than the running build fails validation with a clear message rather than being silently misread.

Validation

validate() runs a long list of range/consistency checks and returns a list of human-readable errors; the Settings page surfaces them before saving. A few that bite in practice:

Dashboard access & optional Basic Auth

By default the dashboard binds to 127.0.0.1:8765 (local machine only). If you set web.host = "0.0.0.0" to reach it from other machines, the dashboard is exposed to your whole LAN.

For an extra layer on the LAN you can enable HTTP Basic Auth (default off):


[web]
host = "0.0.0.0"
auth_enabled = true
auth_username = "your-name"
auth_password_hash = "pbkdf2_sha256$...."   # from scripts/hash_password.py

Generate the hash once with python scripts/hash_password.py. The plaintext password is never stored — only the salted PBKDF2-SHA256 hash (240,000 iterations). A malformed or empty stored hash fails closed (access denied) rather than crashing.

Important: Basic Auth here is defense-in-depth on a trusted LAN, not a substitute for network security. Do not expose this port directly to the internet. For remote access, keep the dashboard LAN-only and reach it through the Cloudflare Tunnel + signed JWT (the Nebula Nest model) or a VPN.

Precise pointing — [pointing]

Precise pointing does slew → plate-solve → sync → re-slew until the solved position is within tolerance. Used by the console precise_slew command and by sequencer slew steps with precise=true.


[pointing]
exposure_s = 4.0          # plate-solve frame exposure
binning = 2               # bin 2x2 by default: lighter load, faster solve (was 1)
tolerance_arcmin = 1.0    # done when the solved offset is below this
max_iterations = 3        # cap on solve/slew loops
settle_s = 2.0            # dwell after each slew before exposing

Note: binning now defaults to 2 (it was 1 in earlier builds). The 2x2 read downloads and solves faster with no practical loss for centering.

Meridian flips - [mount]

Parking - [observatory]

Coordinate frame - [mount]

Camera download - [camera]

ImageArray straight into numpy through the driver's own COM interface instead of pywin32's tuple-of-ints conversion, which costs about 40 bytes per pixel for the seconds a frame takes to read (about 1.1 GB for a 26 megapixel sensor - enough to trip the health monitor's memory floor on an 8 GB PC). Set it to false only if a driver misbehaves with the new path; Starship then logs once and uses the classic conversion.

Autofocus — [autofocus] (selected new knobs)

The [autofocus] section is large (see the Autofocus help topic for the full list). Two recently added knobs:


[autofocus]
hfd_integration_frames = 3       # frames averaged per measurement point (Voyager-style)
hfd_integration_near_hfd = 0.0   # only integrate when measured HFR <= this; above it use 1 frame; 0 = integrate everywhere
wizard_slew_to_focus_star = false

Alerts — [alerts]

Outbound email (SMTP) and Pushover notifications on chosen conditions (v19.62). The AlertsManager subscribes to the event bus and sends when an enabled condition fires. Routing is unit-tested; a real send can only be confirmed against a live SMTP server / Pushover account.


[alerts]
enabled = false
email_enabled = false
smtp_host = ""
smtp_port = 587
smtp_user = ""
smtp_password = ""
smtp_tls = true             # STARTTLS
email_from = ""
email_to = ""               # comma-separated recipients
pushover_enabled = false
pushover_user_key = ""
pushover_app_token = ""
on_sequence_complete = true
on_sequence_failed = true
on_sequence_stopped = false
on_unsafe = true
on_safe = false
on_safety_error = false     # safety monitor error / stale data

Frame acceptance — [frame_acceptance]

Per-frame quality gates that judge each LIGHT sub as it's captured and reject the bad ones (the NINA/Voyager-style frame filter). Default off — with enabled = false every frame is kept, exactly as before. Each gate is judged over a centred crop of the frame and any gate left at 0 is individually disabled, so you can turn on just the one or two you care about.


[frame_acceptance]
enabled = false
max_hfr_px = 0.0            # reject if the median HFR exceeds this (px); 0 = off
min_star_count = 0          # reject if fewer stars are detected; 0 = off
max_eccentricity = 0.0      # reject if median star elongation exceeds this (0 = round, 1 = line); 0 = off
max_background_adu = 0.0    # reject if the background exceeds this (clouds/moon/light leak); 0 = off
reshoot_max = 0             # re-take a rejected sub up to N times (rejects don't count toward the goal); 0 = no reshoot
abort_after_consecutive = 0 # fail the exposure step after N rejects in a row (clouded over); 0 = off
move_rejects = true         # move rejected frames to a sibling 'rejected/' folder so the light stack stays clean
central_region_pct = 60.0   # analyse this centred crop (quality is judged near the optical axis) for speed
per_filter_json = ""        # per-filter threshold overrides (see below)

A rejected sub is journaled and, with move_rejects on (the default), set aside in a rejected/ folder next to your lights so your stacker never sees it. reshoot_max lets a rejected sub be re-taken so a single bad frame doesn't cost you a slot, and abort_after_consecutive stops the step after a run of rejects so a clouded-over night stops wasting exposures instead of grinding on.

Narrowband subs naturally have far fewer stars and larger HFR than broadband, so one global min_star_count is wrong for them. Set per_filter_json to a JSON object mapping a filter name to a subset of {max_hfr_px, min_star_count, max_eccentricity, max_background_adu}; any gate you don't override falls back to the global value. Example:


per_filter_json = "{\"Ha\": {\"min_star_count\": 4, \"max_hfr_px\": 5.0}}"

Validation keeps every threshold &gt;= 0 (0 = off) and central_region_pct in 1–100.

Guiding watchdog — [guiding_watchdog]

Holds the next sub until PHD2 guiding has recovered, so the rig never starts an exposure while guiding is lost or degraded. It pairs with frame acceptance (which rejects a sub ruined mid-exposure): the watchdog stops a bad one from starting, frame acceptance throws away one that went bad partway through. Default off — no gating. It only acts while PHD2 is actually guiding and control is enabled for the plan.


[guiding_watchdog]
enabled = false
rms_max_px = 0.0          # hold if the total guide RMS exceeds this (px); 0 = wait on star-loss only
recover_timeout_s = 120.0 # give up waiting after this many seconds; the exposure step then fails (on-error policy)
poll_interval_s = 3.0     # how often to re-check PHD2 state while holding

With rms_max_px = 0 the watchdog only waits out an outright lost guide star; set a pixel value to also hold when the RMS climbs above your tolerance. Validation keeps rms_max_px &gt;= 0, recover_timeout_s &gt;= 0, and poll_interval_s &gt; 0.

Auto Flat — [flat]

The [flat] section holds the Auto Flat plan (the per-filter target-ADU exposure search, panel/manual/sky flat source, and end-of-run park/close options). It's edited from Settings → Flat device → Auto Flat and has its own Auto Flat help topic with the full workflow — this page just notes that it lives in the config file. flat_type accepts "panel", "manual", "sky_dusk", or "sky_dawn"; the per-filter plan is the filters array of small inline tables (easiest to edit through the Auto Flat form).

Filter library — [filters]

The [filters] section holds your named filter library — one entry per filter carrying a per-filter refocus exposure (the autofocus exposure used when refocusing on that filter, since dim narrowband needs a longer focus exposure than broadband) and a focuser offset. An empty library falls back to the names your filter wheel reports, else the built-in defaults. The virtual OSC (one-shot colour) filter is offered automatically for a colour camera. It's edited from the filter-library editor and documented in the Filter wheel help topic; each library entry is an inline table {name, refocus_exposure_s, focus_offset}, and a missing or 0 refocus exposure falls back to the global [autofocus].exposure_s.

Memory management

Three sections cooperate on RAM-tight machines (e.g. a LattePanda):


[memory]
enabled = true
gc_on_warning = true                  # gc.collect() when the memory check is DEGRADED
drop_preview_cache_on_warning = true  # also drop rendered FITS previews under pressure

[diag]
ring_buffer_size = 2000               # in-memory recent-log lines kept for the diagnostics bundle
max_log_line_length = 0               # 0 = no truncation

The memory thresholds live in [health], so there is a single source of truth for the limits and [memory] only chooses the responses:


[health]
mem_warn_mb = 2200.0        # RSS DEGRADED (leak watch); above a normal ~1.5GB plateau
mem_critical_mb = 3000.0    # RSS leak-guard ceiling (raised from 1400). Only escalates if system memory is ALSO low.
sys_mem_warn_pct = 15.0     # < this % system RAM available -> DEGRADED
sys_mem_critical_polls = 3  # the floor must hold this many consecutive polls before it is imminent OOM (v22.2.3);
                            # a dip during a frame download never counts
sys_mem_critical_pct = 8.0  # < this % available -> CRITICAL (real OOM risk)
sys_mem_critical_mb = 512.0 # OR < this many MB available -> CRITICAL (whichever first)

Important: "imminent OOM" means the system is low on RAM, not that this process crossed a fixed RSS line. The free-system-memory check is primary; the RSS thresholds are a secondary leak guard — a high RSS only escalates safety when system memory is also low. This stops a roomy machine reporting a false "imminent OOM". mem_critical_mb defaults to 3000.0 MB (raised from an earlier 1400) so a stable ~1.5 GB working set reads healthy.

Current RSS, system-available memory, and a leak-rate (growth_mb_per_min) are reported in /api/health/status and in memory.json inside the diagnostics zip. You can also reclaim on demand: POST /api/console/free_memory runs a GC and clears the FITS preview cache, returning how much RSS was freed.

Polar alignment — [polar]

The [polar] section configures the plate-solve polar alignment routine (see the Polar alignment help topic for the full procedure). It's used from Settings → Mount → Polar alignment.


[polar]
exposure_s = 4.0          # exposure for each solve frame
binning = 1
turn_deg = 80.0           # how far to ask you to turn the mount in RA
min_turn_deg = 20.0       # below this the axis can't be measured - refuse
positions = 3             # 3 = ask for a third position as a cross-check (you can still continue with two); 2 = never ask
max_spread_arcmin = 0.75  # three positions must agree on the axis to within this, or the run refuses
target_arcmin = 1.0       # accuracy you're aiming for
apply_refraction = true   # aim at the refracted pole - leave on
adjust_interval_s = 3.0   # how often the error re-solves while you adjust
max_adjust_min = 30.0     # auto-end the live readout after this long
# Motorized adjustment is PENDING (the loop is built for it but the hardware
# path is not wired or calibrated). These stay inert for now:
motorized_enabled = false
motorized_alt_steps_per_arcmin = 0.0
motorized_az_steps_per_arcmin = 0.0

Requires site coordinates, a connected camera and ASTAP. A mount connection is not required — Starship never slews during polar alignment, so this works on a hand controller with no ASCOM driver at all. The mount should be tracking during the live readout, though: if it isn't, Starship detects the sidereal drift in the solved frames and stops rather than showing you a number that is quietly drifting onto a false pole.

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