> For the complete documentation index, see [llms.txt](https://docs.konvu.com/konvu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.konvu.com/konvu/prevent/guardrails-on-your-computer.md). # Guardrails on your computer What the Guardrails plugin installs and does during a Claude Code session. Claude Code installs the plugin through your organization's managed settings. Guardrails keeps its local program, computer credential, repository mappings, downloaded rules, and queued event details in `~/.konvu/guardrails/`. The rules contain patterns to match and advice to show Claude. Checks run on your computer, and edited code stays there. ## Explore the local folder This is what Guardrails stores locally. Select a file in the tabs below to inspect it. {% code title="\~/.konvu/guardrails" %} ``` guardrails/ ├── bin/ │ ├── v0.6.38/ │ │ └── guardrails │ └── current ├── profiles/ │ └── / │ ├── triggers.json │ └── sync.json ├── repos.json ├── credentials.json └── queue.jsonl ``` {% endcode %} {% tabs %} {% tab title="triggers.json" icon="file-code" %} **`profiles//triggers.json`** holds matching patterns and advice for that repository. Guardrails checks for updated rules at session start. ```json { "triggers": [ { "id": "invoice-org-scope", "matches": "content", "files": ["billing/views.py"], "patterns": ["Invoice\\.query\\.get_or_404\\("], "tokens": [{ "pattern": "Invoice\\.query\\.get_or_404\\(", "paths": ["billing/views.py"] }], "text": "Scope invoice lookups to the signed-in user's organization. Use Invoice.for_org(current_user.org).get_or_404(id)." } ] } ``` {% endtab %} {% tab title="sync.json" icon="file-code" %} **`profiles//sync.json`** records when rules for this repository were last fetched. ```json { "repository_id": "billing-app", "fetched_at": 1791547200 } ``` {% endtab %} {% tab title="repos.json" icon="file-code" %} **`repos.json`** maps Git remotes and local checkouts to repository IDs, so each file is checked against the right rules. ```json { "account": "https://api.konvu.com", "remotes": { "https://github.com/example/billing-app": { "repository_id": "billing-app", "resolved_at": 1791547200 } }, "roots": { "/Users/alex/code/billing-app": "https://github.com/example/billing-app" } } ``` {% endtab %} {% tab title="credentials.json" icon="file-code" %} **`credentials.json`** stores this computer's own credential for Konvu. Guardrails creates it with private file permissions; the deployment key is only needed to enroll. ```json { "https://api.konvu.com": { "workstation_id": "11111111-2222-4333-8444-555555555555", "current": { "token": "[redacted]", "credential_id": "66666666-7777-4888-8999-aaaaaaaaaaaa", "expires_at": "2026-10-16T12:00:00Z" } } } ``` {% endtab %} {% tab title="queue.jsonl" %} **`queue.jsonl`** holds rule events until Guardrails sends them to Konvu at the end of a turn. Records include the rule, decision, and relative file path, not edited code. One line is expanded below for readability. ```json { "event_id": "11111111-2222-4333-8444-555555555555", "repository_id": "billing-app", "external_session_id": "session-01", "occurred_at": "2026-10-09T12:05:00Z", "hook_event": "pre_edit", "kind": "trigger", "outcome": "denied", "tool_name": "Edit", "file_path": "billing/views.py", "trigger_id": "invoice-org-scope", "cwe": null, "source_control_observation_ids": [], "profile_fingerprint": null, "scope": "https://api.konvu.com /workstation-services/guardrails/v1 /workstation-services/guardrails/v1/telemetry/batches" } ``` {% endtab %} {% tab title="guardrails CLI" %} **`bin/v0.6.38/guardrails`** is the verified Rust CLI. Claude Code hooks call it to sync rules and check edits; the plugin does not download it for every edit. `bin/current` holds the installed version name. ``` bin/ ├── current └── v0.6.38/ └── guardrails ``` {% endtab %} {% endtabs %} The local footprint is small. On one Mac, the folder used about **14 MB**, including roughly **10 MB** for the CLI. The size varies with the number of repositories and rules. ## During a Claude Code session Claude Code calls Guardrails automatically during a session. This example follows an invoice edit from authentication through guidance, a file check, and sending event details.
Claude Code terminal with an invoice edit corrected after Guardrails advice. Arrows connect session start, before edit, after edit, and end output to explanation cards on the right.
The walkthrough shows four points in the session: * **Session start:** A background task checks the local program, authenticates the computer, and refreshes downloaded rules. It fetches the current repository first, then other mapped repositories. * **Before an edit:** The hook reads those rules locally. It can hold the first write so Claude sees the matching advice before retrying. * **After an edit:** The local program scans the saved file and tells Claude about new risky patterns. * **End of turn:** Guardrails tries to send queued rule events to Konvu in the background. The events do not contain edited code. The plugin also runs a hook when Claude submits a prompt, and clears local session state when the session ends. The walkthrough focuses on file edits. If the local program or rules are unavailable, Claude Code continues. ## What the plugin installs The plugin itself is a small set of Claude Code hook scripts. At session start, it installs or verifies a pinned **Rust Guardrails CLI** for the computer's platform. It checks the archive and executable against their checksums before storing the executable under `~/.konvu/guardrails/bin/`. Later hooks call that local executable; they do not download it for every edit. The CLI exchanges the deployment key for this computer's own credential, matches the repository to its downloaded rules, runs the local checks, and queues rule events for delivery to Konvu. It keeps the computer credential in a private file under `~/.konvu/guardrails/`. ### Read more {% columns %} {% column width="40%" %} ![Security guidance at the edit](https://4216786002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd2uS6kuROSFKDrT5HC1U%2Fuploads%2Fgit-blob-78c1c0c0daf388e4da5b190c4f9be17fd00f6006%2Fguardrails-blog-thumbnail.png?alt=media) {% endcolumn %} {% column width="60%" %} **KONVU BLOG** #### [Steer in the session, enforce at the PR: how Konvu Guardrails works](https://konvu.com/blog/how-konvu-guardrails-works) From repository Controls to local guidance and a pull request check. {% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.konvu.com/konvu/prevent/guardrails-on-your-computer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.