Skip to main content

Sandboxes

A sandbox gives each coding-agent session an environment for its repository checkout, dependencies, and commands. You can also run commands locally or choose another Mastra sandbox provider.

Mastra platform​

PlatformSandbox runs commands in cloud sandboxes managed through Mastra platform. The generated Factory project includes the provider package and its configuration.

Mastra platform deployments supply the sandbox credentials through the environment. To use platform sandboxes from a local server, set the corresponding values in .env:

.env
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-api-token
MASTRA_PROJECT_ID=your-platform-project-id
MASTRA_ENVIRONMENT_ID=your-platform-environment-id

Use an API token from your Mastra platform organization's API Tokens settings and the IDs for the project and environment where the sandboxes should run.

The callback below selects Mastra platform explicitly. createRepoTemplate uses the session's repository and setup command to prepare a reusable template.

TypeScriptsrc/mastra/sandbox.ts
import type { MastraFactorySandboxConfig } from '@mastra/factory'
import { PlatformSandbox, createRepoTemplate } from '@mastra/platform-workspace'

export const sandbox: MastraFactorySandboxConfig = ctx =>
	new PlatformSandbox({
		id: ctx.sessionId,
		template: createRepoTemplate(ctx),
	})

Set the sandbox​

Each code example on this page exports a sandbox callback from src/mastra/sandbox.ts. Choose one provider example and import it in the generated entry:

TypeScriptsrc/mastra/index.ts
import { sandbox } from './sandbox'

Replace the existing inline sandbox callback in new MastraFactory(...) with the imported sandbox value. Keep the rest of the Factory options, including storage, auth, and integrations.

Local execution​

LocalSandbox runs commands directly on the Factory Server's machine. Each session gets its own working directory. Use a cloud sandbox for virtual machine (VM) isolation.

Configure this callback to select local execution explicitly, including when your auth and database use Mastra platform:

TypeScriptsrc/mastra/sandbox.ts
import { homedir } from 'node:os'
import { join } from 'node:path'
import { LocalSandbox } from '@mastra/core/workspace'
import type { MastraFactorySandboxConfig } from '@mastra/factory'

const root =
	process.env.MASTRACODE_LOCAL_SANDBOX_ROOT || join(homedir(), '.mastracode', 'web', 'sandboxes')

export const sandbox: MastraFactorySandboxConfig = ctx =>
	new LocalSandbox({
		workingDirectory: join(root, ctx.sessionId),
		env: { HOME: homedir() },
	})

Install Git and the tools your repository's setup command needs on that computer. Factory creates a repository checkout beneath the session directory. Add any environment variables required by your build to the explicit env values.

Set MASTRACODE_LOCAL_SANDBOX_ROOT to an absolute path to choose where session directories are stored. See the LocalSandbox reference for additional options.

Other sandbox providers​

Factory works with other Mastra sandbox providers. Follow your provider's setup instructions, then return a new provider instance from Factory's sandbox callback.

Check the selected provider​

After changing a callback or environment variable, restart the Factory Server and inspect the sandbox startup logs to confirm that checkout and the repository's setup command complete. For a cloud provider, match the session to the sandbox in its dashboard. For local execution, check the session directory under your configured root.

The unmodified generated callback uses LocalSandbox when FACTORY_SANDBOX_PROVIDER=local. Otherwise, it selects Mastra platform when MASTRA_PROJECT_ID, MASTRA_ENVIRONMENT_ID, and either MASTRA_PLATFORM_ACCESS_TOKEN or MASTRA_PLATFORM_SECRET_KEY are set. If platform credentials aren't configured, it uses direct E2B if E2B_API_KEY is set, or LocalSandbox if it isn't.

Use the explicit callbacks above when you want to select a provider independently of that fallback logic.

Sandbox startup is lazy by default: the first code command starts the environment and can take longer while Factory prepares the repository. See Sandbox startup troubleshooting if it fails.