Kelvar Docs

Concepts

Permissions and sandboxing

Two independent layers limit what an agent can do. Policy decides what a run may ask for. Process authority decides what a process can physically touch. Neither depends on the other, so a mistake in one does not defeat the other.

#Layer 1. Policy and grants

A grant is what one run may do right now. Kelvar forms it again every time something arrives, as the intersection of three things.

  1. The worker's ceiling, which lists the tools and room kinds the agent could ever hold.
  2. The chain of projects the run lives in. Each inner project can only narrow what the outer one allows.
  3. The bindings you authored, which connect a step to an exact interface.

A request outside the grant is refused at the gate and recorded. Nothing a model writes into a run record becomes a right, because the grant is recomputed from descriptors and never read from the record.

#Layer 2. Process authority

Tools, verifiers and interface processes start with a cleared environment. By default they run inside a deny-by-default macOS sandbox. Each process receives only what its descriptor declares.

  • The folders it may read and write.
  • The executables it may run.
  • The environment variable names it may see.
  • Whether it may use the network or local sockets.

A file tool whose path arrives in its arguments starts with authority for that one path. A path outside the permitted roots is refused before anything runs.

#How the layers combine

A room enforces the operation-level grant itself. Because the room is also the executor, a model cannot talk its way past it. Even if policy allowed a request, the sandbox would still stop a process from touching a path it was not given. Even if a process could touch a path, policy would still refuse a request that was never granted.

#Guidance for setting permissions

  • Give each project the smallest set of drivers and applications it needs. A project that only reads code does not need a process room.
  • Prefer a git worktree room for changes. Changes land on an isolated branch and never touch your working copy.
  • Keep untrusted input apart from write access. A run that reads untrusted content and also holds write or execute tools can be steered into using them. See Security model.
  • Do not grant registry paths to a project that reads untrusted input. A run whose room covers the registry can change the system's own agents and interfaces.
  • Read a package before installing it. An installed interface runs with the authority its descriptor declares.

#Read-only by default

Connectors such as GitHub and Linux server collectors attach through read-only guards. The Linux server collector runs as an unprivileged user on loopback, exposing only fixed read-only probes over an SSH tunnel with no mutation privileges. Write-back is a separate application with its own token, and you opt in to it. A read-only guard cannot be widened by an agent, because widening requires a policy change that only you or Home can author.