Home on Clan

Data Mesher

Mon, 30 Mar 2026 12:00:00 +0000

NixOS is great when it comes to declarative state. Instead of running commands to install packages, edit config files and so on, you declare what you want and nixos-rebuild switch takes care of the rest.

Clan takes this one step further, making it easy to define services which span multiple machines and ensuring the end result by running clan machines update.

So, what if we want to update a user’s authorized_keys across a 10, 20 or 30-machine Clan?

As you might have guessed, we first update our Clan config and then run clan machines update. This will build and deploy the new NixOS configuration across all 30 machines.

Feels a little heavy though, doesn’t it? Maybe we just wanted to give that person access for a short while? When we’re finished, we have to update our Clan config and redeploy to every machine in our Clan.

And what if a few of those machines are laptops, used in the field and possibly out of contact or turned off when we are ready to roll back that authorized_keys change? Unless you remember to deploy those machines when they come back online, they will remain out of sync and continue to allow access until the next deployment.

That’s why we are building Data Mesher.

How does it work?

Sign a file, give it to Data Mesher, and it will (eventually) replicate it to every other Data Mesher instance. If a node is offline when the update is received, that isn’t a problem. The next time it connects to the cluster, it will catch up.

There’s no RAFT here. We don’t require a quorum when accepting writes.

Networking is handled by libp2p, and we use a basic anti-entropy mechanism inspired by memberlist to distribute an index of file signatures. It’s definitely more verbose than it needs to be just now, but we are tentatively adding complexity as we go along.

And you can’t just put any old file into Data Mesher. We require some configuration ahead of time, detailing each file name and a list of valid signers.

[files]
"config.json" = [
    # Base64 encoded ED25519 public keys
    "P6AE0lukf9/qmVglYrGPNYo5ZnpFrnqLeAzlCZF0lTk="
]
"data.bin" = [
    # Base64 encoded ED25519 public keys
    "ZasdhiAVJTa5b2qG8ynWvdHqALUxC6Eg8pdn6RVXuQE=",
    "1ru2QQ1eWV7yDlyfTTDEml3xTiacASYn0KprzknN8Pc="
]

This allows us to offload responsibility for managing the signature timestamp. If the signature is valid and the timestamp is later than the node’s current timestamp, it is accepted as the latest version and distributed accordingly.

No more blessed nodes to ensure consistent timekeeping, as we had in V1 (yes, we’re already on V2). It’s up to the signers to ensure timestamps make sense.

One last thing: no files over 10MiB. We aren’t building Syncthing or IPFS. Data Mesher is intended for targeted, small amounts of runtime state that need to be deployed resiliently within a reasonable time frame.

What can it be used for?

We are still fleshing that out, but so far we have dm-dns, a distributed DNS system which leverages Service Exports to collect all the custom endpoints that a Clan wants to expose internally. A zone file is then generated and injected into Data Mesher. From there, systemd is configured to watch for changes to that zone file as they land in the local file system and reloads an instance of unbound.

Other experiments include dm-pull-deploy, an asynchronous deployment system which distributes flake references via Data Mesher. Machines automatically run nixos-rebuild when a new flake reference arrives.

Most recently, Pinpox hooked up an instance of OpenCrow (his own version of OpenClaw) to Data Mesher, which let him change the wallpaper on his machines by chatting with the agent over Matrix. This experiment was tightly scoped, for good reason.

But technically, there’s not much difference between changing a wallpaper and granting the agent access to the async deployment system, which would let it manage much more than just the wallpaper…

What’s Next?

Data Mesher is still experimental and will continue to evolve as we flesh out the various use cases.

In the short term, we are working on signed namespaces so we don’t have to specify every file ahead of time. This will allow machines, for example, to publish self-signed information about themselves, such as their system closure, disk usage, and other basic metrics.

Long-term, we need to see how much mileage we can get out of this file-based API. Perhaps not everything will work well within this model. Or maybe the Linux kernel is on to something 🤷.

We also encourage you, the user, to try it out and see what you can come up with, and be sure to drop anything interesting into the clan-community repository 🙏.

Debugging Offline Nix Builds

Thu, 29 Jan 2026 12:00:00 +0000

I was trying to get our new container-based NixOS tests working. Should be simple, right? Run nixos-rebuild inside a container, verify the configuration applied correctly, done.

Instead, I watched Nix attempt to build what felt like half of nixpkgs from source…

The Setup

We’ve been working on running NixOS tests inside systemd-nspawn containers rather than full QEMU VMs. It’s faster, uses fewer resources, and works in the Nix build sandbox. The test modifies a NixOS configuration and runs nixos-rebuild switch to apply it.

The problem? The container has no network access. It runs inside Nix’s build sandbox, which isolates network by design. We pre-populate the Nix store using closureInfo, but if we miss even a single dependency, Nix can’t fetch it as a substitute. It has to build from source. And since dependencies have dependencies, missing one small package can cascade into rebuilding thousands.

This isn’t the first time I’ve hit this. When working on nixos-anywhere and disko, I ran into similar issues with hermetic builds. The pattern is always the same: something is missing from the closure, but good luck figuring out what.

The Usual Debugging Experience

Normally when this happens, you stare at a wall of build output. Nix is compiling GCC. Why is it compiling GCC? You didn’t change anything related to GCC. You scroll back through thousands of lines trying to find the root cause. Maybe you give up and add more packages to your closure, hoping one of them fixes it.

This time I wanted a better approach.

The Key Insight: `nix build --dry-run`

The --dry-run flag is the hero here. It shows what Nix would build or fetch without actually doing it:

$ nix build --dry-run .#yourPackage

The output has two sections:

Derivations to be built: packages that must be built from source
Paths to be fetched: packages that would be downloaded from a binary cache

In a properly configured hermetic environment, that second list should be empty. Any paths there are exactly what’s missing.

But here’s the catch: --dry-run needs network access to query the binary cache. And our test runs in a sandbox with no network.

Getting Network Access Into the Sandbox

For regular NixOS VM tests, this is straightforward. You build the test driver and run it outside the sandbox:

$ nix build .#checks.x86_64-linux.yourTest.driver
$ ./result/bin/nixos-test-driver

The interactive driver has network access, so you can run nix build --dry-run inside the VM.

For container tests, it’s more complicated. The container runs inside the Nix sandbox’s user namespace (needed for the uid-range feature). We can’t just disable the sandbox because we need those namespaces.

The solution? Inject network after the container starts.

Pausing the Test

The container test driver exposes a wait_for_signal() helper that tests can call to pause and wait for SIGUSR1. Add it to your test script where you want to pause:

start_all()
machine.wait_for_unit("multi-user.target")

# Pause here to allow network injection
wait_for_signal()

# Continue with the test...

When it pauses, the test driver prints a command you can run to inject network and continue:

DEBUG MODE: Test paused, waiting for SIGUSR1...

To inject external network and continue test, run:
sudo /nix/store/...-python3/bin/python3 /nix/store/...-test-driver/.../inject_network.py <uuid>

We’ve packaged all of the network injection logic into an inject_network.py script. Just copy and run the command printed by the test driver. It finds the container, injects network, signals the test to continue, then waits for Ctrl-C to clean up.

How Network Injection Works

The container test driver prints a UUID when it starts. The script uses that to find the container process and inject a network interface. Here’s how it works step by step.

First, find the container process using the UUID:

$ pgrep -af 'abbc0409-94bb-4218-95b4-60b1fd13e4c2'
276568 /bin/sh -c /nix/store/.../sleep 999999999 && echo abbc0409-94bb-4218-95b4-60b1fd13e4c2

Create a veth pair on the host:

$ sudo ip link add veth-host type veth peer name veth-inject

Move one end into the container’s network namespace:

$ sudo ip link set veth-inject netns "/proc/276568/ns/net"

Configure the host side:

$ sudo ip addr add 10.99.0.1/24 dev veth-host
$ sudo ip link set veth-host up

Now here’s the trick: we need to enter both the user namespace and network namespace to configure the container side. Just --net alone fails with “Permission denied”:

$ sudo nsenter --user --net --target 276568 -- ip addr add 10.99.0.2/24 dev veth-inject
$ sudo nsenter --user --net --target 276568 -- ip link set veth-inject up
$ sudo nsenter --user --net --target 276568 -- ip route add default via 10.99.0.1

Don’t forget DNS! The container’s /etc/resolv.conf is likely a symlink, so remove it first:

$ sudo nsenter --user --mount --target 276568 -- rm -f /etc/resolv.conf
$ sudo nsenter --user --mount --target 276568 -- sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

Enable NAT on the host:

$ sudo sysctl -w net.ipv4.ip_forward=1
$ sudo iptables -t nat -A POSTROUTING -s 10.99.0.0/24 -j MASQUERADE

Test connectivity:

$ sudo nsenter --user --net --target 276568 -- ping -c 1 8.8.8.8

PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=119 time=24.3 ms

The inject_network.py script automates all of these steps. It also cleans up the veth pair and NAT rules when you press Ctrl-C.

Running the Dry-Run

With network injected, SSH into the container and run the dry-run:

$ ssh root@192.168.1.1 'cd /flake && nix build --dry-run \
    .#nixosConfigurations.test-machine.config.system.build.toplevel'

Here’s what I got:

these 9 derivations will be built:
  /nix/store/04r01g9s2ckfs4v64gx426r1ac3ssamy-etc-update-build-local-successful.drv
  /nix/store/fyi5gy25qcncs8zf9vxnlb54yah66fs5-stage-2-init.sh.drv
  /nix/store/gbnayc92q4q82jdrcnzfdpm2fw0acgfm-dry-activate.drv
  /nix/store/jf3sixnjh3v7x6fjs1rd0i9hqd9pzsjv-etc.drv
  /nix/store/lhvslpfnh3nr978m0c862qxsl3dnzymi-activate.drv
  /nix/store/hvxxm22ddlig6lvn8pifxa7kpb67acq6-builder.pl.drv
  /nix/store/pv0dybshsabgxf6n8wmdq64lgdimx4pf-perl-5.42.0-env.drv
  /nix/store/xsffzqw02ng2a4dryhxx2pwmndm7cymb-check-sshd-config.drv
  /nix/store/6639244qzcgn3bhvv2gq4kd4ybdvvgl7-nixos-system-update-machine-.drv

these 3 paths will be fetched (0.00 MiB download, 0.01 MiB unpacked):
  /nix/store/4w0spqkn44zlrys9y93x06h949dvcpj8-ensure-all-wrappers-paths-exist
  /nix/store/48zc854y65q0jvsa2na6liawgqvh69cq-make-shell-wrapper-hook
  /nix/store/r0ddi8vysis4rdlqjkv9jp68b8d41i4k-openssh-10.2p1-dev

The 9 derivations are expected. That’s the new configuration we’re building. The 3 paths to be fetched are the problem.

Finding the Packages

Store paths have human-readable names, but we need the actual Nix expressions to add them to closureInfo.

For make-shell-wrapper-hook, we can verify the package name:

$ nix eval nixpkgs#makeShellWrapper --apply 'x: x.name'
"make-shell-wrapper-hook"

For -dev outputs like openssh-10.2p1-dev, it’s usually the main package with .dev:

$ nix eval nixpkgs#openssh.dev --apply 'x: x.name'
"openssh-10.2p1"

For NixOS-internal stuff like ensure-all-wrappers-paths-exist, grep the nixpkgs source:

$ grep -r "ensure-all-wrappers-paths-exist" nixos/modules/
nixos/modules/security/wrappers/default.nix:      pkgs.runCommand "ensure-all-wrappers-paths-exist"

This one is generated by the module system and should be part of the system toplevel closure. If it’s missing, it usually means the toplevel itself wasn’t properly included.

The Fix

Add the missing packages to closureInfo:


closureInfo = pkgs.closureInfo {
  rootPaths = [
    # ... existing paths ...
    pkgs.makeShellWrapper
    pkgs.openssh.dev
  ];
};

After adding these, the test ran successfully. Only those 9 derivations got built, no mass rebuild. ✅

A Note on `.drvPath`

You might be tempted to include pkg.drvPath to get the full build-time closure of a package. Be careful with this. It’s the nuclear option that can pull in a massive closure of build-time dependencies.

Two problems:

Slower test startup: Every path in the closure gets registered with the test’s Nix store database
Unnecessary downloads: You might download gigabytes of stuff you don’t need

Only use .drvPath for specific packages where you’ve verified it’s necessary:


rootPaths = [
  myPackage           # Runtime closure, safe
  pkgs.stdenv.drvPath # Build-time closure, use sparingly
];

Conclusion

The key takeaway: nix build --dry-run tells you exactly which paths are missing from your hermetic environment. The “paths to be fetched” list is your hit list.

For VM tests, run the driver interactively. For container tests or other sandboxed builds, you’ll need to inject network access temporarily. The veth + nsenter approach works but requires some namespace gymnastics.

