Installation

Requirements

Octory 3.1.0 and higher requires macOS 26 and higher. The whole interface has been rebuilt on modern native APIs, and earlier versions of macOS are no longer supported.

warning

If part of your fleet still runs an earlier version of macOS, keep deploying Octory 3.0.3 there. Scope the 3.1.0 package to macOS 26 devices in your MDM before rolling it out.

Download Octory

Octory comes in different shapes and flavors. For more flexibility during deployement, we offer three choices when it comes to Octory.

• Octory (.pkg)
• Octory with Launch Agent (.pkg)
• Octory standalone (.app)

All packages are included in the zip file which can be grabbed from Octory's download page.

tip

We recommend using Octory's main package as it installs all necessary files in the system, including the Helper and the command-line tool Octo-Notifier.

If you want to have full control over what is installed, we suggest looking at Creating an Octory bootstrap package.

warning

Octory packages do not come with a pre-configured configuration file. If you try to launch the app after installing the package, the application will fail to launch.

Create your configuration file

Now that Octory is installed, you should have a folder named Octory in /Library/Application Support.
Copy the blank configuration file inside the created folder and rename it Octory.plist.

warning

The final path should be the System's Library /Library/Application Support/Octory/Octory.plist
NOT the User's Library ~/Library/Application Support/Octory/Octory.plist

Octory.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Admin</key>
	<dict>
		<key>IsAdminModeEnabled</key>
		<true/>
	</dict>
	<key>Slides</key>
	<array>
		<dict>
			<key>Containers</key>
			<array>
				<dict>
					<key>Components</key>
					<array/>
				</dict>
			</array>
		</dict>
	</array>
	<key>Window</key>
	<dict>
		<key>OnScreen</key>
		<string>Simple</string>
	</dict>
</dict>
</plist>

Permissions

Give the proper permissions to our config file.

sudo chown "`whoami`":admin Octory.plist
sudo chmod 644 Octory.plist

tip

If you do not want to start from a blank configuration file, we have created ready-made examples which can be found in the examples folder of our public GitLab to rapidly get started with the application.
To use one, copy and paste the example's folder you want to use inside /Library/Application Support/Octory/.

Launch the App

By default, the application will look for a configuration file named Octory.plist in /Library/Application Support/Octory/ or /Library/Managed Preferences/. You have two possibilites when it comes to launching the app.

cd /Library/Application\ Support/Octory
open Octory.app

OR

/Library/Application\ Support/Octory/Octory.app/Contents/MacOS/Octory

tip

The second command will launch Octory and display the logs in real time in the terminal. It is very useful when debugging or building your workflow.

Launch Octory with a specific config file

You can choose to launch Octory with a specific configuration file by launching it with the configuration argument: -c or --config.

For example, if you pushed via your MDM a custom profile named custom-octory-config.plist, it will be placed inside /Library/Managed Preferences/. You can then launch Octory with that custom profile using:

/Library/Application\ Support/Octory/Octory.app/Contents/MacOS/Octory --args -c custom-octory-config.plist

Another example, if you used an OctoryTest.plist file in /Library/Application Support/Octory/Configs.

open Octory.app --args -c Configs/OctoryTest.plist

note

If your custom Octory config is in a subfolder, watch out for spaces in the path.

If you previously downloaded the preset folder, you would simply have to run the following command:

open Octory.app --args -c Presets/PRESET_FOLDER_NAME/Octory.plist

Since Octory 3.1.0, the argument also accepts an absolute path, so the configuration file no longer has to live inside /Library/Application Support/Octory.

open Octory.app --args -c /Users/Shared/Octory/Enrollment.plist

info

The .plist extension is added for you if you omit it. You can also chain a second configuration when the application terminates, with the NextConfigurationPath key.

Change the default configuration file

When using the -c or --config option, you can add the --save flag to overwrite the default configuration file.

open Octory.app --args -c Configs/OctoryTest.plist --save

Next time you launch the app, if you do not specify a configuration file, the saved one will be used rather than the default Octory.plist file.