OpenSandbox

OpenSandbox gives an agent a disposable sandbox. AIStor Memory gives it memory: a mount of a MinIO AIStor Memory Bucket (a cortex) the agent both works in and remembers through as /workspace. Its real files, long-term memory (memory files, writable per-object annotations, object metadata, and server-side search), and the secrets it needs to act all live in your own AIStor — so they survive the sandbox being torn down, and the next run re-mounts the same state byte-for-byte instead of rebuilding it.

The one wrinkle is where the mount lives. OpenSandbox sandboxes do not expose /dev/fuse or CAP_SYS_ADMIN, so AIStor Memory cannot mount inside the sandbox. Instead, mount AIStor Memory on the host and bind that mountpoint into the sandbox as /workspace — the agent sees ordinary files, and the cortex is reached through the host mount.

Quick start

1. Install and configure the OpenSandbox server once.

   pip install opensandbox-server==0.2.1
   opensandbox-server init-config ~/.sandbox.toml --example docker

   Merge in the example config's [storage].allowed_host_paths (and set [server].api_key), then start it:

   [runtime]
   type = "docker"
   
   [storage]
   allowed_host_paths = ["/mnt/aimem"]

   opensandbox-server --config ~/.sandbox.toml

   Use Docker or Kata. Do not use gVisor or Firecracker; their guest kernels do not observe a host-side FUSE mount, so /workspace would appear empty.

2. Install the OpenSandbox Python SDK and set the values AIStor Memory needs.

   python -m pip install opensandbox==0.1.13
   
   export AIMEM_BUCKET="my-project"
   export AIMEM_ENDPOINT="https://aistor.example.com"
   export AIMEM_ACCESS_KEY="..."
   export AIMEM_SECRET_KEY="..."
   export OPENSANDBOX_DOMAIN="..."
   export OPENSANDBOX_API_KEY="..."

   AIMEM_BUCKET must name an existing cortex (Memory Bucket), not a plain S3 bucket — aimem mounts only cortexes. Create one first with aimem cortex create my-project (or convert an existing bucket with aimem cortex convert my-project). The mount is gated: it requires an explicit endpoint (AIMEM_ENDPOINT) and real signing credentials (AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY), and the target must verify as a cortex over the Memory API — an Enterprise (paid-tier) AIStor capability. Anonymous or default-chain mounts, a missing endpoint, or a plain bucket are all rejected before the mount comes up.

   Optional overrides: AIMEM_SESSION_TOKEN, AIMEM_MOUNT_ROOT, AIMEM_LOCAL, AIMEM_AGENT, AIMEM_VERSION, and AIMEM_DL_BASE.

3. Run the example from the repository root.

   python examples/opensandbox/main.py

main.py mounts AIStor Memory on the host, creates a sandbox with that mount bound to /workspace, then runs the shared external-worker contract through separate OpenSandbox command calls. The contract checks model-key isolation, reads SKILLS, writes and reads /workspace/probe.txt, records redacted tool traces, rejects path and symlink escapes, verifies remote timeout termination, and finally unmounts the host mount.

What the wrapper does

aimem-host-mount.sh installs the correct Linux amd64 or arm64 AIStor Memory binaries if absent, verifies their .sha256sum files, mounts the bucket under /mnt/aimem/<sandbox-id>, waits for the mountpoint, and prints it for main.py. The script also supports cleanup <sandbox-id> so stale host mounts do not accumulate after the sandbox exits.

The mount runs as the host user. If AIStor Memory lacks CAP_SYS_ADMIN, it forwards the FUSE file descriptor to the setuid-root aimem-fusermount helper for the privileged mount(2) call. That privilege is used on the host only, never in the sandbox.

The mount config also sets allow_root: true (a config-file-only tunable, so the wrapper writes it into the --config YAML rather than a CLI flag): the container runtime (dockerd/containerd) that binds this mountpoint into the sandbox runs as root, and a FUSE mount is otherwise only visible to the mounting user — without it, the runtime can't traverse the mount to set up the bind.

Files

• examples/opensandbox/aimem-host-mount.sh - host install, mount, wait, and cleanup wrapper.
• examples/opensandbox/main.py - OpenSandbox SDK flow and read/write probe.
• examples/opensandbox/sandbox.toml.example - server config fragment.

Verified end-to-end

Pin opensandbox-server==0.2.1 and opensandbox==0.1.13 (or newer) — the Volume/Host/Sandbox.create(volumes=...) shape above and the allowed_host_paths config key have both been confirmed working against those versions. Update this page and sandbox.toml.example together if upstream renames allowed_host_paths in a later release.

Reference

• OpenSandbox
• Host-volume mount example
• OpenSandbox Python SDK