Get started
How Kelvar works
Kelvar is built so that you never have to take an agent's word for anything. A small kernel admits requests, decides what each agent may do, and records every step. Everything else, including models, GitHub and the tools that read your files, plugs in around it.
#The loop
Every audit follows the same five steps.
- Connect. You connect a source such as GitHub, or you give an agent a task. Connecting a source starts an audit automatically.
- Audit. An agent reads the code, manifests, workflows and alerts it is allowed to see. If a target sits outside its current room, the agent builds a new read-only room for that one path.
- Record. The agent sends each confirmed issue as a
security.finding. It carries a file, a line, an advisory, evidence and a remediation. - Verify. For actions that change something, a deterministic verifier runs first. Only then does the ledger record a mark.
- Act. You, or another agent, take the next step. A patch agent prepares a fix. A gate holds a merge. A SOC agent escalates.
#One audit, end to end
Here is what happens when you ask an agent to audit a folder it cannot yet see.
| Step | Tool | What happens |
|---|---|---|
| 1 | chat | You ask, for example "Audit target-app for zero-click and CVE risk." The Zero-Click Rapid Defender picks it up. |
| 2 | authoring.apply | The agent authors a child worker with read access to that one path and nothing else. |
| 3 | file.read | It reads source files and dependency manifests, inside a sandbox limited to the admitted path. |
| 4 | security.finding | Each confirmed finding is recorded and appears on the Findings screen. |
| 5 | file.write | If you hand a finding to the patch agent, it writes a fix in an isolated worktree. A verifier must pass before the ledger records a mark. |
#The pieces
Kelvar uses a small vocabulary. These terms appear throughout the documentation.
| Term | Meaning | In the app |
|---|---|---|
| Interface | A typed port. Providers, channels, tools and agents all attach through interfaces. | Applications and Drivers |
| Artifact | The only thing that crosses a boundary, such as a message, a tool call or a finding. | Shown in Activity |
| Run | A durable record of one piece of work. It is data, not a process, so it can pause and resume. | Task |
| Worker | An agent, kept as data. It has a role and a ceiling on what it may ever touch. | Agent |
| Execution environment | A goal with its own policy. Environments nest, and inner ones are narrower. | Project |
| Grant | What a run may do right now. It is formed again every time something arrives. | Capabilities |
| Mark | The recorded fact that a verifier passed. | Verified badge |
| Ledger | The append-only log of every movement between interfaces. | Movements |
#Why a small kernel
The kernel is about 45,000 lines of Rust and it knows nothing about specific providers, tools or models. It cannot branch on a name such as github or gpt. New capabilities are JSON descriptors that attach to the kernel, so they can be inspected, replayed and verified like everything else.
This has three consequences you can rely on.
- Refusals are visible. A request outside an agent's grant is refused at the gate and recorded as a typed row. It is never silently dropped.
- Models are replaceable. The kernel does not depend on any provider, so you can change models without changing how permissions work.
- Failure is closed. When something is missing or a check fails, Kelvar stops with a clear error. It does not substitute a placeholder or return mock data.
#What stays on your machine
Your Home directory holds the registry, runs, ledger and interface state. By default it lives in ~/.vigil on your Mac. Tools run in a deny-by-default sandbox. Source code is read by the model provider you choose, under that provider's terms, and by nothing else. See the Security model for the full boundary.