Repository navigation
02. Getting Started
This guide takes you from an installed Galileo to your first exposure: describing your observatory, connecting a camera, and taking a frame. If you have not installed Galileo yet, start with 01. Installation.
Galileo is pre-alpha. It runs and much of it works, but some screens (Scheduler, Variable Stars and most Options pages) are still placeholders that say "not implemented yet". See the README status section for what is built today. Expect rough edges, and please report them as issues. Need help? Join us on Discord.

- Tour of the window
- Create your Observatory and Pier
- Connect your equipment
- Take your first exposure
- Optional add-ons: focus, guide, solve
- Where Galileo keeps its files
- Troubleshooting
- Next steps
- Sidebar (left): one icon per section (Galileo opens on the Dashboard): Dashboard, Star Atlas, Planning, Imaging, Guiding, Focus, Solve, Library, Science, then Equipment and Options at the bottom. Some sections open a second panel with more choices (Planning opens onto What's Up Tonight, Targets, Sessions and Schedule; Library onto Images, Sessions, Mappings, Dedup, Merge Objects and Cloud; Equipment onto one page per device). Small buttons at the very bottom cycle the theme (light, dark, red night-vision), open Help, open the online manual, open the community menu, View Log (this run's log file, with a level filter, search and auto-refresh — handy when reporting a problem) and show the About box.
- Top bar: the Observatory and Pier selectors, plus Optics and Camera selectors on the screens that use them, and a current object note at the right-hand end (e.g. "Current object: M 31") once you have picked a target in the Star Atlas — see Pick a target. Everything you configure is saved per Pier.
- Status bar (bottom): short messages such as "Connected to Mount 'EQ6'" or "Capture complete."
- Help: every screen has a round ? beside its title, F1 shows help for the control you are in, and hovering any control explains it. This guide and the other articles are the overview; the built-in help is the detail. See Built-in Help.
- Log pane: each Equipment screen has a live scrolling log at the bottom. When something fails, look here first.
Galileo organises your gear the way an observatory is actually laid out:
- An Observatory is a site: name, latitude and longitude, timezone, address and owner.
- A Pier is one mount plus one or more optical tubes (each tube can have its own camera, filter wheel, focuser and rotator).
One Observatory can hold several Piers, so one Galileo instance can run several independent telescopes. If you have one telescope, you need one Observatory with one Pier.
Options (the bottom of the sidebar) holds Galileo's settings, one page per area, in the same order as the main menu. Equipment details live on the Equipment pages; Options is for how Galileo behaves. Each screen's article in this manual describes the options that belong to it (for example the horizon in Star Atlas, autofocus defaults in Focus, and the Library folders in The Image Library).
Some settings are saved per Pier, so each telescope keeps its own — choose the Pier in the top bar first. Focus and Solve are per Pier; the Star Atlas horizon belongs to the selected Observatory; Imaging, Planning, Library and Plugins apply to all of Galileo. The Options pages for Equipment, Guiding and Science are placeholders: their settings are on the screens themselves.
Equipment settings are saved under the selected Pier, so do this first.
-
In the top bar, open the Observatory drop-down and choose New Observatory…
-
Fill in the dialog and click OK:
Field What to enter Name Required. Anything you like, e.g. "Backyard". Latitude / Longitude Decimal degrees. North and east are positive (latitude −90 to 90, longitude −180 to 180). The Star Atlas, Planning and the horizon check all use these, so set them accurately. Timezone An IANA name such as America/Toronto.Physical Address, Owner Optional. -
Open the Pier drop-down and choose New Pier…, then give it a name (e.g. "Pier 1").
Use the pencil buttons beside the Observatory and Pier selectors to edit them later (rename a Pier, correct a latitude), and the bin buttons to delete. Both are stored in Galileo's local database and are still there after a restart. Now that a Pier is selected, you can save equipment settings.
Open Equipment in the sidebar. It has one screen for each device category: Camera, Mount, Filter Wheel, Focuser, Rotator, Switches, Flat Panel, Weather, Dome and Safety Monitor, plus Optics, which ties the devices together into optical tubes.

