Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ManiFed/TTN/llms.txt

Use this file to discover all available pages before exploring further.

The Node Agent build system uses PyInstaller to bundle src/main_service.py and all dependencies into a single self-contained executable, then wraps it in a platform-native installer that registers the agent as a system service, writes the initial config.yaml from a template, and configures the OS to prevent sleep during overnight operation. Donors receive one file to download and one prompt to answer — their activation code — and the telescope is online.

​
Prerequisites

RequirementPlatformNotes
Python 3.10+AllMust be on PATH
PyInstallerAllpip install pyinstaller
NSIS 3.xWindows onlymakensis must be on PATH
NSSMWindows onlyPlaced at build/windows/nssm/nssm.exe — bundled into the installer
Xcode CLI toolsmacOS onlyRequired by pkgbuild/productbuild
Nothing extraLinuxAppImage optional via appimagetool
The build script also automatically downloads the ASTAP plate-solver binary for the current platform from hnsky.org into build/binaries/ before running PyInstaller, so end users do not need to install ASTAP separately. The G18 star catalogue (~6 GB) is not bundled — the Node Agent downloads it on first run via the dashboard setup wizard.

​
Building

pip install pyinstaller

# Auto-detect current platform and build the full installer
python3 build/build.py

# PyInstaller bundle only (skip the OS installer wrapper)
python3 build/build.py --bundle-only

# Remove dist/ and build cache before building
python3 build/build.py --clean

# Embed a version string in the build (e.g. 1.2.0)
python3 build/build.py --version 1.2.0

# Download the ASTAP binary for the current platform, then exit
python3 build/build.py --download-astap

# Skip ASTAP download (bundle will use pointing-WCS fallback)
python3 build/build.py --skip-astap
Output files:
PlatformOutput
Windowsdist/TelescopeNetNode-Setup.exe
macOSdist/TelescopeNetNode-X.Y.Z-macOS.pkg
Linuxdist/BoundlessSkiesNode-linux-x86_64
Windows builds require both makensis (NSIS) and nssm.exe to be available. If makensis is not found on PATH, the script prints a warning and skips the NSIS step — you will get the PyInstaller bundle but not the .exe installer. Install NSIS from nsis.sourceforge.io and ensure it is on your PATH.
Use --bundle-only when you want to test PyInstaller packaging without having NSIS or platform-specific packaging tools installed. The resulting bundle is a working executable — it just lacks the OS installer wrapper that handles service registration and activation code prompts.

​
Windows Installer (NSIS + NSSM)

The Windows installer is built from build/windows/install.nsi using NSIS. It produces dist/TelescopeNetNode-Setup.exe — a standard Windows installer that donors run with a double-click. What the installer does:
1

Prompt for activation code

A custom NSIS page asks for the donor’s Node Activation Code (BS-YYYY-XXXXXXXX). The code is validated for the correct BS- prefix, then written into config.yaml at the cloud.activation_code field. Donors get their code from telescopenet.org/account.
2

Install files

The main executable is installed to %PROGRAMFILES64%\TelescopeNet\NodeAgent\. Data files (config, logs, FITS exports, AAVSO submissions) are placed in %APPDATA%\TelescopeNet\NodeAgent\.
3

Disable AC idle sleep

The installer calls:
powercfg /change standby-timeout-ac 0
powercfg /change hibernate-timeout-ac 0
powercfg /change disk-timeout-ac 0
This prevents Windows from sleeping while the telescope is plugged in — critical for all-night operation. Uninstalling the agent restores the default timeouts (30 min standby, 60 min hibernate).
4

Register as a Windows service via NSSM

NSSM (the Non-Sucking Service Manager) registers TelescopeNetNode as a Windows service set to SERVICE_AUTO_START. Log rotation is configured to cap each log file at 5 MB. The service is started immediately after installation.
5

Create Start Menu shortcuts

Shortcuts are added for the local dashboard (http://localhost:5173), the data folder, and the uninstaller.

​
macOS Package (.pkg)

The macOS build produces a signed .pkg installer via pkgbuild and productbuild (Xcode CLI tools). Installation layout:
PathContents
/Applications/TelescopeNetNode/Main executable
/Library/LaunchDaemons/org.telescopenet.nodeagent.plistlaunchd service definition
/Library/Application Support/TelescopeNet/NodeAgent/Config, logs, data
What the installer does:
  • Installs the launchd plist to /Library/LaunchDaemons/ — the agent starts automatically at boot and restarts if it crashes
  • Calls pmset -c sleep 0 to disable AC idle sleep, preventing the Mac from sleeping while plugged in
  • Data directory: /Library/Application Support/TelescopeNet/NodeAgent/
The launchd approach means the agent runs as a system service even when no user is logged in, which is the correct behaviour for a machine dedicated to overnight telescope operation.

​
Linux (systemd)

Linux installation is handled by build/linux/install.sh. The recommended path is a one-line installer: 
# One-line install (recommended)
curl -sSL https://telescopenet.org/install.sh | sudo bash --code BS-2026-XXXXXXXX

# Or run the install script manually from the repo
sudo bash build/linux/install.sh --code BS-2026-XXXXXXXX
What the installer does:
1

Create service user

Creates a telescopenet system user with no login shell, used to run the agent with minimal privileges.
2

Install binary and config

Installs the Node Agent binary and writes config.yaml from the template with the activation code substituted.
3

Install and enable systemd unit

Installs the telescopenet-node.service unit file and enables it so the agent starts at boot:
systemctl enable --now telescopenet-node.service
4

Mask sleep targets

Prevents the system from sleeping overnight by masking the relevant systemd targets:
systemctl mask sleep.target suspend.target \
                hibernate.target hybrid-sleep.target

​
Sleep Prevention

Preventing the host machine from sleeping is critical for overnight telescope operation. Each platform uses OS-native mechanisms both at install time and at runtime:
PlatformInstall-timeRuntime
Windowspowercfg /change standby-timeout-ac 0SetThreadExecutionState (ES_CONTINUOUS | ES_SYSTEM_REQUIRED)
macOSpmset -c sleep 0caffeinate -i -w <PID>
LinuxMask sleep.target etc.systemd-inhibit --what=sleep
The runtime sleep prevention (src/sleep_prevention.py) is a separate layer from the installer-level power settings. Both must be active for a robust setup — the installer sets the OS policy, and the runtime inhibitor ensures the agent itself holds a sleep lock for the duration of the night.
If sleep prevention is not working, an overnight session can be silently interrupted mid-observation with no error logged. Verify that the OS power settings were applied during installation and that the sleep_prevention component appears as active in the node dashboard.

​
Build System Files

FilePurpose
build/build.pyCross-platform build orchestration script (run this)
build/node_agent.specPyInstaller spec — controls what is bundled into the executable
build/config.template.yamlConfig template written by installers; the cloud.activation_code field is populated from the installer prompt
build/windows/install.nsiNSIS installer script for Windows
build/macos/build_dmg.shmacOS .pkg build script
build/linux/install.shsystemd install script for Linux
build/binaries/ASTAP binary download cache (auto-populated by build.py)

Build docs developers (and LLMs) love

Get started for freeTalk to us