{"record":{"id":"cef439428b17dbeb","repo":"mastra-ai/mastra","slug":"code-mode-requires-a-sandbox-to-run-model-authored","errorCode":null,"errorMessage":"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()`.","messagePattern":"Code Mode requires a sandbox to run model-authored code, but none was configured\\. Pass one to createCodeMode\\((.+?)\\), 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\\(\\)`\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/tools/code-mode/code-mode.ts","lineNumber":94,"sourceCode":"    description:\n      'Execute a TypeScript program that orchestrates the available tools in a sandbox. ' +\n      'Prefer this over calling tools one at a time when a task needs multiple tool calls, ' +\n      'batching, aggregation, or arithmetic.',\n    inputSchema: codeModeInputSchema,\n    outputSchema: codeModeOutputSchema,\n    execute: async ({ code }, ctx): Promise<CodeModeToolResult> => {\n      // Resolve sandbox: explicit config -> workspace from context. There is no\n      // implicit fallback: Code Mode runs model-authored code, so the execution\n      // boundary must be chosen deliberately. To run locally (host privileges),\n      // pass `sandbox: new LocalSandbox()` explicitly. Transports that provide\n      // their own execution boundary (e.g. in-process V8 isolates) declare\n      // `requiresSandbox: false` and run without one.\n      let sandbox: WorkspaceSandbox | undefined = config.sandbox;\n      if (!sandbox && transport.requiresSandbox !== false) {\n        const requestContext = ctx?.requestContext ?? new RequestContext();\n        sandbox = await ctx?.workspace?.resolveSandbox({ requestContext });\n        if (!sandbox) {\n          throw new Error(\n            'Code Mode requires a sandbox to run model-authored code, but none was configured. ' +\n              'Pass one to createCodeMode({ tools, sandbox }), or run the agent in a workspace that provides a sandbox. ' +\n              'To execute on the host (host privileges — only for trusted/local use), pass `sandbox: new LocalSandbox()`.',\n          );\n        }\n      }\n\n      // Each external_* call re-enters the real Mastra tool pipeline (validation,\n      // request-context checks, tracing) on the host, with the outer tool's context.\n      const dispatch: CodeModeToolDispatcher = async (toolId, args) => {\n        const tool = toolsById.get(toolId);\n        if (!tool?.execute) {\n          throw new Error(`Tool \"${toolId}\" is not available in Code Mode`);\n        }\n        const result = await tool.execute(args, {\n          mastra: ctx?.mastra,\n          requestContext: ctx?.requestContext,\n          abortSignal: ctx?.abortSignal,","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/tools/code-mode/code-mode.ts#L76-L112","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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)."],"exampleFix":"// before\nconst codeMode = createCodeMode({ tools });\n// after\nimport { LocalSandbox } from '@mastra/core/sandbox';\nconst codeMode = createCodeMode({ tools, sandbox: new LocalSandbox() });","handlingStrategy":"validation","validationCode":"import { LocalSandbox } from '@mastra/core/sandbox';\nconst sandbox = config.sandbox ?? workspace?.sandbox ?? new LocalSandbox();\nconst codeMode = createCodeMode({ tools, sandbox });","typeGuard":null,"tryCatchPattern":"try {\n  tool = createCodeMode({ tools });\n} catch (e) {\n  if (String(e.message).includes('requires a sandbox')) {\n    tool = createCodeMode({ tools, sandbox: new LocalSandbox() });\n  } else throw e;\n}","preventionTips":["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."],"tags":["code-mode","sandbox","configuration","missing-dependency"],"backgroundTag":"missing-sandbox-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}