Docker Integration

Overview

psys automatically detects Docker containers and their published ports, providing visual indicators and container name labels in the network visualization.

Container Detection

psys uses the docker ps command to discover running containers:

function getDockerPortToContainer(): Map<number, string> {
  const byPort = new Map<number, string>();
  try {
    const out = execSync("docker ps --format '{{.Ports}}\t{{.Names}}'", {
      encoding: "utf8",
      stdio: ["pipe", "pipe", "ignore"],
    });
    for (const line of out.split("\n").filter(Boolean)) {
      const [ports, names] = line.split("\t");
      if (!ports || !names) continue;
      for (const p of ports.split(", ")) {
        const match = p.match(/(?:[\d.]+:)?(\d+)->\d+/);
        const port = match ? parseInt(match[1], 10) : parseInt(p.split("/")[0], 10);
        if (port && !byPort.has(port)) byPort.set(port, names);
      }
    }
  } catch {
    // ignore - docker not available or not running
  }
  return byPort;
}

If Docker is not installed or not running, psys gracefully continues without Docker integration.

Port Mapping Parsing

The function parses Docker’s port mapping format:

0.0.0.0:6379->6379/tcp, :::6379->6379/tcp

Extracts:

Host port: 6379 (the port exposed on the host machine)
Container port: 6379 (the internal container port)
Protocol: tcp

Regex Pattern

const match = p.match(/(?:[\d.]+:)?(\d+)->\d+/);

This pattern matches:

Optional IP address (e.g., 0.0.0.0: or 127.0.0.1:)
Required host port number
Arrow ->
Container port number

Container Name Labeling

Once a port is identified as Docker-published, psys uses the container name as the service label:

const dockerContainer = dockerPortToContainer.get(port);
const serviceLabel = isOwnApp
  ? "psys"
  : dockerContainer
    ? dockerContainer
    : processName === "?" && knownService
      ? `${port} (typical: ${knownService})`
      : processName === "?" && !dockerContainer
        ? `${port} (unknown)`
        : undefined;

listeners.push({
  pid,
  processName,
  serviceLabel: serviceLabel || undefined,
  containerName: dockerContainer,  // Set to container name if Docker
  processIconType: isOwnApp ? "psys" : getProcessIconType(processName, dockerContainer, port),
  address,
  addressDescription: getAddressDescription(address),
  port,
  cmd: pid ? getProcessCmd(pid) : undefined,
});

Docker Icon Indicators

When a listener is associated with a Docker container, a Docker icon is displayed:

In Listener Nodes

function ListenerNode({ data }: NodeProps<{ 
  label: string; 
  port: number; 
  pid?: number; 
  processIconType?: string; 
  isDocker?: boolean 
}>) {
  return (
    <div className="rounded-lg border-2 border-primary/30 bg-card px-3 py-2 shadow-sm">
      <Handle type="source" position={Position.Right} className="!w-2 !h-2" />
      <div className="font-medium text-sm flex items-center gap-1.5 flex-wrap">
        <ProcessIcon type={data.processIconType} size={14} />
        {data.isDocker && <DockerIcon size={12} className="text-[#2496ed]" />}
        {labelMain}
      </div>
      <div className="text-xs text-muted-foreground">port {data.port}</div>
    </div>
  );
}

In Table View

<TableCell className="text-center">
  {l.containerName ? (
    <DockerIcon size={20} className="text-[#2496ed]" />
  ) : (
    <span className="text-muted-foreground text-sm">No</span>
  )}
</TableCell>

The Docker icon uses the official Docker blue color #2496ed for brand consistency.

Enhanced Icon Detection

Docker container names are used to improve icon detection:

