Vercel Sandbox

Give an agent running in a Vercel Sandbox durable memory — mount an AIStor Memory Bucket (cortex) at /workspace so its work and knowledge outlive the disposable microVM.

A Vercel Sandbox is disposable: each one is its own Firecracker microVM, torn down when the run ends. Mounting an AIStor Memory Bucket (a cortex) at /workspace gives the agent inside it memory that outlives the microVM — the files it works in and the knowledge it keeps persist to your own AIStor, so the next sandbox re-mounts the same state at full fidelity instead of starting from nothing.

How the mount works

FUSE is a system-privileged operation inside the microVM (Amazon Linux 2023, x86_64), so the mount runs under sudo; aimem opens /dev/fuse and mounts directly as root — no setuid helper or fuse package required. The FUSE access/ownership settings (allow_other, uid, gid, dir_mode, file_mode) are config-file-only, so the example writes a versioned --config YAML for them: allow_other exposes the mount to the non-root sandbox user, and the example passes that user's UID/GID to AIStor Memory so normal write-permission checks succeed without running agent tools under sudo. Writable directory and file modes preserve access when Vercel isolates separate command sessions behind distinct user namespaces. The cortex contents persist across those sessions — the microVM and its FUSE mount are torn down each time, so each isolated session mounts the cortex again to see the same state.

Quick start

AIMEM_BUCKET must be a cortex

aimem mounts only a Memory Bucket (cortex), never a plain S3 bucket — an Enterprise/paid-tier AIStor capability. Before you set AIMEM_BUCKET, create the cortex launcher-side with aimem cortex create my-project --endpoint-url https://aistor.example.com (or aimem cortex convert an existing bucket). At mount time aimem verifies over the Memory API that an explicit --endpoint-url is set, that real signing credentials are present (AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY — anonymous mounts are refused), that the target is a cortex, and that the server is on a paid tier; a plain bucket fails the gate with 'my-project' is not a Memory Bucket (cortex). See Prerequisites.

The repository ships a complete example:

examples/vercel/
├── .env.example    # copy to .env and fill in once
├── usage.ts        # create sandbox, upload aimem, mount at /workspace, verify
├── aimem-mount     # mount wrapper, uploaded and run under sudo
├── package.json    # pins @vercel/sandbox + dotenv
└── README.md

Run the smoke from the repository root:

cd examples/vercel
cp .env.example .env
$EDITOR .env
npm install
npm start

Fill these required values in .env: VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID, AIMEM_ENDPOINT, AIMEM_BUCKET, AIMEM_ACCESS_KEY, and AIMEM_SECRET_KEY. Temporary credentials can also set AIMEM_SESSION_TOKEN. The mount comes up and /workspace becomes the bucket:

No local build is needed. usage.ts downloads the released linux/amd64 aimem binary from the public CDN, verifies it against its published .sha256sum, uploads it with aimem-mount, waits for /workspace, verifies the aimem skill was installed under the mounting user's home, writes through the mount as the non-root sandbox user, then stops the disposable sandbox. Pin a release with AIMEM_VERSION=RELEASE.<date> (default latest), or set AIMEM_BIN to a local linux/amd64 ELF for an offline or unreleased build (it must run on Amazon Linux 2023 — glibc 2.34).

After provisioning, usage.ts removes storage credentials from the worker environment and dispatches separately traced skill-check, read, and write calls with sandbox.runCommand. It also asserts that OPENAI_API_KEY is absent from the execution sandbox, rejects path traversal and symlink escapes, and verifies that a timed-out command cannot complete a delayed workspace write.

Writes are staged on the sandbox's local disk and uploaded to the bucket. The staging dir is required: set local: (or --local) to a path on /vercel/sandbox (real disk) — don't point it at /tmp, which is memory-backed.

SKILLS

Every mount teaches the agent how to use the workspace through the same three-tier model described in SKILLS — the agent's mount manual; the first two tiers are automatic. On read, instruction files (CLAUDE.md, AGENTS.md, .cursorrules) are served with an in-memory orientation preamble (AIMEM_PREAMBLE_OVERLAY=0 to opt out). On mount, the aimem skill — SKILL.md (frontmatter name: aimem) plus references/{navigation,workspace,memory,metadata,annotations,search}.md — is installed into the mounting user's home skill directories (~/.agents/skills/aimem/ and ~/.claude/skills/aimem/; AIMEM_INSTALL_SKILL=0 to opt out). Here the mount runs under sudo, so those land in root's home (/root), outside the /workspace mount. For host-side agents whose reasoning runs outside the sandbox, install the public skill first with npx skills add minio/skills/aimem.

FUSE availability

Use a current aimem build so it matches the sandbox kernel: aimem negotiates the FUSE ABI with the kernel at mount time, and an older build can fail that handshake against the microVM's kernel.

Long-lived agents

For agents that outlast a single session, use a persistent sandbox and re-mount on resume: a sandbox has a hard duration cap (45 min on Hobby, 5 hr on Pro/Enterprise) and the mount lives only as long as the sandbox process, so the snapshot restores the filesystem but not the aimem process:

const sandbox = await Sandbox.getOrCreate({
  name: "my-agent",
  // upload aimem + aimem-mount once, on first create
  onCreate: async (sb) => {
    /* writeFiles(...) */
  },
  // re-run the mount on every resume (aimem-mount is idempotent — it exits
  // early if /workspace is already mounted)
  onResume: async (sb) => {
    /* runCommand sudo aimem-mount */
  },
});

Reference

examples/vercel/ — the full example.
Vercel Sandbox docs.