E2B

E2B gives an agent a fast Firecracker sandbox; AIStor Memory gives that sandbox memory. Mount an AIStor Memory Bucket (a cortex) and /workspace becomes the agent's memory on one customer-owned store: a workspace for active work where its usual tools run unchanged, plus the long-term memory the agent reads and writes (the memory files it looks for, writable annotations, object metadata, server-side search). The third form — the vault for the secrets it needs to act — is provisioned separately at launch as environment variables, never written to /workspace (see Agent secrets below). The Firecracker microVM is disposable — when it is torn down the files and the knowledge stay in the cortex, so the next sandbox re-mounts the same state byte-for-byte instead of starting from nothing.

How the mount comes up

E2B templates are built from an e2b.Dockerfile via e2b template create. After Sandbox.create, runtime code launches aimem-mount via sb.commands.run with the AIStor Memory env vars; the mount comes up in a couple of seconds and /workspace becomes the cortex the agent works in and remembers through. E2B's sandbox-create envs do not propagate into the template start_cmd lifecycle, so the env-dependent mount happens at command time instead of at boot.

The automated smoke keeps the agent-worker phase on the CI runner and sends only typed list, read, and write operations through sb.commands.run. It uses the shared external-worker contract to verify model-key isolation, SKILLS, and workspace continuity across separate remote commands. Negative probes reject path traversal and symlink escapes and verify that timed-out commands cannot continue writing in the background.

Quick start

From the AIStor Memory repo:

cd examples/e2b
export E2B_API_KEY=...
export AIMEM_BUCKET="my-project"
export AIMEM_ENDPOINT="https://aistor.example.com"
export AIMEM_ACCESS_KEY=...
export AIMEM_SECRET_KEY=...

# Create the cortex once, launcher-side, with admin credentials. Skip if it
# already exists (or run `aimem cortex convert` to upgrade an existing bucket).
aimem cortex create "$AIMEM_BUCKET" \
  --endpoint-url "$AIMEM_ENDPOINT" \
  --access-key "$AIMEM_ACCESS_KEY" \
  --secret-key "$AIMEM_SECRET_KEY"

./build.sh
./run.sh

The aimem cortex verbs (create, convert, list, get, delete, credentials) run launcher-side against the Memory API and read their endpoint from --endpoint-url / AIMEM_ENDPOINT_URL (the mount wrapper's AIMEM_ENDPOINT is not consulted by the cortex subcommand, so pass the flag explicitly as above).

build.sh publishes the aimem-workspace template. It uses a global e2b CLI if present and otherwise falls back to npx @e2b/cli@latest. run.sh installs the tiny local TypeScript runtime on first run, creates a sandbox from the template, starts aimem-mount, waits until /workspace is mounted, writes a smoke file through AIStor Memory, prints it, and cleans up the sandbox.

/workspace inside the sandbox is the AIStor Memory mount. Writes are staged to /tmp/aimem-staging on the sandbox's local disk — the mandatory --local staging store, which the aimem-mount wrapper sets — and uploaded atomically to the cortex on close().

To pin a release, pass the build arg through:

./build.sh --build-arg AIMEM_VERSION=RELEASE.<date>

To use a non-default template name:

TEMPLATE_NAME=my-aimem-template ./build.sh
AIMEM_E2B_TEMPLATE=my-aimem-template ./run.sh

Agent secrets — the vault form

The third form of memory is the vault: the authority an approved agent receives, leased into the agent at launch rather than baked into the sandbox image. The storage credentials reach the sandbox only on the one-shot mount command's own environment; the smoke then keeps them out of the agent-worker phase and asserts that model keys such as OPENAI_API_KEY never leak into the execution environment. When the agent inside the sandbox does need credentials (a model API key, a downstream token), deliver them with aimem secret provision rather than baking them into envs. It fetches only the granted secrets — from a cortex (--cortex <name>, over the Memory API) or a generic HTTP store (--store-endpoint) — and launches the agent with just those values injected as env vars, scrubbing the store credential from the child's environment. For example:

aimem secret provision --cortex "$AIMEM_BUCKET" \
  --endpoint-url "$AIMEM_ENDPOINT" \
  --grant OPENAI_API_KEY=openai-key \
  -- my-agent --run

Cortex secrets are written launcher-side with aimem secret put <cortex> <name> (value from --value or stdin) and are held server-side, envelope-encrypted at rest.

FUSE availability

E2B's Firecracker microVMs expose /dev/fuse readable/writable by the sandbox user. aimem opens it directly and, running unprivileged, forwards the device fd to the setuid-root aimem-fusermount helper to perform the mount. The Dockerfile installs that helper setuid root and chowns the mountpoint to the sandbox user (the helper only mounts on a directory the caller owns). No host-side capability flags are required.

Reference

• The complete template lives in examples/e2b/: e2b.Dockerfile, aimem-mount, build.sh, run.sh, and usage.ts.
• E2B sandbox template docs.