Class: AppKitSshPlugin

AppKit plugin for Databricks Sandbox lifecycle, SSH, service, and route operations.

The plugin registers owner-scoped REST routes, AppKit agent tools, HTTP proxy middleware, and WebSocket upgrade handling. It initializes SshRuntime with the existing service-principal Lakebase pool captured during setup and starts the expiration reaper.

Extends

ToolRegistryPlugin<SshPluginConfig>

Constructors

Constructor

new AppKitSshPlugin(config?): AppKitSshPlugin

Creates a plugin with a supplied shared runtime or a runtime from resolved config.

Parameters

config?

SshPluginConfig = {}

Returns

AppKitSshPlugin

Overrides

ToolRegistryPlugin<SshPluginConfig>.constructor

Properties

app

protected app: AppManager

Inherited from

ToolRegistryPlugin.app

cache

protected cache: CacheManager

Inherited from

ToolRegistryPlugin.cache

config

protected config: SshPluginConfig

Inherited from

ToolRegistryPlugin.config

context?

protected optional context?: PluginContext

Inherited from

ToolRegistryPlugin.context

devFileReader

protected devFileReader: DevFileReader

Inherited from

ToolRegistryPlugin.devFileReader

isReady

protected isReady: boolean

Inherited from

ToolRegistryPlugin.isReady

name

name: string

Plugin name identifier.

Inherited from

ToolRegistryPlugin.name

runtime

readonly runtime: SshRuntime

streamManager

protected streamManager: StreamManager

Inherited from

ToolRegistryPlugin.streamManager

telemetry

protected telemetry: ITelemetry

Inherited from

ToolRegistryPlugin.telemetry

manifest

static manifest: object

config

config: object

config.schema

schema: JSONSchema7 = SSH_CONFIG_SCHEMA

description

description: string = "Creates and manages Databricks Sandboxes over REST and SSH, with remote web routing and Mastra tools."

displayName

displayName: string = "Sandboxes"

name

name: "databricks-sandbox" = "databricks-sandbox"

resources

resources: object

resources.optional

optional: never[] = []

resources.required

required: never[] = []

stability

stability: "beta" = "beta"

phase

static phase: PluginPhase

Plugin initialization phase.

‘core’: Initialized first (e.g., config plugins)
‘normal’: Initialized second (most plugins)
‘deferred’: Initialized last (e.g., server plugin)

Inherited from

ToolRegistryPlugin.phase

Accessors

toolRegistry

Get Signature

get protected toolRegistry(): ToolRegistry

Native AppKit tool entries exposed by this plugin.

Returns

ToolRegistry

Overrides

ToolRegistryPlugin.toolRegistry

Methods

abortActiveOperations()

abortActiveOperations(): void

Cancel in-flight work (abort signals, SSE streams). Runs in the first phase of graceful shutdown, BEFORE any plugin’s shutdown() hook — so it must not tear down shared resources (e.g. connection pools) that other plugins’ hooks may still need. Put teardown in shutdown().

Returns

void

Inherited from

ToolRegistryPlugin.abortActiveOperations

addProject()

addProject(userId, input): Promise<{ directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }>

Creates or updates one isolated Sandbox project with a persisted route.

Parameters

userId

string

input

config?

Record<string, JSONType> = ...

machineId

string = ...

name?

string = ...

openPath?

string = ...

path?

string = ...

port?

number = ...

projectId?

string = ...

route?

boolean = ...

serviceDependencies?

("terminal" | "desktop" | "stats")[] = ...

stripPrefix?

boolean = ...

Returns

Promise<{ directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }>

asUser()

asUser(req): this

Execute operations using the user’s identity from the request. Returns a proxy of this plugin where all method calls execute with the user’s Databricks credentials instead of the service principal.

Parameters

req

Request

The Express request containing the user token in headers

Returns

this

A proxied plugin instance that executes as the user

Throws

AuthenticationError if user token is not available in request headers (production only). In development mode (NODE_ENV=development), skips user impersonation instead of throwing.

