API: @loopstack/docker-sandbox

Classes

DockerContainerManagerService

Service that manages the lifecycle of Docker sandbox containers — registering configs, ensuring containers run, executing commands, and stopping/removing them; inject it for direct container control beyond what the sandbox tools expose.

import { DockerContainerManagerService } from '@loopstack/docker-sandbox';

Provided by: SandboxToolModule

export class DockerContainerManagerService implements OnModuleDestroy {
  constructor(docker?: Docker);
  registerContainer(containerId: string, config: ContainerConfig): void;
  unregisterContainer(containerId: string): void;
  getRegisteredContainerIds(): string[];
  ensureContainer(containerId: string): Promise<Docker.Container>;
  executeCommand(options: ExecuteCommandOptions): Promise<CommandExecutionResult>;
  getDockerContainerId(containerId: string): string | undefined;
  getContainerStatus(containerId: string): Promise<{
    registered: boolean;
    exists: boolean;
    running: boolean;
    dockerId?: string;
  }>;
  stopContainer(containerId: string): Promise<void>;
  removeContainer(containerId: string): Promise<void>;
  onModuleDestroy(): Promise<void>;
}

SandboxCommand

Tool that executes a command inside a sandbox container and captures its stdout, stderr, and exit code.

import { SandboxCommand } from '@loopstack/docker-sandbox';

Provided by: SandboxToolModule

export class SandboxCommand extends BaseTool<SandboxCommandArgs, object, CommandExecutionResult> {
  protected handle(args: SandboxCommandArgs): Promise<ToolEnvelope<CommandExecutionResult>>;
}

SandboxDestroy

Tool that stops a sandbox container and optionally removes it, then unregisters its config.

import { SandboxDestroy } from '@loopstack/docker-sandbox';

Provided by: SandboxToolModule

export class SandboxDestroy extends BaseTool<SandboxDestroyArgs, object, SandboxDestroyResult> {
  protected handle(args: SandboxDestroyArgs): Promise<ToolEnvelope<SandboxDestroyResult>>;
}

SandboxInit

Tool that initializes a new Docker sandbox container from an image and mounts a host directory into it.

import { SandboxInit } from '@loopstack/docker-sandbox';

Provided by: SandboxToolModule

export class SandboxInit extends BaseTool<SandboxInitArgs, object, SandboxInitResult> {
  protected handle(args: SandboxInitArgs): Promise<ToolEnvelope<SandboxInitResult>>;
}

SandboxToolModule

NestJS module that provides Docker sandbox tools — initialize, run commands in, and destroy isolated containers (SandboxInit, SandboxCommand, SandboxDestroy) — plus the DockerContainerManagerService that manages container lifecycle.

Registration:

• SandboxToolModule — bare import; registers the sandbox tools and the container manager service.

Requires: a running Docker daemon on the host; no other Loopstack modules.

import { SandboxToolModule } from '@loopstack/docker-sandbox';

export class SandboxToolModule {}

Interfaces

CommandExecutionResult

Result of executing a command in a sandbox container: captured stdout/stderr, exit code, and whether the command timed out.

import { CommandExecutionResult } from '@loopstack/docker-sandbox';

export interface CommandExecutionResult {
  stdout: string;
  stderr: string;
  exitCode: number;
  timedOut: boolean;
}

ContainerConfig

Config for a sandbox container — the Docker image, container name, and the host directory mounted into the container at rootPath.

import { ContainerConfig } from '@loopstack/docker-sandbox';

export interface ContainerConfig {
  imageName: string;
  containerName: string;
  projectOutPath: string;
  rootPath: string;
}

SandboxDestroyResult

Result of SandboxDestroy.

Reports the affected container id and whether it was removed.

import { SandboxDestroyResult } from '@loopstack/docker-sandbox';

export interface SandboxDestroyResult {
  containerId: string;
  removed: boolean;
}

SandboxInitResult

Result of SandboxInit.

Reports the registered container id and the underlying Docker container id.

import { SandboxInitResult } from '@loopstack/docker-sandbox';

export interface SandboxInitResult {
  containerId: string;
  dockerId: string;
}

Type Aliases

SandboxCommandArgs

Args for SandboxCommand.

Identifies the target container and the executable to run, with optional args, working directory, environment variables, and timeout.

import { SandboxCommandArgs } from '@loopstack/docker-sandbox';

export type SandboxCommandArgs = z.infer<typeof inputSchema>;

SandboxDestroyArgs

Args for SandboxDestroy.

Identifies the container to destroy and whether to remove it or merely stop it.

import { SandboxDestroyArgs } from '@loopstack/docker-sandbox';

export type SandboxDestroyArgs = z.infer<typeof inputSchema>;

SandboxInitArgs

Args for SandboxInit.

Specifies the container id, Docker image, container name, and the host path to mount.

import { SandboxInitArgs } from '@loopstack/docker-sandbox';

export type SandboxInitArgs = z.infer<typeof inputSchema>;

Variables

CommandExecutionResultSchema

Zod schema for CommandExecutionResult — the resultSchema of sandbox_command.

import { CommandExecutionResultSchema } from '@loopstack/docker-sandbox';

CommandExecutionResultSchema: z.ZodObject<
  {
    stdout: z.ZodString;
    stderr: z.ZodString;
    exitCode: z.ZodNumber;
    timedOut: z.ZodBoolean;
  },
  z.core.$strict
>;

SandboxDestroyResultSchema

Zod schema for SandboxDestroyResult — the resultSchema of sandbox_destroy.

import { SandboxDestroyResultSchema } from '@loopstack/docker-sandbox';

SandboxDestroyResultSchema: z.ZodObject<
  {
    containerId: z.ZodString;
    removed: z.ZodBoolean;
  },
  z.core.$strict
>;

SandboxInitResultSchema

Zod schema for SandboxInitResult — the resultSchema of sandbox_init.

import { SandboxInitResultSchema } from '@loopstack/docker-sandbox';

SandboxInitResultSchema: z.ZodObject<
  {
    containerId: z.ZodString;
    dockerId: z.ZodString;
  },
  z.core.$strict
>;