It’s not pretty, but it saves a lot of time, staring at build logs trying to figure out why Nix is mass-rebuilding dependencies.

Clan 2025 Wrap-Up: From Infrastructure to a New Computing Paradigm

Mon, 12 Jan 2026 00:00:00 +0000

Why Clan Exists

Clan’s core mission is to make digital sovereignty accessible to everyone. Clan is not a platform or a product; it is a free, open source framework that empowers people and groups to customize and manage machines within safe, secure, private networks that they alone control. Clan is built to be deeply composable (i.e. systems built from small, interoperable building blocks), reliably reproducible, and entirely self-sovereign.

2025 delivered many forceful reminders of why this mission is more important and urgent than ever. From the rise of technocratic institutions, to increasingly invasive advertising, to the war on general-purpose computing still raging, we are inundated with technology designed to exploit, surveil, manipulate and extract from us. We won’t escape this mess through lobbying, interoperability or clever workarounds. It’s time for an exit, a full reset.

In direct opposition to the capture-and-extract model that dominates the tech sector, Clan is designed to empower anyone to build a digital life that is completely their own. No dark patterns, no rent, no data tax, no black boxes, no backdoors, no copyrights or access controls. Just free, open source, composable infrastructure for truly personal computing – the foundation of a fully sovereign computing stack.

2025 In Review

2025 culminated in the announcement of our first stable release, marking a shift in mindset: Clan is no longer an experiment. It is stable infrastructure that people depend on. We were thrilled this year to see Clan growing beyond the realm of enthusiasts’ homelabs and being used in production for business applications by corporate sysadmins. With this release comes a commitment to predictable behaviour, careful evolution, and responsibility toward users and contributors who are building on top of it.

Read on for more of the exciting milestones we achieved in 2025, both strengthening the foundations of Clan and exploring the horizons of where it can take us in the future.

Networking / VPN work and reliability gains

Reliable networking is foundational for Clan. If machines can’t find each other, stay connected, or recover gracefully from failures, nothing else matters. Over the past year, much of our work has focused on making peer-to-peer networking more robust, flexible, and predictable.

One recurring lesson is that there is no single “best” VPN or overlay network. Every solution comes with tradeoffs. Some rely on centralized controllers; others are fully peer-to-peer, but unreliable or difficult to operate. Some are fast but fragile, others are resilient but slow (see here for a detailed comparison). Instead of betting on one network to rule them all, we take a different approach.

Clan introduces a networking abstraction that allows multiple network technologies to coexist. Rather than forcing users to choose upfront, Clan can automatically select the best available network for a given machine. Networks are treated as services that can be enabled declaratively, assigned priorities, and attached to machines through tags. The Clan CLI then transparently uses the most appropriate network when connecting to a machine.

This abstraction has already led to significant gains in reliability. Clan commands now automatically pick up network configuration from the Clan flake for most operations, removing the need for users to manually specify hosts, IPs, or connection methods. Sensitive connection details, such as Tor hidden service addresses, are handled securely through Clan’s secret system and only decrypted when needed.

Today, this enables admin-to-machine connectivity over networks such as Tor or the public internet, with support for on-demand networking services that start only when required. The result is a system that is more resilient to outages, avoids unnecessary exposure to the public web, and continues working even when individual network components fail.

Looking ahead, this networking layer becomes even more important. Users can already add their own network services to Clan, and in the coming year, we plan to extend the model further by enhancing machine-to-machine networking, supporting additional overlay networks, and unifying userspace networking across all providers. The goal is simple but ambitious: networking that “just works,” without hiding complexity behind a fragile abstraction, and without reintroducing centralized points of control.

Micro VMs

If Clan is about sovereign machines and networks, the next challenge is sovereign applications.

Today’s proprietary platforms have set a very high bar for usability and security. Commercially hosted web and mobile apps are heavily sandboxed by default, can run multiple instances, and are always pre-connected to the services they need. In contrast, much of the peer-to-peer software world is still made up of applications that are complicated to install and configure, have unclear security boundaries, rely on complex or unreliable client-server protocols and are limited to a single instance. As powerful as a lot of this software is, it is often also unsafe, cumbersome, and limiting.

To close this gap, we’ve been exploring micro VMs to make running peer-to-peer applications safer, more convenient and more flexible.

Safer: Rather than the shared-kernel isolation of e.g. Linux namespaces, micro VMs use hardware virtualization to maintain strong security boundaries between applications. This means software you run inside a micro VM environment has no connection to your primary system or any other programs you’re running, so any vulnerabilities stay contained.

More convenient: By running applications inside a micro VM, we can make sure software loads the same for everyone, regardless of what OS they’re using. Nix’s caching and reproducible builds mean programs can launch almost as quickly as web apps, while remaining fully local and user-controlled. Best of all, Clans are ready-made peer-to-peer networks, so communication between them is already established and traffic never needs to touch hosted servers or the open web.

More flexible: Unlike traditional virtual machines, micro VMs are extremely lightweight and can start in a few hundred milliseconds. An everyday desktop or laptop can run a micro VM - or several - that operates in isolation, enabling a user to e.g. bypass compatibility issues, run multiple instances, experiment with different configurations or create an ad hoc environment for a specific purpose.

A key requirement for making all of this practical is deep desktop integration, including graphics acceleration. We’ve been working on GPU-accelerated micro VMs using modern virtio-gpu techniques, enabling Wayland-based graphical applications to run inside micro VMs with near-native performance, without requiring dedicated GPUs or enterprise-only hardware features.

Of course, isolation alone isn’t enough. Applications still need controlled ways to share data with users and with each other. To enable this, we’re integrating D-Bus–based desktop portals, similar to those used by Flatpak, allowing applications to request access to files, cameras, or screens through explicit, user-mediated permissions. This preserves strong isolation while keeping applications genuinely useful.

Together, Nix, micro VMs, GPU acceleration, desktop portals, and mesh VPNs form the basis of a local application platform that is secure by default, fast enough for daily use, and naturally compatible with peer-to-peer networking. As a result, even applications that were never designed for P2P use can be safely retrofitted to work in distributed, self-hosted environments. This work is still evolving, but it represents a critical step toward making community-owned, self-hosted software competitive with proprietary platforms, without sacrificing user experience or sovereignty.

Looking ahead, the next step is to integrate micro VMs more deeply into Clan itself. This includes first-class support in the Clan CLI and, over time, exposing micro VM-based applications and services through the Clan GUI. Our goal is to make strong isolation, reproducibility, and secure application sharing feel like a natural part of managing a Clan, not a separate or specialized workflow.

Our first explorations in this area have focused on deploying micro VMs within NixOS systems, but in the future we will extend this approach to make Clan itself portable: a complete operating environment in a replicable, shareable package, so a user can join a Clan even if they don’t have NixOS installed.

We want to take this opportunity to express our gratitude to our friends at Qubes OS for introducing us to the amazing Val Packett, who has been driving this line of experimentation.

Clan GUI

Strong, safe defaults are a necessary foundation, but for many people, they are still not enough. Especially for those unfamiliar with NixOS, even a well-chosen default configuration leaves too much implicit knowledge unstated. Understanding how machines relate to each other, how services are composed, how secrets are managed, or how changes propagate across a network still requires expertise most users don’t have.

To make Clan accessible beyond experienced Nix users, we needed a more legible way to understand and operate a Clan of machines. This is why we started building the Clan GUI, which we introduced at NixCon.

The GUI does not replace Nix or the Clan CLI; it builds on top of them. Where the CLI is precise and powerful, the GUI makes the system visible and approachable, especially for collaborators who shouldn’t need to touch configuration files to participate.

At its core, the GUI reflects Clan’s opinionated deployment framework. It focuses on the hardest parts of self-hosting: bootstrapping machines, managing secrets, wiring services across multiple systems, and understanding what is running where. A declarative secret management system allows services to opt into their own secrets before deployment, enabling automatic generation, secure storage, rotation, and testing, all exposed consistently through both CLI and GUI.

On top of this sits client services: a multi-machine service layer that makes it possible to define shared infrastructure once and apply it across groups of machines using tags. Because this layer is JSON-compatible, services can be added, removed, or reconfigured through the GUI while remaining fully compatible with Nix-based workflows.

The result is an interface that makes infrastructure easier to understand. Machines appear as part of a network, can be grouped and tagged, and have services applied visually. This makes Clan usable not only by the person who set it up, but also by families, teams, and collaborators.

The Clan GUI is still in early development and today complements, rather than replaces, the CLI. But it already points toward the future: sovereign infrastructure that is not just powerful, but understandable - and maybe even fun.

Secrets and computed values, rethought

In 2025, we replaced our initial secret management approach (“facts”) with vars, a declarative framework that allows services to define how secrets and other values are generated, shared, and rotated across machines. This removed much of the manual bootstrapping traditionally required when deploying infrastructure and made both CLI and GUI workflows more reliable. Looking ahead, we are continuing to move vars to the flake level, attaching secrets to services rather than individual machines to further improve scalability, usability, and cross-machine coordination.

Inventory: from single machines to fleets

NixOS excels at configuring individual machines. Clan extends this paradigm to groups of machines by introducing an inventory and service layer abstraction. This makes it possible to define services, users, secrets, and relationships once and apply them consistently across many machines. It’s a critical shift from “machine configuration” to “infrastructure configuration,” and underpins everything from networking to future collaboration features.

inventory.instances = {
    # One declaration enables VPN across all machines
    zerotier = {
      roles.controller.machines.server = { };
      roles.peer.tags = [ "all" ]; # All machines join the network
    };
  };

You can read more about the inventory here.

Service exports and composability

Clan services can now export values that other services can consume. This allows different parts of the system to wire themselves together automatically, for example, enabling VPN configuration to be reused by higher-level services without manual glue code. The result is a more composable system where services cooperate instead of being configured in isolation.

perInstance = { mkExports, machine, ... }: {
    exports = mkExports {
      peer.hosts = [
        {
          plain = clanLib.getPublicValue {
            machine = machine.name;
            generator = "mycelium";
            file = "ip";
            flake = directory;
          };
        }
      ];
    };
  };

You can read more about how exports work here.

macOS as a first-class Clan member

In 2025, Clan gained full support for managing macOS machines via nix-darwin. MacOS systems can now participate in the inventory, receive declarative configuration, manage secrets, and be deployed from — or deploy to — other Clan machines. This matters because real-world Clans are heterogeneous: families, teams, and communities rarely run Linux everywhere. Supporting macOS makes Clan viable in mixed environments and lowers the barrier to adoption.

What’s next

In dry technical terms, we describe Clan as a peer-to-peer computer management framework. But this idea is deceptively radical: if anyone is free to create secure, autonomous networks, with self-hosted data and services, then we are also free to completely reimagine what it means to be online. The monolithic dead internet, the so-called “global public square”, could be replaced by a living web of individual spaces – some public, some private, all opt-in and entirely self-determined.

However, this also presents a challenge: in a world where one person belongs to many Clans and connects to as many internets, how do they navigate? How do they keep track of where they are, where their people are, what is private and what is public?

No matter how secure the technical foundation might be, it won’t accomplish anything unless it’s also usable. So we’ve started to experiment with different technologies that could weave these pieces together - to determine how multiple networks and applications could exist on the same machine, how those machines could find each other, offer services, exchange resources and more. Micro VMs and Clan GUI are the first, still ongoing, efforts in this direction. The following initiatives are still in early stages of research and prototyping, but we’re excited to share this first glimpse of what’s on the horizon.

Spaces

Spaces is a free and open source operating environment designed to make digital sovereignty the norm by building Clan in at the base level. The networked machines in a Clan represent a group of human beings and the connections between them; Spaces give those connections a tangible form. If your Clan is your village, then spaces are the rooms and common areas where you live, work, and gather together.

Create and share spaces: Customize spaces for work, family, gaming, art, life admin, or anything else you use your computer for. Each space can have its own look and feel, organization, tools, and access rules. One space might be completely private, cut off from the internet, so you can store sensitive files knowing there’s no way for anyone to get in. In another, you might add your family or work Clan. Or you could create a space that’s completely open and discoverable by anyone.

Multiplayer by default: People in a shared space are connected at the OS level - no crashed website, censored platform or cloud outage can keep them apart.

Isolation by design: A space is a self-contained environment, completely isolated by default, so what you do in one space won’t affect the security or functionality of another – even if they’re running on the same machine.

No platform purgatory: Essential tools such as messaging, video chat, shared files, collaborative docs, wallets, and more are built in as modular services and widgets, available to anyone who joins the space. No need for everyone to download anything or make an account anywhere – just get straight to doing whatever you do, together.

Own your OS: Your computer, operating system, and online spaces are entirely your own. Create your own tools, apps and widgets, customize and share them with your Clan or with the whole world. No coding required - Spaces Playground will help you create whatever you dream up with a few text prompts.

There’s much more on the horizon - we’ll follow up with a dedicated post about Spaces in the coming weeks.