Inherited from

ToolRegistryPlugin.asUser

attachContext()

attachContext(deps?): void

Binds runtime dependencies (telemetry provider, cache, plugin context) to this plugin. Called by AppKit._createApp after construction and before setup(). Idempotent: safe to call if the constructor already bound them eagerly. Kept separate so factories can eagerly construct plugin instances without running this before TelemetryManager.initialize() / CacheManager.getInstance() have run.

Parameters

deps?

context?

unknown

telemetryConfig?

TelemetryOptions

Returns

void

Inherited from

ToolRegistryPlugin.attachContext

clientConfig()

clientConfig(): Record<string, unknown>

Returns browser-safe route defaults published through AppKit client config.

Returns

Record<string, unknown>

Overrides

ToolRegistryPlugin.clientConfig

createMachine()

createMachine(userId, input?): Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

Creates and assigns a managed Sandbox to one AppKit user.

Parameters

userId

string

input?

desktop?

boolean = ...

Returns

Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

deleteMachine()

deleteMachine(userId, machineId): Promise<{ deleted: boolean; }>

Deletes one assigned Sandbox.

Parameters

userId

string

machineId

string

Returns

Promise<{ deleted: boolean; }>

execute()

protected execute<T>(fn, options, userKey?): Promise<ExecutionResult<T>>

Execute a function with the plugin’s interceptor chain.

Returns an ExecutionResult discriminated union:

{ ok: true, data: T } on success
{ ok: false, status: number, message: string } on failure

Errors are never thrown — the method is production-safe.

Type Parameters

T

T

Parameters

fn

(signal?) => Promise<T>

options

PluginExecutionSettings

userKey?

string

Returns

Promise<ExecutionResult<T>>

Inherited from

ToolRegistryPlugin.execute

executeAgentTool()

executeAgentTool(name, args, signal?, context?): Promise<unknown>

Executes one registered agent tool with the request resource and workspace identity.

Parameters

name

string

args

unknown

signal?

AbortSignal

context?

AgentToolExecutionContext

Returns

Promise<unknown>

Overrides

ToolRegistryPlugin.executeAgentTool

executeCommand()

executeCommand(userId, input): Promise<{ args: string[]; command: string; executionTimeMs: number; exitCode: number; stderr: string; stdout: string; success: boolean; timedOut?: boolean; }>

Runs one command on an assigned Sandbox.

Parameters

userId

string

input

args?

string[] = ...

command

string = ...

cwd?

string = ...

env?

Record<string, string> = ...

machineId

string = ...

timeoutMs?

number = ...

Returns

Promise<{ args: string[]; command: string; executionTimeMs: number; exitCode: number; stderr: string; stdout: string; success: boolean; timedOut?: boolean; }>

executeStream()

protected executeStream<T>(res, fn, options, userKey?): Promise<void>

Type Parameters

T

T

Parameters

res

IAppResponse

fn

StreamExecuteHandler<T>

options

StreamExecutionSettings

userKey?

string

Returns

Promise<void>

Inherited from

ToolRegistryPlugin.executeStream

exports()

exports(): object

Returns the typed sibling-plugin API for machine, command, service, route, and toolkit operations.

Returns

object

addProject

addProject: (userId, input) => Promise<{ directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }>

Parameters

userId

string

input

config?

Record<string, JSONType> = ...

machineId

string = ...

name?

string = ...

openPath?

string = ...

path?

string = ...

port?

number = ...

projectId?

string = ...

route?

boolean = ...

serviceDependencies?

("terminal" | "desktop" | "stats")[] = ...

stripPrefix?

boolean = ...

Returns

createMachine

createMachine: (userId, input) => Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

Parameters

userId

string

input

desktop?

boolean = ...

Returns

deleteMachine

deleteMachine: (userId, machineId) => Promise<{ deleted: boolean; }>

Parameters

userId

string

machineId

string

Returns

Promise<{ deleted: boolean; }>

executeCommand

