> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/quickstart.md). # Quickstart Warrant v0.3.0 is released as a local macOS gateway. Current source also contains an unreleased Grok Build adapter, a sixth `privacy-locked` policy template, and Linux release work. Commands for testing that source preview appear below; they are not available in the v0.3.0 Homebrew package. The current Linux pipeline builds on Ubuntu 24.04 (glibc 2.39); it does not yet claim compatibility with older-glibc or musl distributions. ### 1. Install your agent Install and authenticate Claude Code separately. Warrant discovers the existing launcher; it does not download or replace it. ```sh command -v claude claude --version ``` Claude Code is the demo-ready v0.3.0 path. Codex, Hermes, OpenClaw, and PicoClaw have experimental exact-version adapters, but Warrant does not provision model credentials into their clean runtimes. ### 2. Install Warrant ```sh brew install cerebral-systems/tap/warrant warrant --version warrant policies list ``` The first `warrant` invocation verifies the checksum-pinned release and installs the owner-private runtime under `~/.local/share/warrant/homebrew/bin`. Expect: ``` warrant 0.3.0 ``` ### 3. Protect one workspace Choose the exact directory that should be in scope. Setup uses the current directory; it does not infer a Git repository root. ```sh cd /absolute/path/to/workspace warrant setup claude --policy read-only ``` Review the discovered launcher, interpreter, version, and SHA-256 commitments. Setup runs an isolated version probe, asks before installing the profile, and creates or verifies a hidden local-owner passphrase. That passphrase is local approval authority, not a Warrant account password. Setup safely prepends the managed shim through zsh or bash startup files when possible. Follow its exact `Next:` instruction. Usually that means opening a new terminal; if a startup file is unsafe to change, Warrant prints a manual PATH command instead. ### 4. Verify the boundary In the new or updated shell, return to the same workspace: ```sh cd /absolute/path/to/workspace command -v claude warrant status claude warrant doctor claude ``` `command -v claude` should resolve to: ``` ~/.local/share/warrant/shims/claude ``` Do not continue if `doctor` denies the profile or reports unexpected drift. A successful doctor is authoritative for the installed agent's launch readiness and remaining gaps. Launch the agent normally: ```sh claude ``` The managed runtime exposes typed Warrant workspace operations: * `list_files` * `read_file` * `search_text` * `write_file` * `write_automation_file` With `read-only`, supported reads can proceed and every write is denied. Raw shell and unmanaged MCP tools remain denied. ### 5. Require approval for writes Switch the same workspace to `owner-approved`: ```sh cd /absolute/path/to/workspace warrant policies show owner-approved warrant policy use owner-approved ``` Policy switching repeats the full setup and evidence qualification. When the agent requests a supported write, inspect and resolve the exact pending action: ```sh warrant approvals warrant approve # Or reject it: warrant reject ``` Approved writes bind the exact artifact bytes and expected preimage. Automation files receive a higher risk classification. The local-owner passphrase is required for policy changes and approval operations. Lock the workspace back to read-only without bypassing Warrant: ```sh warrant policy disable warrant status claude warrant doctor claude ``` `policy disable` means fail-closed read-only lockdown. It does not disable the Warrant boundary. ### Policies in the current source The v0.3.0 package contains the five released templates. Current source adds `privacy-locked` for the next release: | Template | Reads | Standard writes | Automation-file writes | | --------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------- | | `read-only` | Entire workspace | Denied | Denied | | `privacy-locked` *(next release)* | Exact `README.md`; list, search, and read under `docs/`, `src/`, and `tests/` | Denied | Denied | | `owner-approved` | Entire workspace | Owner approval, entire workspace | Owner approval, entire workspace | | `docs-only` | Read `README.md`; list, search, and read under `docs/` | Owner approval for `README.md` and `docs/` | Denied | | `workspace-development` | Entire workspace | Owner approval under `docs/`, `src/`, and `tests/` | Denied | | `automation-locked` | Entire workspace | Owner approval, entire workspace | Denied | Raw shell and unmanaged MCP tools are denied in all six source templates. Inspect any template before selecting it: ```sh warrant policies list warrant policies show workspace-development warrant policy use workspace-development ``` #### Create a custom policy Start from a reviewed template and give the editable copy a distinct name: ```sh cd /absolute/path/to/workspace warrant policy init docs-only --name my-docs-policy --output warrant-policy.json ``` Edit `warrant-policy.json`, then validate, compare, and activate the exact file: ```sh warrant policy validate warrant-policy.json warrant policy diff warrant-policy.json warrant policy use warrant-policy.json warrant status claude warrant doctor claude ``` `policy validate` rejects unknown operations, unknown fields, invalid decisions, and noncanonical paths. `policy diff` compares the candidate with this workspace's active policy. `policy use` recompiles the file, binds its canonical bytes and hash into the profile evidence, and repeats full qualification. The JSON v2 format is deliberately closed to five workspace operations. Path scopes are workspace-relative `exact` paths or `subtree` paths; no regex or glob syntax is accepted. Recursive `workspace.list_files` and `workspace.search_text` require `subtree` includes—an `exact` include is rejected because results can contain descendants. An excluded descendant, including an `exact` exclusion, denies an ancestor list/search traversal as one unit. Read Local policies before authoring path scopes. ### Next-release Grok Build preview > This flow requires a source build containing the unreleased `grok-build` profile; Warrant v0.3.0 from Homebrew does not recognize it. Install Grok Build separately. The adapter is currently pinned to exact version 0.2.101. The npm path avoids the shell installer's optional `x.ai` and `storage.googleapis.com` download hosts: ```sh npm install -g @xai-official/grok@0.2.101 command -v grok grok --version ``` Then bind the exact original workspace to the narrow read template: ```sh cd /absolute/path/to/workspace warrant policies show privacy-locked warrant setup grok --policy privacy-locked ``` Review the measured executable and hash, follow setup's printed `Next:` instruction, and return to the same original directory: ```sh cd /absolute/path/to/workspace command -v grok warrant status grok warrant doctor grok grok ``` The current adapter is binary/configuration-conformance ready, not provider-login or model ready. Warrant neither copies the user's Grok OAuth state nor forwards an `XAI_API_KEY` into the disposable runtime. Until a credential broker ships, a managed session requires fresh provider authentication and that authentication is discarded with the session. Treat this as a boundary preview, not a complete daily-driver flow. The managed shim accepts the interactive launch with no arguments, one positional prompt, or its documented read-only diagnostics; it does not expose Grok management subcommands such as `update`, `setup`, `mcp`, or `plugin`. The managed shim does not run Grok with the original checkout as its current working directory. It creates an empty, owner-private session workspace; Warrant exposes the original workspace through the generated, authenticated Warrant MCP route. Under `privacy-locked`, that route can read exact `README.md` and the `docs/`, `src/`, and `tests/` subtrees; it denies root traversal, root `.git`, root `.env`, root `.github`, other root configuration, and every write. It does not inspect file contents or names inside an allowed subtree: for example, `src/.env` remains readable and must be excluded with a custom policy. This brokers Warrant's tool surface but, without OS containment, cannot prohibit every absolute-path read by the same-user process. The adapter layers provider-specific defenses around that policy: * an isolated `GROK_HOME` with hash-bound `managed_config.toml`, `requirements.toml`, and an MCP-only agent definition; * `[harness] disable_codebase_upload = true` plus telemetry and trace-upload environment vetoes; * strict sandbox selection plus the MCP-only agent definition, verified against both Grok's headless and interactive tool surfaces; * a version pin so a changed Grok binary or configuration contract fails closed. These layers address a version-specific wire analysis of Grok 0.2.93 that recovered an unread tracked file and Git history from an uploaded Git bundle. The analysis proved transmission and storage in those tests—not training, and not universal behavior in every later release. Its maintained update says xAI disabled the upload server-side on 2026-07-14; Warrant still keeps the local upload veto and empty-workspace boundary so security does not depend on that remote default. See the [primary wire analysis](https://gist.github.com/cereblab/dc9a40bc26120f4540e4e09b75ffb547). The limits matter: * Prompts and file content explicitly read through Warrant still go to the configured inference provider. Never expose a file that the provider must not see. * Grok's parent process requires network access for authentication and inference. Warrant does not yet enforce a raw-network allowlist or OS-level containment. * xAI documents child-network blocking for strict/read-only sandbox profiles on Linux, but not on macOS. A same-user process or direct invocation of the pinned binary can bypass this application boundary. * `privacy-locked` limits Warrant-brokered reads; the template alone cannot stop an unmanaged process from reading or transmitting host files. If an organization already enforces host egress, xAI says `cli-chat-proxy.grok.com` and `auth.x.ai` are the core inference/authentication hosts, while `storage.googleapis.com` and the update/sync hosts are optional. Blocking those optional hosts is useful defense in depth, but it is not sufficient proof: the 0.2.93 wire capture also observed repository bundles sent through the core proxy. Warrant does not configure that outer firewall today. xAI's current references describe the [Grok Build install and launch flow](https://docs.x.ai/build/overview), [CLI controls](https://docs.x.ai/build/cli/reference), [enterprise configuration, network, sandbox, and permission behavior](https://docs.x.ai/build/enterprise), [`GROK_HOME` and configuration scopes](https://docs.x.ai/build/settings), and [MCP server configuration](https://docs.x.ai/build/features/mcp-servers). ### Upgrade ```sh brew update brew upgrade cerebral-systems/tap/warrant warrant --version cd /absolute/path/to/workspace warrant setup claude --policy read-only warrant doctor claude ``` Repeat setup for every managed profile and workspace, using its intended policy. Old profile evidence fails closed after the implementation changes. ### Uninstall Remove every workspace integration before uninstalling Homebrew's package: ```sh cd /absolute/path/to/workspace warrant uninstall claude brew uninstall cerebral-systems/tap/warrant ``` `warrant uninstall claude` removes Warrant's workspace integration, not Claude Code. The current Homebrew uninstall leaves the owner-private runtime and managed shell PATH marker for safe upgrade/recovery; complete one-command purge is not implemented yet. ### Current security ceiling v0.3.0 reports an **integrated** application boundary. It is not an OS sandbox, credential broker, or formal `strict_verified` runtime. A separate same-user process with ambient filesystem, shell, credential, or raw-network access can bypass the local gateway. Read Security architecture before relying on it for sensitive work. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/quickstart.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.