Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.boxlite.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page covers BoxLite’s error types for structured error handling and the metrics API for monitoring runtime and per-box resource usage.

​
Error Types

import { BoxliteError, ExecError, TimeoutError, ParseError } from '@boxlite-ai/boxlite';

​
Exception Hierarchy

BoxliteError (base)
+-- ExecError       # Command failed
+-- TimeoutError    # Operation timeout
+-- ParseError      # Output parsing failed

​
BoxliteError

Base error class for all BoxLite errors. All specific error types extend this class. 
try {
  await box.exec('invalid-command');
} catch (err) {
  if (err instanceof BoxliteError) {
    console.error('BoxLite error:', err.message);
  }
}
Always catch BoxliteError as a fallback when you want to handle any BoxLite-specific error generically.

​
ExecError

Command execution failed (non-zero exit code).
PropertyTypeDescription
commandstringFailed command
exitCodenumberNon-zero exit code
stderrstringStandard error output
try {
  await box.exec('false');
} catch (err) {
  if (err instanceof ExecError) {
    console.error(`Command: ${err.command}`);
    console.error(`Exit code: ${err.exitCode}`);
    console.error(`Stderr: ${err.stderr}`);
  }
}

​
TimeoutError

Operation exceeded time limit. 
try {
  await desktop.waitUntilReady(5);
} catch (err) {
  if (err instanceof TimeoutError) {
    console.error('Desktop did not become ready');
  }
}

​
ParseError

Failed to parse command output. 
try {
  const pos = await desktop.cursorPosition();
} catch (err) {
  if (err instanceof ParseError) {
    console.error('Failed to parse cursor position');
  }
}

​
Comprehensive Error Handling

Here is a pattern for handling all BoxLite error types: 
import { BoxliteError, ExecError, TimeoutError, ParseError } from '@boxlite-ai/boxlite';

try {
  const result = await box.exec('some-command');
} catch (err) {
  if (err instanceof ExecError) {
    console.error(`Command "${err.command}" failed with exit code ${err.exitCode}`);
    console.error(`Stderr: ${err.stderr}`);
  } else if (err instanceof TimeoutError) {
    console.error('Operation timed out:', err.message);
  } else if (err instanceof ParseError) {
    console.error('Failed to parse output:', err.message);
  } else if (err instanceof BoxliteError) {
    console.error('BoxLite error:', err.message);
  } else {
    throw err;  // Re-throw unknown errors
  }
}

​
Metrics

BoxLite provides two levels of metrics: runtime-wide metrics and per-box metrics.

​
JsRuntimeMetrics

Runtime-wide metrics covering all boxes managed by a runtime instance.
FieldTypeDescription
boxesCreatedTotalnumberTotal boxes created
boxesFailedTotalnumberBoxes that failed during creation
numRunningBoxesnumberCurrently running boxes
totalCommandsExecutednumberTotal commands executed
totalExecErrorsnumberTotal execution errors
const metrics = await runtime.metrics();
console.log(`Boxes created: ${metrics.boxesCreatedTotal}`);
console.log(`Running: ${metrics.numRunningBoxes}`);

​
JsBoxMetrics

Per-box resource metrics for monitoring individual box usage.

​
Counter Fields

FieldTypeDescription
commandsExecutedTotalnumberCommands executed on this box
execErrorsTotalnumberExecution errors on this box
bytesSentTotalnumberBytes sent via stdin
bytesReceivedTotalnumberBytes received via stdout/stderr

​
Resource Fields

FieldTypeDescription
cpuPercentnumber | undefinedCPU usage (0.0-100.0)
memoryBytesnumber | undefinedMemory usage in bytes
networkBytesSentnumber | undefinedNetwork bytes sent
networkBytesReceivednumber | undefinedNetwork bytes received
networkTcpConnectionsnumber | undefinedCurrent TCP connections
networkTcpErrorsnumber | undefinedTotal TCP errors

​
Timing Fields (milliseconds)

FieldTypeDescription
totalCreateDurationMsnumber | undefinedTotal create time
guestBootDurationMsnumber | undefinedGuest agent ready time
stageFilesystemSetupMsnumber | undefinedDirectory setup time
stageImagePrepareMsnumber | undefinedImage pull/prepare time
stageGuestRootfsMsnumber | undefinedRootfs bootstrap time
stageBoxConfigMsnumber | undefinedConfiguration build time
stageBoxSpawnMsnumber | undefinedSubprocess spawn time
stageContainerInitMsnumber | undefinedContainer init time

​
Example

const metrics = await box.metrics();
console.log(`CPU: ${metrics.cpuPercent}%`);
console.log(`Memory: ${(metrics.memoryBytes || 0) / (1024 * 1024)} MB`);
console.log(`Boot time: ${metrics.guestBootDurationMs}ms`);

​
Monitoring Dashboard Example

Here is a more complete example that polls both runtime and box metrics: 
import { JsBoxlite, SimpleBox } from '@boxlite-ai/boxlite';

const runtime = JsBoxlite.withDefaultConfig();

// Create a box
await using box = new SimpleBox({
  image: 'alpine:latest',
  runtime
});

// Run some commands
await box.exec('echo', 'hello');
await box.exec('sleep', '1');

// Check runtime metrics
const runtimeMetrics = await runtime.metrics();
console.log('--- Runtime Metrics ---');
console.log(`Total boxes created: ${runtimeMetrics.boxesCreatedTotal}`);
console.log(`Running boxes: ${runtimeMetrics.numRunningBoxes}`);
console.log(`Commands executed: ${runtimeMetrics.totalCommandsExecuted}`);
console.log(`Exec errors: ${runtimeMetrics.totalExecErrors}`);