Install Community Edition on macOS

1. 1

   Choose the macOS server installer

   Open /download and select the recommended macOS arm64 DMG under Server Community Edition. The raw PKG is also available for administrators and managed deployment. Neither artifact supports Intel Macs.

2. 2

   Compare its SHA-256

   Open Terminal in the download folder, run shasum against the exact DMG or PKG, and compare the complete value with the SHA-256 shown for that filename on /download.

3. 3

   Check the Apple signature

   Use hdiutil and spctl for the recommended DMG, or pkgutil for the raw PKG, before opening the installer.

The commands below are verification templates. Replace <VERSION> with the version in the exact filename shown on /download.

DMG="./Orchestris-Server-CE-<VERSION>-macos-arm64.dmg"
test -f "$DMG"
shasum -a 256 "$DMG"
hdiutil verify "$DMG"
spctl --assess --verbose=4 --type open "$DMG"

PKG="./Orchestris-<VERSION>-macos-arm64.pkg"
test -f "$PKG"
shasum -a 256 "$PKG"
pkgutil --check-signature "$PKG"

1. 1

   Open the graphical installer

   For the recommended path, open the verified DMG and double-click Orchestris Server CE Installer. For the raw-package path, double-click the verified PKG. Follow Installer and approve the installation when macOS asks; both paths install the complete release under /Applications/Orchestris.

2. 2

   Open the installed Orchestris app

   Launch /Applications/Orchestris/Orchestris.app as the macOS account that will operate the server. The app stores that user's database, settings, setup state, and logs in the user's Library folder.

3. 3

   Complete the detected setup path

   A fresh installation asks for the organization, administrator email and password, API bind address and port, Admin port, and public API origin. An existing installation shows an upgrade-preservation step and reuses its credentials, configuration, and data. Interrupted first setup resumes safely.

The package payload is installed under /Applications/Orchestris, while initialization and normal operation remain per-user. Open the app without sudo from the same macOS account each time.

open "/Applications/Orchestris/Orchestris.app"

The default is this Mac only on 127.0.0.1:8080, Admin at http://127.0.0.1:3000, and public API origin http://127.0.0.1:8080. Successful setup creates orchestris.env and orchestris.db under ~/Library/Application Support/Orchestris and starts both components.

1. 1

   Open the Orchestris menu

   Select the Orchestris menu-bar icon. Show Orchestris displays component health and the current setup state; Open Chat and Open Admin open the local applications.

2. 2

   Control both components together

   Use Start, Restart, or Stop from the menu. The app supervises API and Admin as one Community Edition installation and reports a component-specific failure when either one cannot start.

3. 3

   Choose normal startup behavior

   Enable Start at Login from the menu if this user should start Orchestris automatically after signing in. Leave it disabled when you prefer to start the app manually.

Settings changes the standard API and Admin ports and network choices; View Logs opens the per-user log directory. The command-line run-orchestris.sh wrapper remains available for diagnostics or advanced configuration, but it is not required for normal operation.

curl -fsS http://127.0.0.1:8080/health
curl -fsS http://127.0.0.1:8080/app/ >/dev/null
curl -fsS http://127.0.0.1:3000/api/health/ready

All three commands should exit without an error. Open http://127.0.0.1:8080/app/ for hosted Chat and http://127.0.0.1:3000 for bundled Admin. Sign in to Admin with the organization-administrator credentials created during setup.

Loopback access needs no inbound firewall exposure. LAN or reverse-proxy access requires a reviewed bind address, the actual HTTP(S) public API origin, and any required macOS or network firewall rule. The setup checks the listener but does not change firewall settings.

"/Applications/Orchestris/install-orchestris.sh" \
  --bind-address 0.0.0.0 \
  --port 8080 \
  --public-base-url https://ai.example.com

Use Settings for the standard local or LAN configuration, then choose Restart. Settings deliberately refuses to overwrite an existing advanced Admin listener or proxy topology. For that case, run the configuration command as the same macOS user and provide the complete --admin-host, --admin-port, --admin-public-base-url, and --admin-trusted-proxy-cidrs group for a trusted HTTPS proxy.

"/Applications/Orchestris/run-orchestris.sh" --config-check
"/Applications/Orchestris/run-orchestris.sh" --file-type-detector-check
"/Applications/Orchestris/run-orchestris.sh" --local-search-reranker-check

1. 1

   Stop before upgrading

   Choose Stop from the Orchestris menu, then download and verify the newer arm64 DMG (recommended) or PKG.

2. 2

   Install the newer package

   Install it over /Applications/Orchestris. The package replaces its binaries and runtime assets but does not remove per-user state.

3. 3

   Start as the same user

   The next run detects the package version change and backs up the environment, database, WAL, and SHM files that exist. It retains the latest five automatic upgrade backups.

4. 4

   Verify after upgrade

   Open the graphical application, confirm the detected upgrade path preserves the existing installation, and verify /health, /app/, and Admin readiness.

5. 5

   Remove the application manually

   Choose Stop and Quit from the Orchestris menu, then remove /Applications/Orchestris through Finder or an administrator-managed removal process. The package supplies no uninstaller.

6. 6

   Decide whether to retain user state

   Removing the application does not remove ~/Library/Application Support/Orchestris. Remove each user's state manually only after verifying a backup and deciding that the database, secrets, and upgrade backups are no longer needed.

sudo /usr/sbin/pkgutil --forget com.orchestris.server

• Download the next Community Edition releaseGet the current signed package and its SHA-256.
• Configure providers and modelsAdd a provider and prepare model access before onboarding members.
• Troubleshoot startup or accessCheck configuration and the menu-bar app's View Logs directory after a failed check.