Introducing cardano.nix: Simplifying Cardano Infrastructure Deployment

CardanoNixOS
Written By Andrea Ciceri
The Challenge: Complexity in the Cardano Ecosystem

Running Cardano infrastructure is notoriously complex. Whether you're operating a stake pool, developing DApps, or providing API services, you're likely familiar with these pain points:

  • Configuring and maintaining multiple interconnected services (cardano-node, ogmios, kupo, db-sync)

  • Managing compatible versions across components

  • Implementing load balancing and high availability

  • Setting up monitoring and metrics

Furthermore, each service has its own configuration format, deployment requirements, and operational quirks.

Enter cardano.nix

cardano.nix is an open-source project by MLabs that solves these problems by providing pre-configured NixOS modules for the entire Cardano stack. But what does this mean in practice?

A Brief Introduction to Nix/NixOS

For those unfamiliar, Nix is a package manager that guarantees reproducible builds and declarative dependency management. NixOS extends these concepts to the operating system level, allowing you to define your entire server configuration in code, with atomic rollbacks and reproducibility guarantees.

Think of it as "Infrastructure as Code" taken to its logical conclusion. Instead of imperative scripts that modify system state, you declare what you want, and NixOS makes it happen.

With cardano.nix, you can describe your Cardano infrastructure like this:

{
  cardano = {
    network = "mainnet";
    node.enable = true;
    ogmios.enable = true;
    kupo.enable = true;
    monitoring.enable = true;
  };
}

These few lines automatically provision:

  • A fully synchronized Cardano node (the blockchain node that validates transactions and maintains the ledger)

  • Ogmios for WebSocket access (a lightweight bridge interface that allows applications to interact with the node via JSON-RPC)

  • Kupo for UTxO indexing (a fast, lightweight chain indexer for querying UTxOs and tracking addresses)

  • Complete monitoring stack with Prometheus and Grafana (real-time metrics, dashboards, and alerting for all services)

Testing Infrastructure: NixOS VM Tests and CI

One of cardano.nix's standout features is its comprehensive testing infrastructure, built on NixOS's powerful virtual machine testing framework. This system allows us to validate that all services work correctly together, not just in isolation.

NixOS VM Testing Framework

Every configuration and service combination in cardano.nix is validated through automated VM tests that spin up complete, realistic environments. These tests go far beyond unit testing—they create actual virtual machines running the full stack and verify end-to-end functionality:

# Example: Testing ogmios integration
{
  nodes.machine = {
    cardano = {
      network = "preview";
      node.enable = true;
      ogmios.enable = true;
    };
  };
  testScript = ''
    machine.wait_for_unit("cardano-node")
    machine.wait_for_unit("ogmios")
    
    # Wait for node synchronization
    machine.wait_until_succeeds("cardano-cli query tip --testnet-magic 2")
    
    # Verify ogmios is responding
    machine.succeed("curl --silent --fail http://localhost:1337/health")
    
    # Test actual network synchronization
    machine.wait_until_succeeds(
      "[[ $(curl -s http://localhost:1337/health | jq '.networkSynchronization') > 0.001 ]]"
    )
  '';
}

These tests create real virtual machines that:

  • Boot complete NixOS systems with our configurations

  • Can connect to actual Cardano networks (preview, preprod, mainnet)

  • Verify service startup, networking, and inter-service communication

  • Test failure scenarios and recovery procedures

  • Validate security configurations and permissions

Hercules CI: Effects-Based Testing

For our continuous integration, we leverage Hercules CI, which uniquely supports Nix's declarative approach to CI/CD through effects—a way to declare side-effectful operations (like network tests) directly in Nix expressions.

This is crucial for Cardano testing because standard Nix builds run in a sandbox with no network access, which works well for pure builds but is insufficient for blockchain infrastructure testing. Hercules CI's effects system allows us to break out of this sandbox in a controlled, declarative way.

This enables us to run comprehensive end-to-end tests that connect to the actual Cardano network, ensuring our configurations work correctly with real blockchain data and network conditions.

The combination of NixOS VM tests with Hercules CI effects gives us unprecedented confidence in our configurations—every commit is validated against real Cardano infrastructure, ensuring that users receive thoroughly tested, production-ready configurations.

Auto-Generated Documentation System

cardano.nix provides comprehensive reference documentation by automatically generating it directly from the code. This approach ensures that the documentation stays synchronized with the actual implementation and available configuration options.

Unified Documentation Approach

Our documentation system intelligently combines two sources:

