OpenSandbox

OpenSandbox gives an agent a sandbox that is deleted when the run ends. AIStor Memory mounts a Memory Bucket that the agent sees as /workspace. The agent's files and the memory it keeps are stored in your AIStor, so the next run mounts the same bucket and starts where the last one stopped.

OpenSandbox sandboxes do not provide /dev/fuse or CAP_SYS_ADMIN, so AIStor Memory cannot mount inside the sandbox. Instead, you mount it on the host and bind that mountpoint into the sandbox as a host volume at /workspace. The agent sees ordinary files.

Prerequisites

• opensandbox-server 0.2.1 or later, and the opensandbox Python SDK 0.1.13 or later.
• The Docker or Kata runtime. Do not use gVisor or Firecracker: their guest kernels do not see a FUSE mount made on the host, so /workspace appears empty.
• An AIStor endpoint that the host can reach, and signing credentials for it.

Quick start

1. Install and configure the OpenSandbox server:

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

   In ~/.sandbox.toml, set [server].api_key and allow the host mount path, as in the example's sandbox.toml.example:

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

   Then start the server:

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

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="..."

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

3. Download the example, then run it from that directory:

   mkdir aimem-opensandbox && cd aimem-opensandbox
   base=https://docs.min.io/aimem/examples/opensandbox
   for f in aimem-host-mount.sh contract.py main.py sandbox.toml.example; do
     curl -fsSLO "$base/$f"
   done
   chmod +x aimem-host-mount.sh
   
   python main.py

main.py mounts AIStor Memory on the host and creates a sandbox with that mount bound to /workspace. It writes and reads /workspace/probe.txt through separate sandbox commands, checks that path and symlink escapes are rejected, and then unmounts the host mount.

How the host mount works

The example's aimem-host-mount.sh script installs the Linux amd64 or arm64 AIStor Memory binaries if they are missing, and checks them against their .sha256sum files. It mounts the bucket at /mnt/aimem/<sandbox-id>, waits for the mount, and prints the path for main.py. Run aimem-host-mount.sh cleanup <sandbox-id> to remove a host mount after its sandbox exits.

The mount runs as the host user. If aimem does not have CAP_SYS_ADMIN, it passes the FUSE device to the setuid-root aimem-fusermount helper, which performs the mount. That privilege is used on the host only, never in the sandbox.

The script also sets allow_root: true in the --config YAML. The container runtime (dockerd or containerd) runs as root, and a FUSE mount is visible only to the user who mounted it. Without allow_root, the runtime cannot open the mount to bind it into the sandbox. allow_root exists only as a config key, not as a flag.

Reference

• aimem-host-mount.sh, main.py, and sandbox.toml.example: the example. main.py also needs contract.py, the checks it runs through the mount.
• OpenSandbox
• Host-volume mount example
• OpenSandbox Python SDK