Clan and LLMs

We are deliberately not part of the current AI hype cycle. Calling large language models “AI” is, in our view, misleading at best. These systems are not intelligent in any meaningful sense, and framing them as such obscures both their limitations and the real risks of concentrating power in opaque, corporate-controlled systems. We are also wary of how LLMs are currently used to replace clear interfaces, obscure system behavior, or paper over poor design. Clan remains fundamentally declarative, inspectable, and deterministic by default. Power users should always be able to reason about, audit, and reproduce their systems without a chat window in the way.

That said, large language models are a powerful piece of technology. Especially when combined with open source software, self-hosting, and strong isolation guarantees, they can become genuinely useful tools rather than extractive platforms.

For Clan, the key condition is non-negotiable: LLMs must be able to be self-hosted and locally controlled. Models that depend on centralized APIs, surveillance-driven business models, or proprietary platforms are fundamentally incompatible with digital sovereignty. But when models run locally, inside clearly defined boundaries, they can dramatically lower the barrier to using complex systems.

In the short term, we’re exploring LLMs as an interface layer. One concrete experiment is controlling parts of the Clan UI and services through a locally hosted LLM. Instead of requiring users to learn new terminology or configuration patterns upfront, they can describe what they want in plain language and have the system translate that intent into concrete, inspectable actions.

Used this way, LLMs don’t replace understanding, but help people to get started without being overwhelmed. A second already planned experiment is the use of LLMs within Spaces: locally hosted LLMs could also help facilitate interaction by acting as shared assistants that summarize activity, mediate coordination, surface relevant context, or help people navigate what is happening inside a space without turning it into a noisy or overwhelming environment.

Long-term, we see a more interesting possibility. If Clan becomes the foundation for sovereign, self-hosted computing, then locally hosted and isolated LLMs could act as mediators between Clans. A Clan could describe the services it offers, the resources it is willing to share, or the conditions under which access is granted.

These descriptions could be indexed, queried, and negotiated through LLMs, enabling discovery and coordination without relying on centralized platforms. This direction is inspired by projects such as KOI and aligns closely with our vision of a decentralized, human-scale internet.

In both cases, the principle remains the same: keeping LLMs local, inspectable, and isolated, we can use their strengths without importing the failures of the platforms that currently dominate this space.

ClanHub: A Home for Community Services

As Clan has grown, so has the number of services built on top of it. What started as a small, tightly integrated set of core services has expanded to dozens of modules, many of which don’t require deep coupling with Clan’s core logic. While this growth is exciting, it also creates maintenance overhead that slows down core development.

To address this, we’re introducing ClanHub: a shared home for open source services compatible with Clan that are developed and maintained by the wider community.

ClanHub is intended as a place where contributors can add new services, iterate quickly, and establish best practices together, while relying on stable Clan core APIs. This allows the core team to focus on fundamentals like reliability, networking, and tooling, while giving community services more room to grow on their own terms.

A great example of a contribution that fits naturally into ClanHub is monitoring. Recently, Friedow contributed a new monitoring service that cleanly separates server and client roles, supports metrics, logs, dashboards, and alerting, and has already been tested in real-world Clan setups. This kind of well-scoped, production-proven service benefits from shared CI, clear ownership, and faster iteration, all of which ClanHub is designed to support.

Over time, we plan to move many services that don’t require tight core integration into the community space, while keeping only a small, carefully curated set in Clan itself. ClanHub will provide shared CI, testing patterns, documentation, and visibility, making it easier to review contributions, ensure quality, and help new maintainers succeed.

Most importantly, ClanHub is optional. No one is forced to use it, and nothing prevents experimentation elsewhere. But for contributors who want their services to be discoverable, well-supported, and compatible with Clan’s evolving ecosystem, ClanHub will be the natural place to collaborate.

This is an important step toward a healthier division of responsibilities: a stable, focused core and a thriving, fast-moving ecosystem around it.

Clan as mass-scale decentralized infrastructure

Although we’ve so far focused on smaller scale networks, we have also been researching how Clan might add resilience and value to large-scale decentralized systems such as blockchains. Blockchains, which store more than $3 trillion worth of digital assets in the form of cryptocurrencies, are heavily dependent on centralized infrastructure such as cloud providers and hosted platforms. Now that we have a stable version of Clan, we can finally say to the crypto world: “Clan can fix this.”

We believe this area is worth exploring because it represents a strategic opportunity and proving ground for both Nix and Clan. It’s a highly adversarial environment, so if Clan can endure there, it can endure anywhere. Moreover, most blockchain infrastructure is already open source and Linux-based, so migration costs would be low, but the potential benefits are high.

Blockchain decentralization is undermined at several layers:

Infrastructure: deploying and maintaining nodes is a technical burden that most individuals are unable or unwilling to take on. Nodes instead tend to consolidate around resource-rich enterprises who average users depend on, share private data with, and even pay for access.
Applications: very little usable information can be stored or communicated over a blockchain. The vast majority of user experience and activity happens off-chain, where DApp developers have to bridge the gap with hosted interfaces or outsource to third-party platforms like Discord. This creates friction, restricts what DApps can do, and burdens maintainers with unnecessary liabilities.
Stack depth: the core functionality of a blockchain is to sort transactions and maintain shared global states. It’s actually a very shallow stack, with the ordered logic of the protocol fundamentally disconnected from the chaotic system of human society.

We have considered a number of ways Clan could be used at each of these layers, including:

Communal hosting: not all users need to run their infrastructure personally. Friends, families, and communities can create Clans to collectivize node resources. Useful configurations could then propagate between groups.
DAO desktop: like showing up on the first day of work and being given a preconfigured laptop, DAO members could simply open a DAO-managed Clan to enter into a local, bespoke desktop environment, where things like privacy could be mandatory.
Off-chain smart contracts: instead of relying on application-specific L2s, individuals could simply deploy ephemeral, user-specific private L2s for their personal transactions, executed securely over a Clan with verifiable end states.

Closing Thoughts

The examples discussed above, including blockchain and peer-to-peer coordination, are just one illustration of a broader pattern: many long-standing problems across different industries stem from the same underlying issues of centralization, opacity, and loss of user control. We see Clan as a foundation that can help address these issues far beyond any single domain, and we hope this post sparks curiosity and creativity about where Clan could be useful next, or what could be built on top of it.

2025 marked an important transition for Clan: from experimentation toward production-grade infrastructure. With the first stable release, stronger defaults, and a growing focus on reliability, we’ve taken on a greater responsibility toward the people and communities who depend on this work. Over the past year, we also deepened our involvement in the Nix ecosystem, through community events, sponsorships, and direct contributions, including Lassulus taking on the role of treasurer of the NixOS Foundation. These are signals of long-term commitment, not just to Clan, but to the ecosystem it builds upon.

We are deeply grateful to everyone who contributed code, feedback, ideas, and critical perspectives throughout the year, as well as to our partners and sponsors, especially our friends at Golem, whose support has been instrumental in making this work possible.

Clan is built in public, deliberately and collaboratively. If you’re curious, we invite you to try Clan, explore the repository, join the conversation on Matrix, give feedback, follow development, and share ideas about where Clan could help solve real problems. We believe sovereign computing is not a niche concern, but a prerequisite for a healthier digital future, and we’re excited to keep building toward it together.

Credits

“Voxel art in Spaces UI by Mari Zand, used with permission”

Towards a secure peer-to-peer app platform for Clan

Fri, 26 Sep 2025 06:30:00 -0333

While most of the existing Clan framework is dedicated to machine and service management, there’s more on the horizon. Our mission is to make sure peer-to-peer, user-controlled, community software can beat Big Tech solutions. That’s why we’re working on platform fundamentals that would open the way for our FOSS stack to match the usability and convenience of proprietary platforms.

Unfortunately, the FOSS world is still lagging behind commercial platforms in some important aspects:

Web and mobile apps are strongly sandboxed, so while they can get very aggressive in snooping on the data they are allowed to access, the enforcement of the isolation model is very robust — and there is a model for sharing data that makes the isolated applications actually useful..
- Meanwhile in the FOSS world, it’s still extremely common to run software with full access to the user’s account. The only project that has built anything close to a similar platform for local software is Flatpak, which is still not perfect and its main repo has a very lax policy;
Centralized Web services can have “multiple instances” simply by switching accounts; self-hosting Web services is trivially multi-instance; even Android now provides a multi-instance facility..
- Meanwhile local software often doesn’t have a global database, but when it does, it can be impossible to make it multi-instance without advanced knowledge;
Commercial apps come with their own always-online remote servers. Users don’t have to think about connecting the clients to the servers, it’s all pre-connected!
- Meanwhile decentralized community software is stuck between various bad options. Supporting multiple commercial backends is tedious and defeats the point anyway. Self-hosting traditional web servers can get complex and unreliable, and exposes attack surface to the public Web. Direct peer-to-peer connections can be hard to set up and unreliable too, and typically don’t provide asynchronous communication.

So… What do we need to make it possible for communities to share apps install and load quickly, already pre-connected to network services; are isolated to a worry-free level of security, and yet allow for enough sharing via explicit permissions to make them useful?

The first piece of the puzzle is, unsurprisingly, Nix. The entire Clan project is built on Nix, and the future app platform is no exception. Nix makes it possible to quickly fetch and run any software – thanks to caching, as long as we steer everyone towards using very few common versions of the nixpkgs tree, most downloads could be almost as fast as web app loads.

Then we have to add a microVM hypervisor with Wayland and GPU virtualization and a side of D-Bus portals… and we can finally get a glimpse of the future!

microVMs

Secure isolation is essential for any modern app platform. Hardware-based virtualization is a lot more confidence-inspiring than shared-kernel isolation mechanisms like Linux namespaces. But it’s not only a security measure. Running apps in VMs also improves environment consistency/reproducibility by ensuring everyone runs the same kernel — which can also give us portability, since it enables running on completely different host OSes as well.

If your experience with virtualization on desktop has only been with booting entire Linux distros under something like VirtualBox, you might be very skeptical of the same technology being involved in launching applications all the time. But that’s not at all inherent to the use of KVM!

Conventional VMs feel “heavy” —slow to launch, big RAM footprint, extra background CPU usage, fixed storage allocation, usually not very well integrated with the host desktop— only because their goal is to simulate a whole another computer within your existing computer. For app isolation, we don’t need that, so the whole stack can be vastly simplified and optimized for high performance and low overhead. The microVM idea was first popularized by AWS’s Firecracker on the server side, powering instantly-launching event/request handlers in Lambda. A microVM boots directly into the kernel (skipping firmware) and does not emulate any legacy PC hardware, which results in very fast boot times, on the order of a couple hundred milliseconds.

Now, has this been used on the client side already? Yes, most prominently by Asahi Linux, motivated by a technical restriction that was preventing Apple machines from playing legacy Windows games. That’s the muvm project, powered by libkrun – a Firecracker-like VMM provided as a dynamic library so that different frontends could be built. For our platform development, we have indeed adopted muvm (after submitting some changes that make it more useful for us), combining it with namespace-based Bubblewrap to make a script that runs NixOS system closures in microVMs.

…Wait, did someone mention playing games– like, highly GPU-demanding games? In a VM? Without a dedicated GPU?

Desktop and GPU support

In the Beginning (of virtio-gpu), there was the Framebuffer. An emulated computer monitor, a single rectangle representing the entire graphical output of the VM. Then there was VirGL, a way to forward the OpenGL API across the VM boundary to make the host render on its GPU on behalf of the VM, so that 3D graphics could be displayed on the emulated monitor. It wasn’t super fast, it wasn’t compatible with the latest GL extensions, it wasn’t very secure, but it was something. With the advent of Vulkan, Venus was started as the Vulkan version of the same thing.

Meanwhile, the Chrome OS team was working on adding support for Linux apps. While it was initially based on namespaces, they quickly started working on switching to hardware virtualization. The virtio-gpu device was extended to support arbitrary “cross-domain” protocols, making it possible —with some wrapping-unwrapping— to forward Unix domain sockets that pass certain types of file descriptors (shared memory and DMA-BUF) to the guest. (Well, initially it was a whole separate virtual device but let’s skip over that.) Google’s crosvm supports connecting to the host Wayland socket to that facility, and the team wrote Sommelier as the guest-side proxy that exposes a normal Wayland socket to guest apps.

The part of crosvm responsible for handling the virtio-gpu device was written as a reusable library called Rutabaga (now living outside of the CrOS repos), and integrated into other VMMs such as good old Qemu. Sommelier was packaged by various Linux distros as well, and one enthusiast wrote an entire alternative to Sommelier.

