Code Mode requires a sandbox to run model-authored code, but

Error message

Code Mode requires a sandbox to run model-authored code, but none was configured. Pass one to createCodeMode({ tools, sandbox }), or run the agent in a workspace that provides a sandbox. To execute on the host (host privileges — only for trusted/local use), pass `sandbox: new LocalSandbox()`.

What it means

Code Mode lets the model author TypeScript that calls tools through a sandboxed runtime. If no sandbox was passed to createCodeMode and the workspace/transport cannot resolve one (and the transport does not explicitly declare requiresSandbox: false), createCodeModeTool throws because model-authored code must never run with host privileges implicitly.

Source

Thrown at packages/core/src/tools/code-mode/code-mode.ts:94

    description:
      'Execute a TypeScript program that orchestrates the available tools in a sandbox. ' +
      'Prefer this over calling tools one at a time when a task needs multiple tool calls, ' +
      'batching, aggregation, or arithmetic.',
    inputSchema: codeModeInputSchema,
    outputSchema: codeModeOutputSchema,
    execute: async ({ code }, ctx): Promise<CodeModeToolResult> => {
      // Resolve sandbox: explicit config -> workspace from context. There is no
      // implicit fallback: Code Mode runs model-authored code, so the execution
      // boundary must be chosen deliberately. To run locally (host privileges),
      // pass `sandbox: new LocalSandbox()` explicitly. Transports that provide
      // their own execution boundary (e.g. in-process V8 isolates) declare
      // `requiresSandbox: false` and run without one.
      let sandbox: WorkspaceSandbox | undefined = config.sandbox;
      if (!sandbox && transport.requiresSandbox !== false) {
        const requestContext = ctx?.requestContext ?? new RequestContext();
        sandbox = await ctx?.workspace?.resolveSandbox({ requestContext });
        if (!sandbox) {
          throw new Error(
            'Code Mode requires a sandbox to run model-authored code, but none was configured. ' +
              'Pass one to createCodeMode({ tools, sandbox }), or run the agent in a workspace that provides a sandbox. ' +
              'To execute on the host (host privileges — only for trusted/local use), pass `sandbox: new LocalSandbox()`.',
          );
        }
      }

      // Each external_* call re-enters the real Mastra tool pipeline (validation,
      // request-context checks, tracing) on the host, with the outer tool's context.
      const dispatch: CodeModeToolDispatcher = async (toolId, args) => {
        const tool = toolsById.get(toolId);
        if (!tool?.execute) {
          throw new Error(`Tool "${toolId}" is not available in Code Mode`);
        }
        const result = await tool.execute(args, {
          mastra: ctx?.mastra,
          requestContext: ctx?.requestContext,
          abortSignal: ctx?.abortSignal,

View on GitHub (pinned to 75dd419e61)

Solutions

Pass a sandbox explicitly: createCodeMode({ tools, sandbox: new LocalSandbox() }).
Run the agent inside a workspace that provides a sandbox so ctx.workspace.resolveSandbox() succeeds.
If you truly want in-process execution without a sandbox, use a transport configured with requiresSandbox: false (only for trusted code).

Example fix

// before
const codeMode = createCodeMode({ tools });
// after
import { LocalSandbox } from '@mastra/core/sandbox';
const codeMode = createCodeMode({ tools, sandbox: new LocalSandbox() });

Defensive patterns

Strategy: validation

Validate before calling

import { LocalSandbox } from '@mastra/core/sandbox';
const sandbox = config.sandbox ?? workspace?.sandbox ?? new LocalSandbox();
const codeMode = createCodeMode({ tools, sandbox });

Try / catch

try {
  tool = createCodeMode({ tools });
} catch (e) {
  if (String(e.message).includes('requires a sandbox')) {
    tool = createCodeMode({ tools, sandbox: new LocalSandbox() });
  } else throw e;
}

Prevention

Always pass an explicit sandbox to createCodeMode.
When running inside a workspace, verify it exposes resolveSandbox.
Never rely on implicit sandbox resolution in production code.

When it happens

Trigger: Calling createCodeMode({ tools }) with no sandbox option, no workspace on the execution context, and a transport whose requiresSandbox is not false (e.g. the default StdioCodeModeTransport).

Common situations: Quick-start snippets that omit the sandbox option; running the agent outside a Mastra workspace; upgrading Code Mode where sandbox resolution used to be implicit; forgetting `sandbox: new LocalSandbox()` for local trusted usage.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/cef439428b17dbeb. Report an issue: GitHub.