mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
> Opened by @factory-project:7d5175c3-3a20-42ac-aba9-756f183136f4
## Description
E2B sandboxes ran every agent command as the template's default OS user,
and S3/GCS FUSE mounts were always owned by that same user. That user
has to be privileged — mounting FUSE filesystems needs `sudo`, and the
staged s3fs credentials file (`/tmp/.passwd-s3fs-*`, mode 600) is only
readable by it — so an agent running shell commands as that user could
read bucket credentials or become root.
Two opt-in options fix that:
- **`E2BSandbox({ user })`** — every command the sandbox runs on the
agent's behalf runs as that OS user: `executeCommand`, background
processes, and the tree-kill script that takes their descendants down
(another user cannot signal them). Mounting still runs as the default
user, because it needs `sudo`.
- **`S3Filesystem({ owner })` / `GCSFilesystem({ owner })`** — `{ uid,
gid }` naming the owner of the files inside the FUSE mount, replacing
the `id -u && id -g` probe. This is what gives the command user read and
write access to the mount.
Both are additive and default to today's behavior. `owner` lives on the
filesystem options rather than the sandbox because the mount config is
produced by `filesystem.getMountConfig()`, which is what E2B's `mount()`
reads; `E2BSandboxOptions.user` reaches the provider through the shared
`CommandsApiProcessManager`, and the key is left off entirely when unset
so the SDK's own default user still applies. `owner` is validated as
non-negative integers before it is interpolated into a mount command.
The `user` must already exist in the sandbox template.
## Related issue(s)
Fixes #30349
## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have addressed all Coderabbit comments on this PR
## Test plan
All checks run on this head (`dec4e6ec`):
- `packages/_internals/workspace`: 160 tests, including a new test that
the spawn and the kill script both carry the configured user, and one
that the key stays unset without a user.
- `@mastra/e2b` unit suite: 367 passed, 9 skipped (`validateOwner`
cases; S3 and GCS mounts using an explicit owner skip the `id -u && id
-g` probe and emit `uid=`/`gid=` and `--uid=`/`--gid=`; mounts without
an owner still probe).
- `@mastra/s3` 150 passed, `@mastra/gcs` 91 passed, including
`getMountConfig()` carrying `owner` when set and omitting it when not.
- Typecheck (e2b, s3, gcs, platform-workspace) clean; lint 0 warnings /
0 errors and builds clean for e2b, s3 and gcs.
- Each new test fails against the base source without the change (10 in
e2b, 1 internal, 1 s3, 1 gcs).
- Integration coverage: `index.integration.test.ts` gained a case
asserting an explicit owner yields `1234:1234` from `stat -c %u:%g`. It
needs `E2B_API_KEY`, so it does not run in CI — a manual run on a real
sandbox is the remaining gap.
## Follow-ups (not part of this change)
1. File-API writes (`sandbox.files`, `FilesApiFilesystem`) and code-mode
staging under `/home/user` still run as the default user, so with `user`
set, files written through file tools are not owned by the command user.
2. `E2BProviderConfig.configSchema` does not list `user` (it already
omits `workingDirectory`, `reattach` and `lifecycle`), so the Studio
provider form does not offer it even though the runtime forwards it.
3. `commands.list()` scope relative to the configured user is unverified
without an API key; tracked handles still surface.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
**ELI5:** Agent commands in an E2B sandbox used to run as the same user
that mounts cloud storage. This PR lets you pick a separate,
less-privileged user for agent commands, and lets you set the file owner
for S3 and GCS mounts. Both options are off by default.
## Summary
This PR adds two opt-in E2B options, as described in issue `#30349`:
- **Command user.** `E2BSandbox({ user })` runs agent commands,
background processes, and descendant cleanup as the named OS user.
Mounting still uses the default user. The user must already exist in the
sandbox template.
- **Mount owner.** `S3Filesystem({ owner })` and `GCSFilesystem({ owner
})` accept `{ uid, gid }`. When set, the mount uses these IDs. When
unset, the existing `id -u && id -g` probe runs.
### Changes by area
- **Workspace process manager**
(`packages/_internals/workspace/src/commands-api-process-manager.ts`):
`CommandsApi.run` and `CommandsApiProcessManagerOptions` accept an
optional `user`. Spawned commands and descendant cleanup in `kill()` use
it.
- **E2B provider** (`workspaces/e2b/src/sandbox/`):
- `index.ts` adds `user?: string` to `E2BSandboxOptions`.
- `process-manager.ts` forwards `user` to the base class.
- `mounts/types.ts` adds `MountOwner` and `validateOwner`. Validation
requires non-negative integers for `uid` and `gid`.
- `mounts/s3.ts` and `mounts/gcs.ts` use a supplied owner. Otherwise,
they probe the default user.
- `index.ts` re-exports `MountOwner`.
- **S3 and GCS filesystems** (`workspaces/s3/src/filesystem/index.ts`,
`workspaces/gcs/src/filesystem/index.ts`): add `MountOwner`, an optional
`owner` option, and a `readonly owner` property. `getMountConfig()`
copies `uid` and `gid` into a plain object only when an owner is set.
This copy also handles owners whose fields are prototype getters. Both
packages re-export `MountOwner`.
- **Docs and changeset:** document both options. The changeset sets
minor releases for `@mastra/e2b`, `@mastra/s3`, and `@mastra/gcs`.
### Tests
- Workspace tests check that a configured user reaches spawned commands
and their kill commands. They also check that an unset user is passed as
`undefined`.
- E2B unit tests check owner validation and mount behavior with and
without an owner.
- S3 and GCS tests check `getMountConfig()` with and without an owner.
They also check that later changes to the input owner do not change the
config.
- An E2B integration test checks that an explicit owner of `1234` mounts
with ownership `1234:1234`. This test requires `E2B_API_KEY` and was not
run in CI.
The author reports passing workspace, E2B, S3, and GCS tests. The author
also reports clean typecheck, lint, and build results. These results are
not tied to a completed CI run on the current head. A manual run against
a real E2B sandbox is outstanding.
### Out of scope (per PR description)
- File-API writes and code-mode staging still use the default user.
- The Studio configuration schema does not expose `user`.
- The scope of `commands.list()` relative to the configured user is not
verified.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
|
History
|
|
|---|---|---|
| .. | ||
| _test-utils | ||
| agentcore | ||
| agentfs | ||
| apple-container | ||
| archil | ||
| azure | ||
| blaxel | ||
| cloudflare-sandbox | ||
| daytona | ||
| docker | ||
| e2b | ||
| e2b-desktop | ||
| files-sdk | ||
| gcs | ||
| google-drive | ||
| mesa | ||
| modal | ||
| platform-workspace | ||
| railway | ||
| s3 | ||
| sprites | ||
| vercel | ||