Meanwhile, there was also a lot to improve in terms of accessing the GPU. As we’ve mentioned already, API forwarding solutions like VirGL/Venus leave a lot to be desired. PCIe passthrough requires a dedicated GPU, or SR-IOV support which GPU vendors have mostly restricted to enterprise models. However… of course a better way was possible! Rob Clark presented DRM native contexts at XDC 2022: this approach essentially paravirtualizes the kernel-space GPU driver, letting the guest submit hardware-specific commands that the host would run in separate contexts (relying on the same separation as between programs on the host). That’s the approach that was picked up by the Asahi Linux project for gaming because of the amazing performance it allows for, but it’s also intended to be a stronger security boundary due to providing way less attack surface on the host (it’s all I/O management rather than implementing complex APIs).

So, was it possible to take all of this technology and use it? Well… it required quite a bit of debugging and fixing everywhere – but that’s exactly why I joined! So far I’ve discovered that:

the rutabaga_gfx integration in QEMU (which was the thing we tried to use initially) and other C consumers was broken with the latest versions due to an ifdef mistake (fixed)
it’s not documented everywhere that kernel >= 6.13 is required to be able to touch AMD GPU memory from KVM guests in any way
Sommelier was assuming Chromium OS kernel patches and misinterpreting ioctl responses on regular mainline Linux
libkrun’s internal version of rutabaga_gfx contained a tiny strange API modification incompatible with Sommelier/proxy-virtwl and didn’t handle memfd seals (fixed)
RADV (Radeon Vulkan driver in Mesa) only recognized PCI devices including for virtgpu, ignoring the virtio-mmio setup used by libkrun (fixed)

And we’re continuing with more work in this area.

D-Bus / XDG Desktop Portals

Application isolation is great, but completely isolated applications tend to have limited usefulness. That’s why we’re also integrating desktop portals that Flatpak uses —at least the file-opening / document portal— into the microVM-based platform.

The sidebus project is inspired by Spectrum’s setup for using the document portal with virtiofs to dynamically expose chosen files to the guest, using vsock as the D-Bus transport. It is based on the busd broker library, and uses the portal frontend on the host for perfect integration with arbitrary desktop environments.

With the switch to libkrun however, we are looking at the possibility of making the Camera and Screencast portals working, with full hardware acceleration – by switching to virtgpu cross-domain as the transport instead of vsock. Currently libkrun already has added some PipeWire support to its copy of rutabaga_gfx, however that’s fixed to one system-wide socket. How these portals work is that for every request they pass a new restricted PipeWire remote socket over D-Bus. So we’re looking to make rutabaga’s cross-domain sockets more generic, to be able to just pass through that whole chain of file descriptor passing.

(And yes, lots of people are worried about PipeWire attack surface — it’s definitely possible to mitigate that with a proxy on the host that would only allow a small validated subset of the PipeWire protocol.)

Conclusion

We’re looking to finally make a peer-to-peer community software platform that’s competitive with commercial ones in terms of security, usability and convenience. If you want to try it out now, you can! Just follow the installation instructions on our munix project. Note that it’s still actively being developed, so if you find any issues, please open up a bug report!

The Road Towards a NixOS UI

Mon, 22 Sep 2025 10:08:10 +0200

We recently attended NixCon 2025 in Switzerland 🇨🇭 where we provided an early look at our shiny new user interface for interacting with your Clan 🎉🎉.

UI 2.0

Featuring new and improved workflows, a fresh set of components and a 3D-rendered orthographic overview, the latest version of the UI not only looks better, but it feels better.

Whilst it’s still a work in progress, we’re excited to start sharing it with the community and start getting your feedback.

If you came across our booth 🔨🔨🔨 you might have already seen it in action.

Yes, those are real hammers…

@Kenji and @Qubasa also gave a talk, The Road Towards a NixOS UI, in which they gave a demo of the new UI in action and explained how it was made possible thanks to the many building blocks we have been developing over the past few years.

For those who couldn’t make it to Rapperwsil, you can watch a recording of the talk below.

If you would like to try Clan for yourself, have a look at our docs. To contribute, check out our gitea. And if you need help or just want to chat, come say hi 👋 in our matrix channel.

Why NixOS Modules Need Two JSON Schemas

Thu, 18 Sep 2025 09:11:39 +0200

Why NixOS Modules Need Two JSON Schemas

In our previous blog posts, we explored a techinque that extracts interfaces from NixOS modules and converts them into JSON schemas. This enables building GUIs and APIs that can shallowly validate NixOS configurations without running Nix itself. Our second post explored the broader challenge of maintaining type-safe interfaces across polyglot architectures - specifically how to share consistent data models between Nix, Python, and TypeScript in the Clan project’s tech stack.

The New Discovery

While implementing these JSON schema-based types/interfaces in production, we discovered a subtle but important issue: we actually need two different JSON schemas for each NixOS module, not just one.

When using JSON Schema for type validation at build-time and runtime, the approach proved surprisingly stable for building our tech stack. However, we noticed subtle usage differences that create unnecessary complexity.

The issue stems from how the NixOS module system behaves as a transformation layer. While one might expect that input configuration equals output configuration (since the module system is a fixed point), there’s a notable difference that causes unnecessary type guarding when consuming or producing data.

An example:

{
   options.foo = mkOption {
       type = types.anything;
       default = 42;
   };
}

(Types in CUE lang )

Schema	Purpose	Example
Write	What user/program provides	`foo?: _`
Read	What module system guarantees	`foo: _`

This difference is inherent because the module system applies defaults, merges, does coercions, and normalization. That turns a potentially partial configuration into a total one.

This subtle difference causes unnecessary type guards in our Python code currently.

For example

foo: Foo = read_data()

# Unnecessary typeguard
# Because foo cannot be be None in the `read`-schema
if foo is not None:
     # Do something with foo
     pass

The same goes on for the whole stack. I.e the Typescript frontend also suffers from the same problem. As well as everything that calls the API’s in a typesafe manner.

We use only the write format for everything. which is safe because it is possibly a supertype of the read format. Supertype here just means “more permissive”, it accepts more inputs than the read schema.

I need to put more research into the question of which option types are strict supertypes, which would allow us to utilize that property of the system.

This is a non-trivial question because it ties into how the module system’s types work and requires verifying every option type that exists or some property about option types.

Another example: lib.types.coercedTo A to B, which transforms the value into another value. This can be represented as:

Schema	Purpose	Example
Write	What user/program provides	`foo?: A \| B`
Read	What module system guarantees	`foo: B`

In type-theory terms, this means the read schema is a subtype of the write schema. In practice, this gives us two big wins.

We could either formally prove this for all types, or restrict our usage such that this is always true, so we gain the following:

(a) Safe round-tripping

Any resolved configuration (read) is also valid input (write). That means we can:

serialize the read config,
feed it back into the module system as input,
and get the same or equivalent resolved config.

This is valuable for reproducibility, migration tooling, and debugging.

If read were not a subtype of write, round-tripping would break. We could resolve a config, but not be able to reapply it as input without errors.

(b) Compatibility & stability checks

We can turn read ⊑ write into a CI invariant:

If we change module options, we check whether the new read schema is still a subtype of the old write schema.
If yes; no breaking change for existing configs.
If no; flag it as breaking change. That’s a strong formal guarantee that configuration evolution won’t silently invalidate existing setups. This is a possible future idea.

What if not a subtype?

If read is not a subtype of write, then:

Developers are still safe, they always rely on read or write only.
But we lose our important round-tripping: some values you get from the system can’t be expressed as valid inputs.
We also lose version compatibility checks: breaking schema evolution can’t be detected so easily anymore.

In practice, that would mean more ad-hoc checks and possibly more subtle breakages when integrating different stacks.

Practical takeaway

We should start exporting two schemas, to more closely represent the nature of the system:
- Ensure that all consumers see consistent, reliable types, that closely represent the data.
Always use read schema for reading; For Python developers this means they can drop some type guards and possibly other noise.
If we enforce read ⊑ write we gain important ergonomics:
- We can safely serialize/reserialize configs (roundtrip property).
- We get a cheap and strong compatibility invariant for free.
- We can trust read values as valid inputs everywhere.

Outlook

types.deferredModule breaks with the round-tripping property entirely.

But in clan we use these in a couple of api-facing places. In the next post, I’ll dive into this case and show how I built a solution to restore those properties and make deferred modules api-usable.

Clan + macOS

Tue, 09 Sep 2025 16:44:44 +0200

Over the last year, we’ve been progressively adding macOS support to Clan. This began with sticking a M4 Mac mini in a basement to run all of our builds and test suite. In the beginning, we couldn’t manage this Mac using Clan so we created a repo separate to clan-infra and used nix-darwin directly to configure the machine.

After a while, we started to notice that the GUI and CLI would periodically stop working on macOS as breaking changes would accumulate as the majority of the team runs Linux. So we decided that it was time to actually put the Mac mini to work by configuring it to build the GUI, CLI and all the tests on every PR to ensure they work on macOS as well.

At this point, the CLI ran and worked well on macOS allowing you to deploy to NixOS machines using the clan machines install and clan machines update commands.

However, we wanted macOS machines to be first-class Clan members, with software, settings, and secrets managed declaratively like Linux, so we began adding nix-darwin support to Clan.

What is nix-darwin

nix-darwin is a framework that uses the module system from NixOS to manage macOS, allowing you to bring the reproducibility and declarative power of Nix to macOS.

Clan automatically imports a core set of modules into all machines to provide features like remote deployment and vars. These modules were written specifically for NixOS, but are necessary to make Clan useful on macOS and other systems so we needed to extend them.

multi-OS modules

The NixOS module system has been made into a library and is now used in nix-darwin, Home Manager and other Nix-based projects. To keep a module from being loaded by the wrong module system, authors should set the _class attribute to nixos or darwin.

We could extend the core Clan modules to support macOS by duplicating all the code for nix-darwin, however this would lead to a lot of extra maintainence burden. So instead we decided to make modules that support both NixOS and nix-darwin.

Previously, detecting which module system you were in required hacks like options ? virtualisation which works due to the virtualisation option tree existing only in NixOS and not nix-darwin:

{ options, config, lib, ... }:
{
  config = lib.optionalAttrs (options ? virtualisation) {
    # NixOS specific configuration
  };
}

This hack does not work inside of imports meaning you are not able to do conditional imports:

{ options, config, lib, ... }:
let
  nixosModule = { ... }: {
    # NixOS specific configuration
  };
  darwinModule = { ... }: {
    # nix-darwin specific configuration
  };
in {
  imports = [
    (lib.optionalAttrs (options ? virtualisation) nixosModule)
    (lib.optionalAttrs (options ? launchd) darwinModule)
  ];

  config = {
    # shared configuration
  };
}

This led to me making my first ever PR to improve the module system, which added _class to the module arguments allowing conditional imports based on the module system class:

{ _class, options, config, lib, ... }:
let
  nixosModule = { ... }: {
    # NixOS specific configuration
  };
  darwinModule = { ... }: {
    # nix-darwin specific configuration
  };
in {
  imports = [
    (lib.optionalAttrs (_class == "nixos") nixosModule)
    (lib.optionalAttrs (_class == "darwin") darwinModule)
  ];

  config = {
    # shared configuration
  };
}

This means you can now write modules that support multiple module systems without needing to rely on hacks.

Using this new feature, we have added vars and deployment support to nix-darwin machines managed by Clan.

If you’d like to try it out, you can check out our macOS guide.

Networking

Thu, 28 Aug 2025 00:15:00 +0200

