Skip to main content

​
What is psys?

psys (Process System) is a web app that visualizes which processes expose ports (LISTEN) and how they connect to other services (ESTABLISHED). It provides:
  • A diagram view showing the flow of connections between processes
  • A table view listing all listeners with process details and their outgoing connections
  • Real-time updates every 5 seconds
  • Docker container detection for published ports
  • Process identification with icons for common services (Node.js, Redis, PostgreSQL, etc.)
psys uses ss -tlnp and ss -tnp to gather connection data, and reads from /proc for process information.

​
Quick Installation

1

Install dependencies

npm install
2

Start the development server

npm run dev
This starts Next.js with Turbopack on http://localhost:3000.
3

Open the app

Navigate to http://localhost:3000 in your browser.
That’s it! You should now see your system’s network connections.

​
Development Mode

For development with hot-reload: 
npm run dev
This command runs next dev --turbopack, which:
  • Starts the Next.js development server with Turbopack for faster builds
  • Enables hot module replacement (HMR)
  • Listens on port 3000 by default
  • Shows detailed error messages
Development mode is great for testing, but use production mode for regular use to get better performance.

​
Production Mode

For better performance and a cleaner experience:
1

Build the production bundle

npm run build
This runs next build to create an optimized production build.
2

Start the production server

npm run start
The app will run on http://localhost:3000.
To run psys in the background without terminal output: 
npm run build && npm run start:bg
This command:
  • Builds the production version
  • Starts the server on port 30999 in the background
  • Redirects all output to /dev/null
  • Returns control to your terminal immediately
Access the app at http://localhost:30999.
You must run npm run build at least once before using npm run start:bg.

​
First Look at the UI

psys provides two views of your system’s network connections:

​
Diagram View

The Diagram tab shows a visual flow chart:
  • Left side: Listener nodes (processes exposing ports)
    • Shows process name or service label
    • Displays Docker icon for containerized services
    • Shows port number
    • Icons indicate service type (Node.js, Redis, MongoDB, etc.)
  • Right side: Target nodes (services being connected to)
    • Shows destination address and port
    • Labels known services automatically
  • Edges: Lines connecting listeners to their outgoing connections
  • Controls:
    • Pan: Click and drag
    • Zoom: Mouse wheel or pinch
    • Fit view: Use the controls in the bottom-left corner
    • Mini-map: Bottom-right corner for navigation

​
Table View

The Table tab provides detailed information:
ColumnDescription
ProcessProcess name or service label (e.g., “node”, “Redis”, “PostgreSQL”)
Is Docker ContainerShows Docker icon if the port is published by a container
PortThe listening port number
AddressThe bind address (e.g., 0.0.0.0, 127.0.0.1)
Address descriptionHuman-readable explanation (e.g., “Listening on all IPv4 interfaces”)
Connect toBadges showing outgoing connections to other services
PIDProcess ID
ActionsKill button to terminate the process (SIGTERM)
The table is sorted to show recognizable services (those with specific icons) at the top.

​
Understanding the Data

​
Listener Addresses

  • 0.0.0.0 - Listening on all IPv4 interfaces (accessible from network)
  • 127.0.0.1 - Localhost only (local connections only)
  • :: or ::1 - IPv6 localhost or all interfaces
  • 127.0.0.53 - systemd-resolved (local DNS)

​
Service Detection

psys automatically detects common services:
  • By process name: node, redis-server, mongod, postgres, etc.
  • By port number: 6379 (Redis), 27017 (MongoDB), 5432 (PostgreSQL), 3306 (MySQL)
  • By Docker container: Reads container names from docker ps

​
Auto-refresh

The page polls /api/connections every 5 seconds to show live updates of your system’s network state.

​
Next Steps

Set up an alias

Create a shell alias to start psys with a single command

Production Setup

Learn about background mode and production deployment

Docker Support

Learn how psys detects and displays Docker containers

API Reference

Explore the REST API endpoints

​
Common Commands

Here are the available npm scripts: 
# Development server with Turbopack (hot-reload)
npm run dev

# Build for production
npm run build

# Start production server (foreground)
npm run start

# Start production server (background, port 30999)
npm run start:bg

# Run ESLint
npm run lint
All scripts are defined in package.json and use the Next.js CLI.