nixpkgs/docs/guides/using-modules.md

# Using Modules Guide

How to use NixOS and Home Manager modules from m3ta-nixpkgs.

## Overview

Modules in m3ta-nixpkgs provide reusable configuration for NixOS (system-level) and Home Manager (user-level) settings. All modules use the `m3ta.*` namespace.

## Module Organization

### NixOS Modules

Located in `modules/nixos/`:

```
modules/nixos/
├── default.nix    # Aggregates all NixOS modules
├── ports.nix      # Port management
└── mem0.nix      # Mem0 REST API server
```

### Home Manager Modules

Located in `modules/home-manager/` with categories:

```
modules/home-manager/
├── default.nix      # Aggregates all HM modules
├── ports.nix       # Port management
├── cli/            # CLI tools
│   ├── default.nix # Aggregates CLI modules
│   └── zellij-ps.nix
└── coding/         # Development tools
    ├── default.nix # Aggregates coding modules
    ├── editors.nix
    ├── opencode.nix # OpenCode non-agent config
    └── agents/     # Per-tool agent deployment
        ├── default.nix
        ├── opencode.nix
        ├── claude-code.nix
        └── pi.nix
```

## Importing Modules

### NixOS Modules

#### Import All Modules

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];
}
```

#### Import Specific Module

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.mem0
  ];
}
```

#### Import from Local Path

```nix
{config, ...}: {
  imports = [
    ./modules/nixos/mem0.nix
  ];
}
```

### Home Manager Modules

#### Import All Modules

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

#### Import Specific Module

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.ports
  ];
}
```

#### Import Category

```nix
{config, ...}: {
  imports = [
    # Import all CLI modules
    m3ta-nixpkgs.homeManagerModules.cli.zellij-ps
  ];
}
```

## Available Modules

### NixOS Modules

#### `m3ta.ports`

Port management across hosts.

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

**Documentation**: [Port Management Guide](./port-management.md)

#### `m3ta.mem0`

Mem0 REST API server for AI memory.

```nix
m3ta.mem0 = {
  enable = true;
  port = 8000;
  llm = {
    provider = "openai";
    apiKeyFile = "/run/secrets/openai-api-key";
    model = "gpt-4o-mini";
  };
  vectorStore = {
    provider = "qdrant";
    config = {
      host = "localhost";
      port = 6333;
    };
  };
};
```

**Documentation**: [mem0 Module](../modules/nixos/mem0.md)

### Home Manager Modules

#### `m3ta.ports`

Port management (similar to NixOS, with `generateEnvVars`).

```nix
m3ta.ports = {
  enable = true;
  definitions = {
    dev-server = 3000;
  };
  generateEnvVars = true;
  currentHost = config.networking.hostName;
};
```

**Documentation**: [Port Management Guide](./port-management.md)

#### `cli.zellij-ps`

Zellij project switcher for quickly navigating between project folders.

```nix
cli.zellij-ps = {
  enable = true;
  package = pkgs.zellij-ps;
};
```

**Documentation**: [zellij-ps Module](../modules/home-manager/cli/zellij-ps.md)

#### `coding.editors`

Editor configurations.

```nix
m3ta.coding.editors = {
  enable = true;
  neovim.enable = true;
  zed.enable = true;
};
```

**Documentation**: [Editors Module](../modules/home-manager/coding/editors.md)

### `coding.opencode`

OpenCode AI coding assistant (non-agent config: theme, formatter, plugins).

```nix
coding.opencode = {
  enable = true;
  ohMyOpencodeSettings = {
    agents.sisyphus.model = "anthropic/claude-opus-4-5";
  };
  extraSettings = {
    provider.anthropic.name = "Anthropic";
  };
};
```

### `coding.agents.opencode`

OpenCode agent deployment from canonical TOML definitions.

```nix
coding.agents.opencode = {
  enable = true;
  agentsInput = inputs.agents;
  modelOverrides = {
    chiron = "anthropic/claude-sonnet-4";
  };
  externalSkills = [
    { src = inputs.skills-anthropic; }
  ];
};
```

### `coding.agents.claude-code`

Claude Code agent deployment from canonical TOML definitions.

```nix
coding.agents.claude-code = {
  enable = true;
  agentsInput = inputs.agents;
};
```

### `coding.agents.pi`

Pi agent deployment from canonical TOML definitions.

```nix
coding.agents.pi = {
  enable = true;
  agentsInput = inputs.agents;
};
```

## Common Patterns

### Module Configuration

All modules follow this pattern:

```nix
{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
    # ... other options
  };

  config = mkIf cfg.enable {
    # ... configuration
  };
}
```

### Conditional Configuration

Use `mkIf` to conditionally apply config:

```nix
config = mkIf cfg.enable {
  # Only applied when cfg.enable = true
  services.my-service = {
    enable = true;
  };
}
```

### Multiple Conditions

Use `mkMerge` for multiple conditions:

```nix
config = mkMerge [
  (mkIf cfg.feature1.enable {
    # Applied when feature1 is enabled
  })
  (mkIf cfg.feature2.enable {
    # Applied when feature2 is enabled
  })
];
```

### Optional Dependencies

```nix
options.m3ta.myModule = {
  enable = mkEnableOption "my module";
  package = mkOption {
    type = types.package;
    default = pkgs.defaultPackage;
  };
};

