mac-sandbox

npm i mac-sandbox -g

sandbox start

Or, to expose your API publicly via a Cloudflare Tunnel:

sandbox start -t

Self-hosted sandbox containers on Apple Silicon Macs, with Cloudflare Tunnel routing and a pairing-based auth flow. Built with Hono, TypeScript, and Apple Containers.

Note: This library is still actively being worked on. If you have feedback or run into issues, feel free to DM @jerrickhakim.

Why this was created

Most sandbox solutions are cloud-hosted and charge per execution. This project creates an API layer that lets you self-host sandboxes on hardware you already own — your Mac. If you have an Apple Silicon Mac sitting around, you can run isolated, ephemeral containers locally and expose them publicly through Cloudflare Tunnels, with no third-party sandbox provider needed.

How it works

Your Mac (port 4000)
  ├── Sandbox API server            ← you talk to this
  └── Apple Container(s)            ← your image, your app

• The Sandbox API runs on your Mac at port 4000 and manages container lifecycle.
• Each sandbox runs your own container image — bring whatever stack you need.
• Containers can be exposed publicly via Cloudflare Tunnels (named or free trycloudflare.com).

Prerequisites

• Apple Silicon Mac (M1/M2/M3/M4)
• Node.js ≥ 20
• Apple Containers CLI (container)
• cloudflared (auto-installed by sandbox setup)

Installation

Install the CLI

npm install -g mac-sandbox

Build your container image

Build any Linux container image that suits your workload and tag it:

container build -t sandbox:latest /path/to/your/Dockerfile

Then point the CLI at it:

sandbox start --image my-image:latest

Verify available images:

container image list

If the build fails, run: container system kernel set --recommended --force

CLI Reference

sandbox <command> [options]

COMMANDS:
  start         Start the sandbox server (auto-installs dependencies)
  setup         Install required dependencies (cloudflared, container CLI)
  health        Check system dependencies
  pair          Generate a new pairing code
  tokens        List all active auth tokens
  list          List all running containers
  delete        Delete all containers
  destroy       Stop container system and delete all containers + volumes

OPTIONS:
  --port, -p        Port to run the server on (default: 4000)
  --tunnel, -t      Enable Cloudflare tunnel (generates a public QR code URL)
  --image, -i       Container image name (default: sandbox)
  --skip-setup      Skip dependency check on startup

Quick start

Local network mode (default):

sandbox start

