@mastra/mcp-docs-server 1.2.8-alpha.9 → 1.2.8

package/.docs/reference/voice/mistral.md

@@ -0,0 +1,127 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mistral
+
+The MistralVoice class provides text-to-speech and speech-to-text capabilities using Mistral's Voxtral audio models. It supports buffered and streaming TTS, batch transcription with diarization, and voice cloning via reference audio.
+
+## Usage example
+
+```typescript
+import { MistralVoice } from '@mastra/voice-mistral'
+
+const voice = new MistralVoice()
+
+// Text-to-speech
+const audioStream = await voice.speak('Hello, how can I help you?', {
+  responseFormat: 'mp3',
+})
+
+// Speech-to-text
+const text = await voice.listen(audioStream, {
+  language: 'en',
+})
+
+// List available voices
+const speakers = await voice.getSpeakers()
+```
+
+```typescript
+import { MistralVoice } from '@mastra/voice-mistral'
+
+// Initialize with specific configuration
+const voice = new MistralVoice({
+  speechModel: {
+    name: 'voxtral-mini-tts-2603',
+    apiKey: 'your-mistral-api-key',
+  },
+  listeningModel: {
+    name: 'voxtral-mini-latest',
+    apiKey: 'your-mistral-api-key',
+  },
+  speaker: 'en_paul_neutral',
+})
+```
+
+## Constructor parameters
+
+**speechModel** (`MistralModelConfig`): Configuration for text-to-speech synthesis. (Default: `{ name: 'voxtral-mini-tts-2603' }`)
+
+**speechModel.name** (`string`): Model ID for speech synthesis.
+
+**speechModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
+
+**listeningModel** (`MistralModelConfig`): Configuration for speech-to-text recognition. (Default: `{ name: 'voxtral-mini-latest' }`)
+
+**listeningModel.name** (`string`): Model ID for transcription. Use 'voxtral-mini-2507' for a pinned version.
+
+**listeningModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
+
+**speaker** (`string`): Default voice ID for speech synthesis. Retrieve available IDs from getSpeakers(). (Default: `'en_paul_neutral'`)
+
+## Methods
+
+### `speak(input, options?)`
+
+Converts text to speech using Mistral's Voxtral TTS model. Supports both buffered and streaming output.
+
+**input** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options** (`MistralSpeakOptions`): Configuration options.
+
+**options.speaker** (`string`): Voice ID to use. Overrides the constructor default.
+
+**options.responseFormat** (`'pcm' | 'wav' | 'mp3' | 'flac' | 'opus'`): Audio output format. Use 'pcm' for lowest latency streaming.
+
+**options.refAudio** (`string`): Base64-encoded reference audio for one-off voice cloning (minimum 2-3 seconds).
+
+**options.model** (`string`): Override the speech model for this call.
+
+**options.stream** (`boolean`): Enable streaming TTS. Audio chunks are written to the stream as they arrive.
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### `listen(audioStream, options?)`
+
+Transcribes audio using Mistral's Voxtral transcription model. Supports diarization, context biasing, and timestamp granularity.
+
+**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+**options** (`MistralListenOptions`): Configuration options.
+
+**options.language** (`string`): Language code (e.g., 'en'). Improves accuracy when specified.
+
+**options.diarize** (`boolean`): Enable speaker diarization.
+
+**options.contextBias** (`string[]`): Words or phrases for vocabulary guidance.
+
+**options.timestampGranularities** (`('segment' | 'word')[]`): Timestamp detail level for transcription segments.
+
+**options.filetype** (`string`): Audio file extension hint for the input stream.
+
+Returns: `Promise<string>`
+
+### `getSpeakers()`
+
+Fetches available preset voices from the Mistral Voices API. Each entry contains:
+
+**voiceId** (`string`): Unique identifier for the voice.
+
+**name** (`string`): Display name of the voice.
+
+**languages** (`string[]`): Languages supported by the voice.
+
+**gender** (`string | null`): Gender of the voice.
+
+### `getListener()`
+
+Returns `{ enabled: true }`.
+
+## Notes
+
+- API keys can be provided via constructor options or the `MISTRAL_API_KEY` environment variable
+- TTS supports 9 languages: English, French, Spanish, Portuguese, Italian, Dutch, German, Hindi, Arabic
+- STT supports 13 languages: English, Chinese, Hindi, Spanish, Arabic, French, Portuguese, Russian, German, Japanese, Korean, Italian, Dutch
+- TTS input text should be kept under 300 words per request for best results
+- STT supports up to 3 hours of audio per request
+- Voice cloning via `refAudio` requires a minimum of 2-3 seconds of reference audio
+- `getSpeakers()` returns preset voices with UUID identifiers. The default `en_paul_neutral` is a named alias accepted by the TTS endpoint but not included in the list

package/.docs/reference/workspace/daytona-sandbox.md