executeCommand: (userId, input) => Promise<{ args: string[]; command: string; executionTimeMs: number; exitCode: number; stderr: string; stdout: string; success: boolean; timedOut?: boolean; }>

Parameters

userId

string

input

args?

string[] = ...

command

string = ...

cwd?

string = ...

env?

Record<string, string> = ...

machineId

string = ...

timeoutMs?

number = ...

Returns

Promise<{ args: string[]; command: string; executionTimeMs: number; exitCode: number; stderr: string; stdout: string; success: boolean; timedOut?: boolean; }>

listMachines

listMachines: (userId) => Promise<{ auto: boolean; machines: object[]; supported: boolean; }>

Parameters

userId

string

Returns

Promise<{ auto: boolean; machines: object[]; supported: boolean; }>

listProjects

listProjects: (userId) => Promise<{ pathPrefix: string; projects: object[]; }>

Parameters

userId

string

Returns

Promise<{ pathPrefix: string; projects: object[]; }>

openProjectTerminal

openProjectTerminal: (userId, projectId) => Promise<{ project: { directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }; service: { error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }; }>

Parameters

userId

string

projectId

string

Returns

Promise<{ project: { directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }; service: { error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }; }>

operations

operations: (userId, userClient?) => object

Parameters

userId

string

userClient?

WorkspaceClient$1

Returns

object

add_ssh_project

readonly add_ssh_project: AppKitOperation<ZodObject<{ config: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>; machineId: ZodString; name: ZodOptional<ZodString>; openPath: ZodOptional<ZodString>; path: ZodOptional<ZodString>; port: ZodOptional<ZodNumber>; projectId: ZodOptional<ZodString>; route: ZodOptional<ZodBoolean>; serviceDependencies: ZodOptional<ZodArray<ZodEnum<{ desktop: "desktop"; stats: "stats"; terminal: "terminal"; }>>>; stripPrefix: ZodOptional<ZodBoolean>; }, $strict>, unknown>

create_ssh_machine

readonly create_ssh_machine: AppKitOperation<ZodObject<{ desktop: ZodOptional<ZodBoolean>; }, $strict>, unknown>

delete_ssh_machine

readonly delete_ssh_machine: AppKitOperation<ZodObject<{ machineId: ZodString; }, $strict>, unknown>

execute_ssh_command

readonly execute_ssh_command: AppKitOperation<ZodObject<{ args: ZodDefault<ZodArray<ZodString>>; command: ZodString; cwd: ZodOptional<ZodString>; env: ZodOptional<ZodRecord<ZodString, ZodString>>; machineId: ZodString; timeoutMs: ZodOptional<ZodNumber>; }, $strict>, unknown>

list_ssh_machines

readonly list_ssh_machines: AppKitOperation<ZodObject<{ }, $strict>, unknown>

list_ssh_projects

readonly list_ssh_projects: AppKitOperation<ZodObject<{ }, $strict>, unknown>

open_ssh_project_terminal

readonly open_ssh_project_terminal: AppKitOperation<ZodObject<{ projectId: ZodString; }, $strict>, unknown>

remove_ssh_project

readonly remove_ssh_project: AppKitOperation<ZodObject<{ projectId: ZodString; }, $strict>, unknown>

reset_ssh_project

readonly reset_ssh_project: AppKitOperation<ZodObject<{ projectId: ZodString; }, $strict>, unknown>

start_ssh_machine

readonly start_ssh_machine: AppKitOperation<ZodObject<{ machineId: ZodString; }, $strict>, unknown>

start_ssh_machine_service

readonly start_ssh_machine_service: AppKitOperation<ZodObject<{ machineId: ZodString; service: ZodEnum<{ desktop: "desktop"; stats: "stats"; terminal: "terminal"; }>; }, $strict>, unknown>

stop_ssh_machine

readonly stop_ssh_machine: AppKitOperation<ZodObject<{ machineId: ZodString; }, $strict>, unknown>

removeProject

removeProject: (userId, projectId) => Promise<boolean>

Parameters

userId

string

projectId

string

Returns

