or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

container.md docker-client.md image.md index.md plugin.md swarm.md volume-network.md

tile.json

Container Operations

Complete container lifecycle management including creation, execution, monitoring, file operations, and resource management. Container instances are obtained through the Docker client factory methods.

Capabilities

Container Instance

Container objects are created through Docker client factory methods and represent individual containers.

/**
 * Container instance representing a Docker container
 */
class Container {
  /** Container ID */
  id: string;
  /** Docker modem instance for API communication */
  modem: any;
  
  constructor(modem: any, id: string);
}

Usage Examples:

const Docker = require('dockerode');
const docker = new Docker();

// Get container instance by ID or name
const container = docker.getContainer('my-container');
const containerById = docker.getContainer('3c7b2c5e8f9a');

Inspection and Information

Get detailed container information and monitoring data.

/**
 * Get detailed container information
 * @param opts - Inspection options
 * @param callback - Optional callback
 * @returns Promise resolving to container details
 */
inspect(opts?: InspectOptions, callback?: Function): Promise<ContainerInspectInfo>;

/**
 * List running processes in container
 * @param opts - Process listing options
 * @param callback - Optional callback
 * @returns Promise resolving to process list
 */
top(opts?: TopOptions, callback?: Function): Promise<ContainerTopInfo>;

/**
 * Get filesystem changes since container creation
 * @param opts - Changes options
 * @param callback - Optional callback
 * @returns Promise resolving to filesystem changes
 */
changes(opts?: object, callback?: Function): Promise<ContainerChange[]>;

/**
 * Get container logs with streaming support
 * @param opts - Log options
 * @param callback - Optional callback
 * @returns Promise resolving to log stream
 */
logs(opts?: LogsOptions, callback?: Function): Promise<Stream>;

/**
 * Get real-time container statistics
 * @param opts - Stats options
 * @param callback - Optional callback
 * @returns Promise resolving to stats stream
 */
stats(opts?: StatsOptions, callback?: Function): Promise<Stream>;

