macOS¶

macOS is a development-and-test target, not a production target. Use it to build, run iolake-aio, and point Spark / PyIceberg / boto3 at a local S3 endpoint. The split-service OSD binary runs on macOS, but Darwin does not expose the same raw-disk semantics as Linux (O_DIRECT, ioctl BLKGETSIZE64) and the storage engine has no hardened path for APFS-backed OSD disks. Keep macOS deployments to AIO mode, or run the services in a Linux VM.

Releases publish an Apple Silicon (arm64) binary; on Intel (x86_64), build from source. Erasure coding is ISA-L's on both, as on Linux.

1. AIO binary (recommended)¶

This is the fastest path and the one you'll actually want 95% of the time on macOS.

Apple Silicon¶

TAG=v0.1.0-rc.4
BASE=https://github.com/io-lake/iolake/releases/download/$TAG
curl -LO $BASE/iolake-aio-$TAG-darwin-arm64
curl -LO $BASE/iolake-aio-$TAG-darwin-arm64.sha256
shasum -a 256 -c iolake-aio-$TAG-darwin-arm64.sha256
chmod +x iolake-aio-$TAG-darwin-arm64
sudo mv iolake-aio-$TAG-darwin-arm64 /usr/local/bin/iolake-aio

The release binary is named with its tag, and a pre-release such as v0.1.0-rc.4 isn't reachable through releases/latest: name the tag.

Intel¶

There is no release binary for Intel Macs: build it (below).

Gatekeeper¶

Unsigned release binaries will be quarantined by Gatekeeper on first run. Either remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/iolake-aio

or, on the first launch, open System Settings → Privacy & Security and click Allow Anyway next to the iolake-aio entry.

Run it¶

iolake-aio --data "$HOME/.iolake"

The banner prints the admin AK/SK (also in ~/.iolake/meta/admin-creds.env). --data is optional but recommended — without it, every restart wipes the data tempdir. Authentication is off unless you add --auth.

2. Docker Desktop¶

The published image (ghcr.io/io-lake/iolake, linux/arm64 and linux/amd64) carries the service binaries and iolakectl, not iolake-aio. Use it to run iolakectl, or the services in Docker Desktop's Linux VM (docker.md); for a local endpoint, the AIO binary above is simpler.

3. Build from source (contributor path)¶

Only needed if you're hacking on IOLake itself.

Toolchain¶

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup toolchain install 1.93

# Build deps via Homebrew
brew install nasm autoconf automake libtool llvm protobuf cmake
# ISA-L's build runs autoreconf, which wants `libtoolize`; Homebrew
# names it glibtoolize and keeps the plain name here
export PATH="$(brew --prefix libtool)/libexec/gnubin:$PATH"

# Node 22+ for the console SPA (only if you need /_console/)
brew install node@22

Every build erasure-codes with ISA-L, built from source with autotools. nasm is Intel-only (ISA-L's x86 assembly); on Apple Silicon it is installed and not used.

Build¶

git clone https://github.com/io-lake/iolake
cd iolake

cargo build --workspace --release

Console¶

If you want the React /_console/ UI baked into iolake-aio:

cd console && npm ci && npm run build
cd .. && cargo build --release --bin iolake-aio    # rebuild to embed dist

Run¶

./target/release/iolake-aio --data "$HOME/.iolake"

What does not work on macOS¶

Production OSDs on raw disks. Darwin's /dev/disk* devices don't support the same O_DIRECT / BLKGETSIZE64 interface the storage engine uses. The OSD binary builds and runs against file- backed "disks" (truncate -s 10G disk0.raw), which is fine for unit tests but not for durability-sensitive work.
NBD clients. The block gateway serves volumes over NBD (and gRPC); macOS has no NBD client. Use Linux peers for block-storage testing.
io_uring performance path. Linux-specific. Not a correctness issue, but macOS performance numbers are not representative.

For any of these, run IOLake in a Linux VM (Lima, UTM, Colima, Docker Desktop's Linux VM, or a dedicated machine).

Typical dev loop on macOS¶

# 1. Run AIO in one terminal, persistent data dir
iolake-aio --data "$HOME/.iolake"

# 2. Point your tool at it
source "$HOME/.iolake/meta/admin-creds.env"   # also printed in the banner
export AWS_ENDPOINT_URL=http://localhost:9000

# 3. Work against S3 / Iceberg / Delta Sharing
aws s3 ls
iolakectl --endpoint http://localhost:9000 warehouse create demo
curl -s 'http://localhost:9000/iceberg/v1/config?warehouse=demo' | jq .

# 4. Console (browser)
open http://localhost:9000/_console/

Shut down with Ctrl-C — AIO drains cleanly. The data directory is reusable across restarts.