> ## Documentation Index
> Fetch the complete documentation index at: https://psys.alexcgomez.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get psys up and running in minutes

## 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.)

<Note>
  psys uses `ss -tlnp` and `ss -tnp` to gather connection data, and reads from `/proc` for process information.
</Note>

## Quick Installation

<Steps>
  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    npm run dev
    ```

    This starts Next.js with Turbopack on [http://localhost:3000](http://localhost:3000).
  </Step>

  <Step title="Open the app">
    Navigate to [http://localhost:3000](http://localhost:3000) in your browser.
  </Step>
</Steps>

That's it! You should now see your system's network connections.

## Development Mode

For development with hot-reload:

```bash theme={null}
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

<Note>
  Development mode is great for testing, but use production mode for regular use to get better performance.
</Note>

## Production Mode

For better performance and a cleaner experience:

<Steps>
  <Step title="Build the production bundle">
    ```bash theme={null}
    npm run build
    ```

    This runs `next build` to create an optimized production build.
  </Step>

  <Step title="Start the production server">
    ```bash theme={null}
    npm run start
    ```

    The app will run on [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

### Background Mode (Recommended)

To run psys in the background without terminal output:

```bash theme={null}
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](http://localhost:30999).

<Warning>
  You must run `npm run build` at least once before using `npm run start:bg`.
</Warning>

## 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:

| Column                  | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| **Process**             | Process name or service label (e.g., "node", "Redis", "PostgreSQL")   |
| **Is Docker Container** | Shows Docker icon if the port is published by a container             |
| **Port**                | The listening port number                                             |
| **Address**             | The bind address (e.g., `0.0.0.0`, `127.0.0.1`)                       |
| **Address description** | Human-readable explanation (e.g., "Listening on all IPv4 interfaces") |
| **Connect to**          | Badges showing outgoing connections to other services                 |
| **PID**                 | Process ID                                                            |
| **Actions**             | Kill button to terminate the process (SIGTERM)                        |

<Note>
  The table is sorted to show recognizable services (those with specific icons) at the top.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Set up an alias" icon="terminal" href="/config/shell-aliases">
    Create a shell alias to start psys with a single command
  </Card>

  <Card title="Production Setup" icon="gear" href="/config/production-setup">
    Learn about background mode and production deployment
  </Card>

  <Card title="Docker Support" icon="docker" href="/features/docker-integration">
    Learn how psys detects and displays Docker containers
  </Card>

  <Card title="API Reference" icon="code" href="/api/connections">
    Explore the REST API endpoints
  </Card>
</CardGroup>

## Common Commands

Here are the available npm scripts:

```bash theme={null}
# 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
```

<Note>
  All scripts are defined in `package.json` and use the Next.js CLI.
</Note>