interface InspectOptions {
  /** Return container size information */
  size?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ContainerInspectInfo {
  Id: string;
  Created: string;
  Path: string;
  Args: string[];
  State: {
    Status: string;
    Running: boolean;
    Paused: boolean;
    Restarting: boolean;
    OOMKilled: boolean;
    Dead: boolean;
    Pid: number;
    ExitCode: number;
    Error: string;
    StartedAt: string;
    FinishedAt: string;
  };
  Image: string;
  ResolvConfPath: string;
  HostnamePath: string;
  HostsPath: string;
  LogPath: string;
  Name: string;
  RestartCount: number;
  Driver: string;
  Platform: string;
  MountLabel: string;
  ProcessLabel: string;
  AppArmorProfile: string;
  ExecIDs: string[];
  HostConfig: object;
  GraphDriver: object;
  SizeRw?: number;
  SizeRootFs?: number;
  Mounts: MountPoint[];
  Config: ContainerConfig;
  NetworkSettings: NetworkSettings;
}

interface LogsOptions {
  /** Return stdout logs */
  stdout?: boolean;
  /** Return stderr logs */
  stderr?: boolean;
  /** Return timestamps */
  timestamps?: boolean;
  /** Follow log output (stream) */
  follow?: boolean;
  /** Show logs since timestamp */
  since?: string | number;
  /** Show logs until timestamp */
  until?: string | number;
  /** Number of lines from end of logs */
  tail?: number | string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface StatsOptions {
  /** Stream stats continuously */
  stream?: boolean;
  /** Do not block if no stats available */
  'one-shot'?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

Usage Examples:

// Get container details
const info = await container.inspect();
console.log(`Status: ${info.State.Status}`);
console.log(`Image: ${info.Config.Image}`);

// List processes
const processes = await container.top();
console.log(processes.Processes);

// Get logs
const logStream = await container.logs({
  stdout: true,
  stderr: true,
  follow: true,
  tail: 100
});

logStream.on('data', chunk => {
  console.log(chunk.toString());
});

// Get real-time stats
const statsStream = await container.stats({ stream: true });
statsStream.on('data', chunk => {
  const stats = JSON.parse(chunk.toString());
  console.log(`CPU Usage: ${stats.cpu_stats.cpu_usage.total_usage}`);
  console.log(`Memory Usage: ${stats.memory_stats.usage}`);
});

Lifecycle Management

Control container execution state and lifecycle.

/**
 * Start stopped container
 * @param opts - Start options
 * @param callback - Optional callback
 * @returns Promise resolving to start result
 */
start(opts?: StartOptions, callback?: Function): Promise<object>;

/**
 * Stop running container
 * @param opts - Stop options
 * @param callback - Optional callback
 * @returns Promise resolving to stop result
 */
stop(opts?: StopOptions, callback?: Function): Promise<object>;

/**
 * Restart container
 * @param opts - Restart options
 * @param callback - Optional callback
 * @returns Promise resolving to restart result
 */
restart(opts?: RestartOptions, callback?: Function): Promise<object>;

/**
 * Pause container processes
 * @param opts - Pause options
 * @param callback - Optional callback
 * @returns Promise resolving to pause result
 */
pause(opts?: object, callback?: Function): Promise<object>;

/**
 * Unpause container processes
 * @param opts - Unpause options
 * @param callback - Optional callback
 * @returns Promise resolving to unpause result
 */
unpause(opts?: object, callback?: Function): Promise<object>;

/**
 * Kill container with signal
 * @param opts - Kill options
 * @param callback - Optional callback
 * @returns Promise resolving to kill result
 */
kill(opts?: KillOptions, callback?: Function): Promise<object>;

/**
 * Remove container
 * @param opts - Remove options
 * @param callback - Optional callback
 * @returns Promise resolving to remove result
 */
remove(opts?: RemoveOptions, callback?: Function): Promise<object>;

/**
 * Wait for container to stop
 * @param opts - Wait options
 * @param callback - Optional callback
 * @returns Promise resolving to wait result
 */
wait(opts?: WaitOptions, callback?: Function): Promise<WaitResult>;

interface StartOptions {
  /** Detach keys sequence */
  detachKeys?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface StopOptions {
  /** Seconds to wait before killing container */
  t?: number;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface KillOptions {
  /** Signal to send (default: SIGKILL) */
  signal?: string | number;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface RemoveOptions {
  /** Remove volumes associated with container */
  v?: boolean;
  /** Force removal of running container */
  force?: boolean;
  /** Remove specified link */
  link?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface WaitOptions {
  /** Condition to wait for */
  condition?: 'not-running' | 'next-exit' | 'removed';
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface WaitResult {
  /** Container exit status code */
  StatusCode: number;
  /** Error information if any */
  Error?: {
    Message: string;
  };
}

Usage Examples:

// Start container
await container.start();

// Stop container with timeout
await container.stop({ t: 10 });

// Kill container with specific signal
await container.kill({ signal: 'SIGTERM' });

// Remove container and its volumes
await container.remove({ v: true, force: true });

// Wait for container to exit
const result = await container.wait();
console.log(`Container exited with code: ${result.StatusCode}`);

File Operations

Transfer files and directories to/from containers.

/**
 * Get files/folders as tar stream
 * @param opts - Archive options
 * @param callback - Optional callback
 * @returns Promise resolving to tar stream
 */
getArchive(opts: GetArchiveOptions, callback?: Function): Promise<Stream>;

/**
 * Put files/folders from tar stream
 * @param file - Tar archive stream
 * @param opts - Put archive options
 * @param callback - Optional callback
 * @returns Promise resolving to put result
 */
putArchive(file: Stream, opts: PutArchiveOptions, callback?: Function): Promise<Stream>;

/**
 * Get information about files/folders in container
 * @param opts - Info archive options
 * @param callback - Optional callback
 * @returns Promise resolving to file information
 */
infoArchive(opts: InfoArchiveOptions, callback?: Function): Promise<ArchiveInfo>;

/**
 * DEPRECATED: Copy files from container
 * @param opts - Copy options
 * @param callback - Optional callback
 * @returns Promise resolving to copy stream
 */
copy(opts: CopyOptions, callback?: Function): Promise<Stream>;

interface GetArchiveOptions {
  /** Resource path in container */
  path: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PutArchiveOptions {
  /** Path to directory in container */
  path: string;
  /** Do not overwrite existing directories */
  noOverwriteDirNonDir?: boolean;
  /** Copy UID/GID maps */
  copyUIDGID?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface InfoArchiveOptions {
  /** Resource path in container */
  path: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ArchiveInfo {
  name: string;
  size: number;
  mode: number;
  mtime: string;
  linkTarget: string;
}

Usage Examples:

const tar = require('tar-fs');
const fs = require('fs');

// Extract files from container
const archiveStream = await container.getArchive({
  path: '/app/data'
});
archiveStream.pipe(tar.extract('./extracted'));

// Copy files to container
const tarStream = tar.pack('./local-directory');
await container.putArchive(tarStream, {
  path: '/app/'
});

// Get file information
const fileInfo = await container.infoArchive({
  path: '/app/config.json'
});
console.log(`File size: ${fileInfo.size} bytes`);

Execution and Interaction

Execute commands and interact with containers.

/**
 * Create exec instance for running commands
 * @param opts - Exec creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Exec instance
 */
exec(opts: ExecCreateOptions, callback?: Function): Promise<Exec>;

/**
 * Attach to container's STDIN/STDOUT/STDERR
 * @param opts - Attach options
 * @param callback - Optional callback
 * @returns Promise resolving to attach stream
 */
attach(opts: AttachOptions, callback?: Function): Promise<Stream>;

/**
 * Resize container's TTY
 * @param opts - Resize options
 * @param callback - Optional callback
 * @returns Promise resolving to resize result
 */
resize(opts: ResizeOptions, callback?: Function): Promise<object>;

interface ExecCreateOptions {
  /** Attach to stdout */
  AttachStdout?: boolean;
  /** Attach to stderr */
  AttachStderr?: boolean;
  /** Attach to stdin */
  AttachStdin?: boolean;
  /** Detach keys sequence */
  DetachKeys?: string;
  /** Allocate TTY */
  Tty?: boolean;
  /** Command to execute */
  Cmd: string[];
  /** Environment variables */
  Env?: string[];
  /** Run with extended privileges */
  Privileged?: boolean;
  /** User to run command as */
  User?: string;
  /** Working directory */
  WorkingDir?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface AttachOptions {
  /** Attach to stdout */
  stdout?: boolean;
  /** Attach to stderr */
  stderr?: boolean;
  /** Attach to stdin */
  stdin?: boolean;
  /** Stream attach data */
  stream?: boolean;
  /** Get logs before attaching */
  logs?: boolean;
  /** Detach keys sequence */
  detachKeys?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ResizeOptions {
  /** TTY height */
  h: number;
  /** TTY width */
  w: number;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

Usage Examples:

// Execute command in container
const exec = await container.exec({
  Cmd: ['ls', '-la', '/app'],
  AttachStdout: true,
  AttachStderr: true
});

const stream = await exec.start();
stream.on('data', chunk => {
  console.log(chunk.toString());
});

// Attach to running container
const attachStream = await container.attach({
  stream: true,
  stdout: true,
  stderr: true,
  stdin: true
});

process.stdin.pipe(attachStream);
attachStream.pipe(process.stdout);

// Resize TTY
await container.resize({ h: 40, w: 120 });

Container Management

Advanced container management operations.

/**
 * Rename container
 * @param opts - Rename options
 * @param callback - Optional callback
 * @returns Promise resolving to rename result
 */
rename(opts: RenameOptions, callback?: Function): Promise<object>;

/**
 * Update container resource constraints
 * @param opts - Update options
 * @param callback - Optional callback
 * @returns Promise resolving to update result
 */
update(opts: UpdateOptions, callback?: Function): Promise<UpdateResult>;

/**
 * Create image from container
 * @param opts - Commit options
 * @param callback - Optional callback
 * @returns Promise resolving to Image instance
 */
commit(opts?: CommitOptions, callback?: Function): Promise<Image>;

/**
 * Export container filesystem as tar
 * @param opts - Export options
 * @param callback - Optional callback
 * @returns Promise resolving to export stream
 */
export(opts?: object, callback?: Function): Promise<Stream>;

interface RenameOptions {
  /** New container name */
  name: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface UpdateOptions {
  /** CPU shares */
  CpuShares?: number;
  /** Memory limit in bytes */
  Memory?: number;
  /** Memory + swap limit */
  MemorySwap?: number;
  /** Memory reservation */
  MemoryReservation?: number;
  /** Kernel memory limit */
  KernelMemory?: number;
  /** CPU quota */
  CpuQuota?: number;
  /** CPU period */
  CpuPeriod?: number;
  /** Restart policy */
  RestartPolicy?: RestartPolicy;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface CommitOptions {
  /** Repository name */
  repo?: string;
  /** Tag name */
  tag?: string;
  /** Commit message */
  comment?: string;
  /** Author information */
  author?: string;
  /** Apply Dockerfile instruction */
  changes?: string[];
  /** Pause container during commit */
  pause?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface UpdateResult {
  Warnings: string[];
}

interface RestartPolicy {
  Name: 'no' | 'always' | 'unless-stopped' | 'on-failure';
  MaximumRetryCount?: number;
}

Usage Examples:

// Rename container
await container.rename({ name: 'new-container-name' });

// Update resource limits
await container.update({
  Memory: 512 * 1024 * 1024, // 512MB
  CpuShares: 512
});

// Create image from container
const image = await container.commit({
  repo: 'my-repo',
  tag: 'latest',
  comment: 'Created from running container'
});

// Export container filesystem
const exportStream = await container.export();
exportStream.pipe(fs.createWriteStream('container-export.tar'));

Checkpoint Operations (Experimental)

Container checkpoint and restore operations (experimental feature).

/**
 * List container checkpoints
 * @param opts - List options
 * @param callback - Optional callback
 * @returns Promise resolving to checkpoint list
 */
listCheckpoint(opts?: object, callback?: Function): Promise<CheckpointInfo[]>;

/**
 * Create container checkpoint
 * @param opts - Checkpoint creation options
 * @param callback - Optional callback
 * @returns Promise resolving to checkpoint result
 */
createCheckpoint(opts: CreateCheckpointOptions, callback?: Function): Promise<object>;

/**
 * Delete container checkpoint
 * @param checkpoint - Checkpoint name
 * @param opts - Delete options
 * @param callback - Optional callback
 * @returns Promise resolving to delete result
 */
deleteCheckpoint(checkpoint: string, opts?: object, callback?: Function): Promise<object>;

interface CreateCheckpointOptions {
  /** Checkpoint name */
  CheckpointID: string;
  /** Checkpoint directory */
  CheckpointDir?: string;
  /** Exit container after checkpoint */
  Exit?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface CheckpointInfo {
  Name: string;
}

Usage Examples:

// Create checkpoint
await container.createCheckpoint({
  CheckpointID: 'checkpoint-1',
  Exit: false
});

// List checkpoints
const checkpoints = await container.listCheckpoint();
console.log(checkpoints);

// Delete checkpoint
await container.deleteCheckpoint('checkpoint-1');

Version

Tile

Files

container.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Container Operations

Capabilities

Container Instance

Inspection and Information

Lifecycle Management

File Operations

Execution and Interaction

Container Management

Checkpoint Operations (Experimental)

container.mddocs/