Overview¶

Concepts¶

Three concepts carry most of the weight:

The full vocabulary lives in the Glossary and Common Terms <>, but most of it should be fairly self-explanatory. Details about the providers are available in the Providers <> section.

Usage Lifecycle¶

What Exosphere Is Not¶

Exosphere reports --- it does not act. It will happily tell you what needs patching, where, and how urgently, but it will never apply an update or change a host's configuration on your behalf. Pushing those changes out is left to existing tooling built for the job, such as Ansible <https://www.ansible.com/> and similar automation frameworks, or unattended-upgrades <https://wiki.debian.org/UnattendedUpgrades> and similar.

See the Frequently Asked Questions <> for more on this distinction, and why it is a deliberate one.

Supported Platforms¶

Exosphere is designed to be platform agnostic, and can be run nearly everywhere Python runs. This guide can be used to install Exosphere on the following platforms:

Platform specific notes will appear whenever relevant, but the process should be the same across all platforms.

Exosphere technically supports more platforms than the ones listed above, but these are the ones we have explicitly tested. You can still follow the instructions below in most cases, but your mileage may vary.

Installing from PyPI¶

Exosphere is available on the Python Package Index <https://pypi.org/project/exosphere-cli/> (PyPI) for convenience, and can be installed using various methods.

The package name is exosphere-cli.

pipx install exosphere-cli

If you do not have Python 3.13 or later available, you can use uv <https://docs.astral.sh/uv/getting-started/installation/> to install Exosphere. Click the link above to see how to install uv <https://docs.astral.sh/uv/getting-started/installation/> for your platform, and then simply run:

uv tool install exosphere-cli

uv tool will handle downloading and installing the necessary Python runtime and dependencies for you, and then make the exosphere command available in your PATH.

The pipx or uv tool methods are recommended as they create a virtual environment and isolate the application, making it readily available without having to contend with potential conflicts with other Python packages.

The main difference is that uv tool will also download and manage the necessary Python runtime for you, if you do not have a suitable version available.

pip install is not recommended outside of a venv, as it will interfere with other Python packages and system versions of the libraries, and many distributions will in fact not allow you to install it that way.

Once installed, you can run Exosphere using the exosphere command, like so:

exosphere --help

Installing from Git Repository¶

This is likely the easiest method if you want to track the latest development version, or are simply more comfortable with using Git.

The project is set up with uv <https://docs.astral.sh/uv/getting-started/installation/>, which will download and install the necessary Python runtime and dependencies for you, so you don't have to worry about any of this.

You will require the following tools installed:

First, clone the repository into a directory of your choice. HTTPS

git clone https://github.com/mrdaemon/exosphere.git

git clone git@github.com:mrdaemon/exosphere.git

Then, change into the cloned directory:

cd exosphere

If you want the stable version, you can switch to the latest tag. Stable Release This will fetch the code for the latest stable release of Exosphere. This is recommended for most users.

git checkout v3.0.0

You can substitute v3.0.0 with a specific tag or version to use a specific release, e.g., v0.8.1.

You can find the list of tags on the GitHub releases page <https://github.com/mrdaemon/exosphere/releases>. Latest Development If you want the latest development version, you can switch to the main branch. This is not recommended for most users, as it may contain unstable or untested code.

If you want to hack on Exosphere, or get the latest features even if they are not fully tested, you should use the main branch.

git checkout main

Once that is done, you can simply set up Exosphere using uv <https://docs.astral.sh/uv/getting-started/installation/>:

uv sync --no-dev

This will download and install the necessary Python runtime and dependencies.

You can then either run Exosphere through uv <https://docs.astral.sh/uv/getting-started/installation/>:

uv run --no-dev exosphere

Or, you can activate the virtual environment created by uv <https://docs.astral.sh/uv/getting-started/installation/> and run Exosphere directly: Unix/macOS

source .venv/bin/activate
exosphere

. .venv\Scripts\activate.ps1
exosphere

.venv\Scripts\activate.bat
exosphere

From that point on, you can run Exosphere using the exosphere command.

Release Notes¶

You can (and should) consult the release notes on the GitHub releases page <https://github.com/mrdaemon/exosphere/releases> to see what has changed in each release, and if there are any special instructions or considerations for updating.

Generally, you should be able to update without any issues, however.

From PyPI¶

pipx If you installed Exosphere using pipx, you can update it with:

pipx upgrade exosphere-cli

uv tool upgrade exosphere-cli

From Git Repository¶

If you installed Exosphere from the Git repository, you can update it by pulling the latest changes and then syncing with uv <https://docs.astral.sh/uv/getting-started/installation/>: Stable Release If you are on a stable release, you can update it with:

git fetch --tags
git checkout v3.0.0
uv sync --no-dev

You can substitute v3.0.0 with the latest tag or specific version you want to use, e.g., v0.8.1.

You can find the list of tags on the GitHub releases page <https://github.com/mrdaemon/exosphere/releases>. Latest Development If you are on the main branch, you can update it with:

git pull --rebase
uv sync --no-dev

That's it! Your installation of Exosphere is now up to date.

Next Steps¶

For more fundamental details, you could have a look at How Exosphere Works <>.

To go further, you can:

Or start the full Text User Interface (TUI) <> for a more interactive experience:

$ exosphere ui

Tip:

Compatibility List¶

✅ Exosphere fully supports the following platforms:

☑️ Exosphere has limited support for the following platforms:

The bar for entry is fairly low to fit this description, as long as it can be connected to via SSH, has a POSIX shell available [1] and returns something useful via uname -s, it will work here.

❌ Exosphere explicitly does not support the following platforms:

Tip:

Common Prerequisites¶

All supported platforms share the same basic requirements, as Exosphere operates entirely through SSH connections and standard system utilities.

Essential Requirements

[1]

Exosphere runs all remote queries through the POSIX standard /bin/sh shell, which is present on all supported platforms, ensuring consistent behavior across them.

Optional Requirements

See below for more details.

Network Requirements

Some providers may require elevated privileges to perform certain operations, but this is entirely optional.

More details about all of this are available in the Connections and Authentication <> and Sudo Policies and Privileges <> sections.

Note:

3.0.0 - Reboots, Palettes, Sorting and refreshed CLI¶

The first major version release actually backed by a major set of changes. This release lands several long overdue features, refactors a lot of internals, swaps out the entire CLI engine and provides a much more polished help and documentation experience.

It has been cooking for a while, and the release notes are correspondingly long. Most of these changes are transparent, but there are some unavoidable incompatibilities. Make sure to read User Actions Required and Incompatible Changes before upgrading.

Feature Highlights¶

Pending Reboot Detection¶

[image: image] [image]

Exosphere can now tell you when a host is waiting on a reboot to finish applying updates --- a running kernel that no longer matches the installed one, a distro's reboot-required flag, and so on.

This is another feature grown out of a question that comes up frequently when managing updates across a fleet of hosts: "Has everyone been rebooted?". It felt only natural for Exosphere to attempt to answer that question.

This is presented in several places across the application interfaces:

The feature is implemented for all supported platforms where this information is available (Debian/Ubuntu, RHEL and derivatives, FreeBSD) and is entirely best-effort. None of the reboot checks require elevated privileges, so there is no sudoers change. If a provider cannot determine the status --- a missing tool, an unexpected error --- it is simply reported as unknown rather than failing the operation, so it will never block you from doing anything else.

TUI Command Palette Operations¶

For a long time the only way to perform targeted operations on a specific host was to use the CLI host commands, or specify hosts in bulk inventory operations.

The TUI was previously limited to bulk operations, and on specific screens.

To resolve this, the TUI now makes use of the command palette (Accessible via Ctrl+P) to allow you to run any of the host operations (sync, refresh, ping, etc) from any screen, and targeting any host.

[image: image] [image]

Selecting hosts also conveniently presents as a fuzzy search list, making the whole process light in keystrokes, and high in discoverability.

[image: image] [image]

The palette will also preselect the currently highlighted host in the Inventory screen, further lubricating the process.

[image: image] [image]

The palette and its operations can be invoked from any screen, and with this, there is finally functional parity between the CLI and TUI for host operations.

Inventory Sorting¶

[image: image] [image]

[image: image] [image]

Inventories can now be sorted, in both the CLI and the TUI.

Undiscovered and unsupported hosts always sort last, so the interesting hosts stay at the top regardless of the chosen field.

Reworked Built-in Help and CLI Polish¶

Exosphere has swapped out its CLI framework internals, and with that came the perfect opportunity to give a polish pass to the built-in help system.

[image: image] [image]

Multiple help panels, especially for the most complex commands like sudo or report, have been rewritten to be more helpful, explain what they do, and most importantly, group their copious options and flags into logical, meaningful sections.

[image: image] [image]

Additionally, unknown commands or verbs will now display a helpful message, with fuzzy suggestions for what you might have meant, leading to a friendlier experience when exploring the CLI or REPL.

The CLI engine change also brings a lot of internal improvements and better behavior for both the CLI and REPL.

New Commands¶

A few small but helpful new commands have been added:

All of these are documented more extensively in the Command Line Interface (CLI) <> docs as well as the Reporting and JSON Export <> docs.

The Web UI has been removed¶

It had always been more of an experimental curiosity than a real feature, and had not been actively developed since 1.0.0. Newer features (such as instance/cache locking) had begun to clash with it, and on balance it had become more of a maintenance burden than a useful capability.

As a result:

See the User Actions Required section for details.

Other Improvements¶

Bugfixes¶

Exosphere¶

Providers¶

User Actions Required¶

Shell completion must be reinstalled. The new CLI engine generates completion differently, so re-run exosphere --install-completion to install the updated scripts. On everything except PowerShell the new scripts take precedence and the old ones are harmless leftovers. If you do not use the shell completion feature at all, you have nothing to do. If you would like to remove the old scripts, see the FAQ <#faq-completion-upgrade> for the full details.

PowerShell completion is no longer supported and its leftovers must be cleaned up by hand, unfortunately, as there is no way around it. See the FAQ <#faq-completion-upgrade> for the full details and cleanup steps.

Web UI has been removed. The ui webstart command and the web install extra no longer exist. If you installed Exosphere as exosphere-cli[web], drop the [web] extra from your install. Existing installations will automatically resolve this on their own during upgrade, so there is no need to reinstall. Use the TUI instead, which is now the default ui command.

Incompatible Changes¶

Project and Documentation¶

What's Changed¶

Basic Usage¶

The CLI itself has two main modes of operation:

Tip:

Getting help¶

You can explore the root commands available by running exosphere --help or typing help in the interactive shell. This will show you a list of available commands and their descriptions.

For a complete list of commands and options, see the CLI Command Reference <> page.

Initial Inventory Discovery¶

The first time you run Exosphere after populating your configuration file with options and hosts, you should perform a Discovery operation.

This operation will connect to each host and attempt to detect what platform, operating system, flavor, version and package manager it is using.

It will then assign the appropriate provider to that host, which will allow Exosphere to query and refresh its package update status from here on.

If a host is present in the inventory, but not currently supported by Exosphere, it will be marked as such, and left available for Online checks. You will not be able to perform refresh or repo sync operations on them, and display panels will omit update information for them.

If a host is present in the inventory, not supported by Exosphere and also fails discovery due to not being a Unix-like operating system, it will return an explicit error, and should be removed for smooth operation.

For more details, see the Supported Remote Platforms <> page.

Inventory discovery can be done by running:

exosphere> inventory discover

Any errors will be printed to the console as well as the log file.

Tip:

exosphere> config paths

Refreshing Host State¶

Once you have discovered your hosts, you can refresh their state by running:

exosphere> inventory refresh

This will connect to each host in parallel, and fetch what updates are available, categorizing them, and storing the metadata in the cache file.

As part of the process, Exosphere will also attempt to check if the host has a pending reboot - for example, following a previously applied kernel or core library update.

If you want to also synchronize the repositories on each host to ensure the latest package lists are available, you can run:

exosphere> inventory refresh --sync

This will run the appropriate package manager command to update the repositories on each host, before fetching the update status.

You can also do it all at the same time, including discovery, by running:

exosphere> inventory refresh --discover --sync

For details on how any of this is implemented, see the Providers <> page.

Viewing Inventory Status¶

The main command for viewing the status of your inventory is:

exosphere> inventory status

This will display a table of all hosts, their status and how many updates they have available. [image: Example output of `exosphere inventory status`] [image]

You can also select one or more specific hosts by providing their names as arguments:

exosphere> inventory status host1 host2

This will show the status for only those hosts, allowing you to focus on specific systems.

You can also filter the output to only show hosts with available updates by using the --updates-only or --security-only flags:

exosphere> inventory status --updates-only
exosphere> inventory status --security-only

