Class: SshWorkspaceSandbox

Mastra workspace sandbox backed by one existing assigned Databricks Sandbox.

Lifecycle and command methods delegate to SshRuntime, so assignment, authentication fallback, SSH key, and host-verification policy match the AppKit plugin tools and routes.

Extends

MastraSandbox

Constructors

Constructor

new SshWorkspaceSandbox(id, name, runtime, client, userId): SshWorkspaceSandbox

Parameters

id

string

name

string

runtime

SshRuntime

client

WorkspaceClient$1

userId

string

Returns

SshWorkspaceSandbox

Overrides

MastraSandbox.constructor

Properties

_destroyPromise?

protected optional _destroyPromise?: Promise<void>

Promise for _destroy() to prevent race conditions from concurrent calls

Inherited from

MastraSandbox._destroyPromise

_startPromise?

protected optional _startPromise?: Promise<void | SandboxStartResult>

Promise for _start() to prevent race conditions from concurrent calls

Inherited from

MastraSandbox._startPromise

_stopPromise?

protected optional _stopPromise?: Promise<void>

Promise for _stop() to prevent race conditions from concurrent calls

Inherited from

MastraSandbox._stopPromise

_workingDirectory?

protected optional _workingDirectory?: string

Effective default working directory, exposed via the workingDirectory getter. Protected so providers that compute or probe their effective value (e.g. a default like /workspace, or a runtime probe) can write it back with setWorkingDirectory and keep the getter truthful.

Inherited from

MastraSandbox._workingDirectory

component

component: RegisteredLogger

Inherited from

MastraSandbox.component

computer?

readonly optional computer?: SandboxComputer

Optional computer-use (desktop) capability - implement to enable workspace computer tools

Inherited from

MastraSandbox.computer

id

readonly id: string

Inherited from

MastraSandbox.id

logger

protected logger: IMastraLogger

Inherited from

MastraSandbox.logger

mounts?

readonly optional mounts?: MountManager

Mount manager - automatically created if subclass implements mount()

Inherited from

MastraSandbox.mounts

name

readonly name: string

Inherited from

MastraSandbox.name

networking?

readonly optional networking?: SandboxNetworking

Optional networking capability - implement to expose public port URLs

Inherited from

MastraSandbox.networking

processes?

readonly optional processes?: SandboxProcessManager<MastraSandbox<unknown>>

Process manager

Inherited from

MastraSandbox.processes

provider

readonly provider: "appkit-sandbox" = "appkit-sandbox"

Provider type identifier

Overrides

MastraSandbox.provider

status

status: ProviderStatus = "pending"

Current status of the sandbox

Overrides

MastraSandbox.status

supportsCheckpoints

readonly supportsCheckpoints: boolean

Whether snapshot() persists real checkpoints. Providers overriding snapshot() with a real implementation should also override this to true.

Inherited from

MastraSandbox.supportsCheckpoints

Accessors

workingDirectory

Get Signature

get workingDirectory(): string | undefined

The sandbox’s default working directory, when one is configured.

Commands and process spawns without a per-command cwd run here; per-command cwd always wins. undefined means the provider’s own default applies (typically the home directory).

Returns

string | undefined

Inherited from

MastraSandbox.workingDirectory

Methods

_destroy()

_destroy(): Promise<void>

Destroy the sandbox and clean up all resources (wrapper with status management).

This method is race-condition-safe - concurrent calls will return the same promise. Handles status management.

Subclasses override destroy() to provide their destroy logic.

Returns

Promise<void>

Inherited from

MastraSandbox._destroy

_start()

_start(options?): Promise<void | SandboxStartResult>

Start the sandbox (wrapper with status management and race-condition safety).

This method is race-condition-safe - concurrent calls will return the same promise. Handles status management and automatically processes pending mounts after startup.

Subclasses override start() to provide their startup logic.

Parameters

options?

SandboxStartOptions

Returns

Promise<void | SandboxStartResult>

Inherited from

MastraSandbox._start

_stop()

_stop(): Promise<void>

Stop the sandbox (wrapper with status management and race-condition safety).

This method is race-condition-safe - concurrent calls will return the same promise. Handles status management.

Subclasses override stop() to provide their stop logic.

Returns

Promise<void>

Inherited from

MastraSandbox._stop

connect()?

protected optional connect(handle, options?): void | Promise<void>

Adopt/wake/resume the handle find returned. Throwing fails start(): a provider that should fall back to creating fresh puts that policy in find (return undefined for an unusable handle) instead.

Parameters

handle

unknown

options?

SandboxStartOptions

Returns

void | Promise<void>

Inherited from

MastraSandbox.connect

create()?

protected optional create(options?): void | Promise<void>

Provision a fresh VM/environment for this sandbox’s logical id. Implementing this without overriding start() opts into base-orchestrated acquisition, which derives the outcome from the branch that ran: find then connect reports ‘connected’, create reports ‘created’.

Parameters

options?

SandboxStartOptions

Returns

void | Promise<void>

Inherited from

MastraSandbox.create

destroy()

destroy(): Promise<void>

Disconnects local session state without deleting the remote Sandbox.

Returns

Promise<void>

Overrides

MastraSandbox.destroy

ensureRunning()

ensureRunning(): Promise<void>

