Installation & updates

Install Orek with the installer or by hand, then keep it up to date. Run the commands on this page in your terminal, not in Orek’s composer.

Install with the terminal installer

The installer picks the latest stable release for your platform, checks the download’s size and SHA-256 checksum, and extracts the archive in a temporary directory. The extracted orek binary then places, verifies, and (on failure) rolls back the installation itself through its built-in self-install command, so the scripts never copy files into place. Orek lands with its bundled local-inference runtime in your user directory, without administrator rights.

Windows (PowerShell):

irm https://orek.ai/install.ps1 | iex

macOS and Linux:

curl -fsSL https://orek.ai/install.sh | sh

Verify the installation:

orek --version

To choose a release, save the installer script (install.ps1 or install.sh) and run it with options. Pass --major 2026 (Unix) or -Major 2026 (PowerShell) to stay on one major version, or --channel public-beta / -Channel public-beta for beta builds. On Windows, pass -SkipUserPathUpdate to leave your User PATH unchanged. Environment variables steer both scripts: OREK_INSTALL_DIR chooses the target directory on both platforms (-InstallDir overrides it when you run the PowerShell script file), OREK_MANIFEST_URL points at a different release catalog, OREK_SKIP_MODEL_DOWNLOAD=1 skips the default model download, and OREK_SKIP_PROFILE_UPDATE=1 (Unix) skips the PATH hint. Reading the manifest needs Python 3, Perl with JSON::PP, or POSIX awk — pick one explicitly with OREK_INSTALL_PARSER.

The installer refuses to create a second Orek when orek already resolves on PATH somewhere else: set OREK_INSTALL_DIR (or pass -InstallDir when running the PowerShell script file) to that installation’s directory to update it instead. When the installer reports that this machine is not eligible for the selected release, or that the release is no longer available (Orek exit code 30 from self-install or upgrade), follow the activation guide it prints and run the installer again. If your temporary directory is mounted noexec, the extracted binary cannot run there; point TMPDIR (Unix) or TEMP (Windows) at a directory on an executable filesystem and retry. Running the installer again over an existing installation in the target directory updates it with orek upgrade. Under irm | iex, a failed PowerShell install reports the error and leaves the PowerShell window open, while the command still fails (non-zero exit for powershell -Command); when you run the script file with pwsh -File, the same error exits with code 1.

Manual archive and IT deployment

For managed IT deployment, offline workstations, or systems that block piped scripts, install the standalone archive from the Download page:

1. Download the platform archive from Download, or read https://orek.ai/api/downloads?channel=stable for the exact filename, byte size, and sha256 digest.

2. Verify the SHA-256 checksum before extracting:

   In your shell

   # macOS
   shasum -a 256 <downloaded-file>
   
   # Linux
   sha256sum <downloaded-file>

   In your shell

   # Windows PowerShell
   Get-FileHash <downloaded-file> -Algorithm SHA256

3. Extract the full bundle and add it to PATH. Keep orek (orek.exe on Windows) in the same directory as its companion files: llama-server / llama-server.exe, its shared libraries, LICENSE.txt, and THIRD_PARTY_NOTICES.txt. Local embeddings, reranking, and command auto-review need these files, and use your GPU when Orek finds a compatible one.

   • Windows: Extract the .zip archive into %LOCALAPPDATA%\Programs\orek\ (or C:\Program Files\Orek\) and add that directory to PATH.

   • macOS: Open the verified .dmg and copy orek, llama-server, *.dylib, LICENSE.txt, and THIRD_PARTY_NOTICES.txt into ~/.local/bin/. Keep symbolic links as links, for example with cp -RP.

   • Linux: Install libgomp1 and OpenSSL 3, plus libvulkan1 and your graphics driver’s Vulkan support if you want GPU acceleration. Then extract the verified .tar.gz bundle into ~/.local/bin/:

     In your shell

     mkdir -p ~/.local/bin
     tar -xzf orek-*.tar.gz -C ~/.local/bin
     chmod 0755 ~/.local/bin/orek ~/.local/bin/llama-server

     Ensure ~/.local/bin is on PATH in ~/.zshrc or ~/.bashrc:

     In your shell

     export PATH="$HOME/.local/bin:$PATH"

   Release archives do not include the default local model files; the terminal installer downloads them into Orek’s model cache. For a manual install, copy the .gguf files from a machine that has them into the same folder, into a models/ folder next to orek, or into a folder you set with index.models_dir. See Prepare a disconnected workstation.

