Installing Oxide

Oxide ships as a signed, notarized DMG for macOS 12 and later, on both Apple Silicon and Intel. It keeps itself up to date after that.

Download the app

1. Grab the latest DMG from the releases page (or from the button on oxideterminal.com).
2. Open it and drag Oxide to Applications.
3. Launch it.

Every build is signed with a Developer ID certificate, notarized by Apple, and stapled, so Gatekeeper opens it like any other app — no right-click-to-open, no xattr -d.

Install with Homebrew

brew install --cask bobbycoleman-dev/tap/oxide-terminal

This installs the same signed, notarized build as the DMG. The fully-qualified name taps bobbycoleman-dev/tap and marks just this cask as trusted in one step, so there is no separate brew tap or brew trust to run. To remove it: brew uninstall --cask oxide-terminal.

First run

On first launch Oxide writes a fully commented default config to ~/.config/oxide/config.toml. Open it from inside the app with cmd-, (Oxide → Settings…), which opens it in the focused pane with your $EDITOR — or open -t if you have no $EDITOR set. Nothing is echoed at the prompt; the editor just appears.

See Configuration for what goes in that file.

The oxide command

Optional: a one-line shim so you can open the app at a directory from any terminal.

# from a clone of the repo
sudo cp scripts/oxide-cli /usr/local/bin/oxide
sudo chmod +x /usr/local/bin/oxide

oxide            # open at the current directory
oxide ~/Code     # open at a specific one
oxide --no-startup-commands   # restore pinned workspaces without running their commands

Updating

A copy running from an installed .app checks GitHub for a newer release on launch and every six hours after that. When one exists, Oxide downloads it in the background and offers to install; one click swaps the bundle and relaunches. You can also check on demand from Oxide → Check for Updates… A failed download shows up as an error toast in the corner, and the first launch after an update shows a toast; click it to read the changelog in a new tab.

Version comparison is numeric on major.minor.patch, so a build with a higher version than the latest release is never "updated" backwards. Running through cargo run skips the check entirely.

Building from source

Building needs a couple of things a download does not:

• Rust, 2024 edition
• Full Xcode with the Metal toolchain — GPUI compiles Metal shaders at build time, and the Command Line Tools alone are not enough

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -downloadComponent MetalToolchain   # if the build asks

Then:

git clone https://github.com/bobbycoleman-dev/oxide.git
cd oxide
cargo run                     # development build

./scripts/bundle.sh           # release -> target/Oxide.app (ad-hoc signed)
cp -R target/Oxide.app /Applications/

Maintainers publish a release with ./scripts/release.sh, which takes the notes from CHANGELOG.md, builds the notarized DMG and uploads it twice: once for the website's download button and once as -update.dmg for the in-app updater, so the site's download count doesn't include updates.

The first build compiles GPUI and its shaders — expect several minutes. A locally bundled app is ad-hoc signed rather than notarized; it runs fine on your own machine.

Uninstalling

rm -rf /Applications/Oxide.app
rm -rf ~/.config/oxide      # your config
rm -rf ~/.cache/oxide       # generated scripts, workspaces, window state
sudo rm -f /usr/local/bin/oxide   # if you installed the CLI shim

Oxide never writes to your dotfiles, so there is nothing to unpick in ~/.zshrc or ~/.bash_profile.