ALPHA: wire is a tool to deploy nixos systems
wire.althaea.zone/
althaea.zone
1---
2comment: false
3title: wire Tutorial Overview
4description: In this tutorial we will create and deploy a wire Hive.
5---
6
7# {{ $frontmatter.title }}
8
9wire is a tool to deploy NixOS systems. Its usage is inspired by [colmena](https://colmena.cli.rs/). In many places it's configuration attempts to remain a superset[^1] of colmena, however it is **not** a fork.
10
11[^1]: A lot of your colmena module options will continue to work with wire, but wire has additional ergonomic changes you can take advantage of.
12
13::: warning
14wire is alpha software, please use at your own risk.
15:::
16
17---
18
19In this tutorial we will create and deploy a wire Hive. Along the way we will
20encounter [npins](https://github.com/andir/npins), simple NixOS
21configurations, virtual machines, and deployment keys.
22
23You'll need at least 10~ GB of free disk space to complete this tutorial.
24
25<div class="tip custom-block" style="padding-top: 8px">
26
27Ready? Skip to [Nix Setup](./part-one/nix-setup).
28
29</div>
30
31## Why wire?
32
33### Features
34
35| Features | wire | Colmena |
36| ------------------------------------------------------------- | ------------------ | ------------------ |
37| [Node Tagging](/guides/targeting.html#tag-basics) | :white_check_mark: | :white_check_mark: |
38| [Secret Management](/guides/keys.html) | :white_check_mark: | :white_check_mark: |
39| [Parallel Deployment](/guides/parallelism.html) | :white_check_mark: | :white_check_mark: |
40| Remote Builds | :white_check_mark: | :white_check_mark: |
41| [Key Services](/guides/keys.html#using-keys-with-services) | :white_check_mark: | :white_check_mark: |
42| [Pipeline Support](/guides/targeting.html#reading-from-stdin) | :white_check_mark: | :x:[^2] |
43| [Non-Root Deployments](/guides/non-root-user) | :white_check_mark: | :x:[^3] |
44| `--path` accepts flakerefs | :white_check_mark: | :x: |
45| REPL & Eval expressions | :x: | :white_check_mark: |
46| Adhoc remote command execution[^4] | :x: | :white_check_mark: |
47
48[^2]: You need to write custom nix code to use Colmena hive metadata inside environments like CI pipelines, bash scripting, etc., which requires a knowledge of its internals. Recently it agained the [eval feature](https://colmena.cli.rs/unstable/features/eval.html) which has improved the situation since wire was first started.
49
50[^3]: See https://github.com/zhaofengli/colmena/issues/120
51
52[^4]: wire lacks an equivalent to `colmena exec`.
53
54### Speed
55
56wire is about >2x faster than colmena deploying [identical large
57hives](https://github.com/mrshmllow/wire/blob/trunk/bench/run.nix).
58
59| Command | Mean [s] | Min [s] | Max [s] | Relative |
60| :--------------- | -------: | ------: | ------: | -------: |
61| `wire@HEAD` | 185.075 | 185.075 | 185.075 | 1.00 |
62| `colmena@pinned` | 343.075 | 343.075 | 343.075 | 1.85 |