nixpkgs/docs/guides/getting-started.md

Getting Started Guide

Initial setup and basic usage of m3ta-nixpkgs.

Installation

Prerequisites

Make sure you have Nix installed with flakes enabled:

# Check Nix version (need 2.4+)
nix --version

# Enable flakes (in /etc/nixos/configuration.nix)
nix.settings.experimental-features = ["nix-command" "flakes"]

# Rebuild NixOS
sudo nixos-rebuild switch

Adding to Your Flake

Option 1: NixOS Configuration

Add to your flake.nix:

{
  description = "My NixOS configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";

    m3ta-nixpkgs = {
      url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    home-manager,
    m3ta-nixpkgs,
    ...
  }: {
    nixosConfigurations = {
      myhost = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./hardware-configuration.nix

          # Import m3ta-nixpkgs modules
          m3ta-nixpkgs.nixosModules.default

          # Apply overlay
          ({pkgs, ...}: {
            nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];

            # Packages from m3ta-nixpkgs are now available
            environment.systemPackages = with pkgs; [
              code2prompt
              zellij-ps
            ];
          })

          # Home Manager integration
          home-manager.nixosModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.myusername = {
              imports = [m3ta-nixpkgs.homeManagerModules.default];
              home.packages = with pkgs; [
                launch-webapp
              ];
            };
          }
        ];
      };
    };
  };
}

Option 2: Standalone Home Manager

{
  description = "My Home Manager configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";

    m3ta-nixpkgs = {
      url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    home-manager,
    m3ta-nixpkgs,
  }: let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      inherit system;
      overlays = [m3ta-nixpkgs.overlays.default];
    };
  in {
    homeConfigurations.myusername = home-manager.lib.homeManagerConfiguration {
      inherit pkgs;
      modules = [
        m3ta-nixpkgs.homeManagerModules.default
        {
          home.username = "myusername";
          home.homeDirectory = "/home/myusername";
          home.packages = with pkgs; [
            code2prompt
            zellij-ps
          ];
          programs.home-manager.enable = true;
        }
      ];
    };
  };
}

Quick Usage

Using Packages Directly

Without adding to your configuration:

# Build a package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Run a package
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps

# List all available packages
nix flake show git+https://code.m3ta.dev/m3tam3re/nixpkgs

Using Packages in Configuration

After applying overlay:

# System-wide (NixOS)
environment.systemPackages = with pkgs; [
  code2prompt
  zellij-ps
];

# User-only (Home Manager)
home.packages = with pkgs; [
  launch-webapp
];

Using Modules

# Import all modules
imports = [
  m3ta-nixpkgs.nixosModules.default
];

# Or import specific module
imports = [
  m3ta-nixpkgs.nixosModules.mem0
];

# Configure module
m3ta.mem0 = {
  enable = true;
  port = 8000;
};

Common Tasks

Install a Package System-Wide

# /etc/nixos/configuration.nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    code2prompt
    hyprpaper-random
  ];
}

# Apply
sudo nixos-rebuild switch

Install a Package for Your User

# home.nix
{pkgs, ...}: {
  home.packages = with pkgs; [
    launch-webapp
    zellij-ps
  ];
}

# Apply
home-manager switch

Enable a NixOS Module

# /etc/nixos/configuration.nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  m3ta.mem0 = {
    enable = true;
    port = 8000;
  };

  # Apply
  # sudo nixos-rebuild switch
}

Enable a Home Manager Module

# home.nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];

  cli.zellij-ps = {
    enable = true;
  };

  # Apply
  # home-manager switch
}

Use Port Management

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
    };
    hostOverrides.laptop = {
      nginx = 8080;
    };
    currentHost = config.networking.hostName;
  };

  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen ${toString (config.m3ta.ports.get "nginx")};
        root /var/www;
      }
    '';
  };
}

Available Packages

Package	Description
code2prompt	Convert code to prompts
hyprpaper-random	Random wallpaper setter for Hyprpaper
launch-webapp	Launch web applications
mem0	AI memory assistant with vector storage
msty-studio	Msty Studio application
pomodoro-timer	Pomodoro timer utility
tuxedo-backlight	Backlight control for Tuxedo laptops
zellij-ps	Project switcher for Zellij

Available Modules

NixOS Modules

• ports - Port management across hosts
• mem0 - Mem0 REST API server

Home Manager Modules

• ports - Port management (with generateEnvVars)
• cli.zellij-ps - Zellij project switcher
• coding.editors - Editor configurations

Development

Development Shells

# Default dev shell
nix develop

# Python dev shell
nix develop .#python

# DevOps dev shell
nix develop .#devops

Building and Testing

# Build package
nix build .#code2prompt

# Validate flake
nix flake check

# List outputs
nix flake show

# Format code
nix fmt

Linting (in dev shell)

nix develop

# Run linter
statix check .

# Find dead code
deadnix .

Troubleshooting

Package Not Found

Error: error: undefined variable 'code2prompt'

Solution: Make sure you applied the overlay:

nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];

Module Not Found

Error: error: The option 'm3ta.mem0' does not exist

Solution: Make sure you imported the module:

imports = [
  m3ta-nixpkgs.nixosModules.default
  # or
  m3ta-nixpkgs.nixosModules.mem0
];

Hash Mismatch

Error: got: sha256-AAAAAAAA... expected: sha256-BBBBBB...

Solution: Copy the got hash from the error and update the package definition.

Building for Different System

# Build for aarch64-linux
nix build .#code2prompt --system aarch64-linux

# Build for macOS
nix build .#code2prompt --system x86_64-darwin

Next Steps

• Adding Packages - How to add new packages
• Using Modules - Deep dive into modules
• Port Management - Managing service ports
• Architecture - Understanding the repository structure