Promise<boolean>

resetProject

resetProject: (userId, projectId) => Promise<{ directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }>

Parameters

userId

string

projectId

string

Returns

startMachine

startMachine: (userId, machineId) => Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

Parameters

userId

string

machineId

string

Returns

startMachineService

startMachineService: (userId, input) => Promise<{ error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }>

Parameters

userId

string

input

machineId

string = ...

service

"terminal" | "desktop" | "stats" = ...

Returns

Promise<{ error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }>

stopMachine

stopMachine: (userId, machineId) => Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

Parameters

userId

string

machineId

string

Returns

toolkit

toolkit: (options?) => Record<string, ToolkitEntry>

Parameters

options?

ToolkitOptions

Returns

Record<string, ToolkitEntry>

Overrides

ToolRegistryPlugin.exports

getAgentTools()

getAgentTools(): AgentToolDefinition[]

Tool definitions offered to an AppKit agent.

Returns

AgentToolDefinition[]

Inherited from

ToolRegistryPlugin.getAgentTools

getEndpoints()

getEndpoints(): PluginEndpointMap

Returns

PluginEndpointMap

Inherited from

ToolRegistryPlugin.getEndpoints

getSkipBodyParsingPaths()

getSkipBodyParsingPaths(): ReadonlySet<string>

Returns

ReadonlySet<string>

Inherited from

ToolRegistryPlugin.getSkipBodyParsingPaths

injectRoutes()

injectRoutes(router): void

Parameters

router

Router

Returns

void

Overrides

ToolRegistryPlugin.injectRoutes

listMachines()

listMachines(userId): Promise<{ auto: boolean; machines: object[]; supported: boolean; }>

Lists valid assigned machines through the plugin’s active workspace identity.

Parameters

userId

string

Returns

Promise<{ auto: boolean; machines: object[]; supported: boolean; }>

listProjects()

listProjects(userId): Promise<{ pathPrefix: string; projects: object[]; }>

Lists persisted projects owned by one AppKit user.

Parameters

userId

string

Returns

Promise<{ pathPrefix: string; projects: object[]; }>

openProjectTerminal()

openProjectTerminal(userId, projectId): Promise<{ project: { directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }; service: { error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }; }>

Opens ttyd rooted at one persisted project.

Parameters

userId

string

projectId

string

Returns

operations()

operations(userId?, userClient?): object

Returns the Zod-owned operation contracts used by REST, plugins, and agent tools.

Parameters

userId?

string

userClient?

WorkspaceClient$1

Returns

object

add_ssh_project

readonly add_ssh_project: AppKitOperation<ZodObject<{ config: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>; machineId: ZodString; name: ZodOptional<ZodString>; openPath: ZodOptional<ZodString>; path: ZodOptional<ZodString>; port: ZodOptional<ZodNumber>; projectId: ZodOptional<ZodString>; route: ZodOptional<ZodBoolean>; serviceDependencies: ZodOptional<ZodArray<ZodEnum<{ desktop: "desktop"; stats: "stats"; terminal: "terminal"; }>>>; stripPrefix: ZodOptional<ZodBoolean>; }, $strict>, unknown>

create_ssh_machine

readonly create_ssh_machine: AppKitOperation<ZodObject<{ desktop: ZodOptional<ZodBoolean>; }, $strict>, unknown>

delete_ssh_machine

readonly delete_ssh_machine: AppKitOperation<ZodObject<{ machineId: ZodString; }, $strict>, unknown>

execute_ssh_command

readonly execute_ssh_command: AppKitOperation<ZodObject<{ args: ZodDefault<ZodArray<ZodString>>; command: ZodString; cwd: ZodOptional<ZodString>; env: ZodOptional<ZodRecord<ZodString, ZodString>>; machineId: ZodString; timeoutMs: ZodOptional<ZodNumber>; }, $strict>, unknown>

list_ssh_machines

readonly list_ssh_machines: AppKitOperation<ZodObject<{ }, $strict>, unknown>

list_ssh_projects