(For a more dry and technical explanation, check out the networking docs at https://docs.clan.lol/main/guides/networking/networking/)

Every now and then people ask me, what is the best overlay network/VPN? And each time I give them a long and sad answer: that all of them have different tradeoffs and there’s no one size that fits all.

Here’s a quick idea of what I mean:

(This table is subjective, but is here to make a point)

VPN	Pros	Cons
tailscale	works pretty well	single point of failure, controller needs to be online
tinc	no central server needed, local peer discovery	sometimes unreliable, questionable maintenance
zerotier	no public server needed, continues working if controller is down	BSL, single point of failure (controller), relying on 3rd party servers
tor	no central server needed, anonymous (probably)	no UDP, slow
mycelium	no central server needed	unreliable
yggdrasil	reliable (if setup right)	hard to setup, no local peer discovery
wireguard	fast, native kernel support	no auto peering, no TCP fallback

There are some more VPN solutions that I haven’t tried yet, but there is no ultimate solution and each comes with certain pros and cons. For this reason we have built a network abstraction into Clan that will choose the best network for all the actions you want to run on a remote machine.

How it works

First, you must enable a network-capable Clan Service. At the time of writing, there are only two (because I’ve been too lazy to add more): tor and an internet service. The tor service connects through the Tor network to a hidden service running on the target machine. The internet service requires manual configuration of IP addresses.

Lets look at an example:

...
  inventory.instances = {
    tor = {
      roles.server.tags.nixos = {};
    }
  }
...

This would enable the tor service on all nixos machines.

A network is then exposed with a priority and an attribute set of peers into the global flake, which you can examine with the following command:

clan select 'clan.exports.instances.*.networking.{priority,peers}'

The output should look something like this:

{
  "blabla": {}
  "tor": {
    "priority": 10,
    "peers": {
      "my_cool_machine": {
        SSHOptions": [],
        "host": {
          "var": {
            "file": "hostname",
            "generator": "tor_tor",
            "machine": "my_cool_machine"
          }
        },
        "name": "my_cool_machine"
      }
    }
  }
}

You can see the default priority of 10 and a list of peers corresponding to your machines.

A host entry can either be a plain value or a var (as above) which gets decrypted on demand when used. We do this to prevent our Tor hidden service hostnames from being exposed publicly

NOTE: If you install a machine after enabling the tor service you will have to manually update the machine with --target-host one last time, after which the tor vars for that machine will to be generated and deployed.

You can try out the new networking with:

clan ssh my_cool_machine

This should log you into the target machine via Tor (or something faster if you have another network configured). If you have no Tor daemon running on your system, it will start one for the duration of the connection (thats pretty rad).

The JSON output from the clan select command earlier is a bit annoying to type and the output a bit hard to read, so for this reason we built a nicer interface for interacting with networks:

clan network list

This prints a list of all the networks you have configured. For our test case it would look like this:

Network       Priority  Module      Running   Peers
---------------------------------------------------
tor           10        tor         No        my_cool_machine

(This is only cool with multiple networks).

We can now have multiple networks configured and let the Clan cli decide on the best way to reach our machines via those networks from our admin machine.

What is still missing?

Sadly, a lot. Here is a short list of the top of my head:

Currently only works for admin -> machine connections. Ideally we want them for machine <-> machine connections as well
More network modules like mycelium and zerotier
Userspace networking, like the Tor daemon with on-demand starting. We want to have the same behaviour for all kinds of networks.

There’s likely more features I can’t think of which are missing, so stay tuned for more networking related blogposts in the future :)

nix-unit

Tue, 08 Jul 2025 08:00:00 +0000

When building robust Nix-based systems, testing your evaluation logic becomes crucial. Especially since the module system is flexible and can be used in many ways. One of the ways we test our Nix logic is nix-unit.

What is nix-unit?

nix-unit is a testing framework specifically designed for testing Nix expressions. It’s design makes it ideal to test pure functions, module system configurations and even more complex evaluation logic. It scales well and is fast.

Some notable features:

Fast feedback loops: Tests run at evaluation time, not build time.
Pure function testing: Perfect for testing Nix library functions.
Assertion Based Testing: The expression that is expected can be directly declared in Nix.
Diff Integration Diff integration on error failure makes spotting errors very quick.
Testing errors: Is able to tests and assert on evaluation errors. It can test failures individually, even if the failure is caused by an evaluation error.

The above features are some of the reasons we use it to test our infrastructure on various granularities. Let us look into how a basic test structure would look like.

Basic Test Structure

A nix-unit test is a Nix attribute set, that has an expression that should be tested (expr) and it’s expected outcome (expected). The name of the attribute set should be prefixed with test.

{
  test_answer = {
    expr = builtins.add 40 2;
    expected = 42;
  };
}

We can now also test error cases.

{
  test_error = {
    expr = throw "10 instead of 5";
    expectedError.type = "ThrownError";
    expectedError.msg = "\\d+ instead of 5";
  };
}

Notice how the error message even has regex support?

Grouping

The expressions can be directly declared in Nix and we can test nested attribute sets. This means grouping of hierarchical tests has a good UX.

{
  feature_1 = {
    test_bar = {
      expr = "bar";
      expected = "bar";
    };
  };
  feature_2 = {
    test_foo = {
      expr = "foo"
      expected = "foo";
    };
    test_foo_set = {
      expr = { x = "foo"; };
      expected = { x = "foo"; };
    };
  };
}

Here we test 2 different features, one which has 1 test and one feature which has 2 tests.

Interactive debugging

Since nix-unit tests Nix expressions in an attribute set, we can use the default Nix repl to evaluate and inspect the tests Interactively.

If we have our first test in a file called answer.nix:

$ nix repl
Nix 2.29.1
Type :? for help.
nix-repl> test = import ./answer.nix {}

nix-repl> test
{
  test_answer = { ... };
}

nix-repl> tests.test_answer.expr
42

nix-unit is fast, flexible and has good UX.

Integration with CI

While nix-unit on its own is a valuable tool, a project might want to integrate such functionality into it’s CI pipeline.

To make this seamless we need to evaluate Nix inside the Nix build sandbox. Or in other words nix-unit should be wrapped inside a derivation.

This has mainly two benefits:

When we have a Nix based CI, we can build it anywhere leveraging Nix’s determinism.
We can cache the derivation if there are no changes to the test, or the base logic. Meaning we don’t need to re-run the tests.

To make this work is non-trivial and when we originally started using nix-unit we hooked everything up manually.

But now nix-unit exposes a flake-parts module, which does this integration for you.

Integration with flake-parts

Why would you want to integrate with flake-parts?

In addition to creating a wrapped derivation of nix-unit, it allows to structure your flake in a more composable way. The tests and logic can both be part of a module, meaning the tests live where the module lives. In a larger codebase your tests are now more discoverable and the proximity to the logic makes them easier to maintain.

You can do it too

Here are the steps required, if you want to try it out yourself:

Have a flake with flake-parts
Add nix-unit.url = "github:nix-community/nix-unit"; to your inputs
Create a tests.nix file with the following content:

{
  flake.tests = {
    test_answer = {
      expr = builtins.add 40 2;
      expected = 42;
    };
  };
}

Add the test file and the flake-parts module to your imports:

imports = [
    inputs.nix-unit.modules.flake.default
    ./test.nix
];

And now you can test your functions and logic to your hearts content!

The test will be automatically added to the checks attribute running the tests when you run nix flake check.

Clan + Yubikeys

Fri, 16 May 2025 08:00:00 +0000

All I wanted was to test Data Mesher… 🙃

I had done some local dev testing and created a NixOS module with some VM tests. Pinpox had helped write the Clan module and added some more Clan-specific VM tests. We were ready to start testing this in a real Clan.

Until this point, I wasn’t running Clan. I had always meant to convert, but just never got around to it. So this was as good a reason as any. I fired up the docs, opened up my config and got to work.

But it wasn’t long before I hit a few problems.

Multiple User Keys

I’m a long-time user of SOPS via sops-nix for managing secrets within NixOS configurations, and I like to use it in combination with Yubikeys via AGE plugins. Clan can also use SOPS for secrets management, but it deviates in one important way.

Unlike with SOPS where you configure keys in a .sops.yaml file, Clan takes a more active role in how SOPS keys are configured, introducing concepts like users, groups, and machines. And at the time, the user model didn’t allow for more than one encryption key.

Why is this important?

Well, to protect against loss or failure of a Yubikey, I use more than one. And, just in case they’re all lost or broken, I also use a vanilla age key backed up on paper or in a password manager. Ordinarily, this isn’t a problem with SOPS. But with Clan, it was a non-starter.

So I added support for it. ✅

Age Plugins

Having taken care of multiple user keys, I next found myself dealing with some issues related to AGE plugins.

The first was easy enough to fix, ensuring the Clan CLI was loading any necessary AGE plugins when decrypting with SOPS. I added some packages to an allowlist, tweaked the shell being used when invoking SOPS and added an option allowing a user to specify the plugins they require in their Clan:

{
  inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
  inputs.nixpkgs.follows = "clan-core/nixpkgs";

  outputs =
    { self, clan-core, ... }:
    let
      clan = clan-core.clanLib.buildClan {
        inherit self;

        meta.name = "myclan";

        # Add Yubikey and FIDO2 HMAC plugins
        # Note: the plugins listed here must be available in nixpkgs.
        secrets.age.plugins = [
          "age-plugin-yubikey"
          "age-plugin-fido2-hmac"
        ];

        machines = {
          # elided for brevity
        };
      };
    in
    {
      inherit (clan) nixosConfigurations clanInternals;

      # elided for brevity
    };
}

Recovering Recipients

The second issue required a bit more thought, as it turns out there is no uniform mechanism for recovering the recipient (public key) from a secret key generated by an AGE plugin.

It’s important we can do this because the Clan CLI implements a safety check when creating or updating a secret. If the recipient associated with the currently configured AGE private key is not in the list of recipients when encrypting a secret, we add that recipient to the list.

This helps ensure you do not encrypt a secret which you cannot decrypt.

With vanilla AGE keys this isn’t a problem, since you can recover the recipient with a simple age-keygen -y. But for AGE plugins, we ended up with a workaround in which a user needs to prepend a comment with the recipient key.

For example, this is what your ~/.config/sops/age/keys.txt might look like:

# public key: age1zdy49ek6z60q9r34vf5mmzkx6u43pr9haqdh5lqdg7fh5tpwlfwqea356l
AGE-PLUGIN-FIDO2-HMAC-1QQPQZRFR7ZZ2WCV...

For each private key in this file, we look at the preceding line for a comment containing a recipient of the form age1xxxx. The rest of the line doesn’t really matter. You can prefix it with public key:, recipient: or whatever else.

AGE plugin support: ✅

Success?

By this point, I began porting my configuration over to a new repo I had set up for Clan. I added an initial user key based on age-plugin-fido2-hmac and began fleshing out the configuration for my main desktop machine.

After a while, I remembered that I should add a couple more keys to my user, including my backup key. No big deal, just a simple clan secrets users add-key brian age1xxxxxxx right?

It just keeps asking for my PIN…

Vars + age-plugin-fido2-hmac = Pain

When adding a new user key, under the hood the Clan CLI is making a call to sops updatekeys. As part of the updatekeys process, sops needs to decrypt the underlying value to then encrypt it for the key we are adding. Nothing unusual so far.

The sting in the tail comes when you understand how Vars organises secrets on the filesystem: one file per secret.

This is in stark contrast to how I had been using sops previously, where I typically grouped a number of secrets into the same file on a per-host or a per-user basis. But where’s the problem you might be asking?

age-plugin-fido2-hmac has no form of PIN caching.

For each decryption I have to enter my PIN and touch my Yubikey. And as you can imagine, any non-trivial setup is going to have more than a handful of secrets. When you also consider this needs to be done for shared secrets as well as for each machine’s secrets 😢…

Actual footage of clan secrets users add-key brian age1....

If I had stayed with age-plugin-fido2-hmac, adding a new user key would have been prohibitively expensive and a short path to some form of repetitive strain injury. I could have used a key which didn’t require PIN entry, but I wasn’t comfortable with that.

In the end, I moved to age-plugin-yubikey, as it supports PIN caching and can also be configured to cache presence checks (up to 15 seconds). There is still an issue with pcscd aggressively powering off my yubikey after 5 seconds and ruining the PIN caching, but for day-to-day usage with Clan it works well enough for now.

PIN caching: ✅

Terminal Multiplexing

By this point, having side-quested long enough, I was feeling like I was on the home straight. But there was one last curveball, which at the time of writing, we still don’t have a good solution for: PIN entry when deploying to multiple machines at once.

When you run clan machines update, the Clan CLI will perform the update process concurrently for each machine in your configuration and blend their terminal outputs into one. This becomes a problem when each one of them may ask you to enter a PIN to unlock your Yubikey.

concurrent deployment during clan machines update

Whilst annoying and suboptimal, this isn’t necessarily a show-stopper for small Clans; it just means you have to update machines individually.

Longer-term, we’re still kicking around a few ideas. For example, it would be nice if age plugins could be configured to ask for pin entry using something like ssh-askpass.

Concurrent PIN entry: ❌

Summary

It took me longer than I would have hoped to just run Data Mesher in a Clan of my own 😂, but along the way there have been some much-needed improvements to Clan itself and, for me personally, I’m left with a much better understanding of age, Yubikeys and sops.

We will continue to look at ways of improving Yubikey integration with Clan.

And in the meantime, please bear in mind there are still a few rough edges 🙏.

How to Democratise DevOps

Sun, 06 Apr 2025 21:25:04 +0700

Computers only became mainstream when interfaces borrowed from the analog world. Suddenly, people weren’t staring at cryptic command lines, they had “desktops”, “folders”, and “recycle bins”. Familiar metaphors turned, that digital complexity into something intuitive. They made digital complexity feel natural.

Design makes a product understandable. It slices through complexity and making things click. But what if what you’re designing is buried deep - abstract, technical and invisible to almost everyone?

That is the challenge we face at Clan. How do we design infrastructure and networking concepts in a visual application so that they are not only understandable but truly usable by anyone?

To develop a further sense of legacy interfaces and their calmness visit toastytech.com

Macintosh in 1984 and a screenshot of the Note Pad application

A strong metaphor unlocks a mental model, which is the blueprint of every truly intuitive user experience. Because here is the truth: Without it, even the best tools feel like black boxes.

So where do we find ours? To design the how, we need to understand the why. Why are we building Clan? And why do we want to democratize networking through an application?

