> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # keeper > Configure, inspect, test, and audit Crewship's Keeper security controls from the CLI. # `crewship keeper` The Keeper command group controls the credential-access judge and the workspace watchdog. It also exposes the audit trail, human resolution path, evaluator controls, and health checks. Use `--format json` (or `yaml`/`ndjson` where supported) when another program will consume the result. The command tree itself is generated by the binary: ```bash theme={null} crewship commands --format json | jq '.commands[] | select(.path == "keeper")' ``` ## Authentication and scope Except for `keeper eval`, every command below calls the server in the current authenticated workspace and requires an OWNER or ADMIN workspace role. The server remains the authority for authorization; a CLI-side permission hint does not grant access. `keeper status` includes both instance server status and the workspace governance overlay. `keeper eval` is different: it opens the local Crewship SQLite database read-only, dials models from the machine running the CLI, and does not call the server or require CLI authentication. Pass `--endpoint` and `--incumbent` when the server's judge is configured only through environment variables, because those server settings are not automatically available to the local replay. All commands also accept the normal global CLI flags, including `--server`, `--workspace`, `--format`, and `--no-color`. See [CLI overview](/cli/overview) for those shared flags and authentication setup. ## Safety and side effects * Keeper is fail-closed. An unavailable, slow, or unparseable judge produces a DENY rather than an ALLOW. `keeper config set --enabled on` is refused when no endpoint/model is configured. * `enable`/`disable` and instance configuration affect the next credential request. For runs started afterwards, enabling Keeper withholds SECRET credentials until the request is allowed; a running container keeps the environment it already received. * `ask` uses the real credential-request decision path. It can create an audit request, an inbox escalation, and a health-window sample; it does not merely simulate a response. * `resolve` is a real human (or explicitly named reference-model) adjudication and is written to the journal. Four-eyes rules can refuse an OWNER from resolving an escalation raised by that owner's agent; L4 and any configured tier floor can require human approval. * `review run`, `aux test`, `judge test`, and hosted judge tests make model calls. Hosted evaluator calls can spend tokens; review runs are rate-limited instance-wide. `findings test` makes no model call, but creates a clearly labelled real inbox item. * `aux reset` and `config reset` use DELETE-style reset behavior. They remove local overrides, not the server's environment configuration. `profile reset` and `model clear` reset only their respective workspace/instance settings. * Turning `auto-lease` off does not extend leases already issued. Existing leases still expire; disabling auto-lease only stops future automatic lease issuance. * `keeper eval` never writes the database. It can still make many model calls: one incumbent plus each distinct candidate, multiplied by `--passes`. ## Workspace governance These commands update one workspace governance field at a time unless noted. | Command | What it does | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `keeper status` | Shows server judge status and workspace governance: enabled state, endpoint/model, Ollama reachability, secret count, contact, DENY-notify threshold, effective four-eyes rule, and auto-lease. | | `keeper enable` | Enables the behavioral watchdog for this workspace. It is opt-in and off by default. | | `keeper disable` | Disables the behavioral watchdog. This does not erase its configuration or audit history. | | `keeper contact ` | Resolves a workspace member by email and routes findings to that OWNER/ADMIN. | | `keeper contact --clear` | Clears the named contact and returns to MANAGER+ fanout. Email and `--clear` cannot be combined. | | `keeper threshold <1-10>` | Sets the risk at or above which a DENY also reaches the inbox. ESCALATE always notifies; the default is 7. | | `keeper second-approver enable` | Requires a different human to resolve credential escalations raised by the approver's own agent. | | `keeper second-approver disable` | Disables the workspace toggle; a credential tier can still force the rule. | | `keeper requests` | Lists recent decision-audit rows for agents in the current workspace. | | `keeper history ` | Shows append-only state transitions, actors, risk, exit code, and reasons for one request. An empty result does not distinguish an old/foreign/missing ID. | | `keeper health` | Prints the rolling decision window. It exits non-zero when the Keeper collapse alarm is standing, making it suitable for cron. The window is in memory and empties on restart. | `keeper contact` rejects a missing member and rejects a member whose role is not OWNER or ADMIN. `keeper requests` has these pagination flags: ```text theme={null} --limit int maximum rows (default 50; server caps at 200) --offset int row offset (default 0) ``` ### Auto-issued leases ```bash theme={null} crewship keeper auto-lease status crewship keeper auto-lease set 15m crewship keeper auto-lease off ``` `set` accepts a Go duration from 60 seconds through 30 days (`720h`). It is opt-in and applies only to L3/L4 grants approved by Keeper, including approved credential escalations. It never shortens a longer manually assigned lease. `off` restores standing grants for future approvals but does not un-lease already leased grants. ## Instance judge `keeper config` controls the instance-wide native Ollama judge. `get` shows the effective value and whether it came from an instance override, server environment, or built-in default. It does not configure hosted providers. ```bash theme={null} crewship keeper config get crewship keeper config set --endpoint http://192.168.1.40:11434 --model qwen2.5:7b --enabled on crewship keeper config set --enabled off crewship keeper config set --model "" crewship keeper config set --enabled inherit crewship keeper config reset ``` The empty model value clears that override. `set` is a partial update and requires at least one flag. Its flags are: | Flag | Values and behavior | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `--enabled` | `on`, `off`, or `inherit`; `inherit` drops the instance override. | | `--endpoint` | Native Ollama judge URL; an empty value inherits `KEEPER_OLLAMA_URL`. This is judge-scoped and does not move the embedder or summarizer. | | `--model` | Judge model; an empty value inherits `KEEPER_MODEL`. | | `--judge-timeout` | Positive duration such as `40s`; empty restores the built-in default. A judge slower than the budget denies requests. | `config reset` removes every instance override and returns to `KEEPER_ENABLED`, `KEEPER_OLLAMA_URL`, and `KEEPER_MODEL`. It does not delete those server settings. ### Workspace governance model `keeper model` selects the model backing the workspace's credential gatekeeper and auxiliary evaluators. It can use `ollama`, `anthropic`, or `openai_compat`. Hosted providers use an optional vault `ENDPOINT_URL`/`API_KEY` credential and are workspace-scoped; a revoked credential degrades to the instance judge. Selecting a model does not enable the watchdog. ```bash theme={null} crewship keeper model get crewship keeper model set --provider ollama --model qwen2.5:3b-instruct crewship keeper model set --provider openai_compat --model gpt-4o-mini --credential cred_abc123 crewship keeper model clear ``` `model set` requires `--provider` and `--model`; `--credential` is optional. `--model` is limited to 200 bytes by the CLI/server validation. `clear` falls back to the instance/server default. ### Judge checks ```bash theme={null} crewship keeper judge test crewship keeper judge test --endpoint http://localhost:11434 --model qwen2.5:7b crewship keeper judge test --provider anthropic --model claude-haiku-4-5 --credential ANTHROPIC_KEY crewship keeper judge models --endpoint http://192.168.1.222:11434 ``` `judge test` checks reachability, a pulled model, a valid verdict, and latency inside the credential-path budget. It exits non-zero when any stage fails. With a non-`ollama` provider it uses the hosted test endpoint; `--model` is required and `--credential` may be a stored credential name or ID. `judge models` lists models served by the saved or overridden endpoint and exits non-zero when the endpoint cannot be queried. | Command | Flags | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `keeper judge test` | `--endpoint`, `--model`, `--provider` (`anthropic` or `openai_compat` for hosted mode), `--credential` (stored credential name/ID) | | `keeper judge models` | `--endpoint` | ## Judge profile `keeper profile` controls which credential-judge capabilities are active. The three presets are `lean`, `standard`, and `thorough`; flags override individual capabilities and `inherit` follows the selected profile rather than forcing the capability off. ```bash theme={null} crewship keeper profile get crewship keeper profile set thorough crewship keeper profile set lean --prompt-budget 3500 crewship keeper profile set --evidence-facts credential_bound_to_agent crewship keeper profile reset ``` `profile set [lean|standard|thorough]` accepts: | Flag | Values and behavior | | ----------------------- | --------------------------------------------------------------------------------------------- | | `--evidence` | `on`, `off`, or `inherit`; include computed facts in the prompt. | | `--evidence-facts` | Comma-separated facts; empty means all available facts. | | `--hard-gate` | `on`, `off`, or `inherit`; refuse an unbound L3/L4 credential before the model call. | | `--precedent` | `on`, `off`, or `inherit`; RESERVED, stored but not implemented. | | `--precedent-n` | `1`–`10`; RESERVED, stored but not implemented; empty follows the profile. | | `--consistency-samples` | Odd `1`–`9`; RESERVED, stored but not implemented; `1` means sampling off. | | `--escalate-from` | `1`–`4` starts human approval at that tier; `5` means never; `0` leaves the tier table alone. | | `--prompt-budget` | Token cap; empty follows the profile and `0` means no cap. | `profile reset` clears the profile and all seven capability overrides without touching endpoint, model, or timeout wiring. ## Evaluator models and reviews `keeper aux` configures the instance-level evaluator slots used by Keeper Reviews and the watchdog. Valid slots are `curator`, `behavior`, `memory_health`, and the other slots reported by `aux list`; use the list output as the authoritative catalog for the running server. Hosted slots bill per token, while Ollama does not. ```bash theme={null} crewship keeper aux list crewship keeper aux set behavior --provider anthropic --model claude-opus-5 crewship keeper aux set behavior --credential prod-anthropic crewship keeper aux set memory_health --timeout 45s crewship keeper aux use-judge crewship keeper aux test behavior crewship keeper aux reset behavior crewship keeper aux reset --all ``` `aux set ` has these flags. Only passed fields change; an empty value clears that override or returns it to inheritance. | Flag | Behavior | | -------------- | ------------------------------------------------------------- | | `--provider` | `anthropic`, `openai`, or `ollama`; empty inherits. | | `--model` | Model ID; empty inherits. | | `--timeout` | Positive duration such as `30s`; empty inherits. | | `--credential` | Stored vault `API_KEY` name; empty uses the server's own key. | `aux use-judge` points every evaluator at the local instance judge and avoids per-token cost, at the expense of using the local model's capabilities. `aux reset [slot]` requires either a slot or `--all`: ```text theme={null} --all clear the override on every slot (cannot be combined with a slot) ``` Resetting after `use-judge` can put slots back on hosted defaults and therefore resume token billing. `aux test ` makes one real evaluator call and shares the judge-test probe rate limit. Run one evaluator immediately with: ```bash theme={null} crewship keeper review run ``` `` is `skill-review`, `behavior`, `memory-health`, or `negative-learning`. Without subject flags, the server derives a suitable subject. Available flags are: ```text theme={null} --crew crew scope (defaults to your only crew) --agent agent under review --skill skill-review subject --tool behavior tool name --tool-args behavior tool arguments --trigger negative-learning: run_failed, guardrail_warn, guardrail_error, or keeper_execute_deny --failure negative-learning failure text ``` Review runs are real decisions: DENY/ESCALATE findings enter the Keeper inbox and the request is available through `keeper history`. They are rate-limited to 60 per hour by default. ## Requests, testing, and resolution ### Ask the judge `keeper ask` requires all four flags and accepts agent/crew slugs or IDs: ```text theme={null} --agent agent slug or ID --crew crew slug or ID --credential credential name as shown by credential list --intent stated purpose; the credential tier's minimum applies ``` It follows the same tier floors, audit, inbox, and health behavior as an agent request. It does not grant a credential or execute a command. ### Resolve an escalation ```text theme={null} crewship keeper resolve --decision allow|deny [--reason ] ``` Flags: ```text theme={null} --decision required: allow or deny --reason recorded on the decision and journal --adjudicator optional AI model name; records a reference adjudication rather than a human ground-truth label ``` Only ALLOW and DENY are accepted. Four-eyes policy can refuse the call, and that refusal is recorded. Find waiting escalations with `crewship inbox list`. ### Verify finding delivery ```bash theme={null} crewship keeper findings test ``` This sends one synthetic, non-blocking test finding through the real inbox writer and prints the resolved recipients. It does not call a model, but it does create a real labelled inbox item. It exits non-zero if no recipient is found. ## Local model evaluation `keeper eval` replays stored Keeper prompts against human-resolved labels and candidate models. It is read-only, but can be expensive and may take minutes. At least one candidate is required; the incumbent is replayed as the baseline. Human-labelled rows are kept ahead of other rows when `--limit` is used, and the report withholds rates when the corpus is too small for a meaningful human sample. Candidate specs may be local model names or `anthropic/` / `openai/`; hosted candidates use API keys from the CLI process environment, not stored vault credentials. ```text theme={null} --endpoint model endpoint from this machine; defaults to configured judge endpoint --incumbent baseline model; defaults to configured judge model --candidate candidate to score; repeat this flag --explain print recorded versus replayed decisions per row --limit corpus cap; 0 means all --passes replay passes; default 3, temperature 0.1 --tolerance allowed extra guard-downgrade rate over incumbent ``` The default is three replay passes per prompt (`--passes 3`); `--candidate` is repeatable and defaults to no candidates, so it must be supplied. `--limit 0` means the complete corpus, `--tolerance 0` allows no additional dangerous guard downgrade, and `--explain` is off by default. Human-labelled rows are reported separately from rows labelled only by the incumbent. Human agreement rates are withheld below 20 human-labelled rows and benchmark-grade messaging starts at 100. Human-readable output is a summary/table; `--format json` or `--format ndjson` is suitable for automation. Safety-first scoring marks a candidate non-viable if it downgrades more DENY/ESCALATE decisions to ALLOW than the incumbent, regardless of raw agreement. The endpoint is contacted from the local machine and protected by the CLI's trusted-endpoint restrictions. ## Full command inventory The following is the complete Keeper tree from the current command manifest. Commands with no flags are included so the page does not silently omit a read-only or nested action: ```text theme={null} keeper ├── ask ├── auto-lease: off | set | status ├── aux: list | reset [slot] [--all] | set [--credential --model --provider --timeout] | test | use-judge ├── config: get | reset | set [--enabled --endpoint --judge-timeout --model] ├── contact [--clear] ├── disable ├── enable ├── eval [--candidate --endpoint --explain --incumbent --limit --passes --tolerance] ├── findings: test ├── health ├── history ├── judge: models [--endpoint] | test [--credential --endpoint --model --provider] ├── model: clear | get | set [--credential --model --provider] ├── profile: get | reset | set [--consistency-samples --escalate-from --evidence --evidence-facts --hard-gate --precedent --precedent-n --prompt-budget] ├── requests [--limit --offset] ├── resolve [--adjudicator --decision --reason] ├── review: run [--agent --crew --failure --skill --tool --tool-args --trigger] ├── second-approver: disable | enable ├── status ├── threshold <1-10> └── watch: clear | get | preset: add | list | remove | set ``` `keeper watch` authors the workspace watchdog policy. `watch set ` replaces only the free-form rules; `-` reads them from stdin. `watch clear` clears free-form rules but leaves presets untouched. `watch preset list` shows the catalog and enabled entries; `preset add ` and `preset remove ` validate the key and update the complete preset set. The preset keys are `credentials`, `destructive`, `egress`, `memory`, and `secret_files`. All watch reads and mutations return the current governance object in structured formats. Human output shows every preset with a check mark and the free-form rules; an empty rule set is shown as `(none)`. `watch set` accepts at most the server's maximum watch-spec length (currently 4096 bytes) and authoring a spec does not enable the watchdog. ## Exact command references These headings mirror the live Cobra command paths; the detailed behavior is described in the sections above and in the full command inventory. ### `crewship keeper ask --agent --crew --credential --intent ` Asks the credential-access judge to evaluate a request. ### `crewship keeper contact ` Sets the security contact for Keeper findings. ### `crewship keeper disable` Disables the workspace Keeper watchdog. ### `crewship keeper enable` Enables the workspace Keeper watchdog. ### `crewship keeper eval` Replays recorded Keeper decisions against candidate models. ### `crewship keeper health` Shows the recent Keeper decision window. ### `crewship keeper requests` Lists recent Keeper decision-audit requests. ### `crewship keeper second-approver disable` Disables the second-approver requirement. ### `crewship keeper threshold <1-10>` Sets the DENY-notify risk threshold. ### `crewship keeper watch` Groups workspace watchdog policy actions. ### `crewship keeper watch clear` Clears the free-form watchdog rules. ### `crewship keeper watch get` Shows the current watchdog policy. ### `crewship keeper watch preset` Groups watchdog preset actions. ### `crewship keeper watch preset add ` Enables a watchdog preset. ### `crewship keeper watch preset list` Lists watchdog presets and their enabled state. ### `crewship keeper watch preset remove ` Disables a watchdog preset. ### `crewship keeper watch set ` Replaces the free-form watchdog rules. ## Related commands * [CLI overview](/cli/overview) * [Keeper architecture guide](/guides/keeper) * [Credentials](/guides/credentials) * [Keeper Reviews panel](/guides/keeper-reviews-panel) * [`crewship commands`](/cli/commands)