If this results in no hosts matching the criteria, Exosphere will print a message and exit with code 3.

By default, hosts are listed in the order they are defined in the configuration file. You can sort the table by any column using --sort, optionally reversing the order with --reverse:

exosphere> inventory status --sort updates --reverse
exosphere> inventory status --sort os

The available sort columns are host, os, flavor, version, updates, security and status.

Sorting and filtering can be combined freely.

A useful filter and sort combo you might find useful out of the box would be:

exosphere> inventory status --updates-only --sort security --reverse

Or, in short form:

exosphere> inventory status -u -o security -r

It will show hosts with updates, sorted by amount of security updates, descending, which is a great at-a-glance view of what to patch first.

You can include additional columns, such as each host's description, with the --full flag:

exosphere> inventory status --full

Viewing Host Details and Updates¶

To view detailed information about a specific host, including a detailed list of available updates, you can run:

exosphere> host show <hostname>

This will display detailed information about the host, including all of the useful metadata. This includes the last refresh timestamp, which provider it is using, whether a reboot is pending, etc.

It also will display a table of all available updates. [image: Example output of `exosphere host show`] [image]

Security updates are highlighted by default. You can also filter the updates via --security-only to only show security updates, or --no-updates to refrain from showing the table entirely.

Tip:

Online Checks¶

You can perform a quick online check to see if all your hosts are responding by running:

exosphere> inventory ping

This will attempt to SSH into each host and check if it is online. If a host is not reachable, it will be marked as offline and an error will be printed.

This is not an ICMP ping, but rather a full SSH connectivity check. It will only return "Online" if the host can be connected to successfully, and a trivial test command can be executed.

It can be a good way of validating connectivity to hosts. If ping returns "Online" for all hosts, you can be certain your SSH connectivity is working within the context of Exosphere.

This is by design to avoid scenarios where a host is reachable but not fully operational, for instance mid-startup or mid-shutdown, which would cause subsequent queries or operations to fail.

Hosts marked as Offline will be skipped in most operations such as refresh for performance reasons. You can invoke Ping to refresh this status at any time. [image: Example output of `exosphere inventory ping`] [image]

Viewing Configuration details¶

Exosphere makes it easy to answer questions about where it sourced its configuration from, what the current active configuration is, and what has been changed from the defaults.

You can view the path to the configuration file that was loaded by running:

exosphere> config source

You can view the currently active configuration for Exosphere by running:

exosphere> config show

If you also wish to see the contents of the inventory, you can supply the --full option.

You can also show exclusively the configuration options that have been changed:

exosphere> config diff

The output will include what the default value originally was.

Editing the configuration file¶

The config command has a friendly edit helper subcommand that allows you to easily open the configuration file in your preferred text editor, without needing to consult config paths or config show first.

exosphere> config edit

This launches your editor against the currently loaded configuration file. If no configuration file exists yet, the default platform path is opened instead, so you can create one from scratch.

The editor used is determined from the editor <#cmdoption-arg-editor> configuration option. In its absence, it will fallback to the VISUAL and EDITOR environment variables, and finally a platform default (notepad on Windows, vi elsewhere).

The command may include arguments: for graphical editors that detach immediately, pass the appropriate "wait" flag (for example code --wait) so Exosphere can wait until you are done.

Note:

After you close the editor, the file is validated. If it is invalid, the error is shown and you are offered the chance to re-open the editor and fix it. Pass --no-validate to skip this check.

Viewing the state of SSH connections¶

If you have SSH Pipelining <#ssh-pipelining-docs> enabled, you can view the current state of the SSH connection pool by running:

exosphere> connections show

This will display the currently open SSH connections, their age, and which hosts they are connected to, as well as tell you when they will be reaped.

You can manually close them with the following command:

exosphere> connections close

Both of these commands can take arguments, including specifying particular hosts. See the built in --help argument output for details.

If you do not have SSH Pipelining enabled (the default), connections are automatically closed after each operation, so these commands will have no effect.

Launching the Text-based User Interface¶

You can launch the text-based user interface (TUI) by running:

exosphere> ui

This will start the TUI, which provides a more interactive way to view and manage your inventory. You can navigate through the menus and perform operations using friendly shortcut keys displayed at the bottom of the screen.

An interesting feature of starting the TUI from the interactive shell like this is that you can switch back and forth between them seamlessly.

Once you exit the TUI, you will be returned to the exosphere> prompt, allowing you to run more targeted or specialized commands.

Tip:

For more details on the TUI, continue on to the Text User Interface (TUI) <> page.

Return Codes¶

Exosphere uses specific return codes to indicate the outcome of commands. Key return codes are typically:

The special return code (3) is used very deliberately and is intended to assist with scripting and automation, where you need to differentiate between errors and specific conditions.

For instance, exosphere version check will return 3 if updates are available, and the various --updates-only filters on inventory status will also return 3 if no hosts matched what you requested, and lastly, sudo generate will return it as well if no sudoers snippet needs to be generated for that host/provider.

Commands returning 3 will typically inform you of the meaning in their help text.

Beyond the Basics¶

Every command offers exhaustive built in documentation. Feel free to explore the available commands and options with the --help flag, or by running help in the interactive shell.

For advanced, file based reporting, see the Reporting and JSON Export <> page.

A complete CLI Command Reference <> is also available, which provides a comprehensive list of all the commands and their options.

Launching the UI¶

You can launch the UI by running:

$ exosphere ui

Or, from interactive mode:

exosphere> ui

Tip:

Note:

Interface Navigation¶

The UI is divided into several screens, each accessible via a keybind. At the very top of the screen, you will see the title bar with the current screen name.

The UI is separated in three main screens:

The bottom of the screen contains a status bar with keybinds for navigation and actions. [image: Example of Exosphere TUI with commands] [image]

Some of the keys displayed there will show up globally, while others are specific to the current screen you are on.

For instance here, you can press i to go to the Inventory screen. Keys are shown as they should be typed, so shift+p will trigger Ping All, and ctrl+d will trigger Discover All.

Universally, in every screen, you can press ctrl+p to access the command palette, which you can use to get keybind help, change the color theme, or run operations against all or specific hosts.

On Any Screen, you can press ctrl+q to Quit the UI.

Executing Operations¶

Most if not all of the operations you can perform on hosts in the UI are going to be dispatched through the same parallelized Thread Pool as the CLI, with minor implementation differences.

The UI will present a modal progress bar whenever this is occurring: [image: Example of Exosphere TUI Progress Bar] [image]

The Command Palette¶

Pressing ctrl+p from any screen will open the Command Palette, which allows you to select and fuzzy search through commands that can be invoked. This includes some built-in ones like Keys and Theme, but also Exosphere specific commands allowing you to perform operations on hosts in your inventory.

The palette can be invoked from any screen, and the available commands will be contextual to the screen you are on, if applicable. [image: Example of Exosphere TUI Command Palette] [image]

Host operations come in three flavors:

On All Hosts [image: Example of Exosphere TUI Command Palette with global host operations] [image]

These include operations like Ping all hosts, Discover all hosts, Refresh all hosts etc. Invoking these will perform the action immediately, displaying the progress screen, as described in the previous section. These can be invoked from any screen.

On Any Host

These commands allow you to select a specific host from your inventory and perform an operation on it, such as Ping..., Discover..., Refresh..., etc. [image: Example of Exosphere TUI Command Palette with host-specific operations] [image]

Invoking these will open a second prompt with a list of hosts available in your inventory, allowing you to either select one with the arrow keys and Enter, or to fuzzy search for it by typing its name, completely or partially. [image: Example of Exosphere TUI Command Palette with host selection] [image]

These commands can also be invoked from any screen.

On the currently selected host

When the palette is opened from the Inventory screen, each operation will also propose a variant that applies to the currently selected host in the inventory table. [image: Example of Exosphere TUI Command Palette with current host operations] [image]

Selecting it will let you run that operation immediately on whichever host is currently under the cursor in the inventory. These options will also sort above the global ones in the palette, making them quick to access.

These can only be invoked from the Inventory screen.

Tip:

The Dashboard¶

The default screen Exosphere launches into is the Dashboard. It presents a colored grid, each square representing a host in your inventory. [image: Example of Exosphere TUI Dashboard] [image]

Each square is color coded according to the status of the host. Green for Online, Red for Offline. Basic information about each host is also displayed.

This view is mostly useful as a poor man's monitoring dashboard, allowing you to quickly see which hosts are online or offline at a glance.

The following operations can be performed from the Dashboard:

Inventory Screen¶

[image: Example of Exosphere TUI Inventory] [image]

The Inventory screen provides a detailed view of all the hosts in your inventory.

The following operations can be performed from the Inventory screen:

It functions almost identically to the inventory status command in the CLI, but it allows you to navigate the rows with the Arrow Keys. The same status indicators apply, with * marking stale data and ! marking a pending reboot, as shown in the table legend.

You can select a host with Enter, which will open a panel with more details: [image: Example of Exosphere TUI Host Details] [image]

Any available updates will be displayed in a list. You can navigate this list with the arrow keys, much like the inventory itself, and select any of them with Enter. [image: Example of Exosphere TUI Update Details] [image]

Details about the currently selected update will be displayed in a new panel. This includes the package name, source, version change and whether or not it is a security update.

Filtering Hosts

It is also possible to filter hosts with ctrl+f, which will open a prompt with the available filters. [image: Example of Exosphere TUI Filter Prompt] [image]

Tip:

After selecting a filter, only hosts matching the criteria will be displayed. The active filter will be shown in the status bar at the bottom of the screen: [image: Exosphere TUI Inventory Status Bar with Security Updates filter active] [image]

You can clear the filter by pressing ctrl+f again and selecting the "Show All" option.

Sorting Hosts

You can sort the hosts with ctrl+s, which opens a prompt listing the sortable columns along with a Reverse order checkbox. Navigate the columns with the Arrow Keys, toggle reverse by pressing r (or focusing the checkbox with Tab and pressing Space), and press Enter to apply. [image: Example of Exosphere TUI Sort Prompt] [image]

Tip:

After applying a sort, the active sort field and direction are shown in the status bar alongside any active filter. You can restore the original configuration order by pressing ctrl+s again and selecting the "Default (config order)" option (or pressing D). [image: Exosphere TUI Inventory Status Bar with sorted status and direction] [image]

Sorting and filtering are independent and can be combined freely.

Logs Screen¶

[image: Example of Exosphere TUI Logs] [image]

The Logs screen provides a real-time view of the logs generated by Exosphere. You can access it by pressing l from the Dashboard or Inventory screen.

The window can be scrolled left and right, and will color certain elements.

Tip:

Available Formats¶

Below are examples of each output format to help you choose the right one for your needs. HTML Report Styled with a visually appealing design, entirely self-contained in a single file. Suitable for reading or printing. Offers an optional quick navigation box to jump between hosts.

Recommended for most uses.

=====================
SYSTEM UPDATES REPORT
=====================
Full Report, complete, generated: 2026-06-25 15:44:01 -0400
Summary:


  Total hosts: 5


  Hosts with updates: 4


  Total updates: 11


  Security updates: 4
web-prod-01 (10.0.1.10)
-----------------------
Web Server


  System: linux ubuntu 22.04


  Package Manager: apt


  Last Refresh: 2026-06-25 13:44:01 -0400


  Updates (4):


    Security Updates (2):


    - apache2: 2.4.52-1ubuntu4.6 -> 2.4.52-1ubuntu4.7


      Source: security


    - php8.1: 8.1.2-1ubuntu2.13 -> 8.1.2-1ubuntu2.14

# System Updates Report
Full Report, complete, generated on 2026-06-25 15:44:01 -0400
- **Total hosts:** 5
- **Hosts with updates:** 4
- **Total updates:** 11
- **Security updates:** 4
## web-prod-01 (10.0.1.10)
**System Information:**
- **Description**: Web Server
- **OS**: linux ubuntu 22.04
- **Package Manager**: apt
- **Last Refresh**: 2026-06-25 13:44:01 -0400
**Available Updates (4):**
| Package | Current Version | New Version | Sec | Source |
|---------|-----------------|-------------|-----|--------|
| **apache2** | 2.4.52-1ubuntu4.6 | 2.4.52-1ubuntu4.7 | **Yes** | security |
| **php8.1** | 8.1.2-1ubuntu2.13 | 8.1.2-1ubuntu2.14 | **Yes** | security |

Basic Usage¶

The simplest way to generate a report is:

$ exosphere report generate

This will output a plain text report to your terminal showing all hosts and their update status.

The --format/-f option controls the output format, and accepts any of text, html, markdown, or json.

Save to File

You can save the report to a file with --output/-o:

$ exosphere report generate --format html --output systems-report.html

Displaying Specific Hosts

Which hosts are included in the report can be controlled by specifying them as arguments. For example, to generate a JSON report for just three hosts:

$ exosphere report generate --format json web1 web2 database

Updates Available Only

The report can be filtered to only show hosts with updates available using --updates-only:

$ exosphere report generate --updates-only --format html --output updates.html

Security Updates Only

To exclusively select security updates, use --security-updates-only:

$ exosphere report generate --security-updates-only

Advanced Options¶

File Output with Preview

$ exosphere report generate --format html --output report.html --tee

Quiet Mode

$ exosphere report generate --format json --quiet --output daily-report.json

HTML Navigation

$ exosphere report generate --format html --no-navigation -o report.html

Report Content¶

All reports include:

The presentation and formatting varies by format, but the core information remains consistent across all output types.

Tip:

Status Summary¶

For a quick, at-a-glance overview rather than a full report, report status prints a condensed, plain-text summary of the entire inventory:

$ exosphere report status
15 of 25 hosts have pending updates, 10 with security updates
2 hosts have a pending reboot.
1 host has stale data, consider running a refresh.

The reboot and stale lines only appear when there is something to report, and when nothing is pending the summary simply reads All hosts are up to date.. Hosts that have not yet been discovered contribute nothing to the counts, as they have no known state.

Like the rest of the reporting commands, this operates entirely from the cache and requires no connectivity. Color is automatically dropped when the output is not a terminal, which makes it well suited to non-interactive uses, such as redirecting it into a MOTD or similar through a user cronjob, timer, or periodic task.

JSON Schema Details¶

The JSON output format provides a structured representation of the inventory and update information, making it suitable for programmatic consumption.

If you want to have a Discord bot that reports updates, or feed your event queue for your astoundingly complex MQTT Doorbell Over Zigbee that also brews coffee, this should enable you to do so.

JSON Schema¶

The JSON output follows a well-defined schema for consistency and integration purposes. The schema is available in the source tree as exosphere/schema/host-report.schema.json, but is also made available here, corresponding to the version this documentation is built for:

host-report.schema.json as of v3.0.0

You can also emit the schema for your installed version directly from the CLI with report schema (printed to stdout, or written to a file with --output), which is handy for validating or integrating with the JSON output offline.

$ exosphere report schema --output host-report.schema.json

Structure Overview¶

The report consists of an array of host objects. When generated via the CLI, the hosts will be pre-filtered to only include hosts that have been discovered, are supported, and have a valid package manager provider <> assigned to them.

Tip:

Each host's updates array contains update objects with the following structure. Update Object Properties

Example JSON report structure

[


  {


    "name": "web-server-01",


    "description": "Production web server",


    "ip": "192.168.1.10",


    "port": 22,


    "os": "linux",


    "flavor": "ubuntu", 


    "version": "22.04",


    "supported": true,


    "online": true,


    "package_manager": "apt",


    "updates": [


      {


        "name": "curl",


        "current_version": "7.81.0-1ubuntu1.4",


        "new_version": "7.81.0-1ubuntu1.6", 


        "security": true,


        "source": "security"


      },


      {


        "name": "new-dependency",


        "current_version": null,


        "new_version": "1.0.0",


        "security": false,


        "source": "main"


      }


    ],


    "last_refresh": "2024-03-15T14:30:00.000Z"


  },


  {


    "name": "database-server",


    "ip": "192.168.1.20",


    "port": 22,


    "os": "freebsd",


    "flavor": "freebsd",


    "version": "13.1-RELEASE",


    "supported": true,


    "online": true,


    "package_manager": "pkg",


    "updates": [],


    "last_refresh": null


  }
]

More examples are available in the Sample Reports section above.

Integration Examples¶

Here are some concrete but deeply uncreative examples of how the reporting feature can be used in practice.

If you make a cool thing, please let us know <https://github.com/mrdaemon/exosphere/issues/new/choose> via a GitHub issue! We'll happily showcase it here.

Email text report about security updates

#!/bin/bash
exosphere report generate --updates-only --quiet \
| mail -s "System Updates Available" bigadmin@example.com

JSON Processing with jq

# Count hosts with security updates
exosphere report generate --format json --security-updates-only | jq 'length'
# Extract just host names and update counts
exosphere report generate --format json | jq '.[] | {name, updates: .updates | length}'
# The same but only hosts that have updates
exosphere report generate --format json \
| jq '.[] | select(.updates | length > 0) | {name, updates: .updates | length}'

Connecting to systems¶

Exosphere uses SSH to connect to remote hosts, using the lovely Fabric <https://www.fabfile.org/> library. The intended authentication method is to use SSH keys, which should be loaded into your SSH agent.

Exosphere purposefully does not support password authentication in any of its subsystems, to avoid having to deal with the complexities of storing credentials, or prompting for them in a way that does not introduce a security risk.

The main configurable parameters of host connections (at least through Exosphere's interface) are as follows:

Using SSH Agents¶

An SSH agent is a program that loads your SSH keys into memory, usually with your login session on your workstation or laptop, allowing you to connect to remote hosts without having to enter your passphrase every time. This is instrumental to many SSH automation tools and workflows.

Exosphere relies on the SSH agent to provide the necessary keys for authentication.

The process for setting up an SSH agent and/or generating key pairs for your hosts is beyond the scope of this documentation, but plenty of guides are available online, including your distribution's documentation.

A reasonable place to start is the Arch Linux Wiki's Article on SSH keys <https://wiki.archlinux.org/title/SSH_keys>, which is generic enough to apply to most if not all distributions.

Tip:

Testing connectivity¶

You can test your SSH connectivity to a host using discover as it will display a nice table of errors for hosts where connectivity fails.

You can do this for the entire inventory with:

exosphere> inventory discover

Or for a specific host, such as a host named bigserver:

exosphere> host discover bigserver

Authentication failures will display clearly in the output. The exact cause, however, can vary, but you should check the following:

For debugging purposes, you can try connecting to the host yourself with verbose output:

$ ssh -vvv bigserver

This will provide detailed information about the SSH connection process, which can help pinpoint the exact issue with authentication or connectivity.

Tip:

SSH Pipelining¶

By default, Exosphere closes SSH connections to remote hosts after each operation (with some exceptions for batching purposes). This ensures no resources are left open on both the local and remote systems.

Exosphere makes a best-effort attempt to batch queries within an operation to minimize unnecessary connection churn and overhead, but this is scoped to individual operations (e.g., discover, refresh, sync, etc.).

If you have a reasonably sizeable inventory and/or find that the overhead of repeatedly opening and closing SSH connections reduces performance, you can enable SSH Pipelining via the ssh pipelining option <#ssh-pipelining-option>.

When this setting is enabled, Exosphere will not close connections after each operation, but will instead keep them open for reuse.

Connections will be allowed to idle for a configurable amount of time (default is 5 minutes) before being automatically closed in the background.

This can speed up operations significantly if your workflow involves multiple operations in sequence on the same set of hosts, at the cost of leaving connections to remote hosts open for a longer period of time.

With pipelining enabled, you can view and manage the currently open connections via:

exosphere> connections show

as well as:

exosphere> connections close

See the connections command help for more details.

The configurable values for SSH Pipelining include the maximum lifetime of idle connections <#ssh-pipelining-lifetime-option>, as well as the interval at which they are reaped <#ssh-pipelining-reap-interval-option>.

Location¶

Where the configuration file lives will depend on your platform. For instance, for a YAML configuration file, the default locations are: Linux, Unix ~/.config/exosphere/config.yaml macOS ~/Library/Application Support/exosphere/config.yaml Windows %LOCALAPPDATA%\exosphere\config.yaml

You can of course substitute the file extension with .toml or .json if you wish to use those formats instead.

You can also ask Exosphere where it expects the configuration file to be on your platform:

exosphere config paths

Additionally, you can specify a custom configuration file location via the EXOSPHERE_CONFIG_FILE environment variable, with the full path to the file as the value.

Structure¶

Below is a full example of a configuration file, in all supported formats. Any option left out will use the default values, which are documented below. YAML

options:


  log_level: DEBUG


  max_threads: 5  # Limit parallel actions to 5 threads


  default_username: alice  # Default username across hosts (optional)
hosts:


  - name: host1


    ip: host1.example.com


  - name: host2


    ip: host2.example.com


    port: 2222


    description: "Example Host"


  - name: host3


    ip: host3.example.com


    description: "Another Example Host"


    username: admin  # Override username for this host


    sudo_policy: nopasswd

[options]
log_level = "DEBUG"
max_threads = 5 # Limit parallel actions to 5 threads
default_username = "alice" # Default username across hosts (optional)
[[hosts]]
name = "host1"
ip = "host1.example.com"
[[hosts]]
name = "host2"
ip = "host2.example.com"
port = 2222
description = "Example Host"
[[hosts]]
name = "host3"
ip = "host3.example.com"
description = "Another Example Host"
username = "admin" # Override username for this host
sudo_policy = "nopasswd"

{


    "options": {


        "log_level": "DEBUG",


        "max_threads": 5,


        "default_username": "alice"


    },


    "hosts": [


        {


            "name": "host1",


            "ip": "host1.example.com",


            "description": "Example Host"


        },


        {


            "name": "host2",


            "ip": "host2.example.com",


            "port": 2222,


            "description": "Example Host"


        },


        {


            "name": "host3",


            "ip": "host3.example.com",


            "description": "Another Example Host",


            "username": "admin",


            "sudo_policy": "nopasswd"


        }


    ]
}

The configuration file is split into two main sections, Options and Hosts. The Options section contains general settings for Exosphere, while the Hosts section contains the Inventory of hosts that Exosphere will connect to.

Environment Variables¶

The location of the configuration file can be overridden by setting the EXOSPHERE_CONFIG_FILE environment variable to the full path of the file you wish to use. Unix/macOS

export EXOSPHERE_CONFIG_FILE="/path/to/my/config.yaml"

$env:EXOSPHERE_CONFIG_FILE = "c:\path\to\my\config.yaml"

set EXOSPHERE_CONFIG_FILE="c:\path\to\my\config.yaml"

Tip:

Exosphere also supports loading configuration options from environment variables. You can use this to override any specific Option from the configuration file. You cannot use environment variables to override the Hosts section.

The environment variable names are prefixed with EXOSPHERE_OPTIONS_ and the option name in uppercase.

For example, to override the log_level option, set the following environment variable: Unix/macOS

export EXOSPHERE_OPTIONS_LOG_LEVEL="DEBUG"

$env:EXOSPHERE_OPTIONS_LOG_LEVEL = "DEBUG"

set EXOSPHERE_OPTIONS_LOG_LEVEL=DEBUG

This pattern applies to all configuration options.

Exosphere can display which environment variables are influencing the configuration (if any):

exosphere config source

Options¶

The options section contains general settings for Exosphere. These options are applied globally, and affect how Exosphere behaves at runtime.

Below is a detailed list of all available options, their defaults, and examples of how to set them in the configuration file.

options:


  log_level: DEBUG

[options]
log_level = "DEBUG"

{


    "options": {


        "log_level": "DEBUG"


    }
}

options:


  default_sudo_policy: nopasswd

[options]
default_sudo_policy = "nopasswd"

{


    "options": {


        "default_sudo_policy": "nopasswd"


    }
}

options:


  debug: true

[options]
debug = true

{


    "options": {


        "debug": true


    }
}

options:


  log_file: /home/alice/tmp/exosphere.log

[options]
log_file = "/home/alice/exosphere.log"

{


    "options": {


        "log_file": "/home/alice/exosphere.log"


    }
}

options:


  log_max_bytes: 10485760  # 10 MiB

[options]
log_max_bytes = 10485760  # 10 MiB

{


    "options": {


        "log_max_bytes": 10485760


    }
}

options:


  log_backup_count: 5

[options]
log_backup_count = 5

{


    "options": {


        "log_backup_count": 5


    }
}

options:


  history_file: /home/alice/.exosphere_history

[options]
history_file = "/home/alice/.exosphere_history"

{


    "options": {


        "history_file": "/home/alice/.exosphere_history"


    }
}

options:


  history_max_entries: 5000

[options]
history_max_entries = 5000

{


    "options": {


        "history_max_entries": 5000


    }
}

options:


  cache_autosave: false

[options]
cache_autosave = false

{


    "options": {


        "cache_autosave": false


    }
}

options:


  cache_autopurge: false

[options]
cache_autopurge = false

{


    "options": {


        "cache_autopurge": false


    }
}

options:


  cache_file: /home/alice/tmp/exosphere.db

[options]
cache_file = "/home/alice/tmp/exosphere.db"

{


    "options": {


        "cache_file": "/home/alice/tmp/exosphere.db"


    }
}

options:


  stale_threshold: 3600  # 1 hour

[options]
stale_threshold = 3600  # 1 hour

{


    "options": {


        "stale_threshold": 3600


    }
}

options:


  default_timeout: 60  # 1 minute

[options]
default_timeout = 60  # 1 minute

{


    "options": {


        "default_timeout": 60


    }
}

options:


  default_username: alice  # Use 'alice' as the default SSH username

[options]
default_username = "alice"  # Use 'alice' as the default SSH username

{


    "options": {


        "default_username": "alice"


    }
}

options:


  default_ssh_locale: C.UTF-8

[options]
default_ssh_locale = "C.UTF-8"

{


    "options": {


        "default_ssh_locale": "C.UTF-8"


    }
}

options:


  max_threads: 5  # Limit parallel actions to 5 threads

[options]
max_threads = 5  # Limit parallel actions to 5 threads

{


    "options": {


        "max_threads": 5


    }
}

options:


  ssh_pipelining: true

[options]
ssh_pipelining = true

{


    "options": {


        "ssh_pipelining": true


    }
}

options:


  ssh_pipelining_lifetime: 240  # 4 minutes

[options]
ssh_pipelining_lifetime = 240  # 4 minutes

{


    "options": {


        "ssh_pipelining_lifetime": 240


    }
}

options:


  ssh_pipelining_reap_interval: 60  # 1 minute

[options]
ssh_pipelining_reap_interval = 60  # 1 minute

{


    "options": {


        "ssh_pipelining_reap_interval": 60


    }
}

options:


  update_checks: false

[options]
update_checks = false

{


    "options": {


        "update_checks": false


    }
}

options:


  no_banner: true

[options]
no_banner = true

{


    "options": {


        "no_banner": true


    }
}

options:


  editor: "code --wait"

options:


  editor: '"C:\Program Files\Editor\ed.exe" --wait'

[options]
editor = "code --wait"

[options]
editor = '"C:\Program Files\Editor\ed.exe" --wait'

{


    "options": {


        "editor": "code --wait"


    }
}

{


    "options": {


        "editor": "\"C:\\Program Files\\Editor\\ed.exe\" --wait"


    }
}

Inventory¶

The second section of the configuration file is the Hosts section, which is referred to throughout the documentation as The Inventory.

The Hosts section contains a list of hosts that Exosphere will connect to, as well as their connection parameters and any specific option for each host.

Host entries are structured as follows. This example describes two hosts, one of which has a custom connection timeout value set, overriding default_timeout. YAML

hosts:


  - name: myhost


    ip: myhost.example.com


  - name: anotherhost


    ip: 127.0.1.8


    connect_timeout: 30

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
[[hosts]]
name = "anotherhost"
ip = "127.0.1.8"
connect_timeout = 30

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com"


        },


        {


            "name": "anotherhost",


            "ip": "127.0.1.8",


            "connect_timeout": 30


        }


    ]
}

