AkurAI-Build

public

Latest change ce4b48cfe1decc20a4f7243fa2b30fb78a3e0f12 - worker: hourly stale-workspace pruning; writable-home sandbox docs by Ólafur Búi Ólafsson

# AGENTS.md

Documentation for this repo lives in AkurAI Notes, notebook **AkurAI-Build**
(ID 7) — see `AkurAI-Build — Project Index` (note 65).

- Read `deploy.md` before every implementation, deployment, diagnosis, or operations task.
- The laptop is a source-control client only. Commit intended source changes and push them to hosted Git; `deploy.sh` then fast-forwards Titan with `git pull --ff-only` before dispatching the command there.
- Run every formatter, check, test, build, container, deployment, and operational command on Titan. Never use Syncthing or another file-copy path as a substitute for Git.
- Commit only intended source paths; publish hosted Git, queue exact commits, inspect runs, and promote deployments through the `akurai-build` MCP tools.
- Never manually mutate production files, state, services, Nginx, certificates, packages, hosted Git, artifacts, or databases.
- A successful AkurAI-Build package run is not a deployment; its self-hosted controller requires a non-self-severing MCP-controlled deploy stage.
- Secrets live in the **akurai-passvault** MCP, never in this repo.
- See also note 113 for the Ponytail UI design system.
## Worker sandbox and workspace retention (verified 2026-08-09)

- The controller+worker run on Titan as system unit `akurai-build.service`
(`ProtectSystem=strict`, `NoNewPrivileges`). Jobs MUST be able to write the
invoking user's home (cargo registry, `~/.local/bin` installs), so the
drop-in `/etc/systemd/system/akurai-build.service.d/writable-home.conf` sets
`ProtectHome=false` + `ReadWritePaths=/home/olibuijr`. The service binary
(`~/.local/lib/akurai-build`) and config (`~/.config/akurai-build`) stay
read-only via `ReadOnlyPaths`. "Read-only file system" in a native job log
means this drop-in is missing.
- Native jobs get `HOME=<workspace>/.home`; the real home is exposed as
`AKURAI_BUILD_HOME` for shared toolchain caches.
- Workspace lifecycle: successful runs delete their workspace immediately
(`runner.rs`); `Runner::prune_stale_workspaces` (hourly, from the idle worker
loop) reaps terminal-run workspaces older than 7 days and orphans whose run
row is gone. Non-numeric entries under `workspaces/` are shared repo
checkouts and are never pruned.