Tools#

Nixi uses tools to interact with your NixOS system. The LLM decides which tools to call based on your request.

Available Tools#

`system_info`#

Returns system information: hostname, OS, kernel version, NixOS version, memory, disk, and uptime.

Example: “What system am I running on?”

Multi-Node Support#

Every tool accepts an optional node parameter. If omitted, the tool runs on the local (controller) node. This prepares for future multi-node management where tools can target remote nodes via SSH.

Adding Custom Tools#

Tools implement a simple Go interface:

type Tool interface {
    Name() string
    Description() string
    Parameters() map[string]interface{}
    Notes() string
    Execute(ctx context.Context, exec Executor, args json.RawMessage) (string, error)
}

Key points:

Use the Executor interface for all command execution, never os/exec directly. This ensures your tool works on both local and remote nodes.
Parameters() returns a JSON schema. The registry automatically injects a node parameter.
Notes() returns optional guidance that gets injected into the system prompt.
Register your tool in internal/agent/agent.go via reg.Register(&YourTool{}).

Confirmation Model#

Nixi asks for confirmation before mutating actions:

Requires confirmation: add, update, or remove services/containers/config
No confirmation: read-only operations, start/stop/restart

When confirming, Nixi shows a bulleted list of changes with inline code for identifiers.

Error Handling#

Tools use fuzzy matching on names. If the LLM calls a tool that doesn’t exist, Nixi suggests the closest match (e.g., “did you mean system_info?”). Nixi also retries failed tool calls by diagnosing the error before giving up.

Tools