nixpkgs/docs/modules/home-manager/ports.md

ports Home Manager Module

Port management module for Home Manager.

Overview

This module provides centralized port management for user-level services, similar to the NixOS version but with additional support for generating environment variables.

See Port Management Guide for detailed usage.

Quick Start

{config, ...}: {
  m3ta.ports = {
    enable = true;

    # Define default ports
    definitions = {
      dev-server = 3000;
      nextjs = 3001;
      vite = 5173;
    };

    # Host-specific overrides
    hostOverrides = {
      laptop = {
        vite = 5174;
      };
    };

    # Current host
    currentHost = "desktop";

    # Generate environment variables (Home Manager only)
    generateEnvVars = true;
  };
}

Module Options

m3ta.ports.enable

Enable port management.

• Type: boolean
• Default: false

m3ta.ports.definitions

Default port definitions.

• Type: attrsOf int
• Default: {}

Example:

definitions = {
  dev-server = 3000;
  nextjs = 3001;
  vite = 5173;
};

m3ta.ports.hostOverrides

Host-specific port overrides.

• Type: attrsOf (attrsOf int)
• Default: {}

Example:

hostOverrides = {
  laptop = {
    vite = 5174;
  };
  desktop = {
    vite = 5173;
  };
};

m3ta.ports.currentHost

Current hostname.

• Type: string
• Example: "desktop"

m3ta.ports.generateEnvVars

Generate environment variables from ports.

• Type: boolean
• Default: false
• Home Manager only

When enabled, generates environment variables like:

PORT_DEV_SERVER=3000
PORT_NEXTJS=3001
PORT_VITE=5173

Functions

config.m3ta.ports.get "service"

Get port for a service with host-specific override.

home.sessionVariables = {
  DEV_PORT = toString (config.m3ta.ports.get "dev-server");
};

config.m3ta.ports.getHostPorts "hostname"

Get all ports for a specific host.

laptopPorts = config.m3ta.ports.getHostPorts "laptop";
# Returns: { dev-server = 3000; vite = 5174; ... }

config.m3ta.ports.listServices

List all defined service names.

allServices = config.m3ta.ports.listServices;
# Returns: ["dev-server" "nextjs" "vite"]

Environment Variables

When generateEnvVars = true, the following environment variables are generated:

PORT_<SERVICE_UPPERCASE>=<port_number>

Example:

m3ta.ports = {
  enable = true;
  definitions = {
    dev-server = 3000;
    nextjs = 3001;
  };
  generateEnvVars = true;
};

Generates:

PORT_DEV_SERVER=3000
PORT_NEXTJS=3001

You can then use these in scripts:

#!/usr/bin/env bash
# Use environment variable directly
npm start --port=$PORT_DEV_SERVER

Usage Examples

Basic Usage

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
    };
    currentHost = "desktop";
  };

  home.sessionVariables = {
    DEV_PORT = toString (config.m3ta.ports.get "dev-server");
  };
}

With Environment Variables

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
      nextjs = 3001;
      vite = 5173;
    };
    currentHost = "desktop";
    generateEnvVars = true;
  };

  # Now available as environment variables
  # PORT_DEV_SERVER=3000
  # PORT_NEXTJS=3001
  # PORT_VITE=5173
}

With Multi-Host Setup

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
      vite = 5173;
    };
    hostOverrides = {
      laptop = {
        vite = 5174;
      };
      desktop = {
        vite = 5173;
      };
    };
    currentHost = config.networking.hostName;
    generateEnvVars = true;
  };
}

With Shell Scripts

Create ~/.config/zellij/scripts/dev.ksh:

#!/usr/bin/env ksh
# Start dev server using environment variable
cd ~/projects/my-app
npm start --port=$PORT_DEV_SERVER

Difference from NixOS Module

The Home Manager version has one additional feature:

generateEnvVars

Not available in NixOS module. Generates environment variables for all defined ports:

# Home Manager
m3ta.ports.generateEnvVars = true;  # Available

# NixOS
# Not available

Related

• Port Management Guide - Detailed guide
• NixOS Ports Module - System-level port management