Mandatory fields for each host entry are:

Optional fields for each host entry include:

Below is the detailed list of all available host options and their defaults.

hosts:


  - name: myhost

[[hosts]]
name = "myhost"

{


    "hosts": [


        {


            "name": "myhost"


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com

[[hosts]]
name = "myhost"
ip = "myhost.example.com"

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com"


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com


    port: 2222

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
port = 2222

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com",


            "port": 2222


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com


    username: alice

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
username = "alice"

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com",


            "username": "alice"


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com


    description: "Web Server"

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
description = "Web Server"

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com",


            "description": "Web Server"


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com


    connect_timeout: 30  # 30 seconds

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
connect_timeout = 30  # 30 seconds

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com",


            "connect_timeout": 30


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com


    sudo_policy: nopasswd

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
sudo_policy = "nopasswd"

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com",


            "sudo_policy": "nopasswd"


        }


    ]
}

hosts:


  - name: myhost


    ip: myhost.example.com


    ssh_locale: C.UTF-8

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
ssh_locale = "C.UTF-8"

{


    "hosts": [


        {


            "name": "myhost",


            "ip": "myhost.example.com",


            "ssh_locale": "C.UTF-8"


        }


    ]
}

Enumerating Providers and their Privileges¶

The documentation for Providers <> includes details, but you can query this via the exosphere CLI and its sudo command. Here is an example below:

$ exosphere sudo providers


                                Providers Requirements
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Provider ┃ Platform                       ┃ Sync Repositories ┃ Refresh Updates ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ Apt      │ Debian/Ubuntu Derivatives      │ Requires Sudo     │ No Privileges   │
│ Pkg      │ FreeBSD                        │ Requires Sudo     │ No Privileges   │
│ PkgAdd   │ OpenBSD                        │ No Privileges     │ No Privileges   │
│ Dnf      │ Fedora/RHEL/CentOS Derivatives │ No Privileges     │ No Privileges   │
│ Yum      │ RHEL/CentOS 7 and earlier      │ No Privileges     │ No Privileges   │
└──────────┴────────────────────────────────┴───────────────────┴─────────────────┘

For instance, we can see here that the Apt and Pkg providers require sudo privileges to sync repositories, but do not require any privileges to refresh updates.

Note:

Configuring Sudo Policies¶

There are currently two valid settings for the Sudo Policy options:

The default Sudo Policy for exosphere is skip, configured globally <#default-sudo-policy-option>. This means that Exosphere will not attempt to use sudo at all when running provider commands.

This can also be configured per system, by setting the sudo policy option <#hosts-sudo-policy-option> at the host level.

If you want to be able to use Exosphere to run operations that require sudo privileges, you will need to configure sudoers on the remote host(s) where this applies to allow them to be run without a password.

Attention:

Generating a Sudoers configuration¶

You can manually configure sudoers with NOPASSWD: as you wish, so long as it allows the commands specified in the Providers <> documentation to run.

However, since this can be a combination of tedious, risky and error-prone, Exosphere provides a helper command that will generate a sudoers snippet for you, for any host, or specific provider, while also allowing you to specify a username.

To generate a sudoers configuration snippet for the Apt provider, for instance, with the username bigadmin, you can run the following command:

$ exosphere sudo generate --provider apt --user bigadmin
# Generated for Debian/Ubuntu Derivatives
Cmnd_Alias EXOSPHERE_CMDS = /usr/bin/apt-get update
bigadmin ALL=(root) NOPASSWD: EXOSPHERE_CMDS

You can then take this output and drop it in a file on the remote host, such as /etc/sudoers.d/zz-exosphere (or, if on a FreeBSD System, /usr/local/etc/sudoers.d/zz-exosphere) and then switch the Sudo Policy to nopasswd for that host.

You can also use the --host option to automatically detect the provider for a host and generate the appropriate sudoers snippet for it.

For more details, see exosphere sudo generate --help.

Security Considerations¶

The generated sudoers configuration is designed to be as secure as possible:

This approach is significantly more secure than granting broad sudo access, as it:

Alternatives¶

If your relevant providers only require sudo privileges for repository synchronization, and you prefer not to use the sudoers configuration, you can still configure your remote systems to sync those repositories on a schedule. You will just not be able to use Exosphere to do it on-demand, but the repository contents should always be reasonably up to date.

On Debian/Ubuntu systems, consider these options:

On FreeBSD, you can set up a cron job or periodic task to run /usr/sbin/pkg update regularly.

For other distributions, similar automated package management tools are available.

How can I check what the effective Sudo Policy is for a given host?¶

You can use the sudo check helper command.

As an example, to check the effective Sudo Policy for a host named bigserver:

$ exosphere sudo check bigserver
Sudo Policy for bigserver


 Global Policy:          skip


 Host Policy:            nopasswd (local)


 Package Manager:        apt


 Can Sync Repositories:  Yes


 Can Refresh Updates:    Yes

This will tell you what the effective Sudo Policy is for that host, as well as where that is configured. For instance, in the example above, you can see the global policy is skip, but the host policy has been set to nopasswd locally, in the inventory host options.

The global Sudo Policy can also be displayed via:

$ exosphere sudo policy
Global SudoPolicy: skip

Clearing the Cache¶

If you encounter issues or inconsistencies with the cache, you can clear it. It can generally safely just be deleted on disk, and will be recreated on next run.

The cache file can also be manually cleared within Exosphere in the Command Line Interface (CLI) <>:

$ exosphere inventory clear

The confirmation prompt can be bypassed with the -f flag.

Upon clearing the cache, you will have to perform a full Discovery and subsequent Refresh of the entire inventory to repopulate it.

Check the logs¶

Exosphere always writes a log file, regardless of how you run it, and it is the first place to look. To find it, run:

$ exosphere config paths

and look under the Log: entry for the path on your platform.

If you are in the TUI <>, you can also press l to open the Logs screen and watch events as they happen.

Turn up the verbosity¶

By default, Exosphere logs at INFO level. If the logs do not explain the problem, raise it to DEBUG via the log_level <#log-level-option> option: YAML

options:


  log_level: DEBUG

[options]
log_level = "DEBUG"

{


    "options": {


        "log_level": "DEBUG"


    }
}

You can also raise it for a single run, without editing your config, via the EXOSPHERE_OPTIONS_LOG_LEVEL environment variable <#config-env-vars>. Unix/macOS

$ EXOSPHERE_OPTIONS_LOG_LEVEL=DEBUG exosphere

$env:EXOSPHERE_OPTIONS_LOG_LEVEL = "DEBUG"
exosphere

set EXOSPHERE_OPTIONS_LOG_LEVEL=DEBUG
exosphere

You can confirm this worked by checking the output of exosphere config source and exosphere config diff.

For library-level detail (the SSH internals from Fabric and paramiko, for instance), there is the debug <#debug-option> option, but be warned that it is extremely noisy and is rarely needed outside of development. We suggest not using this unless asked in a bug report.

Check the configuration Exosphere actually loaded¶

A surprising number of "it is not doing what I told it to" problems come down to Exosphere loading a different configuration file than you expect, or an environment variable quietly overriding a value.

Confirm what was loaded, and from where:

$ exosphere config source

This shows the active configuration file path and any environment variables influencing the configuration. To inspect the effective values, use config show, or config diff to see only what differs from the defaults.

Test connectivity¶

Most failures are connectivity or authentication problems. The quickest test is a discovery, which prints a clear table of any errors:

exosphere> inventory discover

or, for a single host:

exosphere> host discover bigserver

If a host fails, work through the checklist:

To reproduce the connection outside of Exosphere, with full detail:

$ ssh -vvv bigserver

Remember that Exosphere honors ~/.ssh/config and /etc/ssh/ssh_config, so double-check any host aliases or per-host settings there. The Connections and Authentication <> page covers all of this in depth.

Tip:

Common situations¶

A few recurring issues, with where to look:

When to look at the providers¶

If a host connects fine but updates or repository sync misbehave, the cause is often specific to the package manager. The Providers <> page documents the exact commands each provider runs, along with platform quirks --- running the failing command by hand on the remote host is often the fastest way to see what is really going wrong.

Still stuck?¶

If you have worked through this guide and the FAQ <#faq-troubleshooting> without luck, head to Getting Help <> for where to ask and how to file a useful bug report.

General Questions¶

Can Exosphere help me apply the updates and patches?¶

Unfortunately, no. Exosphere is not a configuration management or automation tool, simply a reporting and aggregation tool.

The gap it exists to fill is providing you with a unified, centralized view of the state of updates and patches across your systems, so you can make informed decisions about what needs patching, and when.

This functionality is not planned, and left to frankly better tooling that already exists, such as UnattendedUpgrades <https://wiki.debian.org/UnattendedUpgrades>, Ansible <https://www.ansible.com/>, RunDeck <https://www.rundeck.com/>, etc.

Didn't Exosphere used to have a Web UI? What happened to it?¶

It was removed in version 3.0. The Web UI started as a neat curiosity more than a feature, but never left the experimental stage.

It was always provided as a separate, opt-in, extra for the python packages, and installed and used by few, least of all the author.

As the project matured, and new features started clashing with the way it was implemented, it became clear it should be removed instead of being left to rot in its current, janky, underdeveloped state.

Why all the different config file formats?¶

The author is fond of yaml, but recognizes toml is gaining traction in the Python community. At this point also supporting json was so low effort that it was added in.

The overhead of supporting this is so negligible that we'd prefer to make everyone happy, if at all possible.

They all de-serialize to exactly the same data structure (and this is validated with unit tests), so you can use whichever of the formats you feel strongest about, or hate the least.

Why Python 3.13?¶

For completely selfish reasons such as:

Exosphere was written mostly to scratch the author's own itch. While it is made public in the hopes that it will be useful to others, and great care and effort has been spent on documentation and ease of use, the focus at this time remains to keep the author happy.