readonly list_ssh_projects: AppKitOperation<ZodObject<{ }, $strict>, unknown>

open_ssh_project_terminal

readonly open_ssh_project_terminal: AppKitOperation<ZodObject<{ projectId: ZodString; }, $strict>, unknown>

remove_ssh_project

readonly remove_ssh_project: AppKitOperation<ZodObject<{ projectId: ZodString; }, $strict>, unknown>

reset_ssh_project

readonly reset_ssh_project: AppKitOperation<ZodObject<{ projectId: ZodString; }, $strict>, unknown>

start_ssh_machine

readonly start_ssh_machine: AppKitOperation<ZodObject<{ machineId: ZodString; }, $strict>, unknown>

start_ssh_machine_service

readonly start_ssh_machine_service: AppKitOperation<ZodObject<{ machineId: ZodString; service: ZodEnum<{ desktop: "desktop"; stats: "stats"; terminal: "terminal"; }>; }, $strict>, unknown>

stop_ssh_machine

readonly stop_ssh_machine: AppKitOperation<ZodObject<{ machineId: ZodString; }, $strict>, unknown>

registerEndpoint()

protected registerEndpoint(name, path): void

Parameters

name

string

path

string

Returns

void

Inherited from

ToolRegistryPlugin.registerEndpoint

removeProject()

removeProject(userId, projectId): Promise<boolean>

Removes one Sandbox project and its isolated directory.

Parameters

userId

string

projectId

string

Returns

Promise<boolean>

resetProject()

resetProject(userId, projectId): Promise<{ directory: string; error?: string; id: string; machineId: string; name: string; openUrl?: string; path: string; port: number; state: "error" | "starting" | "stopped" | "ready"; stripPrefix: boolean; }>

Wipes and recreates one persisted project from its saved configuration.

Parameters

userId

string

projectId

string

Returns

resolveUserId()

protected resolveUserId(req): string

Resolve the effective user ID from a request.

Returns the x-forwarded-user header when present. In development mode (NODE_ENV=development) falls back to the current context user ID so that callers outside an active runInUserContext scope still get a consistent value.

Parameters

req

Request

Returns

string

Throws

AuthenticationError in production when no user header is present.

Inherited from

ToolRegistryPlugin.resolveUserId

route()

protected route<_TResponse>(router, config): void

Type Parameters

_TResponse

_TResponse

Parameters

router

Router

config

RouteConfig

Returns

void

Inherited from

ToolRegistryPlugin.route

setup()

setup(): Promise<void>

Returns

Promise<void>

Overrides

ToolRegistryPlugin.setup

shutdown()

shutdown(): Promise<void>

Detaches WebSocket handling and closes the shared runtime.

Returns

Promise<void>

startMachine()

startMachine(userId, machineId): Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

Starts one assigned Sandbox.

Parameters

userId

string

machineId

string

Returns

startMachineService()

startMachineService(userId, input): Promise<{ error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }>

Starts or reuses one built-in terminal or metrics service.

Parameters

userId

string

input

machineId

string = ...

service

"terminal" | "desktop" | "stats" = ...

Returns

Promise<{ error?: string; kind: "terminal" | "desktop" | "stats"; openUrl: string; path: string; state: "error" | "starting" | "stopped" | "ready"; }>

stopMachine()

stopMachine(userId, machineId): Promise<{ autoStopSeconds?: number; canConnect: boolean; canStart: boolean; canStop: boolean; createdAt?: string; expiresAt: string; gatewayHost?: string; id: string; lastStartedAt?: string; name: string; projects: object[]; provider: "databricks-sandbox"; services: object[]; status: "error" | "unknown" | "starting" | "running" | "stopping" | "stopped"; }>

Stops one assigned Sandbox.

Parameters

userId

string

machineId

string

Returns

toolkit()

toolkit(options?): Record<string, ToolkitEntry>

Returns selected AppKit toolkit entries backed by this plugin’s agent tools.

Parameters

options?

ToolkitOptions

Returns

Record<string, ToolkitEntry>