Class: SshRuntime

Coordinates Sandbox REST operations, Lakebase assignments, SSH sessions, command execution, built-in services, and web routes.

Every machine operation verifies an unexpired Lakebase assignment for the workspace, AppKit user, and Sandbox ID. Runtime epochs invalidate pending session, service, and route work after stop, delete, or reconciliation.

Constructors

Constructor

new SshRuntime(config, ownership?): SshRuntime

Creates a runtime with optional preinitialized ownership storage.

Parameters

config

auto

boolean = ...

commandTimeoutMs

number = ...

connectTimeoutMs

number = ...

fallbackToServicePrincipal

boolean = ...

gatewayPort

number = ...

keyDirectory?

string = ...

machineSoftware

object[] = ...

reaperIntervalSeconds

number = ...

routePrefix

string = ...

sandboxLifetimeSeconds

number = ...

ownership?

LakebaseMachineOwnershipStore

Returns

SshRuntime

Properties

config

readonly config: object

auto

auto: boolean

commandTimeoutMs

commandTimeoutMs: number

connectTimeoutMs

connectTimeoutMs: number

fallbackToServicePrincipal

fallbackToServicePrincipal: boolean

gatewayPort

gatewayPort: number

keyDirectory?

optional keyDirectory?: string

machineSoftware

machineSoftware: object[]

reaperIntervalSeconds

reaperIntervalSeconds: number

routePrefix

routePrefix: string

sandboxLifetimeSeconds

sandboxLifetimeSeconds: number

routes

readonly routes: SshRouteRegistry

Methods

addProject()

addProject(client, userId, input, signal?): 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, persisted Sandbox project and route.

Parameters

client

WorkspaceClient$1

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 = ...

signal?

AbortSignal

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; }>

close()

close(): Promise<void>

Stops the reaper and closes sessions, routes, service state, and ownership resources.

Returns

Promise<void>

createMachine()

createMachine(client, userId, input?, signal?): 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 a managed Sandbox and persists its assignment before returning it. If the Lakebase write fails, the newly created Sandbox is deleted.

Parameters

client

WorkspaceClient$1

userId

string

input?

desktop?

boolean = ...

signal?

AbortSignal

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(client, userId, machineId, signal?): Promise<{ deleted: boolean; }>

Deletes one assigned Sandbox, removes all assignments, and clears local runtime state.

Parameters

client

WorkspaceClient$1

userId

string

machineId

string

signal?

AbortSignal

Returns

Promise<{ deleted: boolean; }>

disconnect()

disconnect(workspaceScope, userId, machineId): void

Invalidates and closes one cached SSH session without changing the remote Sandbox.

Parameters

workspaceScope

string

userId

string

machineId

string

Returns

void

execute()

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

Executes a command on an assigned Sandbox, starting the machine first when auto is enabled and rejecting stale work after ownership changes.

Parameters

client

WorkspaceClient$1

userId

string

input

args?

string[] = ...

command

string = ...

cwd?

string = ...

env?

Record<string, string> = ...

machineId

string = ...

timeoutMs?

number = ...

signal?

AbortSignal

Returns

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

initializeOwnership()

initializeOwnership(pool?): Promise<void>

Initializes the Lakebase ownership and expiration store.

Parameters

pool?

LakebasePool

Returns

Promise<void>

Throws

When the AppKit Lakebase plugin did not provide a pool.

listMachines()

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

Lists only valid, unexpired Sandboxes assigned to one AppKit user. Returns supported: false when the workspace or region does not expose the Sandbox API.

Parameters

client

WorkspaceClient$1

userId

string

signal?

AbortSignal

Returns

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

openProjectTerminal()

openProjectTerminal(client, userId, projectId, signal?): 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 directory.

Parameters

client

WorkspaceClient$1

userId

string

projectId

string

signal?

AbortSignal

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"; }; }>

projectList()

projectList(client, userId): Promise<object[]>

Lists persisted projects for one AppKit user.

Parameters

client

WorkspaceClient$1

userId

string

Returns

Promise<object[]>

projectPathPrefix()

projectPathPrefix(userId): string

Returns the user-scoped project path prefix beneath the configured root path.

Parameters

userId

string

Returns

string

reapMachines()

reapMachines(client, signal?): Promise<SandboxReaperResult>

Reconciles Lakebase assignments with managed Sandbox names and expirations. Concurrent calls share one in-flight pass, and replicas serialize through the workspace-scoped Lakebase advisory lock.

Parameters

client

WorkspaceClient$1

signal?

AbortSignal

Returns

Promise<SandboxReaperResult>

removeProject()

removeProject(client, userId, projectId, signal?): Promise<boolean>

Removes one project, runs optional mise stop and uninstall, then deletes its directory and route.

Parameters

client

WorkspaceClient$1

userId

string

projectId

string

signal?

AbortSignal

Returns

Promise<boolean>

resetProject()

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

Recreates one persisted project’s directory from its saved mise configuration.

Parameters

client

WorkspaceClient$1

userId

string

projectId

string

signal?

AbortSignal

Returns

startMachine()

startMachine(client, userId, machineId, signal?): 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, waits for the running state, and attempts to provision its terminal and metrics services.

Parameters

client

WorkspaceClient$1

userId

string

machineId

string

signal?

AbortSignal

Returns

startReaper()

startReaper(client): Promise<SandboxReaperResult>

Runs an immediate reconciliation pass and starts the periodic reaper when ResolvedSshPluginConfig.reaperIntervalSeconds is greater than zero. Initial failures are logged and returned as one failure instead of preventing AppKit startup.

Parameters

client

WorkspaceClient$1

Returns

Promise<SandboxReaperResult>

startService()

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

Starts or reuses one built-in browser service and its owner-scoped AppKit route. Concurrent requests for the same service share one operation.

Parameters

client

WorkspaceClient$1

userId

string

input

machineId

string = ...

service

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

signal?

AbortSignal

Returns

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

stopMachine()

stopMachine(client, userId, machineId, signal?): 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, waits for it to stop, and clears local runtime state.

Parameters

client

WorkspaceClient$1

userId

string

machineId

string

signal?

AbortSignal

Returns

withAuthFallback()

withAuthFallback<T>(operation, attempt): Promise<T>

Runs a workspace operation with OBO credentials first and optionally retries it with the app service principal.

Service-principal retry occurs only when ResolvedSshPluginConfig.fallbackToServicePrincipal is enabled. Both attempts emit sanitized diagnostics.

Type Parameters

T

T

Parameters

operation

WorkspaceAuthOperation

attempt

WorkspaceAuthAttempt<T>

Returns

Promise<T>