Modal VM Sandbox

Modal VM Sandboxes run each Sandbox on a full virtual machine with a real Linux kernel. Unlike Modal's default gVisor runtime, the VM runtime provides /dev/fuse and the mount capabilities AIStor Memory needs. AIStor Memory mounts a Memory Bucket at /workspace, so the files the agent closes and the memory it keeps stay in the bucket after the Sandbox ends.

Modal labels VM Sandboxes Beta.

The Modal example, published with these docs, creates two VM Sandboxes. The first writes a unique marker through AIStor Memory, and the second mounts the same Memory Bucket and reads the marker back.

Prerequisites

• A Modal account, and uv on the machine that runs the example.
• An AIStor endpoint that Modal's network can reach, and signing credentials for it. A loopback or private endpoint on your machine is not reachable from the remote VM Sandbox.

Quick start

1. Download the example, then install and authenticate the Modal SDK:

   mkdir aimem-modal && cd aimem-modal
   base=https://docs.min.io/aimem/examples/modal
   for f in aimem-mount contract.py pyproject.toml usage.py uv.lock; do
     curl -fsSLO "$base/$f"
   done
   curl -fsSL "$base/env.example" -o .env.example
   chmod +x aimem-mount
   uv sync --locked
   uv run modal setup

2. Store the signing credentials in a Modal Secret, not in source or the image:

   uv run modal secret create aimem-creds \
     AIMEM_ACCESS_KEY=... \
     AIMEM_SECRET_KEY=...

   For temporary credentials, add AIMEM_SESSION_TOKEN to the same Secret.

3. Copy the settings file, set the Memory Bucket (AIMEM_BUCKET) and endpoint (AIMEM_ENDPOINT), and load it:

   cp .env.example .env
   $EDITOR .env
   set -a
   source .env
   set +a

4. Run the example:

   uv run python usage.py

How it works

The example builds an Ubuntu 24.04 image with the checksum-verified Linux/amd64 aimem release and the aimem-mount entrypoint. It creates each Sandbox with experimental_options={"vm_runtime": True}; default gVisor Functions and Sandboxes cannot run the AIStor Memory FUSE mount.

aimem-mount is the Sandbox's main process, so the mount lasts exactly as long as the Sandbox. Commands you run with sandbox.exec(...) see the mounted workspace. During mount startup, AIStor Memory installs its agent skill in /root/.agents/skills/aimem and /root/.claude/skills/aimem.

AIMEM_LOCAL must point at the VM's local disk, outside AIMEM_MOUNTPOINT. AIStor Memory uses it only to stage writes and cache reads, so its default, /var/lib/aimem-local, can be temporary. Durable data lives in the bucket.

Options

Limitations

• VM Sandboxes are Beta and need the experimental vm_runtime option.
• VM Sandboxes run CPU workloads only; Modal does not support GPUs in the VM runtime yet.
• A VM lives at most until the Sandbox timeout. Files the agent has closed are already in the Memory Bucket, so the next Sandbox can read them.
• Modal's CloudBucketMount cannot replace AIStor Memory. It uses AWS Mountpoint and does not provide AIStor Memory's workspace behavior, agent memory, annotations, search, or skill installation.

Reference

• usage.py — the image recipe and the two-Sandbox example; the download above also fetches the aimem-mount wrapper it uses.
• AIStor Memory operations — endpoint, credential, license, and Memory Bucket prerequisites.
• Modal Secrets — create and manage the signing-credential Secret.
• Modal VM Sandboxes — VM runtime option, resource model, and current limitations.
• Modal Sandboxes — lifecycle and timeout behavior.