Ensure the sandbox is running.

Calls _start() if status is not ‘running’. Useful for lazy initialization where operations should automatically start the sandbox if needed.

This is the lazy entry point into the id-keyed getOrCreate contract described on start.

Returns

Promise<void>

Throws

if the sandbox fails to reach ‘running’ status

Example

async executeCommand(command: string): Promise<CommandResult> {
  await this.ensureRunning();
  // Now safe to use the sandbox
}

Inherited from

MastraSandbox.ensureRunning

executeCommand()

executeCommand(command, args?, options?): Promise<CommandResult>

Runs a command through the shared runtime and current AppKit request identity.

Parameters

command

string

args?

string[] = []

options?

ExecuteCommandOptions = {}

Returns

Promise<CommandResult>

Overrides

MastraSandbox.executeCommand

find()?

protected optional find(options?): Promise<unknown>

Locate an existing VM/environment for this sandbox’s logical id. Returns a provider-native handle for connect to adopt, or undefined when nothing usable exists. Avoid side effects where the provider’s API allows.

Parameters

options?

SandboxStartOptions

Returns

Promise<unknown>

Inherited from

MastraSandbox.find

getEnv()

getEnv(): Record<string, string | undefined>

Snapshot of the current runtime environment overlay.

Returns a fresh copy — mutating it never affects the stored overlay; use setEnv to change it. The process manager reads this per spawn to merge the overlay into command environments.

Returns

Record<string, string | undefined>

Inherited from

MastraSandbox.getEnv

getInfo()

getInfo(): Promise<SandboxInfo>

Returns the latest assigned machine metadata in Mastra’s Sandbox shape.

Returns

Promise<SandboxInfo>

Overrides

MastraSandbox.getInfo

getInstructions()

getInstructions(): string

Returns agent instructions for machine reuse and public route requirements.

Returns

string

Overrides

MastraSandbox.getInstructions

mount()?

optional mount(filesystem, mountPath): Promise<MountResult>

Optional mount method - implement to enable mounting support

Parameters

filesystem

WorkspaceFilesystem

mountPath

string

Returns

Promise<MountResult>

Inherited from

MastraSandbox.mount

setEnv()

setEnv(update): void

Update the sandbox’s runtime environment overlay.

The updater receives a copy of the current overlay and returns the new one, so a single call can set, unset, or batch-update variables:

sandbox.setEnv(env => ({ ...env, GH_TOKEN: token }));

Changes apply immediately to subsequent commands and processes routed through the sandbox’s process manager (including the built-in executeCommand), survive provider pause/resume and VM replacement, and are never written into the VM — the overlay is merged per spawn, not persisted. Removing a key removes it from the overlay only; env values a provider supplies on its own still apply.

Parameters

update

(env) => Record<string, string | undefined>

Returns

void

Inherited from

MastraSandbox.setEnv

setOnStart()

setOnStart(update): void

Attach or replace the start hook after construction. The updater receives the installed hook and returns its replacement, so callers compose instead of clobbering a hook they didn’t know about; ignoring prev replaces it.

sandbox.setOnStart(prev => async args => {
  await prev?.(args); // whatever prepared the sandbox runs first
  await mySetup(args);
});

Errors stay FATAL, so a throw stops the hooks after it. Each call wraps the current hook, so attach once per sandbox or the work stacks.

Parameters

update

(previous) => SandboxStartHook

Returns

void

Inherited from

MastraSandbox.setOnStart

setWorkingDirectory()

protected setWorkingDirectory(dir): void

Set the effective working directory after construction. For providers that resolve the value themselves — a computed default, or a runtime probe that needs a running VM — so the workingDirectory getter stays truthful.

Parameters

dir

string

Returns

void

Inherited from

MastraSandbox.setWorkingDirectory

snapshot()

snapshot(): Promise<void>

Mastra snapshot hook. Databricks Sandboxes do not expose snapshot operations.

Returns

Promise<void>

Overrides

MastraSandbox.snapshot

start()

start(options?): Promise<SandboxStartResult>

Starts the assigned Sandbox and reports a connected Mastra outcome.

Parameters

options?

SandboxStartOptions

Returns

Promise<SandboxStartResult>

Overrides

MastraSandbox.start

stop()

stop(): Promise<void>

Stops the assigned Sandbox.

Returns

Promise<void>

Overrides

MastraSandbox.stop

toRawConfig()

toRawConfig(): Record<string, unknown> | undefined

Returns the raw storage configuration this primitive was created from, or undefined if it was created from code.

Returns

Record<string, unknown> | undefined

Inherited from

MastraSandbox.toRawConfig

unmount()?

optional unmount(mountPath): Promise<void>

Optional unmount method

Parameters

mountPath

string

Returns

Promise<void>

Inherited from

MastraSandbox.unmount

writeFiles()?

optional writeFiles(files, options?): Promise<void>

Optional bulk file upload into the sandbox’s own filesystem.

Method syntax (not property syntax) is intentional — it prevents useDefineForClassFields from emitting this.writeFiles = undefined which would shadow prototype methods defined by subclasses.

Parameters

files

SandboxFileInput[]

options?

WriteFilesOptions

Returns

Promise<void>

Inherited from

MastraSandbox.writeFiles