diff --git a/docs/Architecture.md b/docs/Architecture.md index 5aaea3d..bf84891 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -576,7 +576,7 @@ mean, how it fits, its first step. Labels steer what happens next: than about one PR (D2), work through it as milestones (D4). - **A new project:** a conversation, however vague. If it becomes a project, the agent lists what it needs provisioned (a repository with protection and its own - write access, a build VM, the project's configuration), which the operator + write access, a build VM, and its project entry, D8), which the operator provides (later `nisse-ops`, O6). It then opens a tracking issue ("implement the build plan") as the record, and the architecture lands in one or more PRs, then the plan's milestones. @@ -697,10 +697,11 @@ tokens. It reaches LiteLLM, Gitea, Matrix and SSH to its build VMs, nothing else **Build VMs** (one per project, D3) are where untrusted content meets command execution: - **A real Docker daemon,** since projects build and run containers. -- **Sealed:** egress only to package sources and Gitea's git endpoint, plus whatever - the project declares its tests need (e.g. LiteLLM for the `nisse` project itself), - reviewed like any allowlist (X2). Ingress only SSH from the agent host. No other - route into RFC1918, and none to the agent host or the tailnet; no Tailscale. +- **Sealed:** egress only to package sources and Gitea's git endpoint, plus what + its project entry (D8) declares its tests need (e.g. LiteLLM for the `nisse` + project itself), reviewed like any allowlist (X2). Ingress only SSH from the + agent host. No other route into RFC1918, and none to the agent host or the + tailnet; no Tailscale. - **Their own VLAN,** with test services on predictable ports, and test containers on an internal network with no route out. - **A headless browser** reaches only the internal test network, to exercise what @@ -715,6 +716,23 @@ commands can see must be scoped for testing, never production. `nisse-dev`'s request to `nisse-ops` (an issue in the infrastructure repository, O5), until then by the operator. +### D8. Projects + +**A project is an entry in the agent's configuration,** reviewable and changed by +PR like any configuration (L12). An entry is what makes a project known to the +agent, and it holds everything per-project the rest of this part refers to: +- the repository and its default branch; +- the build VM and the template it comes from (D3); +- the trust dial (L3) and label defaults (e.g. always discuss first, D1); +- the project's secrets by name, each marked as visible to the model's commands or + harness-only (D7); +- egress its tests need beyond the default (D7). + +**For a new project,** the agent proposes the entry alongside its provisioning +request (D1); the operator merges it when the repository and build VM exist. The +agent may propose entries and changes, but never changes the trust dial or a +secret's visibility itself. + --- ## Part O — `nisse-ops` @@ -891,3 +909,7 @@ shared between agents. - **Browser access to network gear:** standing, or handed off per task. - **Relocating a stateful MCP server** off the agent host, if one ever justifies losing attribution. +- **Recovering the agent host.** It is a single point of failure for every agent, + `nisse-ops` included, so its recovery can't depend on ops running. A recovery + plan (rebuilding the host, restoring state from snapshots) is ops work still to + be written.