Install Community Edition on Linux

Open /download and select the Community Edition artifact for the host. Its download row shows the current version, filename, architecture, checksum, detached signature, and any stated operating-system requirement.

The verification block is a template. Replace <DOWNLOADED_FILENAME> with the exact DEB, RPM, or tarball filename from /download. Keep the artifact, its matching .asc signature, and the downloaded public key in the same folder before running it.

export ORCHESTRIS_PACKAGE="./<DOWNLOADED_FILENAME>"

# Compare this value with the SHA-256 displayed on /download.
sha256sum "$ORCHESTRIS_PACKAGE"

gpg --import ./orchestris-linux-release-key.asc
gpg --verify "${ORCHESTRIS_PACKAGE}.asc" "$ORCHESTRIS_PACKAGE"

• Open Community Edition downloadsSelect the live DEB, RPM, or portable artifact and its integrity files.
• Review platform and network requirements

Prefer the native package manager so dependencies are resolved. Use the portable archive when a DEB or RPM is not appropriate. Replace <VERSION> with the version in the downloaded filename before copying the matching template. A new service remains stopped until guided setup succeeds.

sudo apt update
export ORCHESTRIS_DEB="./orchestris_<VERSION>-1_amd64.deb"
test -f "$ORCHESTRIS_DEB"
sudo apt install "$ORCHESTRIS_DEB"

export ORCHESTRIS_RPM="./orchestris-<VERSION>-1.x86_64.rpm"
test -f "$ORCHESTRIS_RPM"
sudo dnf install "$ORCHESTRIS_RPM"

sudo zypper refresh
export ORCHESTRIS_RPM="./orchestris-<VERSION>-1.x86_64.rpm"
test -f "$ORCHESTRIS_RPM"
sudo zypper --no-gpg-checks install "$ORCHESTRIS_RPM"

tar -xzf ./orchestris-<VERSION>-linux-x64.tar.gz
cd ./orchestris-<VERSION>-linux-x64
sudo packaging/linux/tar/install.sh --source-dir "$PWD" --enable --start

sudo orchestris-setup

1. 1

   Choose network access

   Keep the default 127.0.0.1 for access from this computer only, choose 0.0.0.0 for local-network access, or enter a specific IP address. The default port is 8080.

2. 2

   Set the public API origin

   Enter the HTTP(S) origin that Chat and browsers will actually use. Keep http://localhost:8080 only for local-only access; use the client-visible LAN or trusted reverse-proxy origin for other devices.

3. 3

   Create the organization and administrator

   Enter the organization name, administrator email, and password twice. The password is read without echo. Setup initializes SQLite as the orchestris service user so the database remains service-owned.

4. 4

   Let setup enable the service

   After configuration and initialization validate successfully, guided setup enables and starts orchestris.target, which owns the API and bundled Admin services.

sudo systemctl start orchestris.target
sudo systemctl stop orchestris.target
sudo systemctl restart orchestris.target
systemctl status --no-pager orchestris-api.service orchestris-admin.service

curl --fail --silent --show-error http://127.0.0.1:8080/health
curl --fail --silent --show-error http://127.0.0.1:8080/app/ >/dev/null
curl --fail --silent --show-error http://127.0.0.1:3000/api/health/ready

The local checks use the default ports and should exit without an error. Hosted Chat is /app/ on the Server origin; bundled Admin uses its own origin. Sign in to Admin with the first administrator account, configure a provider and model grant, then validate Chat from the intended client network.

sudo journalctl -u orchestris-api.service -u orchestris-admin.service -n 100 --no-pager
sudo journalctl -u orchestris-api.service -u orchestris-admin.service --follow

• Configure providers and models
• Troubleshoot startup, health, or access

These package-owned files can be restored by reinstalling the same release. They are listed for troubleshooting and service administration, not as a substitute for the configuration-and-state backup above.

Both systemd services load /etc/orchestris/orchestris.env first and then the optional /etc/orchestris/orchestris.env.local override. Keep generated secrets in the base file and place reviewed network changes in the override file.

sudoedit /etc/orchestris/orchestris.env.local

ORCHESTRIS_SERVER__HOST=0.0.0.0
ORCHESTRIS_SERVER__PORT=8080
ORCHESTRIS_SERVER__PUBLIC_BASE_URL=https://ai.example.com

sudo env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh -c '
  set -a
  . /etc/orchestris/orchestris.env
  [ ! -r /etc/orchestris/orchestris.env.local ] || . /etc/orchestris/orchestris.env.local
  set +a
  exec runuser -u orchestris -- /usr/bin/orchestris-api --config-check
'

sudo systemctl restart orchestris.target

1. 1

   Create an independent recovery backup

   Stop orchestris.target and archive both /etc/orchestris and the complete /var/lib/orchestris directory into protected backup storage. Include database WAL/SHM files and every secret, attachment, key, and state file; then restart the target.

2. 2

   Test the backup

   Validate the archive and checksum, then periodically restore it to an isolated host. A successful /health response is only the first gate; also sign in, inspect representative records and attachments, and exercise a restored provider credential or pre-backup API key.

3. 3

   Read release notes

   Confirm upgrade prerequisites, migrations, and rollback constraints before installing the newer DEB or RPM from /download.

4. 4

   Install the next package

   Use the same distribution package manager used for the initial installation. If orchestris.target was active, the package upgrade stops both components, validates the new release unit, and starts the target again while preserving configuration and state.

5. 5

   Verify application behavior

   Check both service logs, call /health and Admin readiness, open /app/, sign in, and confirm provider and model access before reopening wider network access.

• Read release notes
• Review configuration and backup boundaries

sudo apt remove orchestris

sudo zypper remove orchestris

sudo dnf remove orchestris

sudo packaging/linux/tar/uninstall.sh

Package or portable-installer removal stops and disables the coupled services and removes installer-owned API, Admin, Node, and support files. It intentionally preserves /etc/orchestris and /var/lib/orchestris. A later reinstall can reuse that configuration and state; the existing organization administrator also means local initialization remains complete.