Compatibility test matrices are unfortunately not a source of happiness.

Platform Support¶

I really like the dashboard. Can I still use it if my systems are unsupported?¶

Yes, as long as the remote system is a Unix-like operating system.

In this case, if your remote operating system is not supported, Exosphere will allow you to use the dashboard and online checks (ping command, etc) just fine.

You won't be able to perform refresh or sync operations on them, and the update counts will be disabled, but this part will remain functional.

If the system in question is not a Unix-like operating system, it will not be discoverable at all, and should not be added to the inventory.

When managing Ubuntu systems, will this handle snaps?¶

Exosphere does not currently support snaps or flatpaks. There are no immediate plans to add support for these, but it is certainly possible in the future, if this becomes a common facet of server management.

On BSD systems, will this handle system updates and source ports?¶

Exosphere does not currently support system updates or source ports. It only supports Binary Packages, for both FreeBSD and OpenBSD.

There are plans to add support for system updates in the future, presenting them as a synthetic package in the updates view, but this needs more work.

For the time being, cron reports and mailing lists for syspatch and freebsd-update are recommended to keep tabs on these.

Does FreeBSD support extend to things like OPNSense?¶

Since 1.3.4, the pkg provider performs repository synchronization in a manner that is compatible with OPNSense, and the platform is supported as FreeBSD.

As long as you configure sudo and sudoers correctly, and that the system uses pkg underneath, it should work just fine.

Is Windows support planned or even possible?¶

The application runs fine on Windows, and while managing Windows is something we would love to implement, the connection methods are not incredibly straightforward, and the APIs and interfaces for update and patch management are not great. Microsoft continues to hope you will buy into their management tools, so the core APIs are not very accessible as a result.

Windows support remains an eventual goal, but it is not currently planned.

Configuration and Customization¶

Can I specify a custom path for the configuration file?¶

Yes! You can specify a custom path for the configuration file by setting the EXOSPHERE_CONFIG_FILE environment variable to the full path of the file you wish to use.

See The Configuration File <> for more details on other environment variables you can define to influence or override the configuration.

I don't like the ascii art banner in interactive mode¶

You can disable it entirely with the no_banner config option <#no-banner-option>.

Is there any way to disable the update check?¶

Yes, you can disable the update check by setting the update_checks config option <#update-checks-option> to false in the configuration file.

This should be helpful in environments where you do not want to talk to PyPI at all.

If you are a prospective package maintainer wishing to package Exosphere for your favorite platform's repositories, it is recommended that you patch out the default value of this option to False in exosphere/config.py, or override via environment variables <#config-env-vars>, if feasible.

Troubleshooting¶

Why does ping report Offline when the system is reachable?¶

The ping checks in exosphere aren't ICMP ping, but SSH pings. They will only return an Online status if the remote system can be connected to successfully, over SSH, and a simple POSIX test command can be executed. (/bin/true or shell built-in equivalent)

As such, scenarios that can cause an Offline status include:

We consider "Online" to mean "the system is up and ready to process further queries", instead of just "the system is reachable over the network".

This is by design, and aims to avoid scenarios where the system is reachable, but is currently shutting down, or has not finished booting.

Generally, if the host shows up as Offline, you would not be able to perform any of the other operations on it anyways.

You can re-run the discovery command to find out what the issue is and correct it, if you are getting this during initial setup.

I get an error with "Private key file is encrypted", what does it mean?¶

The presence of this error in logs means that authentication failed in some way.

Verify that:

The unhelpful error message is unfortunately a Known Issue <https://github.com/paramiko/paramiko/issues/387> in the paramiko library, which is used internally to handle SSH connections. Whenever authentication fails when an SSH agent is used, this is the exception that will be raised, regardless of the actual issue.

Exosphere will generally catch this specific error and rewrite the error message to be more helpful, but there are a few edge cases where it may be displayed as-is.

My system using dnf or yum hangs when refreshing¶

The dnf and yum providers do a best effort to prevent interactive prompts when running the commands they need to synchronize repositories and cache, but sometimes, they will still prompt for user input, which Exosphere cannot handle.

To resolve this, you can simply connect to the remote system as the same user you use within Exosphere, and manually run the following commands: dnf

dnf makecache --refresh
dnf check-update

yum makecache --refresh
yum check-update

And answer all the prompts that may appear. The provider should no longer hang past this point.

After an update, my system using dnf fails to refresh!¶

After certain types of updates, you may get the following error message when trying to refresh a dnf based system:

Failed to get current versions: Error: SQLite error on "/var/lib/dnf/history.sqlite":
Executing an SQL statement failed: attempt to write a readonly database

This is a known issue where dnf apparently needs to perform some database updates before it can perform its queries. This requires root privileges, which Exosphere does not have access to during normal operations.

To resolve this, you can connect to the remote system and run a simple query with root privileges to fix the database:

$ sudo dnf --quiet -y list installed kernel.x86_64

This should resolve the issue, and you should be able to refresh the system without write access errors afterwards.

I've tuned the timeout but this one host keeps getting flagged offline¶

Exosphere does use a fairly aggressive timeout value for its SSH connections, but if you have a host that is consistently supremely slow to respond, yet you can connect to it reliably, it is likely you have DNS issues on that server.

Check your resolvers and/or add UseDNS no to your sshd configuration. FreeBSD notoriously ships with the option enabled by default, for instance.

If you can't or this has no effect, you can increase the timeout value for that host specifically by setting the connect_timeout host option <#connect-timeout-host-option> to a higher value, without having to change the global option.

The frequent SSH connections are causing issues on my SSH server¶

If you have systems that have connection rate limiting, or take a while to authenticate, you can enable SSH connection pipelining to reduce the amount of connection churn.

See the documentation on SSH Pipelining <#ssh-pipelining-docs> as well as the ssh_pipelining configuration option <#ssh-pipelining-option>.

Updates refresh fails on my OpenBSD system with an exotic architecture!¶

Exosphere relies on the availability of the syspatch command to determine if the system is tracking a stable release or -current.

If you're running a more exotic, non-x86 architecture, Exosphere may not be able to handle the failure mode gracefully, and we'd deeply appreciate it if you could file a bug report <https://github.com/mrdaemon/exosphere/issues> with the output of syspatch -l so we can improve this situation.

Help, the sudoers snippet I generated does not work!¶

The usual checklist for files in sudoers.d applies here:

If you are still having issues, a common problem is another rule matching last. Sudo reads rules in lexicographic order (i.e., not strictly alphabetical), but does not merge them, and the last matching rule wins.

You can verify ordering with visudo -c and find out which rule is matching last with:

sudo -l -U youruser /the/sudo/command --and --args

and compare with the output of sudo -ll to see which rule matched vs which was expected.

You can find which exact command exosphere is trying to run in the Providers <> documentation.

A quick workaround for ordering issues is to just name the generated snippet with a prefix that ensures it is loaded and matched last, for instance:

/etc/sudoers.d/zz-exosphere

After upgrading to 3.0, my old shell completion misbehaves¶

Exosphere can install tab-completion for zsh, bash and fish with:

exosphere --install-completion

Versions prior to 3.0 generated completion differently (via Typer) and wrote the scripts to different locations. Re-running --install-completion installs the new script alongside the old one rather than replacing it, so the stale files from the previous version are left behind.

For all cases except PowerShell, the new completion takes precedence and the leftovers are harmless, but it is cleanest to remove them. If a stale script ever did take precedence, it would try to run exosphere at completion time and drop into the interactive REPL, appearing to hang your shell.

To clean up the previous version's files:

Attention:

notepad $PROFILE

Import-Module PSReadLine
Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete
$scriptblock = {


    param($wordToComplete, $commandAst, $cursorPosition)


    $Env:_EXOSPHERE_COMPLETE = "complete_powershell"


    # ... several lines referencing exosphere ...
}
Register-ArgumentCompleter -Native -CommandName exosphere -ScriptBlock $scriptblock

Before reaching out¶

Common issues are already covered in the following places:

It is worth a quick pass through both --- the answer is often there, and if it is not, the steps you already tried are exactly what helps someone help you.

Asking a question¶

For usage questions, "how do I...", ideas, or just to share what you have built, use GitHub Discussions <https://github.com/mrdaemon/exosphere/discussions>. This is the best place for anything that is not clearly a bug.

Reporting a bug¶

If you have found a bug, please open an issue using the bug report form <https://github.com/mrdaemon/exosphere/issues/new/choose>.

To make it actionable, include as much of the following as you can:

$ exosphere version check

For problems with updates or repository sync on a specific platform, the Providers <> page lists the exact commands Exosphere runs --- running the failing one by hand on the remote host and including its output is incredibly helpful.

Feature requests and ideas¶

Suggestions are welcome. Open a discussion on GitHub Discussions <https://github.com/mrdaemon/exosphere/discussions>, or an issue via the bug report form <https://github.com/mrdaemon/exosphere/issues/new/choose> --- whichever feels more appropriate. If you have built something neat on top of Exosphere's Reporting and JSON Export <> (a dashboard, a bot, a coffee-brewing cron job), we would love to hear about it.

Debian/Ubuntu (Apt)¶

The Debian/Ubuntu provider is implemented in the exosphere.providers.debian module.

Repo sync requires sudo privileges, as it needs to run apt-get update to update the package cache from repository.

By default, given the stock Sudo Policy <#default-sudo-policy-option>, in Exosphere, Repo sync will not run for Debian-like hosts, and you will need to configure sudoers appropriately before changing the Sudo Policy.

Updates retrieval is done using apt-get dist-upgrade in simulation mode, and does not require elevated privileges.

Pending reboot detection checks for the presence of /var/run/reboot-required, which the system creates after applying updates that need a reboot to take effect (such as kernel or libc upgrades). This does not require elevated privileges.

Exact Commands run on remote hosts¶

Command dependencies¶

RedHat-Likes (Yum/DNF)¶

The RedHat provider is implemented in the exosphere.providers.redhat module.

It implements the functionality identically between Yum and DNF, as they share an interface for the relevant commands. The only distinction is the command name.

Internally, using Yum as a provider wraps Dnf, but with a different command name.

Repo sync does not require sudo privileges, as it runs yum/dnf makecache as the connection user to retrieve the information.

Updates retrieval is done using yum/dnf check-update, and does not require elevated privileges.

Pending reboot detection uses needs-restarting -r, which reports whether a reboot is recommended following kernel or core library updates, and does not require elevated privileges. The exact invocation depends on the backend:

If the command or plugin is unavailable, the reboot status is reported as unknown rather than failing the refresh, making this feature entirely optional.

Exact Commands run on remote systems¶

Note:

Command dependencies¶

Usage Notes and Issues¶

Some minor limitations:

In some scenarios, the yum or dnf commands may hang when running due to unexpectedly prompting for user input interactively, which Exosphere cannot handle.

The provider is written to avoid this, but if you do encounter this, simply run dnf makecache --refresh or yum makecache --refresh manually on the remote system and answer any prompts that may appear.

Once that is done, you should be able to run Exosphere commands without issues.

Note that we consider having to do this a bug, and would appreciate if you could file a bug report <https://github.com/mrdaemon/exosphere/issues>.

FreeBSD (Pkg)¶

The FreeBSD provider is implemented in the exosphere.providers.freebsd module. It uses the pkg command to manage packages and updates.

Repo sync requires sudo privileges, as it needs to run /usr/sbin/pkg update to update the package cache from repository, as well as refresh vuln.xml for use by pkg audit.

This also means you will need to have the sudo package installed on the remote system if you want to use this functionality. Unfortunately, doas is not supported at this time.

By default, given the stock Sudo Policy <#default-sudo-policy-option>, in Exosphere, Repo sync will not run for FreeBSD hosts, and you will need to configure sudoers appropriately before changing the Sudo Policy.

Alternatively, you can run /usr/sbin/pkg update via a cronjob or similar mechanism to keep the repository information up to date without having to configure sudo privileges for Exosphere.

Updates retrieval is done using pkg upgrade in simulation mode, and does not require elevated privileges.

Pending reboot detection compares the installed kernel version (freebsd-version -k) with the running kernel (freebsd-version -r). A mismatch indicates a kernel update that has been installed but not yet booted. This is intentionally kernel-only, and does not require elevated privileges.

Exact Commands run on remote systems¶

Command dependencies¶

OpenBSD (pkg_add)¶

The OpenBSD provider is implemented in the exosphere.providers.openbsd module. It uses the pkg_add command to manage packages and updates.

Repo sync is essentially a no-op, as OpenBSD does not have a command to synchronize package repositories. The command being run will directly query package mirrors on demand, and maintains no cache.