The digital world has drifted apart

Because the digital world has drifted off course. Our devices have become closed boxes. Platforms addict and manipulate. Social media fractures societies and AI is blurring the line between real and fake by the day.

The original promise of computing was a different one. When the machines entered our homes, they invited tinkering. You had to understand how they worked. You had to code. The barrier to entry wasn’t hidden, it was the whole point.

The age of the internet

Then came the internet: A wave of openness where content flowed freely. Industries were disrupted and subcultures found one another. There was magic in that beginning.

Today the internet is a never-ending ad. Everything is tracked. Everyone is categorized. The internet overwhelms. The global community is a dead-end, leaving people drained, disoriented, and empty. Idealized images, outrage, surveillance, burnout.

So what do we do? We take back the computer! We stop being just users, and start being makers again. Not with likes, but with ideas. With uncertainty. With a bit of beautiful chaos.

A quiet revolution. From the inside.

A quiet revolution

We reclaim the machine. We understand it. We use its building blocks to shape spaces of our own, digital enclaves outside the reach of the algorithmic hive mind.

That’s why we’re building Clan: to make room for a better digital society.

A better digital society

And here’s the metaphor at the heart of our mission: Computers are like houses. You build them. Connect them. Neighborhoods form. Villages grow. Cities emerge. Societies take shape.

Inspired by games like SimCity, we use the metaphor of a digital city to represent networks and infrastructure. But this isn’t a simulation! It’s real, deployed architecture! It’s not just about designing, it’s about actually building, managing, and maintaining technical systems.

At its core, our visual tool is a network simulation game with real technical infrastructure behind it. This is how we make complex systems understandable: playfully, visually, tangibly.

Clan’s Darknet Builder with already created machines

A more advanced build of a network and its respective machines

Some details of Clan’s Darknet Builder UI

It’s our way of rethinking networks and infrastructure and inviting everyone to become the architect of their own digital world!

This is the Darknet Builder by Clan.

That’s how we make complexity understandable. That’s how we democratise DevOps.

Time to architect.

Vars: A framework for managing secrets and computed values

Mon, 24 Mar 2025 21:25:04 +0700

The problem

Deploying NixOS machines is often not a one-click experience. Even when re-using existing NixOS configurations, there is usually some machine specific initialization overhead that needs to be dealt with manually. Machine IDs need to be generated, passwords set, and ssh key pairs generated, to name a few examples.

None of that is very satisfying as an admin, and it is definitely a problem for clan, where our goal is to enable non-technical people to administer NixOS machines by automating away as much as possible.

The current state

Let’s go through the options a NixOS admin currently has.

If secrets are entered or generated on the target machine directly, they become part of its state which means they are either gonna be lost upon re-deployment to new hardware, likely messing up authentication between hosts, or they need to be backed up and restored carefully. Both resembles overhead.

To circumvent that problem, as of now, admins would use tools like sops-nix or agenix to store and re-deploy secrets securely. But even this introduces manual initialization overhead, as secrets need to be generated manually, then copy and pasted between tools.

No matter which of the above strategies is used, admins cannot simply enable a NixOS module that requires a secret without manual interaction. How a secret needs to be generated exactly, is not part of the NixOS module’s definition, so it cannot possibly be automated as of now.

The journey

We wanted to solve this problem, which is why we developed a NixOS based framework for secrets and other computed values, that allows module maintainers to declare how such values need to be generated, instead of offloading that work to the admins.

We have iterated on our solution several times already, going from imperative tooling, through our first module system based approach called facts, to our current solution which we call vars as in ‘variables’.

During this journey we hit a lot of road bumps and learned quite a few things on what is needed to generate, store, manage and share secrets between machines seamlessly.

The clan developers as well as some power users of our community have been using this framework already for several months now. While we are still working on some improvements, we think it is ready to be shared and tested more extensively by the community

Core Concepts of `vars`

Before we jump into examples, here an overview about our core concepts

Secret/Public:
Some generated values need to be stored encrypted, like for example ssh private keys, while others should be world readable, like public keys.

Generators:
Vars (either secret or public) are computed by generators. Generators are scripts which take some input and produce files.

Stores:
Similar to how nix derivations produce files which are stored in the nix store, vars generators produce files which are either stored in a public or secret store. A generic store interface allows swapping out the store. For example, users can choose to store their secrets either in sops-nix or password-store, or even bring their own store.

Prompts:
Some secrets require input from the user before they can be generated. If, for example, a password hash needs to be generated, the user has to enter the password first. As everything else, prompts are declarative, and different frontends, like CLIs or GUIs can be built in order to prompt the user.

Sharing:
Some vars need to be shared between machines. An admin might choose, for example, to re-use their github api key across several machines, instead of generating a new one for each. If the key changes, it should be changed on all machines simultaneously.

Dependencies:
Vars can depend on each other, as in if one secret changes, others have to be updated as well, one simple example being a public key, that is derived from a private key. The dependency system ensures that secrets across the fleet remain in sync and also allows re-rolling the secrets easily without having to worry about forgetting to update something.

Example

In this example, a vars generator is used to:

prompt the user for the password
run the required mkpasswd command to generate the hash
store the hash in a file
set users.users.root.hashedPasswordFile to reference that file

{config, pkgs, ...}:
let
  vars = clan.core.vars;
in
{
  # The vars definition
  clan.core.vars.generators.root-password = {
    # Prompts the user for a password
    # (`password-input` being an arbitrary name)
    prompts.password-input.description = "the root user's password";
    prompts.password-input.type = "hidden";
    # Defines an output file for storing the hash and declare it as non-secret
    files.password-hash.secret = false;
    # Defines the logic for generating the hash
    script = ''
      cat $prompts/password-input | mkpasswd -m sha-512 > $out/password-hash
    '';
    # Tools required by the script
    runtimeInputs = [ pkgs.mkpasswd ];
  };

  # Sets the root password to the file containing the hash
  users.users.root.hashedPasswordFile =
    # Clan will make sure, this path exists at runtime
    vars.generators.root-password.files.password-hash.path;
  # Users need to be immutable, otherwise updating a password might be ignored
  users.mutableUsers = false;
}

As one can see, the vars generators definition is part of the normal NixOS configuration.

In this NixOS module, the root user’s hashedPasswordFile is set to a, yet to be created path which will contain the generated password hash.

A wrapper around nixos-rebuild switch ensures that this path will be created before the machine is deployed.

More Examples

To find more examples, just take a look at the existing clan modules of which several are using vars already, for example the sshd module which sets up a certificate authority to certify ssh host keys across all machines. Never have ssh based scripts stuck again because of having to type in yes to trust the host.

Future work

Service oriented design

As seen in the example above, vars are currently defined inside a machine’s NixOS configuration. While this design choice is nice in terms of compatibility, some interactions become more complex, like defining global vars across all machines. In the worst case, several machines would have to be evaluated in order to update vars reliably across the infrastructure.

We want to add vars support to the clan inventory which improves the UX and performance to manage infrastructure overarching settings.

Upstreaming the framework

We believe vars can be quite beneficial for any NixOS user and therefore want to upstream as much of it as possible. In fact, a first draft PR has been opened by @lassulus a while ago.

VPN Benchmarks Part 1

Fri, 07 Mar 2025 00:08:10 +0200

Which VPN technology really stands out? How efficiently does it scale, and how does it perform under poor network conditions? These are the questions that arise when faced with the endless array of VPN options—yet hard data remains scarce. Often, if you ask around, you’ll hear someone say, “I tried $VPN and it works perfectly for me,” while another retorts, “But it kept crashing for me during $vacation.”

Well, I say enough with this hearsay! It’s time to move beyond anecdotal evidence and start benchmarking. Let’s establish a fully automated, reproducible testing approach so that we can clearly track improvements over time.

At least, that’s our goal. I’ve begun implementing the vpn-benchmark using the Clan Python API (which isn’t stable right now) in combination with the cloud API abstraction opentofu - the open source equivalent of Terraform. With this setup, a user simply needs to execute:

  nix shell git+https://git.clan.lol/Qubasa/vpn-benchmark.git#vpn-bench --refresh

To get a shell that includes our package, vpb. Within this shell, you can run the command vpb create to automatically launch Hetzner Cloud machines for benchmarking. These machines are provisioned with a generated SSH key. The tool accomplishes this by defining a user_data section within our opentofu script, which contains a YAML configuration string. This format is standardized across cloud vendors and documented at cloudinit.readthedocs.io.

However, there was one issue. When logging into a Hetzner machine for the first time, a prompt appears asking the user to change the root password. Normally, adding an SSH key to the machine disables this prompt—but due to a bug, the prompt persists when the SSH key is deployed through the user_data section. Fortunately, the user_data configuration also allows us to change user passwords, which effectively resolves this problem.

resource "hcloud_server" "servers" {
  for_each = { for server in var.servers : server.name => server }

  name        = each.value.name
  server_type = each.value.server_type
  image       = var.os_image
  location    = each.value.location

  # This is the cloudinit config
  user_data = <<-EOF
    #cloud-config
    ssh_authorized_keys:
      - ${join("\n  - ", var.ssh_pubkeys)}
    ssh_pwauth: false
    chpasswd:
      expire: false
      users:
      - {name: root, password: Sahb7pied8, type: text}
  EOF
}

Nextup a user can execute vpb install this is where the Clan magic happens. We create a temporary Clan inside the ~/.local/share/vpn_bench/clan folder, and then create a dynamic amount of machines inside that Clan.

With the power of nixos-anywhere, we can transform any pre-installed Linux OS into our own NixOS-based system. In addition, nixos-facter generates a hardware report to ensure that all necessary drivers are included—without any user interaction. If you’re interested in the code, check out the install.py file in our repository: install.py.

Once the infrastructure is in place, executing vpb bench initiates a suite of benchmarks across all supported VPN technologies. For more targeted testing, users can specify a particular VPN with vpb bench --vpn <name>. This command triggers a clan machine update process behind the scenes, leveraging Clan’s Inventory system to dynamically configure each machine in the test network.

Clan’s Inventory system is the secret sauce that makes this all possible. It provides a programmatic interface to define which services and Nix modules should be enabled on each node in our distributed benchmark environment. Because the Inventory is fully JSON-serializable, our Python code can easily manipulate configurations on the fly, enabling us to test multiple VPN setups with varying parameters in a single automated run. This approach ensures consistent, reproducible results that can be tracked over time, finally giving us objective data to evaluate VPN performance claims.

To then visualize the data a user can execute vpb bench this will build a static website with Nix and serve it over http once compiled.

The current testing methodology is fairly basic, only using iperf3 to benchmark throughput and packetloss. However in the upcoming weeks we plan on extending this, to test things like packet delay, packet reordering, node failures and of course more VPNs.

One thing one has to look out for is the fact that cloud VMs could share a network card with a noisy neigbhour generating lots of traffic and thus skewing the results. But that case should be fairly obvious to spot when looking at the ground truth benchmarks that are not using any kind of VPN.

An interesting finding from our preliminary tests revealed that UDP throughput between VMs was significantly lower than TCP throughput in the baseline tests. This counterintuitive result likely stems from Hetzner’s UDP traffic throttling within their NAT infrastructure. One approach to circumvent this limitation could be implementing tests using the QUIC protocol, which might be whitelisted due to being a webstandard.

For now that’s how far the project is, please note that it’s not yet ready to be used.

Cheers!

nix-select

Mon, 17 Feb 2025 00:08:10 +0200

Find it at: https://git.clan.lol/clan/select

Do you find accessing values from lists cumbersome? Is builtins.elemAt bringing you down? What about filtering nested dictionaries for specific keys?

For this reason, we hacked together an unmatched selection experience. It is written in pure Nix, without dependencies, to make your life 100% more “selectful.”

To use nix-select with the clan CLI, just run clan select.

Prominent features include:

Globs: *
{a,b} (set-based selection)
.0 (index-based access)

Example using the Clan CLI:

clan select 'nixosConfigurations.*.config.clan.core.vars.generators.*.files.*.{path,secret}'

This will print all variables defined in your Clan.

Here’s the equivalent non-selectful expression:

builtins.mapAttrs (
  _: v0:
  builtins.mapAttrs (
    _: v1:
    (builtins.mapAttrs (
      _: v3:
      builtins.intersectAttrs {
        path = { };
        secret = { };
      } v3
    ) v1.files)
  ) v0.config.clan.core.vars.generators
) nixosConfigurations

clan select also uses a transparent caching technique, so running the same command again will be significantly faster.

There are many more operators and constructs supported in nix-select, all of which are documented in the README.

Usage Without Clan

You can also import our 100% pure Nix library and use it directly in your project today!

To use it inside any nix repl:

nix-repl> select = (builtins.getFlake "github:clan-lol/select").lib.select

With this, the select function can be used by simply passing it a query string and an attribute set or list:

nix-repl> select "*.config.networking.hostName" nixosConfigurations

