releases.shpreview
Mastra/GitHub Releases/@mastra/core@1.9.0

@mastra/core@1.9.0

March 4, 2026

March 4, 2026GitHub ReleasesView original ↗
$npx -y @buildinternet/releases show rel_YwHLz7RFYEbrVRDXudcsQ

Highlights

Major Workspace & Sandbox upgrades (token-aware output, mounts, process control, LSP resolution)

Workspaces get significant capabilities: workspace tool output is now token-limited, ANSI-stripped for model context, and .gitignore-aware to reduce token usage. Sandbox commands support abortSignal for cancellation, plus background process streaming callbacks (onStdout/onStderr/onExit), and local symlink mounts in LocalSandbox. Tools can be exposed under custom names via WorkspaceToolConfig.name. LSP binary resolution is now configurable (binaryOverrides, searchPaths, packageRunner), making workspace diagnostics work reliably across monorepos, global installs, and custom setups.

End-to-end Auth + RBAC across Server, Studio, and Providers

Mastra now ships a pluggable auth system (@mastra/core/auth) plus server-side auth routes and convention-based route permission enforcement (@mastra/server + all server adapters). New auth provider packages (@mastra/auth-cloud, @mastra/auth-studio, @mastra/auth-workos) add OAuth/SSO, session management, and RBAC—Studio UI also gains permission-gated auth screens/components.

Workflow execution path tracking + concurrent-safe workflow snapshot updates

Workflow results now include stepExecutionPath (also available mid-execution and preserved across resume/restart), and execution logs are smaller by deduping payloads. Storage backends add atomic updateWorkflowResults/updateWorkflowState with a supportsConcurrentUpdates() check—enabling safer concurrent workflow updates (supported in e.g. Postgres/LibSQL/MongoDB/DynamoDB/Upstash; explicitly not supported in some backends like ClickHouse/Cloudflare/Lance).

Breaking Changes

  • harness.sendMessage() now uses files instead of images (supports any file type, preserves filenames, and auto-decodes text-based files).

Changelog

@mastra/core@1.9.0

