Multi-Node Management#

Nixi can manage multiple NixOS machines from a single controller node. The controller is where Nixi runs; remote nodes are managed via SSH.

Concepts#

• Controller – the machine running Nixi (always local)
• Managed node – full control, all tools work (deploy, configure, restart, etc.)
• Monitored node – read-only, only status/inspection commands are allowed

Adopting a Node#

Use the /adopt TUI command to add a remote node:

/adopt <name> <host> [user] [mode]

Examples:

/adopt web-server 192.168.1.10
/adopt db-server 192.168.1.20 nixi managed
/adopt monitoring 192.168.1.30 nixi monitored

The default user is nixi and the default mode is managed.

SSH Key Setup#

Nixi uses SSH key authentication for all remote connections. During adoption:

1. Nixi first tries key-based SSH to the remote node
2. If that works, the node is adopted immediately
3. If key auth fails, Nixi prompts for the remote password
4. The password is used once to copy your SSH key via ssh-copy-id (using nix-shell -p sshpass)
5. All future connections use key auth – the password is never stored

The password prompt is handled entirely in the TUI and never sent to the LLM.

Setting Up a Node#

After adopting, run setup to configure the remote node for Nixi management:

set up nixi-2

This configures:

• Passwordless sudo rules for system management (nixos-rebuild, container runtime, systemctl, mount, rm, etc.)
• Container runtime (Podman or Docker, matching the controller’s configuration) with container DNS
• NFS/SMB mount utilities
• /srv/ directory with correct ownership
• Triggers a NixOS rebuild on the remote node

Setup only needs to run once per node. Nodes set up via the install script already have these configured.

Listing Nodes#

Use the /nodes TUI command or ask Nixi to list nodes:

/nodes

Output:

NAME                 HOST             USER    MODE        STATUS
myhost (local)       192.168.1.5      -       managed     online
web-server           192.168.1.10     nixi    managed     online
db-server            192.168.1.20     nixi    managed     online
monitoring           192.168.1.30     nixi    monitored   unreachable

Status is probed in parallel via SSH – online means SSH is reachable, unreachable means the connection failed.

Removing a Node#

Ask Nixi to remove a node:

remove the monitoring node

This removes the node from the config and clears its SSH known host entry (so re-adoption with a new key works cleanly).

Targeting a Node#

Every tool accepts an optional node parameter. Nixi routes the tool call to the correct node automatically:

show me system info for web-server
list containers on db-server
check the logs for nginx on web-server

When no node is specified, tools run on the local controller.

Multi-Node Workflows#

Nixi can perform actions across multiple nodes in a single conversation:

deploy postgres on db-server with password MySecretPW, then deploy
my-app on web-server with DB_HOST=192.168.1.20 and DB_PASSWORD=MySecretPW

Batch operations work on remote nodes too:

remove all containers on db-server
stop redis and cache on web-server
install nginx, certbot, and fail2ban on web-server

For cross-node communication, use the target node’s IP address (not container names, which only resolve on the same node via container DNS).

Managed vs Monitored#

Monitored nodes are useful for dashboards, status checks, and troubleshooting without risk of accidental changes.

Configuration#

Nodes can be defined in ~/.config/nixi/config.toml:

[[nodes]]
name = "web-server"
host = "192.168.1.10"
user = "nixi"
mode = "managed"

[[nodes]]
name = "monitoring"
host = "192.168.1.30"
user = "nixi"
mode = "monitored"

Or via the NixOS module:

services.nixi = {
  enable = true;
  package = inputs.nixi.packages.x86_64-linux.default;
  nodes = [
    { name = "web-server"; host = "192.168.1.10"; }
    { name = "db-server"; host = "192.168.1.20"; }
    { name = "monitoring"; host = "192.168.1.30"; mode = "monitored"; }
  ];
};

SSH Security#

• Key-based auth only – BatchMode=yes ensures SSH never falls back to password prompts during operation
• Host key verification – new host keys are accepted on first connection (accept-new), but changed keys are rejected to prevent MITM attacks
• Connection timeout – 10-second timeout prevents hanging on unreachable nodes
• Sudo handling – commands that need elevated privileges are automatically wrapped with sudo on remote nodes

Networking#

• Containers on the same node can reference each other by name (container DNS)
• Containers on different nodes must use the target node’s IP address
• When deploying across nodes, Nixi uses the node’s host IP in environment variables (e.g. DB_HOST=192.168.1.20)