1. Upstream Module Documentation: When we import NixOS modules from upstream projects (like cardano-node, cardano-db-sync, or ogmios), we automatically generate documentation for their options as well, preserving all the detailed configuration options, types, and examples from the original projects.

2. cardano.nix Module Documentation: Our wrapper modules, which provide the simplified cardano.* interface, are fully documented with automatically generated reference material that includes every configuration option with precise types and default values with their rationale. Additionally, we provide hand-curated documentation pages and tutorials for common use cases and getting-started scenarios.

Recent Developments: Beyond 1.0

Since the stable 1.0.0 release in August 2025, we've continued enhancing cardano.nix based on the needs of our projects and real-world usage:

Version 1.0.0: First Stable Release

After reaching a good level of stability and using cardano.nix across multiple projects, we decided to make the first stable release. Along with this milestone, we introduced a proper release process with automatically generated changelogs from commit messages, which we then review and synthesize for clarity.

Version 1.1.0: Flexible Provider System

The most significant addition is the provider abstraction system. Version 1.0.0 laid the groundwork for this flexible architecture, and 1.1.0 builds upon it to allow transparently switching the Cardano node source without modifying dependent service configurations.

In the future, it will be possible to use Demeter.run for the node instead of running one locally:

{
  # Instead of a local node...
  # cardano.node.enable = true;
  
  # ...use a Demeter tunnel
  cardano.demeter-run.node = {
    enable = true;
    instance = "my-mainnet-instance";
    configFile = "/run/secrets/demeter-config.toml";
  };
  
  # Ogmios and Kupo continue working without changes!
  cardano.ogmios.enable = true;
  cardano.kupo.enable = true;
}

Version 1.2.0: Updates and Optimizations

The latest release brings:

  • Component updates: All packages updated to their latest versions - cardano-node 10.5.1, Ogmios 6.13.0, db-sync 13.6.0.5

  • nixpkgs updates: Updated to the latest nixpkgs version

  • Internal optimizations: Reduced the number of Nix flake dependencies and made internal improvements that should significantly reduce Nix evaluation time

Future Developments

The cardano.nix roadmap includes several exciting features based on the needs of our projects and evolving ecosystem requirements:

Enhanced Testing Framework

Leverage Nix's powerful testing framework more extensively by creating additional tests, particularly multi-VM network tests that simulate complex distributed scenarios. This will allow us to test load balancing, failover mechanisms, and cross-node communication patterns more thoroughly.

Developer-Focused VM Environment

Investigate creating easily launchable VMs with all necessary software (reusing the entire cardano.nix stack) but optimized for developers. This would provide developers with a local node socket and everything they need for development work, eliminating the complexity of setting up a complete Cardano development environment.

Extended Service Ecosystem

Continue adding new packages and services to the cardano.nix ecosystem, expanding support for additional tools and infrastructure components that the Cardano community needs for building and operating applications.

Security Audit and Hardening

Conduct a comprehensive security audit of all services and investigate which additional systemd security directives we can activate to make the entire stack as secure as possible. This includes reviewing and potentially tightening the current systemd service configurations across all modules.

Stay updated on these developments through our changelog.

Getting Started Today

cardano.nix is available on GitHub and already used in production by several MLabs projects. Complete documentation is available at mlabs-haskell.github.io/cardano.nix.

To see the simplicity with which cardano.nix spins up the entire infrastructure in just a few minutes, you can try our demo:

# Install Nix (if you don't have it)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
# Start a VM with cardano-node and ogmios (demo)
nix run github:mlabs-haskell/cardano.nix#vm-preview

The VM will start with:

  • cardano-node syncing to preview testnet

  • Ogmios available at http://localhost:1337

  • Kupo at http://localhost:1442

  • cardano-cli pre-configured and ready to use

Why This Matters

The Cardano ecosystem is maturing rapidly, but infrastructure complexity remains a barrier to entry. cardano.nix removes this barrier by providing:

  • For Developers: Focus on building DApps, not fighting with DevOps

  • For SPOs: Reliable, reproducible stake pool deployments

  • For Service Providers: Production-ready infrastructure patterns

  • For Enterprises: Auditable, version-controlled infrastructure

Whether you're running a stake pool, developing DApps, or providing infrastructure services, cardano.nix can dramatically simplify your operations while maintaining complete flexibility and control.

Join the Community

cardano.nix is an open-source project developed and maintained by MLabs. We welcome contributions and feedback from the Cardano community. Find us on:

Andrea Ciceri
Next

Backing the Future: MLabs Proposals for Catalyst Fund14