macOS install guide

Install AthenaOS on macOS

macOS does not have WSL, so AthenaOS runs as a lightweight Linux VM with Lima. This gives you a real AthenaOS environment with the Athena CLI, APT updates, Docker-first tooling, and AI-agent workflows.

1. HomebrewPackage manager used to install Lima if needed.

2. Lima VMRuns the AthenaOS Linux environment locally on macOS.

3. AthenaOSInstalls the CLI from the public AthenaOS APT repository.

Quick install Manual install Verify Update FAQ

Quick Install

Run this in the macOS Terminal. It installs the required tooling, creates the Lima VM, then installs AthenaOS inside it.

curl -fsSL https://apt.athena-os.org/install-macos.sh | bash

After the install, open the AthenaOS shell with limactl shell athenaos.

Manual Install

Use this path if you want to understand each step or debug the install manually.

Install Homebrew

If Homebrew is already installed, skip this step.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then make sure brew is available:

brew --version

Install Lima

brew install lima

Verify Lima:

limactl --version

Create the AthenaOS VM

curl -fsSL https://apt.athena-os.org/macos/athenaos-lima.yaml -o /tmp/athenaos-lima.yaml
limactl start --name athenaos /tmp/athenaos-lima.yaml

Enter AthenaOS

limactl shell athenaos

Verify AthenaOS

Run these commands inside the Lima shell.

athena version
athena banner
athena self-test

If these commands pass, AthenaOS is ready on your Mac.

Update AthenaOS

Inside the AthenaOS Lima shell:

sudo apt update
sudo apt install --only-upgrade athenaos-cli
athena version

Useful Lima Commands

limactl list
limactl shell athenaos
limactl stop athenaos
limactl start athenaos
limactl delete athenaos

FAQ And Common Problems

`brew: command not found`

Homebrew is not installed or your shell cannot find it. Install Homebrew, then reopen Terminal. On Apple Silicon, Homebrew usually lives in /opt/homebrew/bin.

`limactl: command not found`

Install Lima with brew install lima. If it is already installed, reopen Terminal and retry.

Lima asks for permissions

Accept the macOS security prompts for terminal, virtualization, or network access. Lima needs these to run the local Linux VM.

The VM already exists

Open it with limactl shell athenaos. To recreate it from scratch, run limactl stop athenaos then limactl delete athenaos, and run the installer again.

APT update fails inside the VM

Check that your Mac has internet access and that https://apt.athena-os.org opens in a browser. Then retry sudo apt update inside the Lima shell.

How do I know I am inside AthenaOS?

Run athena version. It should print the Athena CLI version and the AthenaOS root path.