atrium — Docs
docs/install.md

Install atrium on macOS

Download the DMG for your Mac, what gets installed where, release channels, updating, and how to cleanly uninstall.

atrium ships as signed, notarized macOS builds — one per architecture (Apple Silicon and Intel) rather than a single universal binary, so the download is roughly half the size.

Download

  1. Open the Download page and select the DMG for your Mac's architecture.
  2. Open the downloaded .dmg.
  3. Drag atrium.app into Applications.
  4. Launch atrium from Applications or Spotlight.
On first launch, macOS may ask you to confirm opening an app downloaded from the internet. atrium is code-signed and notarized, so this confirmation happens once.

System requirements

  • macOS 12 (Monterey) or newer.
  • Apple Silicon or Intel.
  • Enough free space for the downloaded DMG and extracted app; sizes vary by release.
  • Additional space for the data directory (~/.atrium/), which grows with saved workspaces, transcripts, indexes, and captures.
These requirements are for the desktop client. atrium can also connect to Linux locations over SSH, including WSL2 and Intel or ARM Linux boxes. The client still runs on macOS; the remote box runs atriumd, the CLI, tools, repositories, and agent sessions.

What gets installed

  • The app: /Applications/atrium.app.
  • The CLI: ~/.atrium/bin/atrium is auto-installed on every launch. Its path is exported as ATRIUM_CLI_PATH into every terminal pane. Add it to your shell PATH if you want to call atrium from outside atrium panes:
export PATH="$HOME/.atrium/bin:$PATH"
  • The data directory: ~/.atrium/ stores configuration, project snapshots, installed adapters, custom themes, and shell integration files. See Data directory for the full layout.
Adding a remote location provisions a separate data directory and daemon on that box. Removing the location from your Mac does not delete the box or its repositories.

Channels

  • Public Beta is the only release available today. It updates frequently and ships directly from main.
  • Stable and Beta channels are planned after the 1.0 release. They will use isolated bundle identifiers and data directories (~/.atrium/ for stable, ~/.atrium-beta/ for beta).
The public beta's internal updater key remains early-access for compatibility. You may see that literal in config.json; it does not indicate gated access.

Dev builds use a separate bundle ID and instance data directory so they can run alongside a released build without overwriting state. The primary checkout uses ~/.atrium-dev/; linked worktrees have their own directories.

Uninstall

  1. Quit atrium.
  2. Drag /Applications/atrium.app to the Trash.
  3. Optionally remove the data directory: rm -rf ~/.atrium. This deletes saved atrium state, notes, snapshots, custom themes, and installed adapters. Project directories stored outside it remain on disk.

Updating

atrium checks for updates on launch by default. Change the check interval, the channel, and whether updates auto-install under Settings → Updates.

Updates are idle-gated — atrium waits for a quiet moment in the fleet rather than swapping the app out from under a running turn. The swap itself is performed by a small external helper binary, so the app being replaced is never the process doing the replacing.

If an update goes wrong

The generation an update supersedes is kept on disk at ~/.atrium/previous, precisely so there is something to go back to. Recovery is CLI-only by design: the failure it exists for is "the new version will not start", where in-app UI is unreachable.

atrium update rollback

See The daemon → Updates. Adapters and agent CLIs update on their own schedule — see Adapters → Updates.