Terminal helper

Server session methods

const session = await cybr.deployments.createTerminalSession(deploymentId, {
  pollIntervalMs: 2000,
  timeoutMs: 30000,
  signal: abortController.signal
})

// A saved or newly launched deployment handle has the same method.
const anotherSession = await deployment.createTerminalSession()

All configuration fields are optional. The defaults are a two-second interval and a 30-second startup deadline. Only CONTAINER_STARTING triggers the startup loop. Cancellation produces aborted. The deadline produces timeout.

interface TerminalSession {
  wsUrl: string
  protocols: string[]
  expiresAt: string
}

The SDK normalizes an absent REST protocols field to an empty array. It rejects malformed or expired session responses. Both helpers require wss: URLs. Local development also permits ws: for localhost, 127.0.0.1, and [::1]. The REST operation defines server errors.

Browser entry point

import { createTerminalClient } from '@cybr/labs-sdk/terminal'

This entry point contains no server client and accepts no organization API key. The SDK includes dist/terminal.js as a standalone browser ESM build. The public SDK package is coming soon. Its installation instructions will appear when the package is available.

Configuration and callbacks

Field	Type	Purpose
`connectionTimeoutMs`	`number`	Browser connection deadline, default `60000` milliseconds
`getSession`	`() => Promise<TerminalSession>`	Obtain fresh temporary credentials
`onOutput`	`(data: Uint8Array) => void`	Receive terminal output
`onStateChange`	`(state: TerminalState) => void`	Receive connection state
`onExit`	`(code: number \| undefined) => void`	Receive process exit
`onError`	`(error: Error) => void`	Receive connection or protocol errors

Only getSession is required. States are idle, connecting, ready, closed, and disposed.

Controller methods

Method	Result	Behavior
`connect()`	`Promise<void>`	Request credentials and connect until readiness
`reconnect()`	`Promise<void>`	Replace the connection with fresh credentials
`write(text)`	`void`	Send UTF-8 input after readiness
`resize(cols, rows)`	`void`	Set terminal dimensions
`dispose()`	`void`	Close the connection and release listeners

The helper retains the latest dimensions until readiness. It prevents stale session requests from reopening a disposed terminal. The helper does not automatically reconnect, replay input, or end a deployment. Handle rejections from connect() and reconnect(), even with an onError callback. Replacement and disposal reject a pending connection promise. After readiness, a socket close reports closed through onStateChange. It does not call onError for an ordinary close. A disposed controller cannot reconnect. Create another controller for a new terminal view. write() discards input before readiness or after closure. resize() clamps whole-number dimensions to 1 through 500 and rejects non-finite numbers.

xterm integration

This example assumes screen is an open xterm instance. getSession is your application callback:

import { createTerminalClient } from '@cybr/labs-sdk/terminal'

const terminal = createTerminalClient({
  getSession,
  onOutput: (data) => screen.write(data),
  onError: (error) => showConnectionError(error.message)
})

const input = screen.onData((text) => terminal.write(text))
const resize = screen.onResize(({ cols, rows }) => terminal.resize(cols, rows))
terminal.resize(screen.cols, screen.rows)
try {
  await terminal.connect()
} catch {
  // onError reports connection failures. Disposal can also reject this promise.
}

function closeView() {
  input.dispose()
  resize.dispose()
  terminal.dispose()
  screen.dispose()
}

The UI can use the state callback to disable input before readiness. Reconnect controls call terminal.reconnect(). The terminal guide explains session ownership and expiration.

SDK setup

SDK guides

SDK reference

Server session methods

Browser entry point

Configuration and callbacks

Controller methods

xterm integration

​Server session methods

​Browser entry point

​Configuration and callbacks

​Controller methods

​xterm integration

Server session methods

Browser entry point

Configuration and callbacks

Controller methods

xterm integration