Every device screen starts with the same three-part connection row:
| Setting | Meaning |
|---|---|
| Driver | Alpaca or INDI: the protocol your device speaks. |
| Server | Host name or IP address of the machine the device or indiserver is on, e.g. 192.168.1.50 or seestar.local. .local mDNS names work, including on Windows. Don't use localhost or 127.0.0.1, even when the device is on this computer: Galileo refuses them, because a saved address has to mean the same computer on every Galileo node. Use the computer's own name or LAN address. |
| Port | Changes to the usual default when you switch driver: 32323 for Alpaca, 7624 for INDI. Alpaca has no single standard port, so use whatever your device documents (11111 is common for ASCOM Remote and simulators). |
- Open Equipment > Camera.
- Choose the Driver, type the Server and check the Port.
- Click Scan. Galileo queries the server and lists what it finds in the log pane and in each camera's Device drop-down. A status-bar message tells you how many devices were found.
- Pick your camera from the Device drop-down.
- Optional but useful: click Download Info to read the pixel size and sensor dimensions from the camera, or enter them yourself. If it is a one-shot-colour camera, set the Bayer pattern (RGGB is the usual one).
- Click Save to store the settings under the selected Pier.
Need a second camera on the same connection? Use the + button on the page; extra cameras share the connection row but are separate devices.
Saved cameras and focusers connect automatically whenever a Pier is selected, and again at start-up. The status bar confirms with "Connected to primary camera '…'."
The Mount, Filter Wheel, Focuser and Rotator screens work the same way (Driver, Server, Port, Scan, pick the device, Save) and have a Connect button. The Mount page also has slew, park and jog controls once connected. Weather, Dome, Switches, Flat Panel and Safety Monitor use the same connection row.
Open Equipment > Optics. Each optical tube is one telescope. Use the + by the page title to add a tube for each telescope on the Pier, fill in its focal length, aperture and optical design, then use the + next to the tube's Associated: label to attach the devices you saved on the other Equipment pages (camera, filter wheel, focuser and so on). Click Save.
The Associated list only offers devices you have already saved on their own Equipment screens, so do those first.
Optics matters because other screens use it. For example, the Imaging screen's Filter list comes from the filter wheel associated with the selected optics, and plate solving compares the solved pixel scale against the expected one for the chosen tube.
Before you capture, you can open Star Atlas in the sidebar and click (or find by name) an object such as M31. That makes it the selected Pier's current object: the top bar shows "Current object: M 31" on every screen, saved frames are named after it (e.g. M_31_20260101T220000.fits instead of frame_20260101T220000.fits), and it becomes what Solve's Slew to Target action slews to. It is kept only for the running session — it resets after a restart — and is separate per Pier, so two Piers can be working different targets at once.
- Confirm your camera shows as connected (status bar, or the log pane on the Camera page).
- Open Imaging in the sidebar. If your Pier has more than one optical tube or camera, pick which in the top bar.
- Set Type (Light, Dark, Flat or Bias), exposure time and, if you have a filter wheel, the Filter. Choosing a filter here moves the wheel to that slot (the status bar shows "Moving filter wheel to …"), and Capture waits until the move is done.
- Optional: set Quantity (how many frames to take in a row, default 1) and Gain. With Quantity greater than 1, Capture takes them one after another, showing each as it arrives, and Stop abandons the run after the exposure in progress.
- Click Capture. A progress bar and countdown run while it exposes and downloads, off the UI thread, so the window stays responsive.
- The frame appears as an auto-stretched preview you can pan and zoom, with a histogram and per-frame statistics (mean, median, min, max, star count, HFR).
The Imaging page rearranges itself around the shape of the frame you just captured:
- A landscape or square frame (the usual case, and what you see before your first capture) keeps the layout shown above: the preview sits on the right, with Mount Nudge, the histogram and the log stacked below the statistics on the left.
- A portrait frame (taller than it is wide — for example a camera used in a vertical orientation) switches automatically: the preview becomes a full-height column taking about a third of the window's width, and Mount Nudge, the histogram, progress bar and log move into their own column between the capture settings and the preview, with a taller histogram and a longer log so there's something useful to look at in that space.
This happens on its own after each capture — there's nothing to turn on. If you'd rather it didn't (say, you're viewing a portrait frame but prefer the landscape arrangement), tick View > Choose layout manually, which reveals a Portrait/Landscape selector; it starts on whichever layout is currently showing, so ticking it never moves anything by itself, and unticking it goes back to following the frame automatically.
Galileo has two separate, independent ways to keep a captured frame — you can use either, both, or neither for a given run:
| Save Frame… | Auto-Save to Library | |
|---|---|---|
| How it happens | Manual — click the button after (or between) captures. | Automatic — a checkbox under Save Frame, ticked by default. Every frame in the run is saved as it is taken, with no extra click. |
| What it does | Prompts for a path and writes exactly that one FITS file there. Galileo does not track it afterwards. | Writes the frame to a scratch folder and registers it with the Library, which moves and renames it into your repository — so it appears on Library > Images without a separate scan, catalogued by object, session, filter, etc. If you have chosen to compress images in the Library Setup it will also compress them as it is stored in the Library to save disk space. |
| What you need | Nothing extra. | A repository folder set under Options > Library. Without one, nothing is written and the log pane says so. |
| Naming | You choose the file name (pre-filled from the current object and the time, if one is picked). | Named and filed by the Library's own rules. A light frame with no current object picked is filed under "Unknown". |
A common setup is to leave Auto-Save to Library on so every session lands in the catalog automatically, and use Save Frame… only for the occasional frame you want a personal copy of somewhere else. Turning Auto-Save off stops the Library copy but does not affect Save Frame.
Notes:
- Live Stack, off by default, registers and combines a run of three or more frames into one improving image as it is taken (using astroalign where available). Unlike the two saves above, the stack itself is not saved automatically — a separate Save Stack… button offers Save to Library or Save to File…, and the stack is lost if you start a new run or close Galileo without using it.
- The Mount Nudge panel (N/S/E/W and a speed — hold a button to move, release to stop) jogs the connected mount without leaving the Imaging screen — handy for centring a target between exposures.
- A one-shot-colour camera's frames are shown in colour automatically — Galileo asks the camera whether it is a colour one and which Bayer pattern it uses. The Debayer checkbox under View is ticked for you when a colour camera is detected; tick or untick it to override (a camera that reports no pattern then uses the one saved on Equipment > Camera). It changes only the preview; statistics and saved files keep the camera's raw data.
- Subtract dark (also under View) subtracts the Library's dark master from the preview when one exists for your camera and optics at the same exposure and binning, so hot pixels and amp glow don't hide the target while you frame and focus. Like Debayer it is preview-only.
- If you see "No camera connected", go back to Equipment > Camera and make sure a device is selected and saved.
These sections follow the equipment you have already set up.
| Section | What it does | What you need |
|---|---|---|
| Focus | Runs and displays autofocus: the frame being measured, star count / HFR / FWHM and the HFR V-curve with its fit. Use Auto Focus and Stop. | A connected camera and focuser. |
| Guiding | Shows PHD2's live state: guide-star image, guide graph, drift and calibration plots, and statistics, with Loop / Guide / Stop / Dither controls. | A running PHD2. Enter its host and port on the Guiding screen. |
| Solve | Capture & Solve takes an exposure and plate-solves it, then optionally syncs the mount or slews back to the target — your current object, or wherever the mount was pointing if you haven't picked one — until it is within your accuracy. Load & Slew… solves an existing FITS file, slews to where it points and makes that your current object. |
ASTAP and a star database, installed on your PATH or in ASTAP's usual install folder. |
The Solve screen's Solver Action defaults to Nothing, so a click never moves your mount unasked.
Not everything on these screens is built yet. Buttons for unfinished features are greyed out with a "Not implemented yet" tooltip.
| What | Windows | macOS | Linux |
|---|---|---|---|
Database (galileo.db: observatories, piers, equipment, image catalog, and all your settings) |
%APPDATA%\Galileo\galileo.db (typically C:\Users\<you>\AppData\Roaming\Galileo\galileo.db) |
~/Library/Application Support/Galileo/galileo.db |
$XDG_DATA_HOME/galileo/galileo.db (typically ~/.local/share/galileo/galileo.db) |
Logs (logs/) |
%APPDATA%\Galileo\logs |
~/Library/Logs/Galileo |
~/.local/share/galileo/logs |
| Settings (everything under Options, layouts, equipment profiles) | Stored in the database above, in its app_settings table |
All settings live in that one database. If you upgrade from an older version that kept them in separate files (library.ini, guiding.json, ...), Galileo imports them automatically the first time they are needed and renames the old files to *.migrated; nothing is deleted.
Logging captures all application output to a datestamped file that is reset on each run. It is the best thing to attach to a bug report.
The Library is built from the author's AstroFiler tool and is worth configuring early. Under Options > Library, set your repository folder (where your FITS files live) and your incoming folder. Then use Library > Images > Load New to catalog any images you want to add to the Library from your incoming folder.
The Library consists of an Images view which lists all images in the Library using a variety of sort criteria, and Sessions which tie together lights and calibration frames by date. Right clicking on a session allows you to export an entire session (perhaps to load into your favorite image processing application) as well as do calibration runs and create sample stacks and thumbnails. See the Library documentation when it is produced for more info.
If you already use AstroFiler, you can't use it's database directly but you can reconstruct it just by hitting Regenerate on the Images screen. This will look at all FITS files in your Repository folder and read in their headers to the database. You should also Regenerate the Sessions table to link all of your lights and calibration frames.
Library can also load files from remote telescopes and sites as well as store your precious files in the Cloud for backup. See the Library documentation for more details.
Note: if you configure iTelescope credentials there, the password is stored in the OS keychain (not in the database), so it does not appear in plain text anywhere in Galileo's files.
| Symptom | Try this |
|---|---|
PySide6 is required to run Galileo |
You are not using the virtual environment's Python. Use run.ps1 / run.sh, or re-run the pip install -r requirements.txt step. |
pip install fails building a package |
Check python --version (needs 3.11+), and upgrade pip: python -m pip install --upgrade pip. |
| Scan finds no devices | Check the server address and port, that indiserver (or the Alpaca bridge) is running, and that no firewall blocks the port. Try the IP address instead of a .local name. The log pane shows the details. |
| Scan says "failed — see log" | The log pane and the log file name the exact error, such as a refused connection or a name that does not resolve. |
| "Select (or create) an Observatory and Pier before saving" | Create both in the top bar first. See Create your Observatory and Pier. |
| "No camera connected" when capturing | Open Equipment > Camera, pick the device, and click Save. Re-select the Pier to trigger the auto-connect, then check the log pane. |
| The Solve screen cannot solve | Install ASTAP and a star database (for example D50), and make sure ASTAP is on your PATH. |
| A screen says "not implemented yet" | It is a placeholder. See the README status section for what exists. |
If Galileo hits an unexpected error it shows an error dialog and saves a crash report (traceback, version, platform and recent log lines, with passwords and tokens removed) in the reports/crash folder of your Galileo data directory; native crashes are recorded in logs/faulthandler.log. Attach these to a bug report.
If you are still stuck, open an issue and include your OS, Python version, the device protocol (INDI or Alpaca) and the relevant part of the log file.
- Browse the Star Atlas (stars, Messier / Caldwell / NGC / IC objects, Sun, Moon and planets for your Observatory's location and time). Upload a horizon file under Options > Star Atlas to shade trees and buildings and, with Options > Planning, refuse slews into them.
- Use Planning to search the catalogs and Framing to plan a target or mosaic against your optics.
- Read the design documents in
docs/if you want to know where Galileo is headed. The SDD is the architecture reference. - Want to contribute? See CONTRIBUTING.md.