A security-first, minimal NixOS base for agent-centric personal computing. See example use cases.

I use tsurf to manage coding/assistant agents across several remote servers. It enables me to rapidly experiment with new tools and approaches in agentic computing, without feeling like this.

This public repo is the base configuration. Real deployments come from a private overlay.

Warning: This project is not yet stable. Use it as a reference only.

The core assumptions behind tsurf are:

1. Agents are now capable enough to be the primary interface for most computing tasks.
2. Agents are becoming cheap enough to be used heavily and ubiquitously.
3. Agents are untrusted, capricious, and hijackable.

These lead to the following design goals:

1. Optimize the operating system for use by agents. Human-use is always expected to be agent-mediated.
2. Support the effective management of many agents across several machines. The bottleneck should be compute/token costs, not management complexity.
3. Always deploy agents with least privilege and defense-in-depth to mitigate the risks of compromised/misaligned agents.

• Sandboxed agent execution. Agents run through nono, using Landlock-backed filesystem rules with restricted network access. Real credentials never enter the agent process; a separate broker supplies short-lived, per-session tokens.
• Declarative agent launcher. Define a new agent type in a few lines of config and get a sandboxed wrapper, credential brokering, resource controls, and persistent storage automatically.
• Hardened, stateless base. Kernel hardening with nix-mineral and srvos, encrypted secrets via sops-nix / sops, strict firewall rules, and an impermanence-style root filesystem that rolls back to a clean snapshot on every boot.
• Deploy safety. Lockout-prevention assertions catch misconfigurations (e.g., missing SSH keys, exposed ports) before they reach a live machine. deploy-rs-based deploys are locked, health-checked, and rollback-aware.
• Public base / private overlay model. This repo is the reusable foundation. Real credentials, host-specific services, and personal config live in a separate private repo that imports what it needs.

• Run hardened, supervised coding agents against dedicated workspace repos on remote NixOS hosts.
• Host personal assistant agents (e.g. OpenClaw).
• Self-host autonomous agent experiments (e.g. Conway Automata)

These are on top of more standard use cases (which can be built/maintained by the agents), including:

• Web services / static sites: agents field change requests, implement, and redeploy.
• Personal Knowledge Management (PKM): agents help with querying, maintaining, and syncing your knowledge graph(s).
• Home Assistant: agents manage the config directly, no UI needed.
• Cost visibility: private overlays can add lightweight token/API spend reporting when useful.

1. Clone the repo and enter it: git clone <your-fork-or-upstream-url> tsurf && cd tsurf
2. Point tsurf at an existing NixOS host with root SSH access: ./tsurf init root@your-server
3. Deploy the generated quickstart overlay: ./tsurf deploy
4. Check the host: ./tsurf status
5. Jump back onto the box when you need it: ./tsurf ssh

tsurf init creates an ignored local overlay under .tsurf/overlay/, saves the defaults in .tsurf/config, generates a root key under .tsurf/keys/, and probes the target host to pick up its hostname and NixOS release automatically. That gives you a short path for trying tsurf against a vanilla NixOS server without assembling a private overlay first.

When you move past evaluation and want the full production/private-overlay workflow, start from QUICKSTART.md and examples/private-overlay/.

• Architecture: docs/architecture.md
• Operations and commands: docs/operations.md
• Optional modules and home profile: docs/extras.md
• Security model: SECURITY.md
• Private overlay template: examples/private-overlay/README.md
• Repo-specific agent guidance: CLAUDE.md

MIT