Oxagen app
Download the Oxagen app, open it the first time on macOS, Windows, or Linux, and find the oxagen command it puts on your PATH.
The Oxagen app puts one machine under Oxagen control. It bundles the oxagen command, and enrollment runs through it.
Download
The newest Oxagen app for each platform
Every version, with SHA-256 checksumsmacOS 12 or newer. Open the .dmg and drag Oxagen to Applications. Builds are not yet notarized, so macOS refuses the first launch. Choose Done, then click Open Anyway in System Settings > Privacy & Security.
- Apple silicon (.dmg)Oxagen_aarch64.dmg
- Intel (.dmg)Oxagen_x64.dmg
Windows 10 or newer, x64.
- Installer (.exe)Oxagen_x64-setup.exe
- Installer (.msi)Oxagen_x64_en-US.msi
x86_64. Install the package for your distribution.
- .deb (Debian, Ubuntu)Oxagen_amd64.deb
- .rpm (Fedora, RHEL)Oxagen.x86_64.rpm
- AppImage (any distribution)Oxagen_amd64.AppImage
On first launch the app links the oxagen and recorder commands onto your PATH, so a new terminal can run them.
On macOS, the app installs new versions on its own and runs them after your next restart. Windows and Linux ask first. How updates work and how to turn them off.
Every version, with a SHA-256 for each file, is listed at downloads.oxagen.sh. To check a download, put that version's SHA256SUMS.txt beside the file and run:
shasum -a 256 -c SHA256SUMS.txtFirst launch on macOS
Builds are not yet notarized, so macOS refuses the first launch and offers Move to Trash. Choose Done or Cancel instead.
- Open System Settings > Privacy & Security. On macOS 12 it is System Preferences > Security & Privacy.
- Scroll to the message about Oxagen and click Open Anyway.
- Confirm with Open and your login password.
The Open Anyway button shows for about an hour after the refused launch. macOS 15 removed the older Control-click and Open route, so that route no longer works.
If you already have a terminal open, clearing the quarantine flag does the same thing:
xattr -dr com.apple.quarantine /Applications/Oxagen.appThen open Oxagen as usual. Either way, macOS asks only once.
First launch on Windows
Builds are not yet locked with Oxagen's developer key. That lock lets Windows check that a file came from Oxagen unchanged, so without it SmartScreen warns that the publisher is unknown. Choose More info, then Run anyway.
Linux
The packages are not locked with Oxagen's developer key, and no apt or dnf repository exists yet. Install the file you downloaded directly:
sudo dpkg -i Oxagen_amd64.deb
sudo rpm -i Oxagen.x86_64.rpm
chmod +x Oxagen_amd64.AppImage && ./Oxagen_amd64.AppImagePer-user copy
Each time it opens, the app copies oxagen and recorder out of itself into a directory named for its version:
| Platform | Directory |
|---|---|
| macOS | ~/Library/Application Support/oxagen/bin/<version> |
| Linux | ~/.local/share/oxagen/bin/<version> |
| Windows | %LOCALAPPDATA%\oxagen\bin\<version> |
Enrollment writes this copy's path into every hook, the Claude Code credential helper, the Claude Desktop MCP entry, and the collector service. It never writes a path inside the app. Moving the app to the Trash or removing the package leaves the copy in place, so your agents keep working until you uninstall.
A new version copies itself beside the old one, so an update never replaces a file the running collector holds. The hooks and the collector stay on the old copy until you click Re-apply, which the app offers when the two differ. The app removes an old copy at its next launch once no enrollment and no link names it.
Command line
The app links oxagen and recorder from the per-user copy into ~/.local/bin on macOS and Linux. On Windows it writes .cmd shims to a directory on your user PATH. It never asks for administrator rights, and it never replaces a file it did not write.
Open a new terminal after the first launch. On macOS and Linux, this prints the path of oxagen:
command -v oxagenUninstall
In the app, Uninstall removes every enrollment, the links, every per-user copy, and ~/.config/oxagen. Then remove the app: drag it to the Trash on macOS, remove it in Settings > Apps on Windows, or remove the package on Linux.
The local event log holds the only copy of events that have not reached Oxagen. When it holds any, Uninstall says how many and offers Unenroll and keep the event log, which removes every enrollment and leaves the log, the links, and the app's settings. The app does not delete waiting events. To delete them, run oxagen agent uninstall from your own terminal and type purge when it asks.
If you removed the app first, run the per-user copy's oxagen:
"$HOME/Library/Application Support/oxagen/bin/<version>/oxagen" agent uninstallUse the Linux or Windows directory from the table above on those platforms. The command does what Uninstall does, without the app:
- It removes every enrollment: the hooks, the collector service, the keys, and the local event log. If an enrollment cannot be fully removed, the command stops here and says what to fix, because a hook that is left would still run the copy. While the event log holds events that have not reached Oxagen, it removes nothing unless you type
purgewhen it asks. It never asks from an agent's shell, or with no terminal, so run it from your own terminal. - It removes the links in
~/.local/bin, the lines the app added to your shell profile, and on Windows the shims and the entry on your userPATH. The app keeps a list of each of these in~/.config/oxagen/desktop.jsoneach time it opens. The command removes only what is still the way the app wrote it. A link you pointed somewhere else stays, and the command names it. - It removes every per-user copy and
~/.config/oxagen. That folder holds youroxagen loginsession, so theoxagencommand asks you to sign in again afterward.
On Windows the command cannot delete the oxagen.exe it is running from. It names that folder, so you can delete it after the command finishes.
If the per-user copy is gone as well, the Cursor and Stella hooks on macOS and Linux allow each action instead of blocking it, and Claude Code and Codex report a hook error on each tool call. On Windows the Cursor and Stella hooks block. Install the app again and use Uninstall, or run oxagen agent uninstall from any other install of the oxagen CLI.
Updates
On macOS, the Oxagen app installs new versions automatically. It checks for one when it opens, every hour, and when you return to the window after 15 minutes or more. It downloads the new version, checks Oxagen's lock on it, and replaces the app in the background. Your next restart runs it, and the window shows Restart until then.
The app installs automatically only when your account can replace it without a password. When it cannot, for example when a standard account runs it from /Applications, it asks first and offers Install and relaunch or Later. The Updates panel says why.
Windows and Linux always ask first.
Every update is locked with Oxagen's key, and the app installs no update that fails that check. Updates come only from published releases, and the app downloads them from downloads.oxagen.sh.
If Check for updates reports an error, install the app once more from downloads.oxagen.sh over the old one.
To turn automatic installs off, clear Install updates automatically in the Updates panel. The checkbox writes autoUpdate to ~/.config/oxagen/desktop.json, so an administrator can set it for you with a management tool:
{ "autoUpdate": false }With it off, the app still tells you when a new version is out and waits for your click.
Next step
Set up your Oxagen account and enroll this machine.
Installing the CLI
Install the oxagen CLI with the Oxagen app, as a single executable from downloads.oxagen.sh, or from npm.
Wrap an agent
What wrapping means, how to wrap Claude Code, Codex, Cursor, and Stella, how to set it up from a coding agent, how to run two agents on one machine, and how to wrap a custom agent with oxagen agent run or oxagen hook.