The query language is intentionally designed to be compatible with the Nix grammar, so it might be possible to extend the Nix expression language to improve ease of use.

This project was developed during Thaigersprint 2025.

Providing Type-safe interfaces between NixOS and other languages

Wed, 11 Sep 2024 09:08:10 +0200

When building a consumer-facing project on top of NixOS, one crucial question arises: How can we provide type-safe interfaces within a polyglot software stack?

This blogpost discusses one method for creating type-safe interfaces in a software stack by using JSON-schema to maintain consistent models across layers of an application.

Within the clan project, we explored one possible solution to this challenge. Our tech stack is composed of three main components:

Nix: Handles the core business logic.
Python: Acts as a thin wrapper, exposing the business logic through a convenient to use CLI and API.
TypeScript: Manages the presentation and GUI layer, communicating with Python via an API.

This architecture is a product of our guiding principles: We aim to encapsulate as much business logic as possible in pure Nix, ensuring that anyone familiar with Nix can utilize it.

The Challenge of Polyglot Architectures

Throughout the lifecycle of an application, architectural models, relationships, and fields are typically refined and improved over time. By this, I refer to constructs such as classes, structs, or enums.

These elements are often required across multiple layers of the application and must remain consistent to avoid discrepancies. Logically, maintaining these models in a single location is crucial to prevent discrepancies and eliminate a common source of errors — interface inconsistencies between software components.

This approach can save significant time during development cycles, particularly in dynamically typed environments like Nix and Python, where errors are often caught through extensive unit testing or at runtime when issues arise.

The Nix language presents a significant challenge due to its untyped and dynamic nature. Combined with NixOS, a constantly evolving collection of modules, it becomes incredibly difficult to build stable interfaces. As we develop more complex applications, a crucial question emerges: “How can models (such as classes or structs) be shared between multiple foreign languages and Nix?”

One potential solution is to define the model once in a chosen language and then generate the necessary code for all other languages. This approach ensures consistency and reduces the likelihood of errors caused by manual translations between languages.

Well-defined, statically typed models would provide build-time checks for correctness and prevent many issues and regressions that could have been avoided with robust interfaces.

Building on the earlier blog post about the NixOS modules to JSON-schema converter, a further exploration could involve using JSON-schema as an intermediate format. While not explicitly mentioned in the blog post, the JSON-schema converter operates solely on the interface declaration. It can also populate example values and other metadata that may become important later.

In our case, we decided to use NixOS module interface declarations as the source of truth, as all our models are Nix-first citizens. We will use JSON-schema as an interoperable format that can further be utilized to generate Python classes and TypeScript types.

For example, the desired Python code output could be a TypedDict or a dataclass. Since our input data might contain Nix attribute names that are invalid identifiers in Python, and vice versa, it is preferable to choose dataclasses. This allows us to store more metadata about the mapping relationships within the field properties.

{lib, ...}:
let
  types = lib.types;
  option = t: lib.mkOption {
    type = t;
  };
in
{
  options = {
    submodule = option (types.submodule {
      options = {
        string = option types.str;
        list-str = option (types.listOf types.str);
        attrs-str = option (types.attrsOf types.str);
      };
    });
  };
}

With the following nix code this can be converted into python

let
  # Import clan-core flake
  clan-core = builtins.getFlake "git+https://git.clan.lol/clan/clan-core";
  pkgs = import clan-core.inputs.nixpkgs {};

  # Step 1: Convert NixOS module expression to JSON schema
  serialize = expr: builtins.toFile "in.json" (builtins.toJSON expr);
  schema = serialize ((clan-core.lib.jsonschema {}).parseModule ./in.nix);

  # classgenerator
  inherit (clan-core.packages.x86_64-linux) classgen;
in
{
  inherit schema;

  python-classes = pkgs.runCommand "py-cls" {}
  ''
    ${classgen}/bin/classgen ${schema} $out
  '';
}

Now execute the following:

nix build -f convert.nix python-classes

The final Python code ensures that the Python component is always in sync with the Nix code.

@dataclass
class Submodule:
    string: str
    attrs_str: dict[str, str] = field(default_factory = dict, metadata = {"alias": "attrs-str"})
    list_str: list[str] = field(default_factory = list, metadata = {"alias": "list-str"})


@dataclass
class Module:
    submodule: Submodule

However, this approach comes with some constraints for both the interface itself and the tools surrounding it:

All types used in the interface must be JSON-serializable (e.g., Number, String, AttrSet, List, etc.).
We identified certain constraints that work best for dataclasses, while also enhancing the final user experience:
- Top-level options should specify a default value or be nullable.
- Ideally, option identifiers should use names that don’t require a “field-alias,” although this might not always be feasible.
- Neutral values for lists or dictionaries, such as an empty list or empty dictionary, must be supported.

The Python generator adds default constructors for dictionary and list types because the absence of a value would violate our type constraints.

It is also important to note that we control both the JSON schema converter and the class generator, which is crucial. This control allows us to limit their scope to a subset of JSON schema features and ensure interoperability between the two generators.

Another consideration is serialization and deserialization. In Python, Pydantic is typically a great choice, as it also offers custom serializers. However, when working with NixOS modules, we chose not to emit unset or null values because they create merge conflicts in the underlying NixOS modules. We also wanted to use field-aliases for names that are invalid identifiers in Python or TypeScript and wanted validation to catch errors early (in the deserializer) between our frontend and Nix, allowing us to present well-formatted errors instead of Nix evaluation error stack traces. Nevertheless, we ultimately did not use Pydantic because it did not meet our needs.

Catching errors

Interface violations or regressions can be detected during the development cycle at build time.

Submodule(string=1)

> Argument of type "Literal[1]" cannot be assigned to parameter "string" of type "str" in function "__init__"
  "Literal[1]" is incompatible with "str"

Since all our layers communicate through JSON interfaces, any potential runtime type errors are caught in Python during deserialization before they can trigger any Nix stack traces. This allows for errors to be neatly formatted for the consumer.

data = {"submodule": { "string": 1  } }
checked(Model, data)

>>> Traceback (most recent call last):
>>> ...
>>> Expected string, got 1

Future

By adopting this approach, we aim to provide a stable and secure interface for polyglot software stacks built on top of Nixpkgs, ultimately enhancing the reliability and maintainability of complex applications.

Additionally, we will improve the tooling and develop a library, making this methodology applicable to other projects as well.

Introducing NixOS Facter

Fri, 19 Jul 2024 09:08:10 +0200

If you’ve ever installed NixOS, you’ll be familiar with a little Perl script called nixos-generate-config. Unsurprisingly, it generates a couple of NixOS modules based on available hardware, mounted filesystems, configured swap, etc.

It’s a critical component of the install process, aiming to ensure you have a good starting point for your NixOS system, with necessary or recommended kernel modules, file system mounts, networking config and much more.

As solutions go, it’s a solid one. It has helped many users take their first steps into this rabbit hole we call NixOS. However, it does suffer from one fundamental limitation.

Static Generation

When a user generates a hardware-configuration.nix with nixos-generate-config, it makes choices based on the current state of the world as it sees it. By its very nature, then, it cannot account for changes in NixOS over time.

A recommended configuration option today might be different two NixOS releases from now.

To account for this, you could always run nixos-generate-config again. But that requires a working system, which may have broken due to the historical choices made last time, or worst-case, requiring you to fire up the installer again.

A Layer of Indirection

What if, instead of generating some Nix code, we first describe the current hardware in an intermediate format? This hardware report would be ‘pure’, devoid of any reference to NixOS, and intended as a stable, longer-term representation of the system.

From here, we can create a series of NixOS modules designed to examine the report’s contents and make the same kinds of decisions that nixos-generate-config does. The critical difference is that as NixOS evolves, so can these modules, and with a full hardware report available we can make more interesting config choices about things such as GPUs and other devices.

In a perfect world, we should not need to regenerate the underlying report as long as there are no hardware changes. We can take this one step further.

Provided that certain sensitive information, such as serial numbers and MAC addresses, is filtered out, there is no reason why these hardware reports could not be shared after they are generated for things like EC2 instance types, specific laptop models, and so on, much like NixOS Hardware currently shares Nix configs.

Introducing NixOS Facter

Still in its early stages, NixOS Facter is intended to do what I’ve described above.

A user can generate a JSON-based hardware report using a (eventually static) Go program: nixos-facter -o facter.json. From there, they can include this report in their NixOS config and make use of our NixOS modules as follows:

flake.nix

```nix
{
    inputs = {
        nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
        nixos-facter-modules.url = "github:numtide/nixos-facter-modules";
    };

    outputs = inputs @ {
        nixpkgs,
        ...
    }: {
        nixosConfigurations.basic = nixpkgs.lib.nixosSystem {
            modules = [
                inputs.nixos-facter-modules.nixosModules.facter
                { config.facter.reportPath = ./facter.json; }
                # ...
            ];
        };
    };
}
```

without flakes

```nix
# configuration.nix
{
    imports = [
      "${(builtins.fetchTarball {
        url = "https://github.com/numtide/nixos-facter-modules/";
      })}/modules/nixos/facter.nix"
    ];

    config.facter.reportPath = ./facter.json;
}
```

That’s it.

We assume that users will rely on disko, so we have not implemented file system configuration yet (it’s on the roadmap). In the meantime, if you don’t use disko you have to specify that part of the configuration yourself or take it from nixos-generate-config.

Early Days

Please be aware that NixOS Facter is still in early development and is still subject to significant changes especially the output json format as we flesh things out. Our initial goal is to reach feature parity with nixos-generate-config.

From there, we want to continue building our NixOS modules, opening things up to the community, and beginning to capture shared hardware configurations for providers such as Hetzner, etc.

Over the coming weeks, we will also build up documentation and examples to make it easier to play with. For now, please be patient.

Side note: if you are wondering why the repo is in the Numtide org, we started partnering with Clan! Both companies are looking to make self-hosting easier and we’re excited to be working together on this. Expect more tools and features to come!

Declarative Backups and Restore

Mon, 24 Jun 2024 09:08:15 +0200

Our goal with Clan is to give users control over their data. However, with great power comes great responsibility, and owning your data means you also need to take care of backups yourself.

In our experience, setting up automatic backups is often a tedious process as it requires custom integration of the backup software and the services that produce the state. More important than the backup is the restore. Restores are often not well tested or documented, and if not working correctly, they can render the backup useless.

In Clan, we want to make backup and restore a first-class citizen. Every service should describe what state it produces and how it can be backed up and restored.

In this article, we will discuss how our backup interface in Clan works. The interface allows different backup software to be used interchangeably and allows module authors to define custom backup and restore logic for their services.

First Comes the State

Our services are built from Clan modules. Clan modules are essentially NixOS modules, the basic configuration components of NixOS. However, we have enhanced them with additional features provided by Clan and restricted certain option types to enable configuration through a graphical interface.

In a simple case, this can be just a bunch of directories, such as what we define for our ZeroTier VPN service.

{
  clan.core.state.zerotier.folders =  [ "/var/lib/zerotier-one" ];
}

For other systems, we need more complex backup and restore logic. For each state, we can provide custom command hooks for backing up and restoring.

In our PostgreSQL module, for example, we define preBackupCommand and postRestoreCommand to use pg_dump and pg_restore to backup and restore individual databases:

preBackupCommand = ''
  # ...
  runuser -u postgres -- pg_dump ${compression} --dbname=${db.name} -Fc -c > "${current}.tmp"
  # ...
'';
postRestoreCommand = ''
  # ...
  runuser -u postgres -- dropdb "${db.name}"
  runuser -u postgres -- pg_restore -C -d postgres "${current}"
  # ...
'';

Then the Backup

Our CLI unifies the different backup providers in one interface.

As of now, we support backups using BorgBackup and a backup module called “localbackup” based on rsnapshot, optimized for backup on locally attached storage media.

To use different backup software, a module needs to set the options provided by our backup interface. The following Nix code is a toy example that uses the tar program to perform backup and restore to illustrate how the backup interface works:

  clan.core.backups.providers.tar = {
    list = ''
      echo /var/lib/system-back.tar
    '';
    create = let
      uniqueFolders = lib.unique (
        lib.flatten (lib.mapAttrsToList (_name: state: state.folders) config.clan.core.state)
      );
    in ''
      # FIXME: a proper implementation should also run `state.preBackupCommand` of each state
      if [ -f /var/lib/system-back.tar ]; then
        tar -uvpf /var/lib/system-back.tar ${builtins.toString uniqueFolders}
      else
        tar -cvpf /var/lib/system-back.tar ${builtins.toString uniqueFolders}
      fi
    '';
    restore = ''
      IFS=':' read -ra FOLDER <<< "''$FOLDERS"
      echo "${FOLDER[@]}" > /run/folders-to-restore.txt
      tar -xvpf /var/lib/system-back.tar -C / -T /run/folders-to-restore.txt
    '';
  };

