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 exposes /dev/fuse and grants the mount capabilities AIMem needs. That makes /workspace a native AIMem mount whose closed files and memory persist in the cortex after the disposable Sandbox ends.

The complete runnable integration is in examples/modal. It creates two VM Sandboxes: the first writes a unique marker through AIMem, and the second remounts the cortex and reads the marker back.

Configure Modal and the cortex

Install and authenticate the Modal SDK:

cd examples/modal
uv sync --locked
uv run modal setup

The target must already be an AIStor Memory cortex. Keep the signing credentials in a Modal Secret rather than in source or the image:

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

Temporary credentials can include AIMEM_SESSION_TOKEN in the same Secret.

Copy the non-secret runtime configuration and set the cortex and endpoint:

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

Then run the end-to-end smoke:

uv run python usage.py

AIMEM_ENDPOINT must be reachable from Modal's egress network. A loopback or private endpoint on the machine running usage.py is not reachable from the remote VM Sandbox.

Runtime shape

The example builds an Ubuntu 24.04 image containing the checksum-verified Linux/amd64 AIMem release and a small foreground mount entrypoint. It launches:

sandbox = modal.Sandbox.create(
    "/usr/local/bin/aimem-mount",
    app=app,
    image=image,
    env={
        "AIMEM_BUCKET": cortex,
        "AIMEM_ENDPOINT": endpoint,
        "AIMEM_LOCAL": os.environ.get("AIMEM_LOCAL", "/var/lib/aimem-local"),
        "AIMEM_MOUNTPOINT": os.environ.get("AIMEM_MOUNTPOINT", "/workspace"),
        "AIMEM_AGENT": os.environ.get("AIMEM_AGENT", "auto"),
        **(
            {"AIMEM_REGION": os.environ["AIMEM_REGION"]}
            if "AIMEM_REGION" in os.environ
            else {}
        ),
        **(
            {"AIMEM_PREFIX": os.environ["AIMEM_PREFIX"]}
            if "AIMEM_PREFIX" in os.environ
            else {}
        ),
    },
    secrets=[
        modal.Secret.from_name(
            os.environ.get("AIMEM_MODAL_SECRET", "aimem-creds")
        )
    ],
    experimental_options={"vm_runtime": True},
)

Inside the VM, the entrypoint executes:

prefix="${AIMEM_PREFIX:-}"
while [[ "$prefix" == /* ]]; do prefix="${prefix#/}"; done
while [[ "$prefix" == */ ]]; do prefix="${prefix%/}"; done
bucket="${AIMEM_BUCKET%/}"
[[ -n "$prefix" ]] && bucket="${bucket}/${prefix}/"

aimem "$bucket" "$AIMEM_MOUNTPOINT" \
  --endpoint-url "$AIMEM_ENDPOINT" \
  --local "$AIMEM_LOCAL" \
  --agent "$AIMEM_AGENT" \
  ${AIMEM_REGION:+--region "$AIMEM_REGION"} \
  --foreground

The mount process is the Sandbox's main process, so the mount and Sandbox have the same lifecycle. Commands run through sandbox.exec(...) see the mounted workspace. AIMem installs its agent skill under /root/.agents/skills/aimem and /root/.claude/skills/aimem during mount startup.

Optional configuration

Binary and local-store choices

By default the image downloads aimem-linux-amd64 from the public CDN and verifies its .sha256sum. Set AIMEM_VERSION=RELEASE.<date> to pin a release (the default is latest). For an unreleased build, set AIMEM_BIN to a Linux/amd64 binary compatible with Ubuntu 24.04.

AIMEM_LOCAL must point at the VM's local disk and must not be inside AIMEM_MOUNTPOINT. Its default, /var/lib/aimem-local, is ephemeral by design: AIMem uses it only for write staging and read caching, while durable data lives in the cortex.

Automated validation

The modal-smoke job in sandbox-smoke.yml builds AIMem from the current commit, starts an ephemeral AIStor service, and exposes that service to Modal through a temporary HTTPS tunnel. It creates a run-scoped Modal Secret, runs the two-Sandbox skill and persistence checks, and then removes the Secret and stops the Modal App.

The job is credentials-gated: it runs when the repository has both MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, and otherwise skips without failing forks. A green workflow where modal-smoke was skipped is not evidence that the live integration passed. Repository operators can find the complete secret matrix in docs/CONTRIBUTING.md.

Current limitations

• VM Sandboxes are Beta and require an experimental creation option.
• They currently support CPU workloads only; Modal does not yet support GPUs in the VM runtime.
• The VM can live for at most the Sandbox timeout. Closed files have already uploaded to the cortex and are available to the next Sandbox.
• Modal's CloudBucketMount is not interchangeable with AIMem. It uses AWS Mountpoint and does not provide AIMem's workspace semantics, agent memory, annotations, search, or skill installation.

Reference

• examples/modal/README.md — runnable quick start and environment-variable reference.
• examples/modal — image recipe, mount wrapper, and two-Sandbox smoke implementation.
• AIStor Memory operations — endpoint, credential, license, and cortex 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.