Skip to main content

How changes reach the box

Every change to the box starts in one folder in the vault. It is committed and pushed in git. Then one script copies only the changed files onto the box and restarts what needs it. The folder is the boss.

Where you see it​

The owner does not see this. What the owner sees is the result: a routine they approved in chat shows up in the Working for you panel a minute later. There is no terminal step for them.

What happens, step by step​

The normal path.

  1. The change is made in the box-files/ folder (every script, timer, and setting for the box) inside the vault.
  2. It is committed and pushed with git (the tool that tracks every change).
  3. Someone with admin access runs apply.sh.
  4. For each file, apply.sh compares the folder copy to the live copy. Same? Skip it. Different? Install it with the right owner and permissions.
  5. It reloads systemd (the server's job scheduler) if a timer or service changed, and restarts only the services whose files changed.
  6. Before any of that, it checks the registry. A timer with no row in routines.json blocks the whole deploy.

The check mode. apply.sh --check does the same comparison and changes nothing. It prints DRIFT for any file that differs, and MISSING-IN-FOLDER for a file the box expects that the folder lacks. A file it has no permission to read is marked unreadable, not drift. The daily checkup runs this every morning.

The chat-approved path. The owner says "yes, set that up" in chat.

  1. The agent that got the yes writes a small request file on the box. Its first line is a short reason.
  2. apply-watcher.timer checks for that file every minute.
  3. When it finds one, it runs apply.sh and logs the output.
  4. Only after that succeeds does it delete the request. If anything crashes first, the request stays and it tries again. It never drops a request silently.

This is safe to run with admin rights because apply.sh only ever installs files that are already committed to the folder. The request file says "go". It does not say what.

What powers it​

PartWhat it does
box-files/The one folder that defines the box.
apply.shCopies changed files onto the box, restarts what changed, or reports drift with --check.
registry_gate()The part of apply.sh that refuses a timer with no registry row.
apply-watcher.sh, .timerTurns an approved chat request into a deploy, every minute.
fresh-watcher.sh, .timerThe same idea for one repair command. The chat agent asks, a separate watcher runs it.

Why it works this way​

The folder is the boss

The box should never differ from what is committed in the folder. A file copied onto the box by hand gets overwritten on the next deploy, and the change vanishes.

The agent proposes by editing the folder. The deploy applies. The agent can never rewire its own services directly. The chat service runs with a lock (NoNewPrivileges) that stops it from ever gaining admin rights, even through sudo. So when the agent needs something done as admin, it can only leave a request for a separate watcher. That watcher runs one fixed command. The agent's reason text only goes in the log. It is never run.

Secrets are never in the folder. Keys and passwords are set up on the box itself and stay there.

Drift is treated as a bug. Three things check for it: apply.sh --check, the daily checkup, and the weekly link check, which also confirms the routines list matches what is running.

Connected to​