Apple container (macOS)

Give an agent its memory on a Mac — mount a MinIO AIStor Memory Bucket (a cortex) inside an Apple container Linux VM, presented at /workspace.

Status — experimental

Experimental on Mac hardware: the path depends on recent, fast-moving Apple software. Requires macOS 26 (Tahoe) on Apple Silicon; FUSE runs inside the container's Linux VM. The FUSE mount and SMB re-export were validated on container 1.0.0 (guest kernel 6.18.15) for both Mode A (workspace inside the container, via run.sh) and Mode B (host SMB mount, via usage.sh). aimem now mounts only a cortex (Memory Bucket) on a paid-tier AIStor and rejects the default/AWS credential chain (see Prerequisites); re-run run.sh / usage.sh against a cortex with AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY set to confirm in your environment. The examples build release binaries from the public CDN by default and can also use staged Linux/arm64 binaries from examples/apple-container/bin/.

AIStor Memory is the memory your agent keeps — one mount of a MinIO AIStor Memory Bucket (a cortex) that the agent both works in and remembers through: a durable workspace, its long-term memory files, and the secrets it needs to act, all persisted to your own AIStor. This page brings that memory to a Mac.

Apple container runs each Linux container in its own lightweight VM with a real Linux kernel, so the cortex mounts inside the VM with no macFUSE or kernel extension on the Mac. The agent's files survive sandbox teardown because they live in the cortex, not in the VM — the next run re-mounts the same state.

Prerequisites

macOS 26 (Tahoe), Apple Silicon (M1+)
Apple container installed
A reachable AIStor endpoint on a paid (Enterprise) tier — the Memory API that aimem verifies at mount is an Enterprise-only capability; a free-tier server refuses it.
The bucket must be a cortex (Memory Bucket) — aimem mounts only cortexes. Create one once from a host that has the aimem binary and admin credentials:
```
export AIMEM_ACCESS_KEY=ADMIN_KEY AIMEM_SECRET_KEY=ADMIN_SECRET
aimem cortex create my-project --endpoint-url https://aistor.example.com:9000
```
There is no native macOS aimem binary (Linux/arm64 only), so run the cortex command from any Linux host that has the aimem binary and admin credentials (the base image's entrypoint is the mount, not a general aimem shell).
Signing credentials via AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY (plus optional AIMEM_SESSION_TOKEN). The mount gate verifies the cortex over the Memory API with these; the default/AWS credential chain is rejected.

Quick start — agent inside the container

Run this from the AIStor Memory repository:

AIMEM_BUCKET=my-project \
AIMEM_ENDPOINT_URL=https://aistor.example.com:9000 \
AIMEM_ACCESS_KEY=... AIMEM_SECRET_KEY=... \
bash examples/apple-container/run.sh

The script starts Apple container, builds the arm64 image, creates a persistent staging volume, starts/replaces the aimem-ws container, waits for the AIStor Memory mount, and opens a shell in /workspace.

Pass a command after -- to run it directly in the mounted workspace:

AIMEM_BUCKET=my-project \
AIMEM_ENDPOINT_URL=https://aistor.example.com:9000 \
AIMEM_ACCESS_KEY=... AIMEM_SECRET_KEY=... \
bash examples/apple-container/run.sh -- bash -lc 'pwd; touch agent-write.txt'

Re-enter the workspace later:

container exec -ti aimem-ws bash -lc 'cd /workspace && exec bash'

Stop it:

container stop aimem-ws
container rm aimem-ws

Also visible on the Mac host

Use the full image when Finder or host-side tools need the same workspace over SMB:

AIMEM_BUCKET=my-project \
AIMEM_ENDPOINT_URL=https://aistor.example.com:9000 \
AIMEM_ACCESS_KEY=... AIMEM_SECRET_KEY=... \
bash examples/apple-container/usage.sh

usage.sh builds aimem-mac-full, starts AIStor Memory and Samba, mounts the share at $HOME/aimem-workspace, runs a temporary write/read smoke, and leaves the mount and container running. It auto-generates the SMB password unless AIMEM_SMB_PASSWORD is set.

Unmount and stop it:

umount "$HOME/aimem-workspace"
container stop aimem-ws
container rm aimem-ws

Options

AIMEM_VERSION=RELEASE.<date> pins a release; default is latest.
AIMEM_REGION, AIMEM_PREFIX, AIMEM_AGENT, and AIMEM_SESSION_TOKEN pass through when set.
AIMEM_CONTAINER_NAME, AIMEM_IMAGE, and AIMEM_STAGING_VOLUME override the default container/image/volume names.
AIMEM_MNT, AIMEM_SMB_USER, and AIMEM_SMB_PASSWORD customize Mode B.
For offline or unreleased builds, drop Linux/arm64 aimem and aimem-fusermount into examples/apple-container/bin/; the Containerfiles use those before trying the CDN.

FUSE and SMB notes

/dev/fuse is present in the guest VM. aimem runs as root and mounts via the direct mount(2) path, so the container needs --cap-add SYS_ADMIN; the scripts add it. No --device or --privileged flag is required. The image also ships the setuid aimem-fusermount helper for future non-root variants. Use a recent aimem build so it matches the sandbox kernel — the guest kernel is 6.x (observed 6.18.15 on container 1.0.0), which offers FUSE ABI ≥ 7.40, and aimem's FUSE ABI negotiates cleanly against it.

Mode B re-exports /workspace over SMB. AIStor Memory mounts /workspace as root, so the Samba share uses force user = root; SMB authentication still uses the configured SMB account. SQLite and other heavy byte-range-locking workloads are unreliable over SMB; use the container workspace for those.

If the SMB mount is unreachable, the default container subnet may collide with your router. Set another with container system property set network.subnet. macOS may also prompt once to allow Local Network access.

Optional checks

bash examples/apple-container/tests.sh

For a live Mode A smoke with an independent S3 object check, configure mc and run:

AIMEM_IMAGE=aimem-mac-base AIMEM_BUCKET=testbucket \
AIMEM_ENDPOINT_URL=https://aistor.example.com:9000 \
AIMEM_ACCESS_KEY=... AIMEM_SECRET_KEY=... MC_ALIAS=myaistor \
bash examples/apple-container/phase0-smoke.sh

Reference

Apple container — the runtime.
Released binaries: https://dl.min.io/aistor/aimem/release/<version>/.