Minor Changes

  • Added onStepFinish and onError callbacks to NetworkOptions, allowing per-LLM-step progress monitoring and custom error handling during network execution. Closes #13362. (#13370)

    Before: No way to observe per-step progress or handle errors during network execution.

    const stream = await agent.network('Research AI trends', {
  memory: { thread: 'my-thread', resource: 'my-resource' },
});

    After: onStepFinish and onError are now available in NetworkOptions.

    const stream = await agent.network('Research AI trends', {
  onStepFinish: event => {
    console.log('Step completed:', event.finishReason, event.usage);
  },
  onError: ({ error }) => {
    console.error('Network error:', error);
  },
  memory: { thread: 'my-thread', resource: 'my-resource' },
});

  • Add workflow execution path tracking and optimize execution logs (#11755)

    Workflow results now include a stepExecutionPath array showing the IDs of each step that executed during a workflow run. You can use this to understand exactly which path your workflow took.

    // Before: no execution path in results
const result = await workflow.execute({ triggerData });
// result.stepExecutionPath → undefined

// After: stepExecutionPath is available in workflow results
const result = await workflow.execute({ triggerData });
console.log(result.stepExecutionPath);
// → ['step1', 'step2', 'step4'] — the actual steps that ran

    stepExecutionPath is available in:

    • Workflow results (WorkflowResult.stepExecutionPath) — see which steps ran after execution completes
    • Execution context (ExecutionContext.stepExecutionPath) — access the path mid-execution inside your steps
    • Resume and restart operations — execution path persists across suspend/resume and restart cycles

    Workflow execution logs are now more compact and easier to read. Step outputs are no longer duplicated as the next step's input, reducing the size of execution results while maintaining full visibility.

    Key improvements:

    • Track which steps executed in your workflows with stepExecutionPath
    • Smaller, more readable execution logs with automatic duplicate payload removal
    • Execution path preserved when resuming or restarting workflows

    This is particularly beneficial for AI agents and LLM-based workflows where reducing context size improves performance and cost efficiency.

    Related: #8951

  • Added authentication interfaces and Enterprise Edition RBAC support. (#13163)

    New @mastra/core/auth export with pluggable interfaces for building auth providers:

    • IUserProvider — user lookup and management
    • ISessionProvider — session creation, validation, and cookie handling
    • ISSOProvider — SSO login and callback flows
    • ICredentialsProvider — username/password authentication

    Default implementations included out of the box:

    • Cookie-based session provider with configurable TTL and secure defaults
    • In-memory session provider for development and testing

    Enterprise Edition (@mastra/core/auth/ee) adds RBAC, ACL, and license validation:

    import { buildCapabilities } from '@mastra/core/auth/ee';

const capabilities = buildCapabilities({
  rbac: myRBACProvider,
  acl: myACLProvider,
});

    Built-in role definitions (owner, admin, editor, viewer) and a static RBAC provider are included for quick setup. Enterprise features require a valid license key via the MASTRA_EE_LICENSE environment variable.

  • Workspace sandbox tool results (execute_command, kill_process, get_process_output) sent to the model now strip ANSI color codes via toModelOutput, while streamed output to the user keeps colors. This reduces token usage and improves model readability. (#13440)

    Workspace execute_command tool now extracts trailing | tail -N pipes from commands so output streams live to the user, while the final result sent to the model is still truncated to the last N lines.

    Workspace tools that return potentially large output now enforce a token-based output limit (~3k tokens by default) using tiktoken for accurate counting. The limit is configurable per-tool via maxOutputTokens in WorkspaceToolConfig. Each tool uses a truncation strategy suited to its output:

    • read_file, grep, list_files — truncate from the end (keep imports, first matches, top-level tree)
    • execute_command, get_process_output, kill_process — head+tail sandwich (keep early output + final status)
    const workspace = new Workspace({
  tools: {
    mastra_workspace_execute_command: {
      maxOutputTokens: 5000, // override default 3k
    },
  },
});

  • Workspace tools (list_files, grep) now automatically respect .gitignore, filtering out directories like node_modules and dist from results. Explicitly targeting an ignored path still works. Also lowered the default tree depth from 3 to 2 to reduce token usage. (#13724)

  • Added maxSteps and stopWhen support to HarnessSubagent. (#13653)

    You can now define maxSteps and stopWhen on a harness subagent so spawned subagents can use custom loop limits instead of relying only on the default maxSteps: 50 fallback.

    const harness = new Harness({
  id: 'dev-harness',
  modes: [{ id: 'build', default: true, agent: buildAgent }],
  subagents: [
    {
      id: 'explore',
      name: 'Explore',
      description: 'Inspect the codebase',
      instructions: 'Investigate and summarize findings.',
      defaultModelId: 'openai/gpt-4o',
      maxSteps: 7,
      stopWhen: ({ steps }) => steps.length >= 3,
    },
  ],
});

  • Added OpenAI WebSocket transport for streaming responses with auto-close and manual transport access (#13531)

  • Added name property to WorkspaceToolConfig for remapping workspace tool names. Tools can now be exposed under custom names to the LLM while keeping the original constant as the config key. (#13687)

    const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './project' }),
  tools: {
    mastra_workspace_read_file: { name: 'view' },
    mastra_workspace_grep: { name: 'search_content' },
    mastra_workspace_edit_file: { name: 'string_replace_lsp' },
  },
});

    Also removed hardcoded tool-name cross-references from edit-file and ast-edit tool descriptions, since tools can be renamed or disabled.

  • Adds requestContext passthrough to Harness runtime APIs. (#13650)

    Added You can now pass requestContext to Harness runtime methods so tools and subagents receive request-scoped values.

  • Added binaryOverrides, searchPaths, and packageRunner options to LSPConfig to support flexible language server binary resolution. (#13677)

    Previously, workspace LSP diagnostics only worked when language server binaries were installed in the project's node_modules/.bin/. There was no way to use globally installed binaries or point to a custom install.

    New LSPConfig fields:

    • binaryOverrides: Override the binary command for a specific server, bypassing the default lookup. Useful when the binary is installed in a non-standard location.
    • searchPaths: Additional directories to search when resolving Node.js modules (e.g. typescript/lib/tsserver.js). Each entry should be a directory whose node_modules contains the required packages.
    • packageRunner: Package runner to use as a last-resort fallback when no binary is found (e.g. 'npx --yes', 'pnpm dlx', 'bunx'). Off by default — package runners can hang in monorepos with workspace links.

    Binary resolution order per server: explicit binaryOverrides override → project node_modules/.bin/ → process.cwd() node_modules/.bin/ → searchPaths node_modules/.bin/ → global PATH → packageRunner fallback.

    const workspace = new Workspace({
  lsp: {
    // Point to a globally installed binary
    binaryOverrides: {
      typescript: '/usr/local/bin/typescript-language-server --stdio',
    },
    // Resolve typescript/lib/tsserver.js from a tool's own node_modules
    searchPaths: ['/path/to/my-tool'],
    // Use a package runner as last resort (off by default)
    packageRunner: 'npx --yes',
  },
});

    Also exported buildServerDefs(config?) for building config-aware server definitions, and LSPConfig / LSPServerDef types from @mastra/core/workspace.

  • Added a unified observability type system with interfaces for structured logging, metrics (counters, gauges, histograms), scores, and feedback alongside the existing tracing infrastructure. (#13058)

    Why? Previously, only tracing flowed through execution contexts. Logging was ad-hoc and metrics did not exist. This change establishes the type system and context plumbing so that when concrete implementations land, logging and metrics will flow through execute callbacks automatically — no migration needed.

    What changed:

    • New ObservabilityContext interface combining tracing, logging, and metrics contexts
    • New type definitions for LoggerContext, MetricsContext, ScoreInput, FeedbackInput, and ObservabilityEventBus
    • createObservabilityContext() factory and resolveObservabilityContext() resolver with no-op defaults for graceful degradation
    • Future logging and metrics signals will propagate automatically through execution contexts — no migration needed
    • Added loggerVNext and metrics getters to the Mastra class

  • Added setServer() public method to the Mastra class, enabling post-construction configuration of server settings. This allows platform tooling to inject server defaults (e.g. auth) into user-created Mastra instances at deploy time. (#13729)

    const mastra = new Mastra({ agents: { myAgent } });

// Platform tooling can inject server config after construction
mastra.setServer({ ...mastra.getServer(), auth: new MastraAuthWorkos() });

  • Added local symlink mounts in LocalSandbox so sandboxed commands can access locally-mounted filesystem paths. (#13474) Improved mounted paths so commands resolve consistently in local sandboxes. Improved workspace instructions so developers can quickly find mounted data paths.

    Why: Local sandboxes can now run commands against locally-mounted data without manual path workarounds.

    Usage example:

    const workspace = new Workspace({
  mounts: {
    '/data': new LocalFilesystem({ basePath: '/path/to/data' }),
  },
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
});

await workspace.init();
// Sandboxed commands can access the mount path via symlink
await workspace.sandbox.executeCommand('ls data');

  • Abort signal and background process callbacks (#13597)

    • Sandbox commands and spawned processes can now be cancelled via abortSignal in command options
    • Background processes spawned via execute_command now support onStdout, onStderr, and onExit callbacks for streaming output and exit notifications
    • New backgroundProcesses config in workspace tool options for wiring up background process callbacks

Patch Changes

  • Added supportsConcurrentUpdates() method to WorkflowsStorage base class and abstract updateWorkflowResults/updateWorkflowState methods for atomic workflow state updates. The evented workflow engine now checks supportsConcurrentUpdates() and throws a clear error if the storage backend does not support concurrent updates. (#12575)

  • Update provider registry and model documentation with latest models and providers (edee4b3)

  • Fixed sandbox command execution crashing the parent process on some Node.js versions by explicitly setting stdio to pipe for detached child processes. (#13697)

  • Fixed an issue where generating a response in an empty thread (system-only messages) would throw an error. Providers that support system-only prompts like Anthropic and OpenAI now work as expected. A warning is logged for providers that require at least one user message (e.g. Gemini). Fixes #13045. (#13164)

  • Sanitize invalid tool names in agent history so Bedrock retries continue instead of failing request validation. (#13633)

  • Fixed path matching for auto-indexing and skills discovery. (#13511) Single file paths, directory globs, and SKILL.md file globs now resolve consistently. Trailing slashes are now handled correctly.

  • Harness.cloneThread() now resolves dynamic memory factories before cloning, fixing "cloneThread is not a function" errors when memory is provided as a factory function. HarnessConfig.memory type widened to DynamicArgument<MastraMemory>. (#13569)

  • Fixed workspace tools being callable by their old default names (e.g. mastra_workspace_edit_file) when renamed via tools config. The tool's internal id is now updated to match the remapped name, preventing fallback resolution from bypassing the rename. (#13694)

  • Reduced default max output tokens from 3000 to 2000 for all workspace tools. List files tool uses a 1000 token limit. Suppressed "No errors or warnings" LSP diagnostic message when there are no issues. (#13730)

  • Add first-class custom provider support for MastraCode model selection and routing. (#13682)

    • Add /custom-providers command to create, edit, and delete custom OpenAI-compatible providers and manage model IDs under each provider.
    • Persist custom providers and model IDs in settings.json with schema parsing/validation updates.
    • Extend Harness model catalog listing with customModelCatalogProvider so custom models appear in existing selectors (/models, /subagents).
    • Route configured custom provider model IDs through ModelRouterLanguageModel using provider-specific URL and optional API key settings.

  • sendMessage now accepts files instead of images, supporting any file type with optional filename. (#13574)

    Breaking change: Rename images to files when calling harness.sendMessage():

    // Before
await harness.sendMessage({
  content: 'Analyze this',
  images: [{ data: base64Data, mimeType: 'image/png' }],
});

// After
await harness.sendMessage({
  content: 'Analyze this',
  files: [{ data: base64Data, mediaType: 'image/png', filename: 'screenshot.png' }],
});
    • files accepts { data, mediaType, filename? } — filenames are now preserved through storage and message history
    • Text-based files (text/*, application/json) are automatically decoded to readable text content instead of being sent as binary, which models could not process
    • HarnessMessageContent now includes a file type, so file parts round-trip correctly through message history

  • Fixed Agent Network routing failures for users running Claude models through AWS Bedrock by removing trailing whitespace from the routing assistant message. (#13624)

  • Fixed thread title generation when user messages include file parts (for example, images). (#13671) Titles now generate reliably instead of becoming empty.

  • Fixed parallel workflow tool calls so each call runs independently. (#13478)

    When an agent starts multiple tool calls to the same workflow at the same time, each call now runs with its own workflow run context. This prevents duplicated results across parallel calls and ensures each call returns output for its own input. Also ensures workflow tool suspension and manual resumption correctly preserves the run context.

  • Fixed sub-agent instructions being overridden when the parent agent uses an OpenAI model. Previously, OpenAI models would fill in the optional instructions parameter when calling a sub-agent tool, completely replacing the sub-agent's own instructions. Now, any LLM-provided instructions are appended to the sub-agent's configured instructions instead of replacing them. (#13578)

  • Tool lifecycle hooks (onInputStart, onInputDelta, onInputAvailable, onOutput) now fire correctly during agent execution for tools created via createTool(). Previously these hooks were silently ignored. Affected: createTool, Tool, CoreToolBuilder.build, CoreTool. (#13708)

  • Fixed an issue where sub-agent messages inside a workflow tool would corrupt the parent agent's memory context. When an agent calls a workflow as a tool and the workflow runs sub-agents with their own memory threads, the parent's thread identity on the shared request context is now correctly saved before the workflow executes and restored afterward, preventing messages from being written to the wrong thread. (#13637)

  • Fix workspace tool output truncation to handle tokenizer special tokens (#13725)

  • Added a warning when a LocalFilesystem mount uses contained: false, alerting users to path resolution issues in mount-based workspaces. Use contained: true (default) or allowedPaths to allow specific host paths. (#13474)

  • Fixed harness handling for observational memory failures so streams stop immediately when OM reports a failed run or buffering cycle. (#13563)

    The harness now emits the existing OM failure event (om_observation_failed, om_reflection_failed, or om_buffering_failed), emits a top-level error with OM context, and aborts the active stream. This prevents normal assistant output from continuing after an OM model failure.

  • Fixed subagents being unable to access files outside the project root. Subagents now inherit both user-approved sandbox paths and skill paths (e.g. ~/.claude/skills) from the parent agent. (#13700)

  • Fixed agent-as-tools schema generation so Gemini accepts tool definitions for suspend/resume flows. (#13715) This prevents schema validation failures when resumeData is present.

  • Fixed tool approval resume failing when Agent is used without an explicit Mastra instance. The Harness now creates an internal Mastra instance with storage and registers it on mode agents, ensuring workflow snapshots persist and load correctly. Also fixed requestContext serialization using toJSON() to prevent circular reference errors during snapshot persistence. (#13519)

  • Fixed spawn error handling in LocalSandbox by switching to execa. Previously, spawning a process with an invalid working directory or missing command could crash with an unhandled Node.js exception. Now returns descriptive error messages instead. Also fixed timeout handling to properly kill the entire process group for compound commands. (#13734)

  • HTTP request logging can now be configured in detail via apiReqLogs in the server config. The new HttpLoggingConfig type is exported from @mastra/core/server. (#11907)

    import type { HttpLoggingConfig } from '@mastra/core/server';

const loggingConfig: HttpLoggingConfig = {
  enabled: true,
  level: 'info',
  excludePaths: ['/health', '/metrics'],
  includeHeaders: true,
  includeQueryParams: true,
  redactHeaders: ['authorization', 'cookie'],
};

  • Remove internal processes field from sandbox provider options (#13597)

    The processes field is no longer exposed in constructor options for E2B, Daytona, and Blaxel sandbox providers. This field is managed internally and was not intended to be user-configurable.

  • Fixed abort signal propagation in agent networks. When using abortSignal with agent.network(), the signal now correctly prevents tool execution when abort fires during routing, and no longer saves partial results to memory when sub-agents, tools, or workflows are aborted. (#13491)

  • Fixed Memory.recall() to include pagination metadata (total, page, perPage, hasMore) in its response, ensuring consistent pagination regardless of whether agentId is provided. Fixes #13277 (#13278)

  • Fixed harness getTokenUsage() returning zeros when using AI SDK v5/v6. The token usage extraction now correctly reads both inputTokens/outputTokens (v5/v6) and promptTokens/completionTokens (v4) field names from the usage object. (#13622)

  • Model pack selection is now more consistent and reliable in mastracode. (#13512)

    • /models is now the single command for choosing and managing model packs.
    • Model picker ranking now learns from your recent selections and keeps those preferences across sessions.
    • Pack choice now restores correctly per thread when switching between threads.
    • Custom packs now support full create, rename, targeted edit, and delete workflows.
    • The built-in Varied option has been retired; users who had it selected are automatically migrated to a saved custom pack named varied.

  • Added support for reading resource IDs from Harness. (#13690)

    You can now get the default resource ID and list known resource IDs from stored threads.

    const defaultId = harness.getDefaultResourceId();
const knownIds = await harness.getKnownResourceIds();

  • chore(harness): Update harness sub-agent instructions type to be dynamic (#13706)

  • Added MastraMessagePart to the public type exports of @mastra/core/agent, allowing it to be imported directly in downstream packages. (#13297)

  • Added deleteThread({ threadId }) method to the Harness class for deleting threads and their messages from storage. Releases the thread lock and clears the active thread when deleting the current thread. Emits a thread_deleted event. (#13625)

  • Fixed tilde (~) paths not expanding to the home directory in LocalFilesystem and LocalSandbox. Paths like ~/my-project were silently treated as relative paths, creating a literal ~/ directory instead of resolving to $HOME. This affects basePath, allowedPaths, setAllowedPaths(), all file operations in LocalFilesystem, and workingDirectory in LocalSandbox. (#13739)

  • Switched Mastra Code to workspace tools and enabled LSP by default (#13437)

    • Switched from built-in tool implementations to workspace tools for file operations, search, edit, write, and command execution
    • Enabled LSP (language server) by default with automatic package runner detection and bundled binary resolution
    • Added real-time stdout/stderr streaming in the TUI for workspace command execution
    • Added TUI rendering for process management tools (view output, kill processes)
    • Fixed edit diff preview in the TUI to work with workspace tool arg names (old_string/new_string)

  • Fixed tilde paths (~/foo) in contained LocalFilesystem silently writing to the wrong location. Previously, ~/foo would expand and then nest under basePath (e.g. basePath/home/user/foo). Tilde paths are now treated as real absolute paths, and throw PermissionError when the expanded path is outside basePath and allowedPaths. (#13741)

@mastra/agent-builder@1.0.9

Patch Changes

@mastra/ai-sdk@1.1.1

Patch Changes

@mastra/arize@1.0.5

Patch Changes

@mastra/auth-better-auth@1.0.2

Patch Changes

@mastra/auth-cloud@1.1.0

Minor Changes

  • Added @mastra/auth-cloud — a new auth provider for Mastra Cloud with PKCE OAuth flow, session management, and role-based access control. (#13163)

    import { MastraCloudAuthProvider, MastraRBACCloud } from '@mastra/auth-cloud';

const mastra = new Mastra({
  server: {
    auth: new MastraCloudAuthProvider({
      appId: process.env.MASTRA_APP_ID!,
      apiKey: process.env.MASTRA_API_KEY!,
    }),
    rbac: new MastraRBACCloud({
      appId: process.env.MASTRA_APP_ID!,
      apiKey: process.env.MASTRA_API_KEY!,
    }),
  },
});

    Handles the full OAuth lifecycle including login URL generation, PKCE challenge/verification, callback handling, and session cookie management.

Patch Changes

@mastra/auth-studio@1.1.0

Minor Changes

  • Added @mastra/auth-studio — an auth provider for deployed Mastra Studio instances that proxies authentication through the Mastra shared API. (#13163)

    Deployed instances need no secrets — all WorkOS authentication is handled by the shared API. The package provides SSO login/callback flows, session management via sealed cookies, RBAC with organization-scoped permissions, and automatic forced account picker on deploy logins.

Patch Changes

@mastra/auth-workos@1.1.0

Minor Changes

  • Added full auth provider to @mastra/auth-workos with SSO, RBAC, SCIM directory sync, and admin portal support. (#13163)

    import { MastraAuthWorkos, MastraRBACWorkos } from '@mastra/auth-workos';

const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
    }),
    rbac: new MastraRBACWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
      roleMapping: {
        admin: ['*'],
        member: ['agents:read', 'workflows:*'],
      },
    }),
  },
});
    • SSO via WorkOS AuthKit (SAML, OIDC)
    • RBAC with wildcard permission mapping from WorkOS organization roles
    • Directory Sync webhook handler for SCIM-based user provisioning
    • Admin Portal helper for customer self-service SSO configuration

Patch Changes

@mastra/blaxel@0.1.0

Minor Changes

  • Abort signal support in sandbox commands (#13597)

    • Sandbox commands can now be cancelled via abortSignal in command options
    • Partial stdout/stderr output is now preserved when a command is aborted or times out

  • Added background process management support for Blaxel sandboxes. Agents can now spawn, monitor, and kill long-running processes using the standard ProcessHandle interface. (79177b1)

    Example usage:

    const sandbox = new BlaxelSandbox({ timeout: '5m' });
const workspace = new Workspace({ sandbox });

// Process manager is available via sandbox.processes
const handle = await sandbox.processes.spawn('python server.py');

// Monitor output
handle.onStdout(data => console.log(data));

// Check status
const info = await sandbox.processes.list();

// Kill when done
await handle.kill();

    Note: Process stdin is not supported in Blaxel sandboxes.

    Additional improvements:

    • Fixed detection of expired sandboxes, ensuring operations automatically retry when a sandbox has timed out

Patch Changes

@mastra/braintrust@1.0.5

Patch Changes

@mastra/clickhouse@1.2.3

Patch Changes

@mastra/client-js@1.7.2

Patch Changes

@mastra/cloudflare@1.2.2

Patch Changes

@mastra/cloudflare-d1@1.0.1

Patch Changes

@mastra/convex@1.0.5

Patch Changes

@mastra/datadog@1.0.4

Patch Changes

@mastra/daytona@0.1.0

Minor Changes

  • Add DaytonaSandbox workspace provider — Daytona cloud sandbox integration for Mastra workspaces, implementing the WorkspaceSandbox interface with support for command execution, environment variables, resource configuration, snapshots, and Daytona volumes. (#13112)

    Basic usage

    import { Workspace } from '@mastra/core/workspace';
import { DaytonaSandbox } from '@mastra/daytona';

const sandbox = new DaytonaSandbox({
  id: 'my-sandbox',
  env: { NODE_ENV: 'production' },
});

const workspace = new Workspace({ sandbox });
await workspace.init();

const result = await workspace.sandbox.executeCommand('echo', ['Hello!']);
console.log(result.stdout); // "Hello!"

await workspace.destroy();

  • Added S3 and GCS cloud filesystem mounting support via FUSE (s3fs-fuse, gcsfuse). Daytona sandboxes can now mount cloud storage as local directories, matching the mount capabilities of E2B and Blaxel providers. (#13544)

    New methods:

    • mount(filesystem, mountPath) — Mount an S3 or GCS filesystem at a path in the sandbox
    • unmount(mountPath) — Unmount a previously mounted filesystem

    What changed:

    • Added S3 and GCS bucket mounts as local directories in Daytona sandboxes.
    • Improved reconnect behavior so mounts are restored reliably.
    • Added safety checks to prevent mounting into non-empty directories.
    • Improved concurrent mount support by isolating credentials per mount.

    Usage:

    import { Workspace } from '@mastra/core/workspace';
import { S3Filesystem } from '@mastra/s3';
import { DaytonaSandbox } from '@mastra/daytona';

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
  },
  sandbox: new DaytonaSandbox(),
});

Patch Changes

  • Remove internal processes field from sandbox provider options (#13597)

    The processes field is no longer exposed in constructor options for E2B, Daytona, and Blaxel sandbox providers. This field is managed internally and was not intended to be user-configurable.

  • Improved S3/GCS FUSE mounting reliability and sandbox reconnection. (#13543)

    Mounting improvements

    • Replaced direct SDK coupling in mount helpers with callback-based context, making mount operations more testable and resilient
    • Added tmpfs overlay to handle FUSE-on-FUSE remount scenarios that previously failed with ENOENT
    • Added mount --move fallback when standard FUSE unmount fails on stuck mounts
    • stop() now unmounts all filesystems before stopping the sandbox
    • Added early connectivity check for GCS mounting that detects Daytona's restricted internet tiers and fails fast with an actionable error message instead of hanging
    • Improved gcsfuse installation with distro-aware codename detection (bookworm for Debian, jammy for Ubuntu)
    • Added input validation for bucket names, endpoints, and credentials before interpolating into shell commands

    Reconnection improvements

    • findExistingSandbox now looks up sandboxes by name first (works for stopped sandboxes), then falls back to label search
    • Added transitional state handling that polls and waits when a sandbox is starting/stopping/restoring before attempting to start it, avoiding "State change in progress" errors

  • Sandbox instructions no longer include a working directory path, keeping instructions stable across sessions. (#13520)

  • Updated dependencies [504fc8b, f9c150b, 88de7e8, edee4b3, 3790c75, e7a235b, d51d298, 6dbeeb9, d5f0d8d, 09c3b18, b896379, 85c84eb, a89272a, ee9c8df, 77b4a25, 276246e, 08ecfdb, d5f628c, 524c0f3, c18a0e9, 4bd21ea, 115a7a4, 22a48ae, 3c6ef79, 9311c17, 7edf78f, 1c4221c, d25b9ea, fe1ce5c, b03c0e0, 0a8366b, 85664e9, bc79650, 9257d01, 3a3a59e, 3108d4e, 0c33b2c, 191e5bd, f77cd94, e8135c7, daca48f, 257d14f, 352f25d, 93477d0, 31c78b3, 0bc0720, 36516ac, [`e947

Fetched April 7, 2026