tsurf-overlay-authoring

Étoiles15

Forks1

Mis à jour7 juillet 2026 à 20:52

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.

Installation

Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.

Source

dangirsh

dangirsh/tsurf

Ouvrir le dépôt GitHub Voir les dépôts du créateur

Téléchargement

Métiers associésSOC

Basé sur la classification professionnelle SOC

Administrateurs de réseaux et de systèmes informatiquesProfessions informatiques et mathématiques·SOC 15-1244

Explorateur de fichiers

2 fichiers

SKILL.md

readonly

name	tsurf-overlay-authoring
description	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.

Tsurf Overlay Authoring

Use this skill after host discovery. The output should be a private overlay change, not a deploy.

Workflow

Read the private overlay first: flake.nix, role files, host file, deploy nodes, and any private module replacing a public module.
Prefer exported public modules: inputs.tsurf.nixosModules.base, boot, networking, impermanence, agent-launcher, agent-sandbox, nono, and role modules when they match.
Preserve private overrides. If a private repo replaces a public module for a real host constraint, do not force it back to the public role.
Keep secrets and host identity private. Do not add real hostnames, keys, service credentials, or personal users to the public repo.
Keep host facts local to the host config: disk devices, network interfaces, provider routing, ACME domains, and state version belong beside the host that needs them.
When adding agent workloads, use services.agentLauncher.agents.<name> unless the public launcher lacks a needed extension point. If it lacks one, prefer improving the public launcher API over copying launcher code.
Hand off to tsurf-deploy-validation before any deploy.

Module Selection

Use agent-host only for hosts that should run brokered prompt-controlled agents. Use agent-host-with-secrets only after sops is ready.
Use service-host for service machines that should inherit public base hardening without the agent sandbox. Use service-host-with-secrets only after sops is ready.
Use individual nixosModules when the private overlay already has a mature role split and role modules would hide important provider-specific overrides.

Guardrails

Do not import modules/secrets.nix until sops.defaultSopsFile and persisted SSH host-key assumptions are true for the host.
Do not put raw agent CLIs in global environment.systemPackages; expose them through generated wrappers.
Keep writable exceptions on individual agents with services.agentLauncher.agents.<name>.nonoProfile.extraAllow; do not widen services.agentLauncher.scopeAccess without documenting why the workflow needs that access.

Plus depuis ce dépôt

même dépôt

tsurf-deploy-validation

dangirsh/tsurf

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.

2026-07-0115

tsurf-host-discovery

dangirsh/tsurf

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.

2026-07-0115

deploy

dangirsh/tsurf

Deploy tsurf NixOS config to a server

2026-03-2715

nix-test

dangirsh/tsurf

Run tests and manage .test-status for the tsurf repo

2026-03-2315

nix-module

dangirsh/tsurf

Create a new NixOS module for the tsurf repo

2026-03-2115

Tsurf Overlay Authoring

Use this skill after host discovery. The output should be a private overlay change, not a deploy.

Workflow

Read the private overlay first: flake.nix, role files, host file, deploy nodes, and any private module replacing a public module.

Prefer exported public modules: inputs.tsurf.nixosModules.base, boot, networking, impermanence, agent-launcher, agent-sandbox, nono, and role modules when they match.

Preserve private overrides. If a private repo replaces a public module for a real host constraint, do not force it back to the public role.

Keep secrets and host identity private. Do not add real hostnames, keys, service credentials, or personal users to the public repo.

Keep host facts local to the host config: disk devices, network interfaces, provider routing, ACME domains, and state version belong beside the host that needs them.

When adding agent workloads, use services.agentLauncher.agents.<name> unless the public launcher lacks a needed extension point. If it lacks one, prefer improving the public launcher API over copying launcher code.

Hand off to tsurf-deploy-validation before any deploy.

Module Selection

Use agent-host only for hosts that should run brokered prompt-controlled agents. Use agent-host-with-secrets only after sops is ready.

Use service-host for service machines that should inherit public base hardening without the agent sandbox. Use service-host-with-secrets only after sops is ready.

Use individual nixosModules when the private overlay already has a mature role split and role modules would hide important provider-specific overrides.

Guardrails

Do not import modules/secrets.nix until sops.defaultSopsFile and persisted SSH host-key assumptions are true for the host.

Do not put raw agent CLIs in global environment.systemPackages; expose them through generated wrappers.

Keep writable exceptions on individual agents with services.agentLauncher.agents.<name>.nonoProfile.extraAllow; do not widen services.agentLauncher.scopeAccess without documenting why the workflow needs that access.