@@ -440,12 +440,8 @@ Then use the snapshot name in your sandbox config:
 ```typescript
 const workspace = new Workspace({
   mounts: {
-    '/s3-data': new S3Filesystem({
-      /* ... */
-    }),
-    '/gcs-data': new GCSFilesystem({
-      /* ... */
-    }),
+    '/s3-data': new S3Filesystem({/* ... */}),
+    '/gcs-data': new GCSFilesystem({/* ... */}),
   },
   sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
 })

package/.docs/reference/workspace/platform-filesystem.md

@@ -0,0 +1,182 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# PlatformFilesystem
+
+Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
+
+Use `PlatformFilesystem` when your agent runs on a Mastra Platform deployment and you want the filesystem to be backed by the platform-provisioned bucket. For direct S3 access, see [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem). For a local directory during development, see [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem).
+
+> **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Configure the platform credentials. The access token, project ID, and bucket name fall back to environment variables, so a Mastra Platform deployment can pass zero constructor options.
+
+**.env file**:
+
+```bash
+MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+**Constructor**:
+
+```typescript
+new PlatformFilesystem({
+  accessToken: 'your-platform-access-token',
+  projectId: 'your-project-id',
+  bucketName: 'your-bucket-name',
+})
+```
+
+On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
+
+## Usage
+
+Add a `PlatformFilesystem` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem } from '@mastra/platform-workspace'
+
+const workspace = new Workspace({
+  filesystem: new PlatformFilesystem({
+    // accessToken, projectId, bucketName all fall back to env vars
+  }),
+})
+
+const agent = new Agent({
+  id: 'file-agent',
+  name: 'File Agent',
+  instructions: 'You are a research assistant that reads and writes reports.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+```
+
+### Reading and writing files
+
+Object keys are percent-encoded per segment, so filenames with `?`, `#`, `%`, `&`, `+`, or spaces are preserved end-to-end:
+
+```typescript
+const fs = new PlatformFilesystem()
+
+await fs.writeFile('/analyses/repo.md', markdown)
+const content = await fs.readFile('/analyses/repo.md')
+const entries = await fs.readdir('/analyses')
+await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')
+```
+
+### Read-only mode
+
+Pass `readOnly: true` to mount the bucket read-only. Any mutating call throws `WorkspaceReadOnlyError`:
+
+```typescript
+const fs = new PlatformFilesystem({ readOnly: true })
+
+await fs.readFile('/analyses/repo.md') // ok
+await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
+```
+
+### Overwrite semantics
+
+`writeFile` supports `overwrite: false` and throws `FileExistsError` when the destination already exists.
+
+`copyFile` and `moveFile` always overwrite the destination. Passing `overwrite: false` to either method throws an error rather than silently overwriting.
+
+### Appending files
+
+`appendFile` is a read-modify-write and is not atomic. Concurrent appends to the same path can overwrite each other. For concurrent writers, use `writeFile` with distinct keys.
+
+## Constructor parameters
+
+**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
+
+**projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
+
+**bucketName** (`string`): Platform bucket name to store files in. Falls back to the MASTRA\_PLATFORM\_BUCKET\_NAME environment variable.
+
+**readOnly** (`boolean`): When true, all mutating calls throw WorkspaceReadOnlyError. (Default: `false`)
+
+**displayName** (`string`): Human-readable name shown in workspace UIs.
+
+**description** (`string`): Short description shown in workspace UIs.
+
+**icon** (`FilesystemIcon`): Icon shown in workspace UIs.
+
+**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.
+
+**id** (`string`): Unique identifier for this filesystem instance. (Default: `Auto-generated`)
+
+**fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
+
+## Properties
+
+**id** (`string`): Filesystem instance identifier.
+
+**name** (`string`): Provider name ('PlatformFilesystem').
+
+**provider** (`string`): Provider identifier ('platform').
+
+**readOnly** (`boolean | undefined`): Whether the filesystem was mounted read-only.
+
+## Errors
+
+Filesystem-specific errors match the standard workspace error types:
+
+- `FileNotFoundError`: The path does not exist. Thrown by `readFile`, `stat`, and `deleteFile` (unless `force: true` is set).
+- `FileExistsError`: `writeFile` was called with `overwrite: false` and the destination already exists.
+- `WorkspaceReadOnlyError`: A mutating call was made on a read-only filesystem.
+
+Other Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string):
+
+```typescript
+import { FileNotFoundError, PlatformApiError } from '@mastra/platform-workspace'
+
+try {
+  await fs.readFile('/missing.txt')
+} catch (err) {
+  if (err instanceof FileNotFoundError) {
+    // handle missing file
+  } else if (err instanceof PlatformApiError) {
+    if (err.code === 'authentication_error') {
+      // refresh token
+    }
+    console.error(err.status, err.code, err.proxyMessage)
+  }
+}
+```
+
+`code` and `proxyMessage` are `undefined` when the response body is not JSON, for example an HTML 502 from a load balancer.
+
+## Related
+
+- [PlatformSandbox reference](https://mastra.ai/reference/workspace/platform-sandbox)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)

package/.docs/reference/workspace/platform-sandbox.md

@@ -0,0 +1,200 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# PlatformSandbox
+
+Executes commands inside a Mastra Platform sandbox tied to a Platform environment. Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed.
+
+Use `PlatformSandbox` when your agent runs on a Mastra Platform deployment and you want the sandbox to be provisioned and managed by the platform. For self-hosted Railway sandboxes, see [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox). For a local sandbox during development, see [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox).
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Configure the platform credentials. The access token, project ID, and environment ID fall back to environment variables, so a Mastra Platform deployment can pass zero constructor options.
+
+**.env file**:
+
+```bash
+MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_ENVIRONMENT_ID=your-environment-id
+```
+
+**Constructor**:
+
+```typescript
+new PlatformSandbox({
+  accessToken: 'your-platform-access-token',
+  projectId: 'your-project-id',
+  environmentId: 'your-environment-id',
+})
+```
+
+On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
+
+## Usage
+
+Add a `PlatformSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformSandbox } from '@mastra/platform-workspace'
+
+const workspace = new Workspace({
+  sandbox: new PlatformSandbox({
+    // accessToken, projectId, environmentId all fall back to env vars
+    idleTimeoutMinutes: 30,
+  }),
+})
+
+const agent = new Agent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  instructions: 'You are a coding assistant working in this workspace.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+
+const response = await agent.generate(
+  'Print "Hello, world!" and show the current working directory.',
+)
+
+console.log(response.text)
+```
+
+### Private networking
+
+Set `networkIsolation` to `PRIVATE` to join the environment's private network and reach other services running in the same Mastra Platform environment:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new PlatformSandbox({
+    networkIsolation: 'PRIVATE',
+  }),
+})
+```
+
+The default `ISOLATED` mode allows outbound internet access only, with no private network connectivity.
+
+### Reattaching to a running sandbox
+
+Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one. This is useful for stateful agents that resume between requests:
+
+```typescript
+const sandbox = new PlatformSandbox({
+  sandboxId: 'sbx_abc123',
+})
+await sandbox.start()
+
+const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
+```
+
+When `sandboxId` is set, `environmentId` is not required because the sandbox already exists.
+
+### Executing commands
+
+`executeCommand` runs a command on the remote sandbox and returns its output. Pass `args` to have arguments safely shell-quoted:
+
+```typescript
+const result = await sandbox.executeCommand('python', ['analyze.py'], {
+  timeout: 30_000,
+  cwd: '/workspace',
+  env: { INPUT: 'repo' },
+})
+
+console.log(result.stdout)
+console.log(result.exitCode)
+```
+
+> **Warning:** The `command` argument is a shell string and is concatenated verbatim into the remote shell. This lets you use pipes, redirects, and chaining (`ls -la | grep foo`) but means untrusted input must be passed through `args` (safely quoted) or shell-quoted by the caller. Untrusted `command` values allow arbitrary shell execution on the sandbox.
+
+## Constructor parameters
+
+**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
+
+**projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
+
+**environmentId** (`string`): Platform environment ID the sandbox belongs to. Falls back to the MASTRA\_ENVIRONMENT\_ID environment variable. Required unless sandboxId is passed.
+
+**sandboxId** (`string`): Existing sandbox ID to reattach to instead of creating a new sandbox. When set, environmentId is not required.
+
+**idleTimeoutMinutes** (`number`): How long the sandbox stays alive with no activity before the platform destroys it.
+
+**networkIsolation** (`'ISOLATED' | 'PRIVATE'`): Network mode. 'ISOLATED' (default) allows outbound internet only. 'PRIVATE' joins the platform environment's private network.
+
+**env** (`Record<string, string>`): Environment variables baked into the sandbox at creation time. Per-command environment variables can also be passed to executeCommand.
+
+**timeout** (`number`): Default command execution timeout in milliseconds. Overridable per call via ExecuteCommandOptions.timeout.
+
+**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.
+
+**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('PlatformSandbox').
+
+**provider** (`string`): Provider identifier ('platform').
+
+**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'.
+
+**processes** (`PlatformProcessManager`): Background process manager. See SandboxProcessManager reference.
+
+## Errors
+
+Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string); the raw response body stays available on `.body`:
+
+```typescript
+import { PlatformApiError } from '@mastra/platform-workspace'
+
+try {
+  await sandbox.executeCommand('cat', ['/missing.txt'])
+} catch (err) {
+  if (err instanceof PlatformApiError) {
+    if (err.code === 'not_found') {
+      // handle missing resource
+    } else if (err.code === 'authentication_error') {
+      // refresh token
+    }
+    console.error(err.status, err.code, err.proxyMessage)
+  }
+}
+```
+
+`code` and `proxyMessage` are `undefined` when the response body is not JSON, for example an HTML 502 from a load balancer.
+
+## Related
+
+- [PlatformFilesystem reference](https://mastra.ai/reference/workspace/platform-filesystem)
+- [RailwaySandbox reference](https://mastra.ai/reference/workspace/railway-sandbox)
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)

package/.docs/reference/workspace/railway-sandbox.md

@@ -2,7 +2,7 @@
 
 # RailwaySandbox
 
-Executes commands in ephemeral, isolated [Railway](https://docs.railway.com/sandboxes) sandboxes. Each sandbox is an isolated Debian Linux VM provisioned on demand through the Railway TypeScript SDK. Supports command execution with streaming output, command timeouts, configurable idle timeout, `ISOLATED`/`PRIVATE` network isolation, custom base images via the Railway template builder, forking a running sandbox, and reattaching to an existing sandbox by ID. For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+Executes commands in ephemeral, isolated [Railway](https://docs.railway.com/sandboxes) sandboxes. Each sandbox is an isolated Debian Linux VM provisioned on demand through the Railway TypeScript SDK. Supports command execution with streaming output, command timeouts, configurable idle timeout, `ISOLATED`/`PRIVATE` network isolation, custom base images via the Railway template builder, checkpoint-backed recovery, forking a running sandbox, and reattaching to an existing sandbox by ID. For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
 ## Installation
 
@@ -128,6 +128,38 @@ console.log(result.stdout)
 
 The forked sandbox inherits the parent's credentials and defaults unless overridden via the `fork()` options.
 
+### Checkpoint recovery
+
+Set `checkpointName` to preserve a sandbox filesystem across Railway sandbox replacement. On `start()`, `RailwaySandbox` first tries to create the sandbox from the named checkpoint. If the checkpoint is missing, it creates a sandbox from the configured template or default image, then captures the checkpoint.
+
+```typescript
+const sandbox = new RailwaySandbox({
+  checkpointName: 'project-session-42',
+  idleTimeoutMinutes: 30,
+})
+```
+
+`RailwaySandbox` refreshes the checkpoint shortly before the idle timeout. Recovery restores the latest successful checkpoint. It doesn't restore running processes or filesystem writes made after the last checkpoint.
+
+Use one stable checkpoint name for each independent filesystem. Do not share a checkpoint name across unrelated sessions or projects.
+
+### Derived sandbox checkpoints
+
+Use `derive({ checkpointName })` when a configured `RailwaySandbox` acts as the template for a sandbox fleet:
+
+```typescript
+const template = new RailwaySandbox({ idleTimeoutMinutes: 30 })
+
+const sessionSandbox = template.derive({
+  id: 'session-42',
+  checkpointName: 'project-session-42',
+})
+
+await sessionSandbox.start()
+```
+
+A derived sandbox uses the checkpoint passed to `derive()`. If no override is passed, it inherits the template sandbox's `checkpointName`.
+
 ### Streaming output
 
 Stream command output in real time via `onStdout` and `onStderr` callbacks:
@@ -162,6 +194,8 @@ const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
 
 **sandboxId** (`string`): Reattach to an existing Railway sandbox by its Railway ID instead of creating a new one. When set, start() calls Sandbox.connect().
 
+**checkpointName** (`string`): Named Railway checkpoint used to seed new sandboxes and preserve the filesystem before idle teardown. Use a unique stable name for each independent filesystem.
+
 **idleTimeoutMinutes** (`number`): How long the sandbox can sit idle (no exec interaction) before Railway destroys it automatically. The valid range and default depend on your Railway plan.
 
 **networkIsolation** (`'ISOLATED' | 'PRIVATE'`): Network access mode. 'ISOLATED' allows outbound internet only; 'PRIVATE' joins the environment's private network. (Default: `'ISOLATED'`)
@@ -192,6 +226,8 @@ const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
 
 **fork** (`(options?) => Promise<RailwaySandbox>`): Clone this running sandbox into a new, independent RailwaySandbox. The returned sandbox is already started and reattached to the forked Railway sandbox. Accepts optional id, idleTimeoutMinutes, networkIsolation, and env overrides. Throws SandboxNotReadyError if this sandbox has not been started.
 
+**derive** (`(options?) => RailwaySandbox`): Construct an unstarted sibling sandbox that inherits credentials and defaults. Accepts optional id, sandboxId, env, idleTimeoutMinutes, and checkpointName overrides. The derived sandbox uses options.checkpointName when set, otherwise it inherits the template checkpointName.
+
 ## Background processes
 
 `RailwaySandbox` includes a built-in process manager for spawning and managing background processes. Each spawned process runs as a Railway `exec` session.