Updates retrieval is done using pkg_add -un, and does not require elevated privileges.

Branch detection is done using syspatch -l, which is in turn used to determine whether updates should be considered security updates or not. This does not require elevated privileges either.

Pending reboot detection is not implemented for OpenBSD, as it does not really provide any useful tooling around this.

Additionally, as the provider only handles binary packages and not syspatch or system updates, reboot status is always reported as unknown.

Limitations¶

Exact Commands run on remote systems¶

Command dependencies¶

inventory¶

Inventory and Bulk Operations Commands

Commands to bulk query, discover and refresh hosts in the inventory. Most commands accept an optional list of host names to operate on.

status is the primary command to display the current state of hosts in the inventory.

discover¶

Detect and gather platform information for hosts

inventory discover [ARGS...]

On a fresh inventory start, this needs to be done at least once before operations can be performed on the hosts. It can also be used to refresh this information if it has changed, or if a new provider has been added to Exosphere.

The discover operation will connect to the specified host(s) and gather their current state, including Operating System, flavor, version and pick a Package Manager implementation for further operations.

Arguments:

refresh¶

Refresh the state and update data for hosts

inventory refresh [OPTIONS] [ARGS...]

Connects to hosts in the inventory and retrieves pending package updates.

If --discover is specified, the platform information (Operating System flavor, version, package manager) will also be refreshed. Also refreshes the online status in the process.

If --sync is specified, the package repositories will also be synchronized remotely.

Synchronizing the package repositories involves invoking whatever mechanism the package manager uses to achieve this, and can be a very expensive operation, which may take a long time, especially on large inventories with a handful of slow hosts.

By default, only the progress bar is shown during the operation. If --verbose is specified, the name and completion status of each host will be shown in real time.

Arguments:

Parameters:

ping¶

Check connectivity and online status of hosts

inventory ping [ARGS...]

Attempts to connect to all hosts in the inventory. On failure, the affected host will be marked as offline.

You can use this command to quickly check whether or not hosts are reachable and online.

You can also invoke this command to explicitly refresh the Online status of hosts in the inventory.

The connectivity check is based on SSH reachability, and the criteria for a host being considered online is "ready to execute commands via SSH".

Arguments:

status¶

Show inventory hosts and their status

inventory status [OPTIONS] [ARGS...]

Display a nice table with the current state of all the hosts in the inventory, including their package update counts, their online status and whether or not the data is stale.

Output can be filtered to show only hosts with pending updates (--updates-only) or only those with pending security updates (--security-only). These two filters are mutually exclusive.

Output can also be sorted by any column with --sort, optionally reversed with --reverse. Sorting by 'version' groups hosts by flavor first, since versions are not comparable across flavors.

When sorting by any column other than name, hosts with unknown or unsupported values for that column will be grouped together at the end.

Use --full to include extra columns, such as the host description.

No matches when filtering will exit with code 3.

Arguments:

Parameters:

Filtering Options:

Sorting Options:

save¶

Save the current inventory state to disk

inventory save

Manually save the current state of the inventory to disk using the configured cache file.

The data is compressed using LZMA.

If options.cache_autosave is enabled, this will be automatically invoked after every discovery or refresh operation.

Since this is enabled by default, you will rarely need to invoke this manually.

This command is only available in interactive mode, as the inventory state is not persisted between separate CLI invocations when autosave is disabled.

clear¶

Clear the inventory state and cache file (reset state)

inventory clear [OPTIONS]

This will empty the inventory cache file and re-initialize all hosts from scratch.

This is useful if you want to reset the inventory state, or have difficulties with stale data that cannot be resolved.

Note that this will remove all cached host data, so you will need to re-discover the entire inventory after this operation.

Parameters:

host¶

Host Operations Commands

Commands to query, refresh and discover individual hosts.

show is the primary command to display the current state of a host in the inventory.

show¶

Show detailed state of a specific host

host show [OPTIONS] HOST

This command retrieves the host by name from the inventory and displays its details in a rich format on the terminal.

Arguments:

Parameters:

discover¶

Detect and gather platform data for a host

host discover HOST

This command retrieves the host by name from the inventory and synchronizes its platform data, such as OS, version and package manager.

Arguments:

refresh¶

Refresh the state and update data for a specific host

host refresh [OPTIONS] HOST

This command retrieves the host by name from the inventory and refreshes its state and available updates.

If --sync is specified, the package repositories will also be synchronized remotely.

Arguments:

Parameters:

ping¶

Ping a specific host to check connectivity and online status

host ping HOST

The ping status is based on ssh connectivity, and will update the host's online status in the inventory accordingly.

Arguments:

connections¶

Connection State Management Commands

Commands to inspect the state of SSH connections to inventory hosts. These commands are only useful when SSH Pipelining is enabled, otherwise no persistent connections to hosts are maintained.

Only useful from Interactive Mode, as connections are not maintained between separate CLI invocations.

show¶

Show SSH connection state for inventory hosts

connections show [OPTIONS] [ARGS...]

Display the current SSH connection state for specified hosts, or all hosts if none are specified.

Connections that have been idle for longer than the configured maximum age will be marked as "Expiring".

Only useful when SSH Pipelining is enabled, and exclusively from interactive mode, as connections are not maintained between individual CLI invocations.

Arguments:

Parameters:

close¶

Close SSH connections explicitly

connections close [OPTIONS] [ARGS...]

Close SSH connections to specified hosts, or all hosts if none are specified.

Only useful when SSH Pipelining is enabled, and exclusively from interactive mode, as connections are not maintained between individual CLI invocations.

Arguments:

Parameters:

ui¶

Start the Exosphere User Interface

Launches the Text-based User Interface (TUI). When started from interactive mode, quitting the UI returns you to the prompt.

Takes no arguments; the 'start' subcommand is an alias kept for backward compatibility with older versions of Exosphere.

start¶

Start the UI (compatibility alias)

ui start

This subcommand is kept for backwards compatibility with older versions of Exosphere, to preserve the muscle memory of users who have relied on it since 1.0.0. It simply launches the UI, exactly like invoking 'ui' with no arguments.

configuration¶

Configuration-related Commands

Commands to inspect or modify the currently loaded configuration.

show¶

Show the current configuration

config show [OPTIONS] [ARGS]

Displays the current configuration options, or the value of a specific option if specified.

If --full is specified, it will show the entire configuration structure, including the inventory, beyond just the "options" section.

Arguments:

Parameters:

source¶

Show the configuration source, where it was loaded from

config source [OPTIONS]

Displays the path of the configuration file loaded, if any, and any environment variables that affect the configuration.

Parameters:

paths¶

Show the paths of application directories

config paths

Will display the platform-specific filesystem paths that exosphere uses for configuration, state, logs, and cache.

diff¶

Show the differences between the current configuration and the defaults

config diff [OPTIONS]

Exosphere follows convention over configuration, so your configuration file can exclusively contain the options you want to change.

This command allows you to see exactly what has been changed, optionally in its context, using the --full option.

For a full config dump, use the show command instead.

Parameters:

edit¶

Open the current configuration file in an editor

config edit [OPTIONS]

Launches your text editor against the currently loaded configuration file. If no configuration file is loaded, the default platform path is opened instead, letting you create one from scratch.

The editor to use is determined from the editor configuration option and then falls back to the VISUAL and EDITOR environment variables, then finally, a platform default.

Changes do not affect the running process; they take effect on next startup. After editing, the file is validated and, if invalid, you are offered the chance to re-open the editor and fix it.

Parameters:

report¶

Reporting Commands

Commands to generate reports about the current state of the inventory. Allows exporting the state of the inventory to various formats, including JSON for use in other tools or custom reporting.

generate¶

Generate a report of the current inventory state

report generate [OPTIONS] [ARGS...]

The report can be generated in various formats, including html for for a pretty self-contained document, json for easy integration with other tools, or plain text for human readability.

The report can also be filtered to include only specific hosts by providing their names as arguments. If no hosts are specified, the report will include all hosts in the inventory.

It can further be narrowed to hosts with pending updates (--updates-only) or pending security updates (--security-updates-only), which are mutually exclusive.

Note: Undiscovered or unsupported hosts are excluded from the report.

Arguments:

Filtering Options:

Output Options:

schema¶

Show or write the JSON Schema for the current version of Exosphere

report schema [ARGS]

Emits the JSON Schema (draft-07) describing the structure produced by report generate --format json, for the currently running version of Exosphere.

This allows anyone to easily get an overview of the structure, validate and integrate, offline, without a local source tree or access to the online documentation.

By default the schema is printed to stdout. Use --output to write it to a file instead.

Parameters:

status¶

Show a brief, condensed status summary of the inventory.

report status

Prints a short, executive-summary overview of the whole inventory: how many hosts have pending updates (and how many of those include security updates), how many are awaiting a reboot, and whether any host data has gone stale.

The output is plain and compact, suitable as an at-a-glance overview or for inclusion in a system MOTD (e.g. by redirecting it to a file).

Color is automatically dropped when the output is not a terminal.

Hosts that have not yet been discovered contribute nothing to the update and reboot counts, as they have no known state.

sudo¶

Sudo Policy Management Commands

Exosphere providers may require sudo privileges to execute certain operations on remote systems. These commands allow you to inspect, validate and generate suitable sudoers configurations.

Exosphere has a global Sudo Policy that dictates how operations requiring those privileges are handled (the default is to skip them).

Individual hosts may override the global Sudo Policy with their own Sudo Policy in the inventory configuration.

For more details, see the Sudo Policies and Privileges section of the Exosphere documentation.

policy¶

Show the current global Sudo Policy

sudo policy

This command will display the current global Sudo Policy in effect. Individual hosts may override this with their own Sudo Policy.

check¶

Check the effective Sudo Policies for a given host

sudo check HOST

The command will take in consideration the current global Sudo Policy and the host-specific Sudo Policy (if defined) to determine if the host can execute all of its Package Manager provider operations.

Arguments:

providers¶

Show Sudo Policy requirements for available providers

sudo providers [ARGS]

Some providers require sudo privileges to execute certain operations. You can use this command to enumerate these requirements, if applicable.

Arguments:

generate¶

Generate a sudoers configuration for passwordless operations

sudo generate [OPTIONS]

