apple-sandboxes

Local dev and agent sandboxes for Apple Silicon Macs, built on Apple's native container runtime.

It gives you long-lived Linux containers with a stable /workspace, command execution, snapshots, volumes, lifecycle limits, an HTTP API, a TypeScript SDK, and a CLI.

It is not a microVM security boundary. It is a lightweight Apple-container-native layer for local development and agent workloads.

Requirements

• macOS on Apple Silicon
• Node.js 20+
• Apple container

container system status
container run --rm --platform linux/arm64 alpine:3.20 uname -a

Quick Start

npm install -g @unionstreet/apple-sandboxes
apple-sandboxes serve

The server listens on 127.0.0.1:9102 by default.

For Tailscale, LAN, or public access, require an API key:

APPLE_SANDBOXES_API_KEY="$(openssl rand -hex 32)" \
  apple-sandboxes serve --host 0.0.0.0

CLI

npx @unionstreet/apple-sandboxes serve

apple-sandboxes image create ubuntu-base ubuntu:24.04
apple-sandboxes sandbox create --name dev --image-id ubuntu-base
apple-sandboxes sandbox exec dev 'uname -a; pwd; echo hello > hello.txt'
apple-sandboxes snapshot create baseline dev
apple-sandboxes sandbox create --name forked --snapshot-id baseline

SDK

import { AppleSandboxes } from '@unionstreet/apple-sandboxes'

const client = new AppleSandboxes('http://127.0.0.1:9102', process.env.APPLE_SANDBOXES_API_KEY)

const image = await client.images.create({
  name: 'ubuntu-base',
  image: 'ubuntu:24.04',
})

const sandbox = await client.sandboxes.create({
  name: 'dev',
  imageId: image.id,
  cpus: 2,
  memory: '2G',
  network: false,
  idleTimeoutSeconds: 900,
})

const result = await client.sandboxes.exec(sandbox.id, {
  command: 'python3 --version',
})

console.log(result.stdout)

Primitives

• Image: a named OCI image ref or Dockerfile/Containerfile definition built with container build.
• Sandbox: a long-lived Apple container with a host-backed /workspace.
• Snapshot: a reusable /workspace archive used to fork new sandboxes.
• Volume: a named persistent host directory mounted into sandboxes.
• Lifecycle policy: idle, max-lifetime, and auto-delete limits enforced by the server reaper.

HTTP API

GET    /health         (always public)
GET    /openapi.json   (always public)

/v1/images      create, list, build, delete image definitions
/v1/volumes     create, list, delete persistent host volumes
/v1/snapshots   create, list, delete workspace snapshots
/v1/sandboxes   create, list, start, stop, exec, delete
/v1/sandboxes/:id/files/*   read and write workspace files

State

State lives in ~/.apple-sandboxes unless APPLE_SANDBOXES_HOME is set.

APPLE_SANDBOXES_HOME=/path/to/state apple-sandboxes serve

Limits

• Network policy is currently deny or open.
• SSH, PTY sessions, service ingress, and secret policy are not implemented yet.
• /openapi.json is a route index, not a full schema contract yet.

License

Apache-2.0