Agentix is a safety-first control layer for building toward an agentic operating system. The long-term goal is an OS where AI agents can help configure, repair, maintain, and evolve the machine — without receiving unrestricted live-system control.

It starts with NixOS because NixOS gives us a strong foundation: declarative configuration, reproducible builds, rollback-friendly changes, and clear system boundaries. The current workflow is deliberately conservative.

plan -> sandbox -> propose -> verify -> human apply/rebuild

Agentix does not run sudo, nixos-rebuild switch, or rebuild-nixos. It does not edit /etc/nixos. It does not push or commit system config changes. Apply, verify, and activation are human-only. Agentix prepares verified proposals; the human owns the apply and rebuild step.

The safety ladder

Every NixOS goal walks the same ladder. Each rung is reversible until the next.

controller-plan                # describe what is allowed
       v
controller-run (dry-run)       # parse + validate; no subprocess
       v
controller-run --execute       # run goal in temp worktree, save proposal
       v
saved proposal patch           # human reviews the diff
       v
human apply-verify             # human applies the patch
       v
human rebuild-nixos            # human activates the new system

The LLM controller stops at the saved-proposal rung. Everything below is human-only.

What it does today

Three versions have shipped. Each builds on the last.

v0.1 — MVP. Inspect repos, propose Nix dev shells, save patches, manual apply with audit. Doctor and status checks, safe NixOS verification without switching, a high-level goal runner, proposal patch creation, approval before apply, dirty-tree preflight, stale patch rejection, and an installed-command self-test.

v0.2 — Sandboxed agent-loop. Run a goal in a temporary Git worktree, save the diff as a proposal. The source workspace stays untouched. This is the key isolation primitive: the agent works in a disposable copy, and only a patch file crosses back into the real repo.

v0.3 — Controller layer. controller-plan describes the safety contract. controller-run plans and optionally executes a goal end-to-end with full audit, a hardened source-untouched invariant, and conservative subprocess timeouts. Claude Code integrates here.

Source workspace untouched

This is the core safety invariant. Every controller and worktree run snapshots the source workspace before and after the inner subprocess: HEAD commit, git diff HEAD --, and SHA-256 of every untracked file.

Any of these is a violation:

  • HEAD changed
  • Any tracked file added, modified, deleted, renamed, or mode-changed
  • Any untracked file added or removed outside .agentix/proposals/
  • Any untracked file’s content changed

Violation exits non-zero with error="source_workspace_mutated". The only allowed mutation is exactly one new patch under .agentix/proposals/ when the run asks to save a proposal. A failed git snapshot itself fails closed with error="source_snapshot_failed".

Commands

The main commands and what they do.

Command What it does
controller-plan --json Print the safety contract (allowed commands, forbidden commands, safety boundaries)
controller-run "<goal>" Dry-run: parse the goal, print the plan, stop
controller-run "<goal>" --execute Run in temp worktree, save proposal patch, stop
worktree-run "<goal>" --save-proposal --json Lower-level form for scripts
agent-loop "<goal>" Single-pass agent loop with proposal save
audit tail --json Review what happened
audit summary --json Summarize audit log
public-check Check for private artifacts before sharing
export-public --dest <out> --yes Strip private artifacts and export clean

The --keep flag on any worktree command retains the temporary worktree for inspection. --timeout SECONDS overrides the default 30-minute subprocess limit. On timeout: exit code 124, error="timeout".

Claude Code integration

Claude Code operates against the same contract as any other controller. It reads the session prompt, runs controller-plan first, may run controller-run for sandboxed work, and must stop at the saved proposal.

The workflow:

  1. Run controller-plan --json. Summarize the contract.
  2. For each NixOS goal: dry-run first, explain the plan, wait for human approval, then --execute.
  3. Report the result. Stop before apply or rebuild.
  4. The human reviews the proposal patch and runs apply-verify and rebuild-nixos.

Claude Code must not run sudo, rebuild-nixos, nixos-rebuild switch, or directly mutate /etc/nixos. If a controller-run reports source_workspace_mutated, source_snapshot_failed, or timeout, it stops and surfaces the error.

Audit

Every invocation appends one JSON line to .agentix/audit.jsonl (gitignored). Fields include action, mode, goal, result, whether the source was modified, and whether a proposal was saved. Inspect with audit tail and audit summary.

When controller-run --execute runs, the inner worktree audit is suppressed so each top-level invocation produces exactly one event.

Public release safety

Private workspaces contain memory files, audit logs, Claude session state, checkpoints, and transcripts. Do not publish a private repo’s history directly.

agentix public-check --path ~/projects/agentix
agentix export-public --path ~/projects/agentix --dest /tmp/agentix-public --yes
agentix public-check --path /tmp/agentix-public

public-check recursively flags private artifacts. export-public mirrors the same exclusions when copying. The intentional public docs are preserved.

What is intentionally not included

Agentix does not include automatic live system switching, direct sudo operations, broad natural-language config editing, model or provider integration, Home Manager support, or unsupervised live machine operation.

Those are future phases. The current system is about making the safety loop boring and reliable. The agent proposes. The human decides. The machine rebuilds only when the human says so.

GitHub: Beach-Bum/Agentix