Apple container (macOS)

Apple container runs each Linux container in its own lightweight VM with a real Linux kernel. AIStor Memory mounts a Memory Bucket inside that VM at /workspace, so the Mac needs no macFUSE or kernel extension. The agent's files and the memory it keeps are stored in your AIStor, not in the VM, so the next run mounts the same bucket and starts where the last one stopped.

This setup depends on recent Apple software that changes quickly. It works with container 1.0.0 on macOS 26.

Prerequisites

• macOS 26 (Tahoe) on Apple Silicon (M1 or later).

• Apple container installed.

• An AIStor endpoint that the Mac can reach, and signing credentials for it (AIMEM_ACCESS_KEY and AIMEM_SECRET_KEY, plus AIMEM_SESSION_TOKEN for temporary credentials).

• A Memory Bucket. There is no macOS aimem binary, so create the bucket from a Linux host that has aimem and admin credentials:

  export AIMEM_ACCESS_KEY=ADMIN_KEY AIMEM_SECRET_KEY=ADMIN_SECRET
  aimem create my-project --endpoint-url https://aistor.example.com:9000

Quick start

Download the example, then run run.sh from that directory:

mkdir aimem-apple-container && cd aimem-apple-container
base=https://docs.min.io/aimem/examples/apple-container
for f in aimem-mount Containerfile Containerfile.dockerignore Containerfile.full \
  entrypoint-full.sh run.sh smb.conf usage.sh; do
  curl -fsSLO "$base/$f"
done
chmod +x aimem-mount entrypoint-full.sh run.sh usage.sh
mkdir -p bin

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

The script starts Apple container, builds the arm64 image with the released binaries, and creates a persistent staging volume. It then starts (or replaces) the aimem-ws container, waits for the AIStor Memory mount, and opens a shell in /workspace.

To run a command in the mounted workspace instead, pass it after --:

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

To open the workspace again later:

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

To stop it:

container stop aimem-ws
container rm aimem-ws

Share the workspace with the Mac

When Finder or tools on the Mac need the same workspace, run usage.sh from the same directory. It shares /workspace with the Mac over SMB:

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

usage.sh builds the aimem-mac-full image, starts AIStor Memory and Samba, and mounts the share at $HOME/aimem-workspace. It writes and reads a test file, then leaves the mount and the container running. It generates the SMB password unless you set AIMEM_SMB_PASSWORD.

To unmount and stop it:

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

Options

• AIMEM_VERSION=RELEASE.<date> pins a release. The default is latest.
• AIMEM_REGION, AIMEM_PREFIX, AIMEM_AGENT, and AIMEM_SESSION_TOKEN are passed through when set.
• AIMEM_CONTAINER_NAME, AIMEM_IMAGE, and AIMEM_STAGING_VOLUME change the default container, image, and volume names.
• AIMEM_MNT, AIMEM_SMB_USER, and AIMEM_SMB_PASSWORD change the SMB share on the Mac.
• For an offline build, put Linux/arm64 aimem and aimem-fusermount binaries in bin/ in the example directory. The image uses them instead of downloading the release.

Limitations

• aimem runs as root inside the container and mounts with mount(2), so the container needs --cap-add SYS_ADMIN. The scripts add it; you do not need --device or --privileged.
• Use a current aimem release, so that its FUSE protocol version matches the VM's kernel.
• Over SMB, SQLite and other tools that rely on byte-range locks are unreliable. Run them in the container workspace instead.
• The SMB share runs with force user = root, because AIStor Memory mounts /workspace as root. SMB sign-in still uses the configured SMB account.
• If the Mac cannot reach the SMB share, the container subnet may clash with your router's. Set another with container system property set network.subnet. macOS may also ask once to allow Local Network access.

Reference

• run.sh and usage.sh: the scripts. They build Containerfile and Containerfile.full.
• Apple container: the runtime.
• Released binaries: https://dl.min.io/aistor/aimem/release/linux-arm64/.