4. Activate the license. For online scripted provisioning:

   In your shell

   echo "$OREK_LICENSE_KEY" | orek license activate --key-stdin
   orek license status --json

   For an offline workstation, run orek license request --output activation-request.json on that machine, issue an activation code in Licenses from a connected browser, and import it on the offline machine with orek license import --code-file signed-license.txt. Orek checks the code without a network connection. See Activate your license and Prepare a disconnected workstation.

Release contents and third-party notices

Release archives include LICENSE.txt and THIRD_PARTY_NOTICES.txt alongside the orek binary. They list the open-source libraries, the bundled llama.cpp (llama-server) runtime, and the default GGUF models (EmbeddingGemma 2, Qwen3-Reranker-0.6B, and Shieldstral-1.0-3B) distributed with Orek.

This software incorporates components licensed under the Mozilla Public License 2.0, including nucleo-matcher, cssparser, selectors, dtoa-short, thin-slice, cssparser-macros, and option-ext. You may obtain the unmodified source code for these components from their official public distributions on https://crates.io and https://github.com.

If macOS or Windows blocks Orek

Current archives are not notarized by Apple or code-signed for Windows, so your system may warn you when you first run Orek. Always verify the SHA-256 checksum from orek.ai before bypassing the warning:

• macOS: If Gatekeeper blocks orek, open System Settings → Privacy & Security and click Open Anyway, or clear the quarantine attribute on the extracted directory:

  In your shell

  xattr -dr com.apple.quarantine ~/.local/bin

• Windows: If SmartScreen shows Windows protected your PC, choose More info → Run anyway, or unblock the verified .zip archive in PowerShell before extracting:

  In your shell

  Unblock-File <downloaded-file>

Upgrade Orek

Finish or stop active tasks and workflows, then close Orek and any editor sessions connected to it. Save your project work before replacing the running version. Check System requirements & release status for platform support and system requirements.

Check for an update

orek upgrade --check
orek upgrade --check --json

The command reports your installed version and the newest eligible release without installing it. It exits 0 when Orek is current and 10 when an update is available; --check --json prints the same verdict as one JSON object. Other exit codes (20 network, 30 not eligible, 40 integrity, 50/51 install or rollback failure) are listed in the upgrade command reference. If Orek is already current, no update is needed.

Install the update

orek upgrade

Orek streams the download to a resumable .part file under the cache directory (an interrupted download continues with an HTTP Range request), checks its size and checksum, backs up the current files to orek.bak, and installs the new ones. It then checks that the new version and its local runtime start; if they do not, Orek restores the backup. Without --force, when Orek is already current, it checks only the files listed in .orek-installed-companions and repairs missing ones by reinstalling the same version; no runtime self-test runs on an up-to-date install (orek doctor diagnoses it, --force reinstalls it), and Orek never downgrades. The upgrade also checks for missing or updated bundled model files. If other Orek sessions are still running from the same installation, Orek warns on stderr and continues.

Wait for the command to finish before reopening Orek. See the upgrade command reference for release channels, major-version selection, and exit codes.

What stays in place

The updater replaces application files without clearing your saved work or settings:

Workflow runs saved by earlier builds no longer list or resume, so finish them before upgrading. Their conversations stay readable.

See Configuration for settings locations and Manage sessions for saved conversations.

Verify the upgrade

Check the installed version and run the diagnostic check:

orek --version
orek doctor

The Installation section of orek doctor shows the install directory, whether it is on PATH, any shadowing orek binaries, the companion manifest against the files on disk, and the backups — useful right after an upgrade.