Prints a QR code, a 6-digit pairing code, and the local network URL (e.g. http://192.168.1.100:4000). Scan the QR code or POST the code to /pairing/confirm from any device on the same network.

Tunnel mode:

sandbox start -t

Same as above, but the QR code points to a public trycloudflare.com URL so remote devices can pair.

Pairing Flow

1. sandbox start                  → server starts, displays QR code + 6-digit code
2. Client scans QR or POSTs code  → POST /pairing/confirm
3. Server returns Bearer token    → client stores it
4. Token used on all API calls    → Authorization: Bearer <token>

Confirm pairing (public — no auth required)

POST /pairing/confirm
Content-Type: application/json

{
  "code": "ABC123",
  "deviceName": "My Laptop"   // optional
}

Response:

{ "token": "tok_secret..." }

Environment Variables

Server (runtime)

| Variable | Default | Description | | -------------------------------- | --------- | ------------------------------------------------------------------------------- | | PORT | 4000 | Port the sandbox API server listens on | | SANDBOX_IMAGE | sandbox | Container image name used when spawning sandboxes | | FLAGS_DESTROY_CONTAINERS | — | Set "true" to stop & delete all containers on server shutdown | | FLAGS_PRESERVE_SANDBOX_TUNNELS | — | Set "true" to also tear down per-sandbox Cloudflare tunnels on shutdown | | AUTO_INSTALL_CONTAINER_PKG | — | Set "1" to run sudo installer silently instead of opening the GUI installer |

Cloudflare (optional — only for named tunnels)

Skip these if you use free trycloudflare.com tunnels and pass flags.tunnel: false when creating sandboxes.

| Variable | Description | | --------------------------- | -------------------------------------------- | | CLOUDFLARE_TUNNEL_API_KEY | Cloudflare API token with tunnel permissions | | CLOUDFLARE_ACCOUNT_ID | Cloudflare account ID | | CLOUDFLARE_ZONE_ID | Cloudflare zone ID for your domain |

Sandbox API

All sandbox endpoints require Authorization: Bearer <token>.

Create sandbox

POST /sandbox/create

{
  "cpus": 2,
  "memory": "4G",
  "storage": "10G",
  "volumeId": "existing-volume-id",
  "flags": {
    "tunnel": false,
    "lan": true
  },
  "healthCheck": {
    "url": "tunnel",
    "timeout": 5000,
    "interval": 1000,
    "maxAttempts": 10,
    "destroy": true
  },
  "env": {
    "MY_VAR": "my-value"
  }
}

env is an arbitrary key/value map passed as environment variables to your container. Use it however your image expects.

storage options: 1G 5G 10G 15G 20G 25G 30G 32G 64G 128G

Response:

{
  "id": "abc123",
  "ipAddress": "192.168.64.5",
  "urls": {
    "tunnel": "https://abc.trycloudflare.com",
    "lan": "http://192.168.1.100:8080",
    "container": "http://192.168.64.5:80"
  }
}

Other sandbox endpoints

| Method | Endpoint | Description | | -------- | ---------------------- | ------------------------------------------------------------------ | | GET | /sandbox/list | List all sandboxes | | GET | /sandbox/:id | Get sandbox details | | GET | /sandbox/:id/health | Check container reachability | | GET | /sandbox/:id/inspect | Full inspection: sandbox + container + volume info | | DELETE | /sandbox/:id | Stop and remove sandbox (?preserveStorage=true keeps the volume) |

Attach a Cloudflare tunnel

POST /sandbox/:id/tunnel

{
  "tunnelToken": "<from-cloudflare>",
  "tunnelId": "<tunnel-uuid>",
  "url": "https://abc123.yourdomain.com",
  "checkhealth": true
}

Execute a command

POST /sandbox/:id/exec

{
  "command": "npm",
  "args": ["run", "build"],
  "timeout": 30000,
  "user": "node"
}

Response:

{
  "success": true,
  "exitCode": 0,
  "stdout": "...",
  "stderr": "",
  "durationMs": 1234
}

Execute with streaming output (SSE)

POST /sandbox/:id/exec/stream

Same request body as /exec. Returns a Server-Sent Events stream with events:

| Event | Payload | | -------- | ------------------------------------- | | stdout | Base64-encoded stdout chunk | | stderr | Base64-encoded stderr chunk | | exit | { exitCode, signal } | | error | { error } | | ping | { timestamp } (keepalive every 15s) |

Volume API

Persistent volumes can be attached to sandboxes at /workspace.

| Method | Endpoint | Description | | -------- | ---------------------- | ----------------------- | | POST | /volume/create | Create a volume | | GET | /volume/list | List all volumes | | GET | /volume/:id | Get volume details | | DELETE | /volume/:id | Delete a volume | | POST | /volume/batch-delete | Delete multiple volumes |

Create a volume

POST /volume/create

{
  "id": "my-volume",
  "size": "10G",
  "label": "my-label"
}

Attach a volume to a sandbox

Pass volumeId in the create sandbox request to mount an existing volume at /workspace:

{ "volumeId": "my-volume", ... }

Or pass storage: "10G" to create and mount a new volume automatically.

API Documentation

The server serves interactive API docs:

• Scalar UI: http://localhost:4000/reference
• OpenAPI JSON: http://localhost:4000/doc

Server Integration Example

Minimal backend code to create a sandbox and wire up a Cloudflare tunnel:

import axios from "axios";

const api = axios.create({
  baseURL: "https://xyz.trycloudflare.com", // from pairing
  headers: { Authorization: `Bearer ${platformToken}` },
});

// 1. Create sandbox
const { data } = await api.post("/sandbox/create", {
  cpus: 2,
  memory: "4G",
  env: {
    // pass whatever env vars your image expects
    MY_VAR: "my-value",
  },
});

const { id: sandboxId, ipAddress } = data;

// 2. Create a named Cloudflare tunnel + CNAME pointing to the container
const { tunnelId, tunnelToken } = await createCloudflareTunnel({
  hostname: `${sandboxId}.yourdomain.com`,
  localServiceUrl: `http://${ipAddress}:80`,
});

// 3. Send tunnel credentials to Mac so cloudflared starts in the container
await api.post(`/sandbox/${sandboxId}/tunnel`, {
  tunnelToken,
  tunnelId,
  url: `https://${sandboxId}.yourdomain.com`,
  checkhealth: true,
});

Type Definitions

interface SandboxConfig {
  cpus?: number;
  memory?: string;
  storage?: "1G" | "5G" | "10G" | "15G" | "20G" | "25G" | "30G" | "32G" | "64G" | "128G" | null;
  volumeId?: string;
  flags?: { tunnel?: boolean; lan?: boolean };
  healthCheck?: {
    url?: "tunnel" | "lan" | "container";
    timeout?: number;
    interval?: number;
    maxAttempts?: number;
    destroy?: boolean;
  };
  env?: Record<string, string>;
}

interface SandboxEntry {
  id: string;
  ipAddress: string;
  hostPort: number;
  createdAt: number;
  volume: string | null;
  urls: {
    tunnel: string | null;
    lan: string | null;
    container: string;
  };
}

interface ExecRequest {
  command: string;
  args?: string[];
  timeout?: number;
  user?: string;
}

interface ExecResponse {
  success: boolean;
  command: string;
  args?: string[];
  exitCode: number;
  stdout: string;
  stderr: string;
  durationMs: number;
}

Troubleshooting

| Issue | Solution | | ---------------------------------------------- | --------------------------------------------------- | | Container build fails | container system kernel set --recommended --force | | Build export error: "structure needs cleaning" | See Build Export Error below | | Stuck containers | sandbox restart or sandbox destroy | | cloudflared not found | sandbox setup | | Container system not running | container system start |

Build export error

If you see Error: failed to write compressed diff: lstat /tmp/containerd-mount*: structure needs cleaning:

# 1. Clean stale mounts
sudo rm -rf /tmp/containerd-mount*

# 2. Restart container system
container system stop && container system start

# 3. Retry build without cache
container build --no-cache -t sandbox:latest .

If it still fails:

container system kernel set --recommended --force
container system start
container build -t sandbox:latest .

License

MIT