@groundbox/mastra 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +9 -0
- package/README.md +132 -2
- package/dist/index.cjs +1258 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +375 -0
- package/dist/index.d.ts +375 -0
- package/dist/index.js +1237 -0
- package/dist/index.js.map +1 -0
- package/package.json +70 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Groundbox
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,133 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @groundbox/mastra
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[Groundbox](https://groundbox.dev) sandboxes for [Mastra](https://mastra.ai) workspaces. Each sandbox
|
|
4
|
+
is a Firecracker microVM with its own cores: Ubuntu 24.04 with git, Node, Python and Docker, a
|
|
5
|
+
20 GB disk, and user `runner` with passwordless sudo. It plugs into Mastra's `WorkspaceSandbox`
|
|
6
|
+
interface the same way `@mastra/e2b` and `@mastra/daytona` do, so an agent gets
|
|
7
|
+
`mastra_workspace_execute_command`, background processes, file tools and, with a desktop,
|
|
8
|
+
computer-use tools that all run in the VM.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @groundbox/mastra @mastra/core
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Node 22.13 or newer. Set `GROUNDBOX_API_KEY` (create a key at https://app.groundbox.dev/keys), or
|
|
17
|
+
pass `apiKey`.
|
|
18
|
+
|
|
19
|
+
## Use it in a workspace
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import { Agent } from '@mastra/core/agent';
|
|
23
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
24
|
+
import { GroundboxSandbox } from '@groundbox/mastra';
|
|
25
|
+
|
|
26
|
+
const sandbox = new GroundboxSandbox({
|
|
27
|
+
cpus: 2,
|
|
28
|
+
timeoutMinutes: 60, // lifetime of the VM; the default action at the end is delete
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
const workspace = new Workspace({
|
|
32
|
+
sandbox,
|
|
33
|
+
filesystem: sandbox.filesystem, // optional: file tools on the VM's own disk
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
const agent = new Agent({
|
|
37
|
+
id: 'coder',
|
|
38
|
+
name: 'coder',
|
|
39
|
+
instructions: 'You are a careful engineer. Use the workspace to run code.',
|
|
40
|
+
model: 'openai/gpt-4.1',
|
|
41
|
+
workspace,
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
const result = await agent.generate('Write a Python script that prints the first 20 primes, then run it.');
|
|
45
|
+
console.log(result.text);
|
|
46
|
+
|
|
47
|
+
await workspace.destroy(); // deletes the VM
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Without an agent:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
const sandbox = new GroundboxSandbox();
|
|
54
|
+
await sandbox.start();
|
|
55
|
+
const { stdout } = await sandbox.executeCommand('python3', ['-c', 'print(6 * 7)']);
|
|
56
|
+
await sandbox.destroy();
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## What maps to what
|
|
60
|
+
|
|
61
|
+
| Mastra | Groundbox |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| `start()` | Finds the sandbox for this `id` (metadata `mastra-sandbox-id`) and resumes or starts it; otherwise creates one. Reports `created` or `connected`. |
|
|
64
|
+
| `stop()` | Pauses the VM: memory, processes and disk are kept, only storage is billed. A sandbox with volumes is shut down instead (disk kept). |
|
|
65
|
+
| `destroy()` | Deletes the VM. Billing stops. |
|
|
66
|
+
| `executeCommand()` | One `POST /exec` call. With `onStdout`/`onStderr` or an `abortSignal` (as Mastra's tools pass), a background command followed over the exec stream. |
|
|
67
|
+
| `processes` | Background commands (`ex_...` ids): spawn, stdin, close stdin, kill, list, and `get(id)` to pick up a command started elsewhere. Output survives a dropped connection. |
|
|
68
|
+
| `filesystem` | Groundbox's files API (read, write, list, stat, mkdir, delete); copy, move and append run as one `sh` command in the VM. |
|
|
69
|
+
| `writeFiles()` | One tar.gz upload, file modes kept. |
|
|
70
|
+
| `networking.getPortUrl(port)` | A Groundbox preview, `https://<slug>-<port>.groundbox.page`. |
|
|
71
|
+
| `computer` | With `desktop: true`: screenshots, mouse, keyboard and a live-view link for a Linux desktop with Chrome. |
|
|
72
|
+
| `snapshot()` / checkpoints | A kept Groundbox snapshot (memory, disk and processes) labelled with `checkpointName`; the next start for that name boots from it. |
|
|
73
|
+
| `clone()` | A sibling sandbox with the same settings; `idleTimeoutMinutes` becomes Groundbox's idle pause. |
|
|
74
|
+
| `groundboxSandboxProvider` | Registers the sandbox with the Mastra editor: `new MastraEditor({ sandboxes: [groundboxSandboxProvider] })`. |
|
|
75
|
+
|
|
76
|
+
`sandbox.groundbox` is the `@groundbox/sdk` client and `sandbox.sandboxId` the VM's id, for
|
|
77
|
+
anything this package does not wrap (fork, save points, egress changes while it runs).
|
|
78
|
+
|
|
79
|
+
## Options
|
|
80
|
+
|
|
81
|
+
| Option | Default | |
|
|
82
|
+
| --- | --- | --- |
|
|
83
|
+
| `id` | random | Logical id. A later start with the same id, in any process, reconnects to the same VM. |
|
|
84
|
+
| `sandboxId` | | Reattach to this `sbx_...` first. |
|
|
85
|
+
| `apiKey`, `baseUrl` | `GROUNDBOX_API_KEY` | |
|
|
86
|
+
| `timeout` | `300000` | Default command timeout in ms. |
|
|
87
|
+
| `cpus`, `memoryGb`, `diskGb` | 2, 2 per vCPU, 20 | Up to 16 vCPUs and 4 GB per vCPU. |
|
|
88
|
+
| `image` | | A Docker image (`python:3.12-slim`, or one in your Groundbox registry). Commands run as root. |
|
|
89
|
+
| `template`, `snapshotId` | | Start from a Groundbox template or kept snapshot. |
|
|
90
|
+
| `env` | | Set on the VM and kept as Mastra's env overlay (`setEnv` changes it later). |
|
|
91
|
+
| `secrets`, `envFromSecrets` | | Team secrets as environment variables. |
|
|
92
|
+
| `allowHosts`, `denyHosts` | | Egress rules: names, `*.wildcards`, IPv4 addresses and networks. |
|
|
93
|
+
| `volumes` | | `[{ volume: 'data', path: '/data', readOnly?: boolean }]` |
|
|
94
|
+
| `timeoutMinutes`, `onTimeout` | 60, `delete` | Lifetime of the VM, and `delete`, `stop` or `pause` at the end. |
|
|
95
|
+
| `idleTimeoutSeconds` | off | Pause when idle; the next request wakes it. |
|
|
96
|
+
| `flex` | `false` | Half price; starts when a machine has spare room. |
|
|
97
|
+
| `desktop` | `false` | `true` or `{ width, height, startUrl, recording }`. |
|
|
98
|
+
| `publicPreviews` | `false` | Previews open to anyone. Private ones need a signed-in member of your team. |
|
|
99
|
+
| `checkpointName`, `seedCheckpointName` | the `id` | Names for `snapshot()` checkpoints. |
|
|
100
|
+
| `workingDirectory` | `/home/runner` | `/root` (or the image's `HOME`) on a Docker image. |
|
|
101
|
+
| `instructions` | | A string, or a function of the default instructions. |
|
|
102
|
+
|
|
103
|
+
## Limits
|
|
104
|
+
|
|
105
|
+
- Not supported: `mount()` of S3, GCS or Azure filesystems (the FUSE mounts `@mastra/e2b` and
|
|
106
|
+
`@mastra/daytona` do), and `FactorySandbox` for Mastra Code's factory. A Groundbox volume
|
|
107
|
+
(`volumes`) is the way to keep data across sandboxes.
|
|
108
|
+
- Commands run as the image's user (`runner`, or root on `image`); there is no per-command user.
|
|
109
|
+
Use `sudo` on the default image.
|
|
110
|
+
- `filesystem` does not confine paths: the agent reaches whatever the sandbox user can. A
|
|
111
|
+
no-clobber `writeFile` checks, then writes (not atomic); copy and move with `overwrite: false`
|
|
112
|
+
are checked inside one shell command.
|
|
113
|
+
- Previews, kept snapshots (checkpoints), volumes, templates and `onTimeout: 'stop' | 'pause'`
|
|
114
|
+
are on the paid plan. The free trial gives $1 of use, 2 sandboxes at a time, up to 2 vCPUs and
|
|
115
|
+
4 GB, 60 minutes each.
|
|
116
|
+
- A single `executeCommand` without callbacks can run for up to 60 minutes; with callbacks or a
|
|
117
|
+
longer `timeout`, as long as the sandbox lives.
|
|
118
|
+
|
|
119
|
+
## Develop
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm ci
|
|
123
|
+
npm test # unit tests, no network
|
|
124
|
+
GROUNDBOX_API_KEY=gbx_... npm run test:live # creates real sandboxes and deletes them
|
|
125
|
+
npm run build
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The live tests drive Mastra's own `Workspace`, its workspace tools and an `Agent` loop with a
|
|
129
|
+
scripted model (no LLM key needed) against real sandboxes.
|
|
130
|
+
|
|
131
|
+
## License
|
|
132
|
+
|
|
133
|
+
MIT. See [LICENSE](./LICENSE).
|