Reopen Orek in your project and confirm that your model and tools are ready. If the diagnostic check reports an incompatible code index, follow Repair an unavailable index.

Unknown config keys

If Orek reports an unknown configuration key, compare its name with the Configuration reference. The message names the file and the key’s full dotted name (for example, a misspelled routing.pinned_modle) without showing its value. orek doctor lists every unknown key. Correct the setting in the named file and restart Orek.

Settings that Orek no longer uses receive the same unknown-key diagnostics. Remove retired keys or replace them with their current documented setting. exec.truncation_policy accepts bytes, and MCP servers use named [mcp.servers.<name>] tables; obsolete spellings fail loading.

Saved sessions

Current session and workflow formats remain supported. Some pre-release saved formats are incompatible: Orek names the session and refuses the whole resume, without deleting or rewriting its journal. Open that session with the build that saved it, or start a new session. To keep the conversation in this build, run the orek session fork command the message names. Unknown records and variants from newer builds remain readable. Paid license records, installation binding and trial history are preserved during upgrades.

Roll back Orek

Restore the most recent application backup:

orek upgrade --rollback

Rollback requires an existing backup and works without a network connection. It restores the application files; it does not undo project edits or changes to saved data made since the upgrade. A rolled-back Orek cannot see workflow runs started after the upgrade.

If an upgrade fails or the backup is unavailable, contact support with your operating system, the output of orek --version, and the error message. Remove credentials and private project content before sharing logs.

Uninstall Orek

Downloaded releases have no uninstall command; remove Orek with these steps.

1. Release the license slot (optional). Deleting files does not free a device slot. If you activated online with a license key or orek license login, run orek license deactivate while online before removing the executable. Otherwise, or afterwards, release the device from the customer console. See Deactivate a device.

2. Delete the executable and its update backup.

   Installed with	Delete
   Terminal installer on macOS or Linux	~/.local/bin/orek, ~/.local/bin/llama-server, any bundled *.dylib / *.so*, LICENSE.txt, THIRD_PARTY_NOTICES.txt, .orek-installed-companions, any models/, and any orek.bak or .orek-companion-backup/ in ~/.local/bin/ (or your custom OREK_INSTALL_DIR).
   Terminal installer on Windows	The %LOCALAPPDATA%\Programs\orek\ folder (or your custom -InstallDir), which holds orek.exe, llama-server.exe, *.dll, LICENSE.txt, THIRD_PARTY_NOTICES.txt, .orek-installed-companions, orek.bak, .orek-companion-backup/, and any models/. Then remove the folder from your User Path environment variable.
   Manual archive	The directory where you extracted orek / orek.exe and its companion files, plus the PATH entry you added.

3. Delete your data (optional). Removing the executable keeps your settings, sessions, and license records, so a later installation finds them again. To remove them too, delete Orek’s per-user folders:

   Platform	Folders
   macOS	~/Library/Application Support/orek-ai/ and ~/Library/Caches/orek-ai/
   Linux	~/.config/orek-ai/, ~/.local/share/orek-ai/, and ~/.cache/orek-ai/, or the matching XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_CACHE_HOME folders
   Windows	%APPDATA%\orek-ai\ and %LOCALAPPDATA%\orek-ai\

   These folders hold your user configuration, routes, memories, sessions, logs, license records, and downloaded models. If you set OREK_HOME, they are under that folder instead. Custom index.models_dir, OREK_MODELS_DIR, or OREK_MODEL_CACHE_DIR paths stay where configured. Each project’s .orek/ folder holds project config, the code index, and plans; keep any files your repository tracks.

4. Remove saved credentials (optional). Before deleting the executable, clear provider keys from the OS credential store with orek providers setup <provider> --clear-credential --delete-secret and MCP sign-ins with orek mcp logout <name>. Any remaining credential-store entries under service name orek-ai.credentials.v1 (in Keychain Access, Windows Credential Manager, or Secret Service) include the secret that ties your license to this installation; delete them only together with the data folders above.