@unionstreet/apple-sandboxes 0.1.0

package/dist/store.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { storePaths } from './paths.js';
+import { ensureDir, exists, readJson, writeJson } from './util.js';
+const prefixes = {
+    sandboxes: 'sbx',
+    images: 'img',
+    snapshots: 'snap',
+    volumes: 'vol',
+};
+export class Store {
+    paths;
+    constructor(root) {
+        this.paths = storePaths(root);
+    }
+    async init() {
+        await Promise.all(Object.values(this.paths).map((dir) => ensureDir(dir)));
+    }
+    dir(kind, id) {
+        return path.join(this.paths[kind], id);
+    }
+    meta(kind, id) {
+        return path.join(this.dir(kind, id), 'meta.json');
+    }
+    async put(kind, value) {
+        await writeJson(this.meta(kind, value.id), value);
+        return value;
+    }
+    async get(kind, idOrName) {
+        const direct = this.meta(kind, idOrName);
+        if (await exists(direct))
+            return readJson(direct);
+        for (const item of await this.list(kind)) {
+            if (item.name === idOrName)
+                return item;
+        }
+        throw Object.assign(new Error(`${kind.slice(0, -1)} not found`), { status: 404 });
+    }
+    async list(kind) {
+        const dir = this.paths[kind];
+        await ensureDir(dir);
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const metas = entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(`${prefixes[kind]}_`))
+            .map((entry) => path.join(dir, entry.name, 'meta.json'));
+        const existing = await Promise.all(metas.map(async (file) => ((await exists(file)) ? file : undefined)));
+        const values = await Promise.all(existing.filter(Boolean).map((file) => readJson(file)));
+        return values.reverse();
+    }
+    async delete(kind, idOrName) {
+        const item = await this.get(kind, idOrName);
+        await fs.rm(this.dir(kind, item.id), { recursive: true, force: true });
+        return item.id;
+    }
+    sandboxWorkspace(id) {
+        return path.join(this.dir('sandboxes', id), 'workspace');
+    }
+    sandboxSnapshots(id) {
+        return path.join(this.dir('sandboxes', id), 'snapshots');
+    }
+    imageContext(id) {
+        return path.join(this.dir('images', id), 'context');
+    }
+    snapshotArchive(id) {
+        return path.join(this.dir('snapshots', id), 'workspace.tar.gz');
+    }
+    volumePath(id) {
+        return path.join(this.dir('volumes', id), 'data');
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,128 @@
+export type SandboxState = 'creating' | 'created' | 'running' | 'stopped' | 'deleted' | 'error';
+export type NetworkMode = 'deny' | 'open';
+export interface NetworkPolicy {
+    mode?: NetworkMode;
+    allowedHosts?: string[];
+}
+export interface VolumeMount {
+    volumeId: string;
+    mountPath: string;
+    readonly?: boolean;
+}
+export interface CreateSandboxRequest {
+    name?: string;
+    image?: string;
+    imageId?: string;
+    snapshotId?: string;
+    env?: Record<string, string>;
+    cpus?: number;
+    memory?: string;
+    network?: boolean | NetworkPolicy;
+    autoStart?: boolean;
+    idleTimeoutSeconds?: number;
+    maxLifetimeSeconds?: number;
+    autoDeleteSeconds?: number;
+    volumes?: VolumeMount[];
+}
+export interface Sandbox {
+    id: string;
+    name: string;
+    state: SandboxState;
+    source: 'inline' | 'image' | 'snapshot';
+    image: string;
+    imageId?: string;
+    snapshotId?: string;
+    containerName: string;
+    workspace: string;
+    cpus: number;
+    memory: string;
+    network: NetworkPolicy;
+    volumes: VolumeMount[];
+    createdAt: string;
+    updatedAt: string;
+    lastActivityAt: string;
+    idleTimeoutSeconds?: number;
+    maxLifetimeSeconds?: number;
+    autoDeleteSeconds?: number;
+    ssh?: SshAccess;
+}
+export interface ExecRequest {
+    command: string;
+    timeoutSeconds?: number;
+    env?: Record<string, string>;
+    background?: boolean;
+}
+export interface ExecResult {
+    id: string;
+    sandboxId: string;
+    command: string;
+    status: 'queued' | 'running' | 'succeeded' | 'failed' | 'timed_out' | 'error';
+    exitCode?: number | null;
+    stdout?: string;
+    stderr?: string;
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+}
+export interface CreateImageRequest {
+    name: string;
+    image?: string;
+    dockerfile?: string;
+    build?: boolean;
+    cpus?: number;
+    memory?: string;
+    labels?: Record<string, string>;
+}
+export interface ImageDefinition {
+    id: string;
+    name: string;
+    image: string;
+    state: 'created' | 'building' | 'ready' | 'error';
+    hasDockerfile: boolean;
+    cpus: number;
+    memory: string;
+    labels: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+    error?: string;
+}
+export interface CreateSnapshotRequest {
+    name: string;
+    sandboxId: string;
+    labels?: Record<string, string>;
+}
+export interface Snapshot {
+    id: string;
+    name: string;
+    state: 'ready' | 'error';
+    sourceSandboxId: string;
+    image: string;
+    archivePath: string;
+    archiveBytes: number;
+    workspaceBytes: number;
+    labels: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateVolumeRequest {
+    name: string;
+    labels?: Record<string, string>;
+}
+export interface DeleteVolumeOptions {
+    force?: boolean;
+}
+export interface Volume {
+    id: string;
+    name: string;
+    path: string;
+    labels: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SshAccess {
+    host: string;
+    port: number;
+    user: string;
+    identityFile?: string;
+    command: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/util.d.ts

@@ -0,0 +1,15 @@
+export declare function id(prefix: string): string;
+export declare function now(): string;
+export declare function ensureDir(dir: string): Promise<void>;
+export declare function readJson<T>(file: string): Promise<T>;
+export declare function writeJson(file: string, value: unknown): Promise<void>;
+export declare function exists(file: string): Promise<boolean>;
+export declare function run(cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<{
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+export declare function safeJoin(root: string, requested: string): string;

package/dist/util.js

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export function id(prefix) {
+    return `${prefix}_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+}
+export function now() {
+    return new Date().toISOString();
+}
+export async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+export async function readJson(file) {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+}
+export async function writeJson(file, value) {
+    await ensureDir(path.dirname(file));
+    await fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function exists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function run(cmd, args, opts = {}) {
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    const timer = opts.timeoutMs
+        ? setTimeout(() => {
+            child.kill('SIGKILL');
+        }, opts.timeoutMs)
+        : undefined;
+    child.stdout.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+    child.stderr.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+    const exitCode = await new Promise((resolve) => {
+        child.on('error', (error) => {
+            stderr.push(Buffer.from(error.message));
+            resolve(127);
+        });
+        child.on('close', resolve);
+    });
+    if (timer)
+        clearTimeout(timer);
+    return {
+        exitCode,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+    };
+}
+export function safeJoin(root, requested) {
+    const target = path.resolve(root, requested.replace(/^\/+/, ''));
+    const resolvedRoot = path.resolve(root);
+    if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new Error('path escapes root');
+    }
+    return target;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,130 @@
+# Architecture
+
+`apple-sandboxes` is a local control plane for Apple's native `container` runtime.
+
+The shape is inspired by systems like Gondolin and Daytona, but the implementation is intentionally Apple-container-native:
+
+- no Docker daemon
+- no Linux host requirement
+- no microVM guest image pipeline
+- no rootful daemon
+
+## Primitives
+
+### Image
+
+An image is a named runtime definition.
+
+It can be:
+
+- a reference to an existing OCI image, such as `ubuntu:24.04`
+- a Dockerfile/Containerfile stored in the local registry and built with `container build`
+
+Images are stored under:
+
+```text
+~/.apple-sandboxes/images
+```
+
+### Sandbox
+
+A sandbox is a long-lived Apple container with:
+
+- a host-backed `/workspace`
+- optional named volume mounts
+- CPU/memory limits
+- a network policy
+- lifecycle metadata
+
+Sandboxes are stored under:
+
+```text
+~/.apple-sandboxes/sandboxes
+```
+
+### Snapshot
+
+A snapshot is a reusable `/workspace` archive.
+
+Creating a new sandbox from a snapshot restores the archive into a fresh sandbox workspace before the container starts.
+
+Snapshots are stored under:
+
+```text
+~/.apple-sandboxes/snapshots
+```
+
+This is a workspace snapshot, not a VM checkpoint and not a full root filesystem snapshot.
+
+### Volume
+
+A volume is a named persistent host directory mounted into one or more sandboxes.
+
+Volumes are stored under:
+
+```text
+~/.apple-sandboxes/volumes
+```
+
+## Runtime Model
+
+Sandbox creation maps to Apple `container create`:
+
+```text
+container create \
+  --platform linux/arm64 \
+  --cpus N \
+  --memory SIZE \
+  --mount type=bind,source=WORKSPACE,target=/workspace \
+  --workdir /workspace \
+  IMAGE \
+  sh -lc 'while true; do sleep 3600; done'
+```
+
+Command execution maps to:
+
+```text
+container exec -w /workspace CONTAINER sh -lc COMMAND
+```
+
+## Network Model
+
+The first implementation supports:
+
+- `deny`: maps to `--network none`
+- `open`: leaves the default Apple container network enabled
+
+The intended next step is a host-mediated allowlist model:
+
+```json
+{
+  "network": {
+    "mode": "allowlist",
+    "allowedHosts": ["api.github.com"]
+  }
+}
+```
+
+That is closer to Gondolin's policy direction, but is not implemented yet.
+
+## SSH Model
+
+SSH is not implemented in this first cut.
+
+The intended shape is:
+
+- generate ephemeral Ed25519 keys
+- inject the public key into the sandbox
+- run `sshd` inside a prepared sandbox image
+- bind only to a localhost host port
+- return a hardened SSH command with agent/forwarding disabled
+
+## API Layers
+
+The package exposes:
+
+- TypeScript runtime class: `AppleSandboxRuntime`
+- TypeScript HTTP client: `AppleSandboxes`
+- Express API server
+- npm CLI: `apple-sandboxes`
+

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@unionstreet/apple-sandboxes",
+  "version": "0.1.0",
+  "description": "Daytona/Gondolin-inspired sandbox API for Apple container on Apple Silicon Macs.",
+  "type": "module",
+  "bin": {
+    "apple-sandboxes": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js serve",
+    "test": "tsx --test test/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run test"
+  },
+  "keywords": [
+    "apple-container",
+    "sandbox",
+    "agents",
+    "local-first",
+    "macos"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/UnionStreetAI/apple-sandboxes#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UnionStreetAI/apple-sandboxes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/UnionStreetAI/apple-sandboxes/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/node": "^24.10.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}