Creates snippet suitable for /etc/sudoers.d/* on target systems.

Will use username from host configuration, global configuration, or current user if not specified.

Outputs to stdout, can be redirected to a file.

Parameters:

Target:

(Required, Mutually Exclusive)

version¶

Version and Update Check Commands

Show current version, check for updates.

details¶

Show detailed version and environment information

version details

Displays the currently installed version along with Python version, virtual environment status, and operating system details.

check¶

Check for exosphere updates

version check [OPTIONS]

Compares the current installed version with the latest version available on PyPI and reports if an update is available.

Exits with code 3 if an update is available.

Parameters:

3.0.0 - Reboots, Palettes, Sorting and refreshed CLI¶

The first major version release actually backed by a major set of changes. This release lands several long overdue features, refactors a lot of internals, swaps out the entire CLI engine and provides a much more polished help and documentation experience.

It has been cooking for a while, and the release notes are correspondingly long. Most of these changes are transparent, but there are some unavoidable incompatibilities. Make sure to read User Actions Required and Incompatible Changes before upgrading.

Feature Highlights¶

Pending Reboot Detection¶

[image: image] [image]

Exosphere can now tell you when a host is waiting on a reboot to finish applying updates --- a running kernel that no longer matches the installed one, a distro's reboot-required flag, and so on.

This is another feature grown out of a question that comes up frequently when managing updates across a fleet of hosts: "Has everyone been rebooted?". It felt only natural for Exosphere to attempt to answer that question.

This is presented in several places across the application interfaces:

The feature is implemented for all supported platforms where this information is available (Debian/Ubuntu, RHEL and derivatives, FreeBSD) and is entirely best-effort. None of the reboot checks require elevated privileges, so there is no sudoers change. If a provider cannot determine the status --- a missing tool, an unexpected error --- it is simply reported as unknown rather than failing the operation, so it will never block you from doing anything else.

TUI Command Palette Operations¶

For a long time the only way to perform targeted operations on a specific host was to use the CLI host commands, or specify hosts in bulk inventory operations.

The TUI was previously limited to bulk operations, and on specific screens.

To resolve this, the TUI now makes use of the command palette (Accessible via Ctrl+P) to allow you to run any of the host operations (sync, refresh, ping, etc) from any screen, and targeting any host.

[image: image] [image]

Selecting hosts also conveniently presents as a fuzzy search list, making the whole process light in keystrokes, and high in discoverability.

[image: image] [image]

The palette will also preselect the currently highlighted host in the Inventory screen, further lubricating the process.

[image: image] [image]

The palette and its operations can be invoked from any screen, and with this, there is finally functional parity between the CLI and TUI for host operations.

Inventory Sorting¶

[image: image] [image]

[image: image] [image]

Inventories can now be sorted, in both the CLI and the TUI.

Undiscovered and unsupported hosts always sort last, so the interesting hosts stay at the top regardless of the chosen field.

Reworked Built-in Help and CLI Polish¶

Exosphere has swapped out its CLI framework internals, and with that came the perfect opportunity to give a polish pass to the built-in help system.

[image: image] [image]

Multiple help panels, especially for the most complex commands like sudo or report, have been rewritten to be more helpful, explain what they do, and most importantly, group their copious options and flags into logical, meaningful sections.

[image: image] [image]

Additionally, unknown commands or verbs will now display a helpful message, with fuzzy suggestions for what you might have meant, leading to a friendlier experience when exploring the CLI or REPL.

The CLI engine change also brings a lot of internal improvements and better behavior for both the CLI and REPL.

New Commands¶

A few small but helpful new commands have been added:

All of these are documented more extensively in the Command Line Interface (CLI) <> docs as well as the Reporting and JSON Export <> docs.

The Web UI has been removed¶

It had always been more of an experimental curiosity than a real feature, and had not been actively developed since 1.0.0. Newer features (such as instance/cache locking) had begun to clash with it, and on balance it had become more of a maintenance burden than a useful capability.

As a result:

See the User Actions Required section for details.

Other Improvements¶

Bugfixes¶

Exosphere¶

Providers¶

User Actions Required¶

Shell completion must be reinstalled. The new CLI engine generates completion differently, so re-run exosphere --install-completion to install the updated scripts. On everything except PowerShell the new scripts take precedence and the old ones are harmless leftovers. If you do not use the shell completion feature at all, you have nothing to do. If you would like to remove the old scripts, see the FAQ <#faq-completion-upgrade> for the full details.

PowerShell completion is no longer supported and its leftovers must be cleaned up by hand, unfortunately, as there is no way around it. See the FAQ <#faq-completion-upgrade> for the full details and cleanup steps.

Web UI has been removed. The ui webstart command and the web install extra no longer exist. If you installed Exosphere as exosphere-cli[web], drop the [web] extra from your install. Existing installations will automatically resolve this on their own during upgrade, so there is no need to reinstall. Use the TUI instead, which is now the default ui command.

Incompatible Changes¶

Project and Documentation¶

What's Changed¶

2.4.3 - Hotfix Release¶

Released May 28, 2026

This optional hotfix release constraints a dependency (Typer) to a specific version to ensure compatibility and prevent runtime breakage, especially when exosphere is installed or updated via pipx. This is due to an upstream change in Typer <https://github.com/fastapi/typer/releases/tag/0.26.0>.

2.4.2 - Bugfix Release¶

Released April 14, 2026

An additional bugfix release containing some more pressing fixes before we embark on the 2.5 series where new features will land.

Bugfixes¶

Minor Features¶

The Documentation <> is written with Sphinx, and used a visual theme that has been declared as unmaintained. It also has a history of friction with versions of sphinx >=9. It has been removed and replaced with sphinx-rtd, alongside a custom CSS override that has been written to replicate the original look and feel. Additional enhancement to code boxes, syntax highlighting and general layout were also added. This also allows us to further customize the look and feel in the future.

What's Changed¶

2.4.1 - Red Hat Provider Bugfix Release¶

Released April 06, 2026

Minor point release including a refactor and streamlining of the Red Hat dnf/yum Provider, as well as correction of two bugs, while work is being done on the upcoming 2.5 release.

Red Hat provider Refactor¶

Handling of kernel packages no longer hinges on manual resolution to work around vendor-specific kernel repositories having odd configurations in some environments. This mostly affected certain cloud platform images with misconfigured repositories.

This streamlining resolves a handful of bugs, and also massively improves performance on Red Hat-like systems by no longer having to do expensive rpm database queries, sometimes twice.

Bugfixes¶

What's Changed¶

2.4.0 - Sudo, FreeBSD vuln.xml improvements¶

Released March 10, 2026

A minor update that resolves two annoyances:

It gets a minor version bump due to user-facing configuration changes, detailed in the next section.

User Actions Required¶

The minor change to the FreeBSD provider implies a change to sudoers configuration. The reposync operation, which runs through sudo, now also runs /usr/sbin/pkg audit -qF as part of the process.

If you have FreeBSD hosts with a sudo policy of NOPASSWD within exosphere, you will need to update or regenerate your sudoers configuration.

This can be done very simply via exosphere sudo generate. Failure to do so will result in an error message that will point you to the documentation on how to configure this <#generating-a-sudoers-configuration>.

If you use SKIP (the default) as a sudo policy, or do not have FreeBSD hosts in your inventory, no action is required.

What's Changed¶

2.3.0 - Maintenance Release¶

Released February 19, 2026

It is time for a periodic maintenance release, with mostly a fix to the json output, some internal library and dev tools upgrades, as well as a bunch of minor documentation improvements.

New "stale" field in json export¶

Previously, json format exports in reporting module did not include whether or not Exosphere considers the host stale according to its configuration.

A "stale" boolean field has been added to both the to_dict() method on Host objects as well as the expected json schema. The documentation now covers this as well.

This has been a long standing oversight, since every other reporting format actively includes this information, and consumers of the json data should not have to do date math to figure out that information.

Since it is an addition to the schema, the change is backwards compatible.

Documentation improvements¶

What's Changed¶

2.2.0 - SSH Pipelining and Spring Cleanup¶

Released January 12, 2026

A polish pass and a feature¶

This release contains a hot new feature and a polish pass on the entire codebase, refactoring a lot of internal code that was either sub-par, or naively designed for simpler times back in 1.0, and had not been revisited since.

It's not spring, but spring cleaning is a state of mind, unbound to such trivial things as calendars.

New Feature: SSH Pipelining¶

[image: image] [image]

A new opt-in configuration setting <#ssh-pipelining-docs> now allows you to leave SSH connections open between operations in Interactive (REPL) or TUI mode, which will allow Exosphere to reuse them, reducing connection open/close churn, and improving performance on larger inventories, or setups where the ssh negotiation part of the connection is particularly slow.

The connection will be closed after a configurable idle time <#ssh-pipelining-lifetime-option> that defaults to 300 seconds.

This comes with a new REPL command, connections which will display the current state of any connection currently held open by Exosphere, as well as let you manually close them if that is something you want to do.

By default, the pipelining feature is disabled and the previous Exosphere behavior of closing connections after each operation remains unchanged.

However, some minor batching and optimizations have been done in the dispatch and provider code to ensure there is significantly less connection churn, batching all queries related to a single operation (sync, refresh, ping etc) within the same connection. Performance should be improved in general, even with pipelining disabled.

The choice of which mechanism is preferable is left entirely to the user.

Internal refactoring and polish pass¶

A lot of the earlier code within Exosphere was designed around a much smaller, more naive ideal for how Exosphere should function. As the application grew and found its exact scope, a lot of these design decisions were mostly hacked around or left alone.

The primary one is the way the state cache (exosphere.db) is built and loaded. Several improvements have been done around the serialization machinery. The state of a Host object is now contained within a HostState dataclass that is easily serializable, with a proper version schema.

This allows us to ensure seamless migration of data between exosphere versions in a much cleaner way, replacing the series of horrifying serialization hacks we had previously to achieve this.

Migration to this new serialization format will be handled transparently by Exosphere, so there is no user action required. INFO level logs are produced on the initial conversion, but otherwise the cached state of your hosts should carry over.

Other than this, a lot of miscellaneous warts and unpleasant areas of the code that bothered the author for a while have been rewritten to be much, much nicer, with no user facing changes or differences. The UI code in particular had a lot of horrifying hacks removed, and duplicated code with subtle differences unified, resulting in a much cleaner code base.

Dependencies changes¶

Some runtime libraries had their version constraints changed, for compatibility or security reasons:

Bugfixes¶

What's Changed¶

2.1.2 - Optional hotfix¶

Released November 09, 2025

Optional Hotfix Release¶

Minor hotfix and minimum version bumps to accommodate Python 3.14 environments, specifically the optional web ui component of Exosphere.

Also contains internal changes to the CI jobs and test suite to prevent future regression and better test against minimum versions in pyproject to avoid the 2.1.1 issues.

No Exosphere code changes, purely metadata and dependencies, so this hotfix is entirely optional, but of interest if you:

What's Changed¶

2.1.1 - Hotfix¶

Released November 01, 2025

Hotfix Release¶

Minimum version of Textual as a dependency was incorrectly set, in some installations this can result in the Inventory screen crashing on access with Footer.__init__() got an unexpected keyword argument 'compact'

Bumps Textual dependency minimum to v6.2.0 to resolve the issue.

I blame the spooky Halloween ghosts.

👻 sorry my release was haunted sorry

2.1.0 - The Big Quality Release¶

Released November 01, 2025

Big Quality of Life Update¶

🎃 A spooky Halloween Release 🎃

This update contains multiple long standing QoL changes that I have been wanting to put in for a while. It is my hope that this makes the experience of using Exosphere more pleasant.

Let's go over the major ones:

TUI Inventory Screen Features¶

[image: image] [image]

Sync Repos as an action has been reworked into Sync & Refresh. When hitting ctrl+x, Exosphere will now do a repository sync followed by a refresh, as there was essentially no scenario in which you would just want a sync alone. This saves you the need to hit ctrl+r immediately after, as it will do it for you.

Filtering functionality on TUI Inventory Screen¶

[image: image] [image]

You can now hit ctrl+f to filter the inventory view to only display hosts with updates, or hosts with Security Updates exclusively. The CLI inventory command had this functionality for a while, and I strongly felt like the TUI one needed feature parity.

[image: image] [image]

A status bar has been added at the bottom of the inventory screen which will inform you whenever the view is filtered in any way.

Themes Support¶

Most of the Textual CSS and Colors within the Exosphere TUI have been reworked to use generalized colors that honor the selected Color Theme. So you can now fully swap to your favorite using the appropriate Palette command, and Exosphere will absolutely respect it.

TUI navigation improvement¶

The bottom footer with navigation keybinds no longer shows the keybind for the screen you are currently on. This conserves screen real estate significantly, and prevents the menu from being overwhelming.

Additionally, the inventory screen now switches the layout of the footer to a more compact one to ensure it is legible on smaller terminal sizes.

Before: [image: image] [image]

After: [image: image] [image]

REPL Improvements¶

In addition to a new shiny logo banner on startup (which can now be disabled <#no-banner-option>, if you don't share my eclectic tastes in ascii art), the REPL has seen massive improvements to its tab completion features.

Host Completion¶

Exosphere in interactive mode can now tab complete inventory hosts, either as positional or option arguments.

[image: image] [image]

This includes the expected readline-like double tab to show all possible matches features.

Better readline/shell-like completion flow¶

The Completion code has been refactored significantly to allow closer behavior to that of unix shells and readline in general. More specifically, trailing spaces are appended after matches, and options that do not take arguments (i.e. --sync) will simply tab through, allowing you to tab complete lines at blazing speed, in a context sensitive way.

What's Changed¶

2.0.1 - Hotfix Release¶

Released October 12, 2025

Small bugfix release¶

Fixes the issue described in #111 where exosphere version check would exit with 0 status when options.update_checks is disabled. Now properly exits with nonzero.

What's Changed¶

2.0.0 - CLI exit codes and Python 3.14 Support¶

Released October 11, 2025

Big number, small changes¶

Exosphere now uses consistent and documented exit codes across all of its CLI components. Since, strictly speaking, this is a backwards incompatible change (although it is unlikely to affect many people), the version has been incremented to 2.0.0 to communicate this, in accordance with the holy texts of Semantic Versioning.

Return Codes¶

Exosphere now consistently returns the following exit codes:

Using 2 for argument errors is a consistent behavior with the Typer library (which we use extensively for CLI commands) and multiple Unix utilities, such as grep.

Status 3 is used very sparingly, and so far only returned by exosphere version check to communicate that a new version is available, as well as by inventory status whenever any of its filtering options (--updates-only etc) do not match any hosts.

This is documented in our Lovely Documentation in its Appropriate Section <#return-codes>

Python 3.14 Compatibility¶

Python 3.14 is now officially supported with this release.

Internally, the test suite for Exosphere has been put in a Matrix that runs against both 3.13 and 3.14, to prevent regressions across supported versions. The uv lockfile has been updated with versions of main dependencies and dev tools that support both, but the minimum required versions have been left alone.

This should ensure compatibility between 3.13 and 3.14, and lays the groundwork to support upcoming versions without too much hassle.

New detailed version command¶

In order to make diagnostics and debugging easier, the version command now has a details subcommand that will return information about the current Python environment, venv, and host system.

What's Changed¶

v1.5.1 - Minor QoL Update¶

Released October 10, 2025

Minor point release introducing a small QoL improvement that is fully backwards compatible, as well as Python 3.14 uv housekeeping.

[image: image] [image]

Exosphere now has the ability to filter inventory status output with --updates-only and --security-only, and it feels weird that it didn't from day one.

Documented in the CLI section <#viewing-inventory-status>.

Additionally, the inventory being empty is now correctly considered an error case, and Exosphere commands will correctly return non zero exit when unable to perform their actions due to that scenario.

The lockfile for uv dependencies has been updated with a handful of dependencies that are either minor, or have explicit Python 3.14 support patches added in. We're preemptively adding them it for consistency and future compatibility tests.

1.5.0 - The Reporting Update¶

Released October 04, 2025

Exosphere can now generate reports¶

[image: image] [image]

If you ever felt it was weird that a patch reporting tool could not actually produce reports you can print, email or otherwise use outside of the application, this update will likely please you.

Exosphere now provides a report command which allows you produce document based reports in HTML, Plain Text and Markdown formats, which should hopefully cover most use cases.

The reports can be filtered to include only a selection of hosts, updates only, or security only, and have a wealth of useful options. Various in depth examples of the formats as well as copious details on usage can be found in our ever growing documentation <>.

Exosphere can now emit JSON with the current state¶

[image: image] [image]

As part of the same feature, we now have a nice JSON report format available for programmatic consumption of the data and inventory state. It is simply treated as an extra format the reporting module can handle.

This should be helpful if you ever wanted to integrate Exosphere into something else, or feed the data that it generates into something else, ranging from a Discord bot to your event system for your overly complex Doorbell over zigbee MQTT system.

It's also reasonably helpful for use with jq <https://jqlang.org/> to perform ad-hoc queries that Exosphere itself doesn't expose.

This feature is discussed in great detail, including a full definition of the JSON Schema, in our ever growing documentation <#json-schema>.

Version Check command¶

There is now a version command with a check subcommand that will query PyPI to tell you whether or not your version of exosphere is up to date, and provide you with links to release notes and upgrade documentation if relevant.

We do not have automatic checks on startup or anything of that nature, it is strictly on-demand. This feature can also be forcefully disabled via the relevant configuration option <#update-checks-option> if necessary for your environment.

Minor CLI improvements¶

[image: image] [image]

Changes in this Release¶

1.4.1 - Hotfix Release¶

Released September 14, 2025

This hotfix release corrects handling of the scenario where OpenBSD hosts can exclusively have packages installed that have never gotten any sort of update. This scenario is now checked early and handled gracefully instead of raising an exception in the provider.

What's Changed¶

1.4.0 - OpenBSD Support¶

Released September 13, 2025

Exosphere now fully supports OpenBSD as a remote platform¶

[image: image] [image]

The major feature in this release is the addition of a new PkgAdd provider, which targets OpenBSD remote systems. If you add OpenBSD systems to your inventory, discovery should enumerate them fully and you will be able to perform refresh actions on it, and obtain host details, just like any other supported remote Operating System.

Notes¶

If you already have OpenBSD hosts in your inventory , and they have been discovered as unsupported, that state will not automatically change. You must run exosphere inventory discover at least once after updating to 1.4.0 to have them fully setup and integrated into exosphere.

By default, on a release or stable install, all package updates are Security Updates, by definition, and will show up as such in Exosphere.

If you are running -current or -beta, the security status of package updates can't be ascertained and none of them will show up as security updates.

Special Thanks¶

Thanks to Solène (@solene@bsd.network) on the Fediverse for the helpful pointers regarding the specific semantics of package updates on OpenBSD

What's Changed¶

1.3.5 - Optional Documentation Hotfix¶

Released September 12, 2025

This completely optional releases updates the lockfile dependencies, and corrects a handful of minor issues in the project documentation.

No code changes.

What's Changed¶

1.3.4 - Provider reposync enhancements¶

Released September 08, 2025

This is a small release that changes a few behaviors for reposync in providers that require sudo privileges.

The second change should have no impact on your systems, and the change is reflected in the documentation <>.

The first change however may need some configuration adjustments, if you want to opt into the new feature.

FreeBSD Provider Changes (potential actions required)¶

Previously, the FreeBSD provider's reposync method was basically a no-op, and did nothing. If your sudo policy <> (either globally or local to freebsd hosts) is skip (which is the default), nothing changes, and you can continue using the software as-is if you are happy with the behavior.

If you have a global policy set to nopasswd, ensure your FreeBSD systems have sudoers configured for Exosphere. You should configure this either way if you wish to be able to perform a repository sync (^x in the ui, or refresh --sync in the cli) on FreeBSD hosts.

This is not mandatory, and you could instead elect to run pkg update -q via a cron or periodic job on the systems to ensure repository freshness.

Documentation regarding this procedure is available <#generating-a-sudoers-configuration>.

Why the late change?¶

Previously, the FreeBSD provider worked on the assumption that the upgrade process synchronized repositories automatically during updates/upgrades -- which it does. However, this does not actually occur in the simulation mode we use to query available updates on the systems.

Given the presence of the sudoers policy system, and the fact that doing nothing maintains the existing behavior, I've elected to make an actual reposync available on FreeBSD hosts, as an incremental fix.

What's Changed¶

1.3.3 - FreeBSD Bugfix Release¶

Released September 04, 2025

This is a bugfix release containing fixes for the FreeBSD package manager provider in Exosphere.

Recent versions of pkg(7) on FreeBSD 14 now include the Repository tag in brackets in the output of packages, which broke parsing due to where it was inserted. This would cause no updates to ever be shown on affected systems.

This bugfix adds support for the output format of newer pkg versions, while still retaining compatibility with older versions. Parsing has been made slightly more defensive to minimize the chance of future issues.

Additionally, since we now have access to the repository name metadata, we now correctly report it in Exosphere. If the version of pkg on the target system does not report it, the previous "Packages Mirror" value will continue to be used.

Additional changes¶

Minor dependencies updates in lockfile

Dependencies:

Transitive (deps of deps):

Internal/Dev:

1.3.2 - Bugfix Release¶

Released August 30, 2025

This release is a bugfix release correcting issues in the discovery process and redhat providers for Fedora systems and dnf5.

What's Changed¶

1.3.1 - Optional Hotfix¶

Released August 24, 2025

Version 1.3.1 is comprised mostly of obvious documentation fixes (mostly spelling, typos and grammar). An editing pass has been done over comments and docstrings as well.

The uv lockfile has also been updated with a few dependencies updates.

This hotfix is entirely optional, and contains no actual code changes beyond updated dependencies if you install Exosphere via uv tool.

What's Changed¶

1.3.0 - Supporting the Unsupported Release¶

Released August 20, 2025

Exosphere now supports keeping unsupported hosts in the inventory¶

[image: image] [image]

The main major feature of this release is the ability to add unix-like systems that do not have a package manager Provider available to the inventory. This allows the connectivity checks to function, and the hosts to show up on the dashboard, but you will not be able to perform package refresh and repository syncs on them.

A recurring piece of user feedback has been the expectation that unsupported hosts in the inventory that pass the Online check should not suddenly turn Offline when the discovery process identifies them as unsupported. This feature update now resolves this, and we now officially support this scenario! The UI (cli commands and TUI both) will properly accommodate them as well, marking them explicitly as unsupported, and will not attempt to display Update counts or stale indicators for them.

Note that this is still limited to Unix-like, or at least Reasonably POSIX Compliant hosts. Other proprietary platforms where SSH is available (i.e. Network equipment, Windows hosts with sshd that does not lead to WSL, etc) will simply not be supported at all, and the discovery process will report them as such, encouraging you to remove them from the inventory.

Upgrade Notes¶

There are two important notes if you are upgrading from 1.2.0 or earlier:

New Features¶

Bugfixes¶

Misc¶

1.2.0 - The Reactive UI release¶

Released August 04, 2025

The dashboard is now fully reactive¶

The grid of hosts will now adjust itself, dynamically changing its amount of columns to optimally present the contents in varying terminal sizes.

Additionally, much of the presentation code has been rewritten to use a nice hierarchy of labels, making maintaining the position of the online status line across tiles with different contents much easier. The result should be a much more consistent display, even when the terminal is resized.

UI Logs¶

The UI logs screen has also gotten a coat of fresh paint with a custom Formatter that now presents the information in a much more helpful way. Additionally, multiple modules repeated the same host exceptions at INFO level. Most of these have been moved to DEBUG, since they are not particularly helpful at runtime for users.

This should make for a much more pleasant experience when trying to figure out what the error was on any of the UI Screens.

What's changed¶

1.1.0 - The Fancy CLI Release¶

Released August 01, 2025

[image: image] [image]

After spending the last weeks before 1.0 polishing up the TUI, the Interactive command line interface was in dire need of some love. At the center of this release is a brand new, improved interactive CLI component and improved error reporting.

Highlights¶

A brand new REPL Module¶

Previously, the interactive shell, or REPL for Exosphere was provided by a quick hack around click_shell, in order to get the hierarchy going quickly. The experience it provided wasn't up to scratch, and functionality depended on platform. Not to mention, a bunch of horrifying compatibility hacks were added to ensure basic feature parity on Windows.

All of this has been completely replaced with a brand new, purpose built REPL module! Some exciting features include:

Much Improved error reporting¶

The discover command, both at inventory and host level, will now clearly report authentication issues, allowing for a much smoother first experience when adding hosts to the inventory. Apologies to people who had to look at the logs previously and furrow their brows at less than useful error messages written in SSH Library Speech.

The documentation has also been refreshed to cover this very topic, which hopefully should make onboarding much smoother.

Dependency Slimming¶

The Web UI component of Exosphere is mostly experimental, and more of a curiosity than Generally Helpful, and burdening every install with its large stack of dependencies felt rude, so it has been made completely opt-in.

By default, it will not be installed, but you can very easily add it back by installing exosphere-cli[web], as an extra.

Finally, on a personal note, seeing other people get use out of my silly little piece of software has brought immense joy to my cold, bitter, industry veteran heart. If you sent any sort of experience report, thank you. If you didn't, thank you all the same. <3

What's Changed¶

1.0.1 - Bugfix release¶

Released July 29, 2025

It's been very nice to see other people enjoy Exosphere, and so here is a bugfix release to celebrate!

What's Changed¶

1.0 - Initial Public Release¶

Released July 26, 2025

First Public Release¶

I've been working on this tool for quite a while now, and I am feeling comfortable enough with the state it is in to release it in the wild. Hopefully it is helpful to others, because I quite enjoyed writing it, and I'm enjoying using it even more.

Initial Pre-Release¶

Released July 05, 2025

This initial build was pushed to PyPI as a preview, and to validate documentation and processes.

It probably isn't suitable for human consumption, but can be installed.

Exosphere configuration¶

The configuration module in Exosphere is wildly flexible, allowing you to essentially provide your configuration structure in any format you'd like.

At runtime, the effective, current configuration structure is accessible through exosphere.app_config, which will always contain (at the very least) the default values defined in the Configuration.DEFAULTS dict.

Package Manager Provider API¶

This document provides an overview of the API used internally by Exosphere to implement package manager providers.

A package manager provider is a Python class that implements the low level API for a specific package manager. It is generally responsible for connecting to the host, querying available package updates, parsing that list and returning Update objects that can be used to populate state.

Implementing a new provider requires creating a new class under exosphere.providers that inherits from the base provider class exosphere.providers.api.PkgManager.

This class should implement the methods and members below.

Providers API

This module defines the abstract base class for package managers as well as helper functions and decorators to be used by package manager provider implementations.

SUDOERS_COMMANDS = [


    "/usr/bin/apt-get update",


    "/usr/bin/something-else --with-args -o option=value",
]

Data Classes¶

The core objects used by Exosphere are mostly Host and Update objects.

Host is the high level object, providing functionality to interact with the host and perform operations on it, such as discovery or refreshing package updates.

The only mandatory fields for a Host are defined by the HostInfo dataclass, listed below.

Exosphere objects¶

The primary low level objects used by Exosphere are Host and Inventory objects.

They provide the main functionality to interact with the hosts and perform operations on them.

Reporting Interfaces¶

The exosphere.reporting module provides interfaces for generating reports in various formats, including HTML, Markdown, and plain text. It leverages the Jinja2 templating engine.

It is also responsible for returning the JSON representation of Host objects.

Reporting module

This module provides functionality to render reports in various formats using Jinja2 templates.