tsurf-overlay-authoring

Estrellas15

Forks1

Actualizado7 de julio de 2026 a las 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.

Instalación

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Fuente

dangirsh

dangirsh/tsurf

Abrir repositorio de GitHub Ver repositorios del creador

Descarga

Ocupaciones relacionadasSOC

Basado en la clasificación ocupacional SOC

Administradores de redes y sistemas informáticosOcupaciones informáticas y matemáticas·SOC 15-1244

Explorador de archivos

2 archivos

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.

Más de este repositorio

mismo repositorio

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.