Apple container sandboxes

Apple's container runs each Linux container in its own lightweight VM on a Mac. @mayurajs/sandbox-apple-container makes each sandbox one such container and plugs them into mayura/sandbox, so agents get them through the same createSandboxes pool, limits and tools as the built-in Docker sandboxes. It drives the container command line as a child process, without a shell, and has no dependencies. It runs on Node only, on a Mac with macOS 26 on Apple silicon, with container installed and its system service started (container system start).

#Install

npm install mayura @mayurajs/sandbox-apple-container

Then pull the images your sandboxes run: images are never pulled for you.

container image pull docker.io/library/python:3.13-slim

#Credentials

None: sandboxes run on your Mac. Nothing is read from the environment.

#Use it

import { createSandboxes, sandboxTools } from 'mayura/sandbox';
import { appleContainerSandboxes } from '@mayurajs/sandbox-apple-container';

const sandboxes = createSandboxes(appleContainerSandboxes({
  image: 'docker.io/library/python:3.13-slim',
  hostOnlyNetwork: 'mayura-offline',
}), {
  maxSandboxes: 4,
  maxLifetimeMs: 3_600_000,
});

const sandbox = await sandboxes.create({ lifetimeMs: 600_000 }); // network 'none': on the host-only network
const result = await sandbox.exec(['python3', '-c', 'print(6 * 7)']);
console.log(result.exitCode, result.stdout); // 0 "42\n"
await sandbox.release();

// Or give an agent tools that work in the sandbox; grant tool:workspace.exec, sandbox:workspace:exec and effect:write.
const tools = sandboxTools(sandbox, { name: 'workspace', exec: true });

createSandboxes enforces your limits before anything is run. See Sandboxes for the pool, per-run sandboxes and every tool.

#Options

A sandbox may ask for fewer whole cpus and less memoryMiB, never more. Its labels become container labels, beside mayura.sandbox=true. A sandbox whose working directory cannot be made is deleted, and create fails.

#Lifetime

Each container runs sleep for the sandbox's lifetime, under an init that reaps processes, and is removed when it ends (--rm). A release deletes it sooner (container delete --force); one already gone counts as released.

#Network and ports

Apple's container has no network that reaches nothing. What this provider can enforce depends on hostOnlyNetwork:

• Without it, features.network is ['all'] only: list 'all' in the network option of createSandboxes and ask for it in create. The default 'none' fails with INVALID_INPUT before anything is run.
• With it, sandboxes created with 'none' go on that host-only network, made with container network create --internal if it is missing. It reaches no further than this Mac, but it does reach this Mac: services listening on it are reachable from the sandbox. Sandboxes created with 'all' use the default network.

Domain allowlists, ports and a desktop are not available.

#Commands and files

Commands run with container exec, through sh in their directory. The sandbox's env is written to a file in the sandbox when it is created, and each command's own env to a file that is read and removed before the command starts, so no value of env is ever on a command line on your Mac. Standard input is passed to the command, and only as much output as you keep (maxOutputBytes) is read.

A timeout or cancellation kills every process the command started, found by a tag in their environment, then the container exec process.

Files are read, written, listed and removed through commands in the sandbox, so the image needs a POSIX shell and the usual tools. Reads stop at the size you allow and fail with LIMIT_EXCEEDED beyond it.

#Errors

#How it is tested

• Unit tests check the configuration it refuses, the networks it claims, and that ports, extra CPUs or memory, and a missing command line are refused before anything runs.
• An integration test runs the sandbox conformance suite through a stand-in container that runs the same command lines with Docker, whose flags match, and checks the host-only network, that no environment is left behind, and that a failed setup is deleted.
• It has not been run against a real Mac yet: the live check, scripts/live/sandbox-apple-container.mjs, needs a Mac with macOS 26 on Apple silicon.

#Related

• Sandboxes: pools, per-run sandboxes, tools and the built-in Docker sandboxes.
• Fly.io Machines sandboxes: another provider that cannot keep sandboxes offline.
• Code Mode: run model-written programs in a sandbox.