@mastra/apple-container 0.0.0-agent-learning-fetch-again-20260701195212

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @mastra/apple-container
+
+## 0.0.0-agent-learning-fetch-again-20260701195212
+
+### Minor Changes
+
+- Add an Apple container CLI workspace sandbox provider. ([#18643](https://github.com/mastra-ai/mastra/pull/18643))
+
+  ```ts
+  import { AppleContainerSandbox } from '@mastra/apple-container';
+
+  const sandbox = new AppleContainerSandbox({
+    id: 'local-apple-container',
+    image: 'node:22-slim',
+    volumes: { [process.cwd()]: '/workspace' },
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`0f69865`](https://github.com/mastra-ai/mastra/commit/0f69865aced225d98eac812e22699dc445ee18cb), [`cc440a3`](https://github.com/mastra-ai/mastra/commit/cc440a39400d8ce06655462b26c1666a1b3d4320), [`ea6327b`](https://github.com/mastra-ai/mastra/commit/ea6327ba2d63ca647804bc97b347e03a58617162), [`3439fa8`](https://github.com/mastra-ai/mastra/commit/3439fa836ecfcaa257b40c20b30ac2a8be22e9ea), [`85107f2`](https://github.com/mastra-ai/mastra/commit/85107f2758b527147fccbedff962961927c2d3b8), [`06ff9e0`](https://github.com/mastra-ai/mastra/commit/06ff9e0befd1d642ab87ff749285ee4091205c7e), [`7f5e1ff`](https://github.com/mastra-ai/mastra/commit/7f5e1ff695a92f672bb3976363925d1e9136b54a), [`b8375c1`](https://github.com/mastra-ai/mastra/commit/b8375c1f8fe905df8ae2ae9a893bb365f17aec4e), [`003f35d`](https://github.com/mastra-ai/mastra/commit/003f35d19e07b23b4bacc591c8bc0c59b42124ae)]:
+  - @mastra/core@0.0.0-agent-learning-fetch-again-20260701195212

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,118 @@
+# @mastra/apple-container
+
+Apple container CLI sandbox provider for [Mastra](https://mastra.ai) workspaces.
+
+Implements the `WorkspaceSandbox` interface with Apple's [`container`](https://github.com/apple/container) CLI. The provider starts a long-lived OCI Linux container and runs workspace commands through `container exec`.
+
+## Install
+
+```bash
+pnpm add @mastra/apple-container @mastra/core
+```
+
+Requires Apple silicon, macOS 26 or newer, and the Apple `container` CLI. Start Apple's container system before using the provider:
+
+```bash
+container system start
+```
+
+## Usage
+
+```typescript
+import { Workspace } from '@mastra/core/workspace';
+import { AppleContainerSandbox } from '@mastra/apple-container';
+
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/Users/me/project': '/workspace',
+  },
+  workingDir: '/workspace',
+});
+
+const workspace = new Workspace({ sandbox });
+await workspace.init();
+
+const result = await workspace.sandbox?.executeCommand?.('node', ['--version']);
+console.log(result?.stdout);
+
+await workspace.destroy();
+```
+
+## Options
+
+| Option             | Type                         | Description                                                        |
+| ------------------ | ---------------------------- | ------------------------------------------------------------------ |
+| `id`               | `string`                     | Unique sandbox ID.                                                 |
+| `name`             | `string`                     | Apple container name. Defaults to the sandbox ID.                  |
+| `image`            | `string`                     | OCI image to run. Defaults to `node:22-slim`.                      |
+| `command`          | `string[]`                   | Container init command. Defaults to `['sleep', 'infinity']`.       |
+| `env`              | `Record<string, string>`     | Environment variables applied to the container and command execs.  |
+| `volumes`          | `Record<string, string>`     | Host-to-container bind mounts.                                     |
+| `mounts`           | `string[]`                   | Raw `--mount` specs passed to `container run`.                     |
+| `network`          | `string`                     | Apple container network attachment spec.                           |
+| `publishedPorts`   | `string[]`                   | Port publish specs passed as `--publish`.                          |
+| `publishedSockets` | `string[]`                   | Socket publish specs passed as `--publish-socket`.                 |
+| `cpus`             | `number \| string`           | Number of CPUs allocated to the container.                         |
+| `memory`           | `string`                     | Memory allocation, for example `1G`.                               |
+| `platform`         | `string`                     | OCI platform, for example `linux/arm64`.                           |
+| `arch`             | `string`                     | Image architecture when selecting multi-arch images.               |
+| `os`               | `string`                     | Operating system when selecting multi-platform images.             |
+| `rosetta`          | `boolean`                    | Enable Rosetta in the container.                                   |
+| `readonlyRootfs`   | `boolean`                    | Start the container with a read-only root filesystem.              |
+| `ssh`              | `boolean`                    | Forward the host SSH agent socket.                                 |
+| `init`             | `boolean`                    | Enable Apple's init process in the container.                      |
+| `virtualization`   | `boolean`                    | Expose virtualization capabilities to the container.               |
+| `capAdd`           | `string[]`                   | Linux capabilities to add.                                         |
+| `capDrop`          | `string[]`                   | Linux capabilities to drop.                                        |
+| `tmpfs`            | `string[]`                   | tmpfs destination paths, for example `/tmp`.                       |
+| `dns`              | `string[]`                   | DNS nameserver IPs.                                                |
+| `dnsSearch`        | `string[]`                   | DNS search domains.                                                |
+| `noDns`            | `boolean`                    | Do not configure DNS in the container.                             |
+| `labels`           | `Record<string, string>`     | Container labels. Mastra labels are always added.                  |
+| `workingDir`       | `string`                     | Working directory inside the container. Defaults to `/workspace`.  |
+| `timeout`          | `number`                     | Default command timeout in milliseconds.                           |
+| `deleteOnDestroy`  | `boolean`                    | Delete the Apple container on destroy. Defaults to `true`.         |
+| `containerBinary`  | `string`                     | Path or name for the Apple container CLI. Defaults to `container`. |
+| `onStart`          | `({ sandbox }) => unknown`   | Lifecycle hook called after the sandbox reaches `running`.         |
+| `onStop`           | `({ sandbox }) => unknown`   | Lifecycle hook called before the sandbox stops.                    |
+| `onDestroy`        | `({ sandbox }) => unknown`   | Lifecycle hook called before the sandbox is destroyed.             |
+| `instructions`     | `string \| (opts) => string` | Override or extend the default workspace sandbox instructions.     |
+
+Apple `--tmpfs` accepts container paths only, such as `/tmp`; it does not accept Docker-style option specs like `/tmp:rw,size=256m`.
+When `readonlyRootfs` is enabled, make sure `workingDir` points to a path supplied by the image, a bind mount, or a writable tmpfs.
+
+## Security model
+
+This provider runs local containers through the host Apple `container` service. Treat constructor options as trusted server-side configuration:
+
+- `volumes`, `mounts`, and `publishedSockets` can expose host paths to containerized code.
+- `publishedPorts` can expose in-container services on the host or network; bind to `127.0.0.1` when only local access is intended.
+- `ssh` forwards the host SSH agent socket.
+- `capAdd` and `virtualization` can expand what containerized code can do.
+- `containerBinary` is intentionally a constructor-only escape hatch for trusted code and is not part of the serializable editor provider schema.
+
+Use the narrowest mounts and capabilities your workload needs. Existing containers are only reconnected when they carry Mastra ownership labels for the sandbox ID. Containers created by this provider also include a config-hash label; when that label is present, reconnect fails if immutable runtime options such as image, command, mounts, ports, capabilities, or working directory changed.
+
+## Limitations
+
+`AppleContainerSandbox` implements foreground workspace command execution with `executeCommand()`. It does not yet expose a `SandboxProcessManager` for background processes or LSP sessions.
+
+Command timeouts are enforced inside the container so timed-out commands are cleaned up by the container runtime. Abort signals cancel the host CLI wait path and should not be used as a substitute for command timeouts when in-container cleanup matters.
+
+## Editor provider
+
+Register the provider with `MastraEditor` to hydrate stored sandbox configs:
+
+```typescript
+import { MastraEditor } from '@mastra/editor';
+import { appleContainerSandboxProvider } from '@mastra/apple-container';
+
+const editor = new MastraEditor({
+  sandboxes: { [appleContainerSandboxProvider.id]: appleContainerSandboxProvider },
+});
+```
+
+## License
+
+Apache-2.0