function getProcessIconType(
  processName: string,
  containerName: string | undefined,
  port: number
): string | undefined {
  const name = processName.toLowerCase();
  const container = (containerName ?? "").toLowerCase();
  
  // Process name detection
  if (name.includes("node") || name === "mainthread") return "node";
  if (name.includes("redis")) return "redis";
  // ... more process checks
  
  // Container name detection
  if (container.includes("redis")) return "redis";
  if (container.includes("mongo")) return "mongo";
  if (container.includes("postgres")) return "postgres";
  if (container.includes("mysql")) return "mysql";
  
  // Fall back to port-based detection
  return PORT_ICON_TYPE[port] ?? "generic";
}

Name your Docker containers descriptively (e.g., my-redis, api-postgres) to enable automatic icon detection.

Connection Labeling

Docker container names are also used to label connection targets:

function getDockerPortLabels(): Map<string, string> {
  const labels = new Map<string, string>();
  try {
    const out = execSync("docker ps --format '{{.Ports}}\t{{.Names}}\t{{.Image}}'", {
      encoding: "utf8",
      stdio: ["pipe", "pipe", "ignore"],
    });
    for (const line of out.split("\n").filter(Boolean)) {
      const [ports, names] = line.split("\t");
      if (!ports || !names) continue;
      const portMappings = ports.split(", ");
      for (const p of portMappings) {
        const match = p.match(/(?:[\d.]+:)?(\d+)->\d+/);
        const port = match ? match[1] : p.split("/")[0];
        if (port) labels.set(`127.0.0.1:${port}`, names);
        labels.set(`0.0.0.0:${port}`, names);
      }
    }
  } catch {
    // docker not available or not running
  }
  return labels;
}

This creates a mapping from address:port to container name, which is used when building connection labels:

let toLabel = dockerLabels.get(toKey) || knownPortLabel(toPort);

Example Docker Scenarios

Redis Container

docker run -d --name my-redis -p 6379:6379 redis

psys will display:

Service label: my-redis
Docker icon indicator
Redis process icon
Port: 6379

PostgreSQL Container

docker run -d --name postgres-db -p 5432:5432 postgres

psys will display:

Service label: postgres-db
Docker icon indicator
PostgreSQL process icon
Port: 5432

Custom Port Mapping

docker run -d --name api-server -p 8080:3000 node:alpine

psys will display:

Service label: api-server
Docker icon indicator
Node.js process icon
Port: 8080 (host port)

psys detects the host port (8080), not the container’s internal port (3000).

Requirements

Docker Engine

Docker must be installed and running on the system

Docker Permissions

User must have permissions to run docker ps (typically requires docker group membership)

Graceful Degradation

If Docker is not available:

No errors are thrown
Docker integration is silently disabled
All other psys features continue to work normally
Non-Docker processes are still monitored and displayed

try {
  const out = execSync("docker ps --format '{{.Ports}}\t{{.Names}}'", {
    encoding: "utf8",
    stdio: ["pipe", "pipe", "ignore"],
  });
  // ... parse output
} catch {
  // Docker not available - ignore and continue
}

Get Started

Core Features

Usage

Configuration

Docker Integration

Overview

Container Detection

Port Mapping Parsing

Regex Pattern

Container Name Labeling

Docker Icon Indicators

In Listener Nodes

In Table View

Enhanced Icon Detection

Connection Labeling

Example Docker Scenarios

Redis Container

PostgreSQL Container

Custom Port Mapping

Requirements

Docker Engine

Docker Permissions

Graceful Degradation

​Overview

​Container Detection

​Port Mapping Parsing

​Regex Pattern

​Container Name Labeling

​Docker Icon Indicators

​In Listener Nodes

​In Table View

​Enhanced Icon Detection

​Connection Labeling

​Example Docker Scenarios

​Redis Container

​PostgreSQL Container

​Custom Port Mapping

​Requirements

Docker Engine

Docker Permissions

​Graceful Degradation

Overview

Container Detection

Port Mapping Parsing

Regex Pattern

Container Name Labeling

Docker Icon Indicators

In Listener Nodes

In Table View

Enhanced Icon Detection

Connection Labeling

Example Docker Scenarios

Redis Container

PostgreSQL Container

Custom Port Mapping

Requirements

Graceful Degradation