For better real-world implementations, check out the implementations for BorgBackup and localbackup.

What It Looks Like to the End User

After following the guide for configuring a backup, users can use the CLI to create backups, list them, and restore them.

Backups can be created through the CLI like this:

clan backups create web01

BorgBackup will also create backups itself every day by default.

Completed backups can be listed like this:

clan backups list web01
...
web01::u366395@u366395.your-storagebox.de:/./borgbackup::web01-web01-2024-06-18T01:00:00
web03::u366395@u366395.your-storagebox.de:/./borgbackup::web01-web01-2024-06-19T01:00:00

One cool feature of our backup system is that it is aware of individual services/applications. Let’s say we want to restore the state of our Matrix chat server; we can just specify it like this:

clan backups restore --service matrix-synapse web01 borgbackup web03::u366395@u366395.your-storagebox.de:/./borgbackup::web01-web01-2024-06-19T01:00:00

In this case, it will first stop the matrix-synapse systemd service, then delete the PostgreSQL database, restore the database from the backup, and then start the matrix-synapse service again.

Future work

As of now we implemented our backup and restore for a handful of services and we expect to refine the interface as we test the interface for more applications.

Currently, our backup implementation backs up filesystem state from running services. This can lead to inconsistencies if applications change the state while the backup is running. In the future, we hope to make backups more atomic by backing up a filesystem snapshot instead of normal directories. This, however, requires the use of modern filesystems that support these features.

Introducing the NixOS to JSON Schema Converter

Sat, 25 May 2024 09:08:10 +0200

Overview

We’ve developed a new library designed to extract interfaces from NixOS modules and convert them into JSON schemas, paving the way for effortless GUI generation. This blog post outlines the motivations behind this development, demonstrates the capabilities of the library, and guides you through leveraging it to create GUIs seamlessly.

Motivation

In recent months, our team has been exploring various graphical user interfaces (GUIs) to streamline NixOS machine configuration. While our opinionated Clan modules simplify NixOS configurations, there’s a need to configure these modules from diverse frontends, such as:

Command-line interfaces (CLIs)
Web-based UIs
Desktop applications
Mobile applications
Large Language Models (LLMs)

Given this need, a universal format like JSON is a natural choice. It is already possible as of now, to import json based NixOS configurations, as illustrated below:

configuration.json:

{ "networking": { "hostName": "my-machine" } }

This configuration can be then imported inside a classic NixOS config:

{config, lib, pkgs, ...}: {
  imports = [
    (lib.importJSON ./configuration.json)
  ];
}

This straightforward approach allows us to build a frontend that generates JSON, enabling the configuration of NixOS machines. But, two critical questions arise:

How does the frontend learn about existing configuration options?
How can it verify user input without running Nix?

Introducing JSON schema, a widely supported standard that defines interfaces in JSON and validates input against them.

Example schema for networking.hostName:

{
  "type": "object",
  "properties": {
    "networking": {
      "type": "object",
      "properties": {
        "hostName": {
          "type": "string",
          "pattern": "^$|^[a-z0-9]([a-z0-9_-]{0,61}[a-z0-9])?$"
        }
      }
    }
  }
}

Client-Side Input Validation

Validating input against JSON schemas is both efficient and well-supported across numerous programming languages. Using JSON schema validators, you can accurately check configurations like our configuration.json.

Validation example:

$ nix-shell -p check-jsonschema
$ jsonschema -o pretty ./schema.json -i ./configuration.json
===[SUCCESS]===(./configuration.json)===

In case of invalid input, schema validators provide explicit error messages:

$ echo '{ "networking": { "hostName": "my/machine" } }' > configuration.json
$ jsonschema -o pretty ./schema.json -i ./configuration.json
===[ValidationError]===(./configuration.json)===

'my/machine' does not match '^$|^[a-z0-9]([a-z0-9_-]{0,61}[a-z0-9])?$'

Failed validating 'pattern' in schema['properties']['networking']['properties']['hostName']:
    {'pattern': '^$|^[a-z0-9]([a-z0-9_-]{0,61}[a-z0-9])?$',
     'type': 'string'}

On instance['networking']['hostName']:
    'my/machine'

Automatic GUI Generation

Certain libraries facilitate straightforward GUI generation from JSON schemas. For instance, the react-jsonschema-form playground auto-generates a form for any given schema.

NixOS Module to JSON Schema Converter

To enable the development of responsive frontends, our library allows the extraction of interfaces from NixOS modules to JSON schemas. Open-sourced for community collaboration, this library supports building sophisticated user interfaces for NixOS.

Here’s a preview of our library’s functions exposed through the clan-core flake:

lib.jsonschema.parseModule - Generates a schema for a NixOS module.
lib.jsonschema.parseOption - Generates a schema for a single NixOS option.
lib.jsonschema.parseOptions - Generates a schema from an attrset of NixOS options.

Example: module.nix:

{lib, config, pkgs, ...}: {
  # a simple service with two options
  options.services.example-web-service = {
    enable = lib.mkEnableOption "Example web service";
    port = lib.mkOption {
      type = lib.types.int;
      description = "Port used to serve the content";
    };
  };
}

Converted, using the parseModule function:

$ cd clan-core
$ nix eval --json --impure --expr \
  '(import ./lib/jsonschema {}).parseModule ./module.nix' | jq | head
{
  "properties": {
    "services": {
      "properties": {
        "example-web-service": {
          "properties": {
            "enable": {
              "default": false,
              "description": "Whether to enable Example web service.",
              "examples": [
...

This utility can also generate interfaces for existing NixOS modules or options.

GUI for NGINX in Under a Minute

Creating a prototype GUI for the NGINX module using our library and react-jsonschema-form playground can be done quickly:

Export all NGINX options into a JSON schema using a Nix expression:

# export.nix
let
  pkgs = import <nixpkgs> {};
  clan-core = builtins.getFlake "git+https://git.clan.lol/clan/clan-core";
  options = (pkgs.nixos {}).options.services.nginx;
in
  clan-core.lib.jsonschema.parseOption options

Write the schema into a file:

$ nix eval --json -f ./export.nix | jq > nginx.json

Open the react-jsonschema-form playground, select Blank and paste the nginx.json contents.

This provides a quick look at a potential GUI (screenshot is cropped).

Potential Nginx Gui

Limitations

Laziness

JSON schema mandates the declaration of all required fields upfront, which might be configured implicitly or remain unused. For instance, services.nginx.virtualHosts.<name>.sslCertificate must be specified even if SSL isn’t enabled.

Limited Types

Certain NixOS module types, like types.functionTo and types.package, do not map straightforwardly to JSON. For full compatibility, adjustments to NixOS modules might be necessary, such as substituting listOf package with listOf str.

Parsing NixOS Modules

Currently, our converter relies on the options attribute of evaluated NixOS modules, extracting information from the type.name attribute, which is suboptimal. Enhanced introspection capabilities within the NixOS module system would be beneficial.

Future Prospects

We hope these experiments inspire the community, encourage contributions and further development in this space. Share your ideas and contributions through our issue tracker or matrix channel!

New documentation site and weekly new meetup

Tue, 16 Apr 2024 09:08:10 +0200

Last week, we added a new documentation hub for clan at docs.clan.lol. We now have weekly office hours where people are invited to hangout and ask questions. They are every Wednesday 15:30 UTC (17:30 CEST) in our jitsi. Otherwise drop by in our matrix channel.

Introducing Clan: Full-Stack Computing Redefined

Tue, 19 Mar 2024 09:08:10 +0200

In a digital age where users are guided increasingly toward submission and dependence, Clan reclaims computing and networking from the ground up.

Clan enables users to build any system from a git repository, automate secret handling, and join devices in a secure darknet. This control extends beyond applications to communication protocols and the operating system itself, putting you fully in charge of your own digital environment.

Why We’re Building Clan

Our mission is simple: to restore fun, freedom, and functionality to computing as an open source project. We believe in building tools that empower users, foster innovation, and challenge the limitations imposed by outdated paradigms. Clan, in its essence, is an open source endeavor; it’s our contribution to a future where technology serves humanity, not the other way around.

How Clan Changes the Game

Clan embodies a new philosophy in system, application, and network design. It enables seamless, secure communication across devices, simplifies software distribution and updates, and offers both public and private network configurations. Here are some of the ways it accomplishes this:

Nix as a Foundation: Imagine a safety net for your computer’s operating system, one that lets you make changes or updates without the fear of causing a crash or losing data. Nix simplifies the complexities of system design, ensuring that updates are safe and systems are more reliable.

Simplified System Deployment: Building and managing a computer system, from the operating system to the software you use, often feels like putting together a complex puzzle. With Clan, the puzzle pieces are replaced by a set of building blocks. Leveraging the power of Nix and Clan’s innovative toolkit, anyone from tech-savvy administrators to everyday users can create and maintain what we call “full-stack systems” (everything your computer needs to run smoothly).

A Leap in Connectivity: Imagine if you could create private, secure pathways between your devices, bypassing the noisy and often insecure internet. Clan makes this possible through something called “overlay networks.” These networks are like private tunnels, allowing your devices to talk to each other securely and directly. With Clan’s built-in overlay networks and automatically configured services, connecting your devices becomes seamless, secure, and hassle-free.

Security Through Separation: Clan employs sandboxing and virtual machines, a technology that runs code in isolated environments - so even if you explore new Clans, your system remains protected from potential threats.

Reliable: With Clan, your data and services are preserved for the long haul. We focus on self-hosted backups and integration with the Fediverse, a network of interconnected, independent online communities, so your digital life remains uninterrupted and under your control.

A Glimpse at Clan’s Features

Social Scaling: Choose between creating a private sanctuary for your closest contacts, a dynamic space for a self-contained community, or embracing the open web with public Clans anyone can join.

Seamless VM Integration: Applications running in virtual machines can appear and behave as if they’re part of your main operating system — a blend of power and simplicity.

Robust Backup Management: Keep your data safe forever - never worry about cloud services disappearing in 10 years.

Intuitive Secret Management: Clan simplifies digital security by automating the creation and management of encryption keys and passwords for your services.

Remote Install: Set up and manage Clan systems anywhere in the world with just a QR scan or SSH access, making remote installations as easy as snapping a photo or sharing a link.

Who Stands to Benefit?

Clan is for anyone and everyone who believes in the power of open source technology to connect, empower, and protect. From system administrators to less tech-savvy individuals, small business owners to privacy-conscious users, Clan offers something for everyone — a way to reclaim control and redefine how we interact with technology.

Join the Revolution

Ready to control your digital world? Clan is more than a tool—it’s a movement. Secure your data, manage your systems easily, or connect with others how you like. Start with Clan for a better digital future.

Connect with us on our Matrix channel at clan.lol or through our IRC bridges (coming soon).

Want to see the code? Check it out on our Gitea or on GitHub.

Or follow our RSS feed!

Join us and be part of changing technology for the better, together.

Home on Clan

Data Mesher

How does it work?

What can it be used for?

What’s Next?

Debugging Offline Nix Builds

The Setup

The Usual Debugging Experience

The Key Insight: nix build --dry-run

Getting Network Access Into the Sandbox

Pausing the Test

How Network Injection Works

Running the Dry-Run

Finding the Packages

The Fix

A Note on .drvPath

Conclusion

Clan 2025 Wrap-Up: From Infrastructure to a New Computing Paradigm

Why Clan Exists

2025 In Review

Networking / VPN work and reliability gains

Micro VMs

Clan GUI

Secrets and computed values, rethought

Inventory: from single machines to fleets

Service exports and composability

macOS as a first-class Clan member

What’s next

Spaces

Clan and LLMs

ClanHub: A Home for Community Services

Clan as mass-scale decentralized infrastructure

Closing Thoughts

Towards a secure peer-to-peer app platform for Clan

microVMs

Desktop and GPU support

D-Bus / XDG Desktop Portals

Conclusion

The Road Towards a NixOS UI

Why NixOS Modules Need Two JSON Schemas

Why NixOS Modules Need Two JSON Schemas

The New Discovery

(a) Safe round-tripping

(b) Compatibility & stability checks

What if not a subtype?

Practical takeaway

Outlook

Clan + macOS

What is nix-darwin

multi-OS modules

Networking

How it works

What is still missing?

nix-unit

What is nix-unit?

Basic Test Structure

Grouping

Interactive debugging

Integration with CI

Integration with flake-parts

You can do it too

Clan + Yubikeys

Multiple User Keys

Age Plugins

Recovering Recipients

Success?

Vars + age-plugin-fido2-hmac = Pain

Terminal Multiplexing

Summary

How to Democratise DevOps

Vars: A framework for managing secrets and computed values

The problem

The current state

The journey

Core Concepts of vars

Example

More Examples

Future work

Service oriented design

Upstreaming the framework

The Key Insight: `nix build --dry-run`

A Note on `.drvPath`

Core Concepts of `vars`