Menu
Deploy tsurf NixOS config to a server
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Create or update a private tsurf overlay from discovered host facts. Use when an agent needs to author NixOS modules, choose public tsurf role modules, or preserve private services.
Validate a tsurf public repo or private overlay before deployment. Use when an agent is about to run checks, prepare a deploy, override a deploy target, verify rollback/recovery safety, or decide whether a tsurf host change is safe enough to push.
Inspect an existing or prospective NixOS host before applying tsurf. Use when an agent needs to choose a safe tsurf setup path, adapt to unknown disk/network/provider details, determine whether a host can use the public roles directly, or collect facts for a private overlay.
Run tests and manage .test-status for the tsurf repo
Create a new NixOS module for the tsurf repo
Based on SOC occupation classification
| name | deploy |
| description | Deploy tsurf NixOS config to a server |
| user_invocable | true |
Deploy the tsurf NixOS configuration via deploy-rs.
CRITICAL: ALL deploys MUST run from the private overlay. The public repo's
deploy.sh refuses all deploys because hosts run the private overlay config.
When the user asks to deploy (or invokes /deploy), follow these steps:
Always use the private overlay:
cd /path/to/private-overlay
If public tsurf was updated, refresh the input first:
nix flake lock --update-input tsurf
Execute the deploy script:
# Deploy a specific host:
./scripts/deploy.sh --node <hostname>
# Local build fallback (if server can't build):
./scripts/deploy.sh --node <hostname> --mode local
# Fast mode (local build, single eval):
./scripts/deploy.sh --node <hostname> --fast
# First migration deploy from nixos-rebuild:
./scripts/deploy.sh --node <hostname> --first-deploy
Monitor output:
Verify deployment:
Commit flake.lock if updated:
--update-input tsurf, commit the updated flake.lock in the private overlay.| User says | Action |
|---|---|
| "deploy" (no qualifier) | Ask which node, or deploy the node relevant to current work |
| "deploy to " | --node <hostname> |
| "deploy both" / "deploy all" | Deploy each node separately in sequence |
Never deploy a host when only a different host's changes were made. Hosts are independent -- deploy only what changed.
| Flag | Description |
|---|---|
--node NAME | Flake node to deploy (required) |
--mode remote | (default) Build on target host via deploy-rs --remote-build |
--mode local | Build locally, push closure + switch remotely |
--target USER@HOST | Override SSH target (default: root@<node>) |
--first-deploy | Disable magic rollback for one-time migration |
--fast | Local build, single evaluation |
--magic-rollback | Enable deploy-rs magic rollback (300s confirm timeout) |
--public-ip IP | Public IP for post-deploy connectivity check |
--post-hook PATH | Run script at absolute PATH after successful deploy |
tsurf.url in flake.nix)--mode local)ssh root@<hostname> nixos-rebuild switch --rollbackssh root@<hostname> journalctl -u <service> -n 50ssh root@<hostname> rm -rf /var/lock/deploy-<node>.lock
nix flake lock --update-input tsurf in the private overlay.