config = mkIf cfg.enable {
  services.my-service = {
    package = cfg.package;
  };
};
```

## Configuration Examples

### Minimal NixOS Configuration

```nix
{pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  m3ta.ports = {
    enable = true;
    definitions = {
      my-service = 8080;
    };
    currentHost = "laptop";
  };

  services.my-custom-service = {
    enable = true;
    port = config.m3ta.ports.get "my-service";
  };
}
```

### Full NixOS Configuration

```nix
{config, pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  # Port management
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
      prometheus = 9090;
      mem0 = 8000;
    };
    hostOverrides.laptop = {
      nginx = 8080;
      mem0 = 8081;
    };
    currentHost = config.networking.hostName;
  };

  # Mem0 service
  m3ta.mem0 = {
    enable = true;
    port = config.m3ta.ports.get "mem0";
    llm = {
      provider = "openai";
      apiKeyFile = "/run/secrets/openai-api-key";
    };
    vectorStore = {
      provider = "qdrant";
      config = {
        host = "localhost";
        port = 6333;
      };
    };
  };

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

  # Grafana
  services.grafana = {
    enable = true;
    settings.server.http_port = config.m3ta.ports.get "grafana";
  };
}
```

### Minimal Home Manager Configuration

```nix
{pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];

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

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

### Full Home Manager Configuration

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

  # Port management
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
      nextjs = 3001;
      vite = 5173;
    };
    hostOverrides.laptop = {
      vite = 5174;
    };
    currentHost = config.networking.hostName;
  };

  # CLI tools
  cli.zellij-ps = {
    enable = true;
  };

  # Coding tools
  coding.editors = {
    enable = true;
    neovim.enable = true;
  };

  # Packages
  home.packages = with pkgs; [
    code2prompt
    zellij-ps
  ];

  # Environment variables
  home.sessionVariables = {
    EDITOR = "nvim";
    DEV_SERVER_PORT = toString (config.m3ta.ports.get "dev-server");
  };
}
```

## Module Options Reference

### Standard Options

All modules typically include:

| Option | Type | Description |
|---------|-------|-------------|
| `enable` | `boolean` | Enable the module |
| `package` | `package` | Custom package to use |
| `extraConfig` | `attrs` | Additional configuration |

### Port Management Options

| Option | Type | Description |
|---------|-------|-------------|
| `definitions` | `attrsOf int` | Default port definitions |
| `hostOverrides` | `attrsOf attrs` | Host-specific overrides |
| `currentHost` | `string` | Current hostname |
| `generateEnvVars` | `boolean` | Generate environment variables (HM only) |

## Combining with Other Flakes

### Using Multiple Module Sources

```nix
{config, ...}: {
  imports = [
    # m3ta-nixpkgs modules
    m3ta-nixpkgs.nixosModules.default

    # Other flake modules
    inputs.impermanence.nixosModules.impermanence
    inputs.sops-nix.nixosModules.sops
  ];

  # Configure all modules
  m3ta.ports = {
    enable = true;
    definitions = {nginx = 80;};
    currentHost = config.networking.hostName;
  };

  environment.persistence = {
    "/persist" = {
      directories = ["/var/lib/mem0"];
    };
  };
}
```

### Using with Secrets

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
    inputs.sops-nix.nixosModules.sops
  ];

  sops.secrets = {
    openai-api-key = {};
  };

  m3ta.mem0 = {
    enable = true;
    llm = {
      apiKeyFile = config.sops.secrets.openai-api-key.path;
    };
  };
}
```

## Troubleshooting

### Module Not Found

Error: `error: The option 'm3ta.mymodule' does not exist`

**Solutions**:
1. Make sure you imported the module:

```nix
imports = [
  m3ta-nixpkgs.nixosModules.default
];
```

2. Check module name is correct

```nix
# Correct
m3ta.mem0.enable = true;

# Wrong
m3ta.mymodule.enable = true;  # Doesn't exist
```

### Option Type Mismatch

Error: `type mismatch at 'm3ta.mymodule.enable', expected a boolean but got a list`

**Solution**: Check option types in documentation

```nix
# Correct
m3ta.mymodule.enable = true;

# Wrong
m3ta.mymodule.enable = [true];  # Should be boolean
```

### Port Not Defined

Error: `Service "foo" not defined`

**Solution**: Add to port definitions

```nix
m3ta.ports = {
  definitions = {
    foo = 8080;  # Add this
  };
};
```

## Best Practices

### Use Namespaces

Always use the `m3ta.*` namespace:

```nix
# Good
m3ta.mem0.enable = true;

# Bad (potential conflicts)
mem0.enable = true;
```

### Document Your Configuration

Add comments explaining module usage:

```nix
# Port management for multi-host setup
m3ta.ports = {
  enable = true;
  definitions = {
    nginx = 80;
    grafana = 3000;
  };
  hostOverrides.laptop = {
    nginx = 8080;  # Use different port on laptop
  };
  currentHost = config.networking.hostName;
};

# Mem0 AI memory service
m3ta.mem0 = {
  enable = true;
  port = config.m3ta.ports.get "mem0";
};
```

### Test Configuration

```bash
# Test NixOS configuration without applying
sudo nixos-rebuild test --flake .#hostname

# Check configuration
nix flake check

# Show all options
nix eval .#nixosConfigurations.hostname.config.m3ta --apply builtins.attrNames
```

## Next Steps

- [Port Management](./port-management.md) - Detailed port management guide
- [Adding Packages](./adding-packages.md) - How to add new packages
- [Adding Modules](./adding-modules.md) - How to add new NixOS or Home Manager modules
- [Templates](../templates.md) - Boilerplate for new packages and modules
- [Architecture](../ARCHITECTURE.md) - Understanding module structure
- [Contributing](../CONTRIBUTING.md) - Code style and guidelines