CLI & vocabulary

The npm package is the easiest cross-platform installation. It requires Node.js 20+ and selects a native binary for Windows, macOS, or Linux on x64 or ARM64.

$ npm install --global @keydris/cli$ keydris version  # confirm the installed build

On macOS or Linux, the native installer is an alternative that does not require Node.js:

$ curl -fsSL https://get.keydris.com/keydris-cli/install.sh | bash

Update with the same package manager that installed Keydris:

$ npm install --global @keydris/cli@latest  # npm-managed installation$ keydris upgrade  # native installer; stays on its configured channel

$ keydris init  # interactive: choose a harness and enter an Agent ID$ keydris init claude-code <agent-id>  # configure Claude Code$ keydris init codex <agent-id>  # configure OpenAI Codex$ keydris init claude-desktop <agent-id>  # configure Claude Desktop (macOS)$ keydris init codex-desktop <agent-id>  # configure the Codex desktop app (macOS)

Use the Agent ID created in the Keydris console. The policy is assigned there; the CLI does not select or override it. On a fresh machine, init opens browser sign-in and binds the local device identity to that agent. A valid identity already bound to the same agent is reused.

Claude Code setup is strict by default: Keydris enables the sandbox, fails if it is unavailable, and disables the unsandboxed escape. Add --trust-store to either explicit init command only when native tools need the Keydris CA in the operating system trust store. That change may require elevated privileges.

$ keydris login  # sign in again or renew the local identity$ keydris login --no-browser  # print the sign-in URL for a remote shell$ keydris whoami  # show the stored user, device, agent, and expiry$ keydris logout  # remove the local identity

$ keydris proxy up  # start the proxy in the background$ keydris status  # check identity, scope, harness config, and control plane$ keydris proxy scope list  # show policy-derived governed origins$ claude  # Claude Code: configured hooks own the session$ keydris codex [args...]  # Codex: wrapper owns the session$ keydris claude-desktop  # Claude Desktop: one governed session$ keydris codex-desktop  # Codex desktop app: one governed session$ keydris run -- <command> [args...]  # wrap another command in a Keydris session$ keydris proxy down  # stop the background proxy

proxy up backgrounds itself and prints its log path; no trailing & is needed. Proxy scope is detected from the agent's assigned policy and refreshed at session start, so there is no manual scope list to maintain.

keydris run -- is the harness-independent path. It opens a session, runs the command through the configured Keydris data plane, and revokes the session when the command exits.

$ keydris logs  # print the local evidence ledger and verify its chain$ keydris status  # diagnose the current setup$ keydris help  # show built-in command help$ keydris version  # print the build version$ keydris deinit claude-code  # remove Keydris entries from Claude Code$ keydris deinit codex  # remove Keydris entries from Codex$ keydris deinit claude-desktop  # remove the Claude Desktop integration$ keydris deinit codex-desktop  # remove the Codex desktop integration$ keydris doctor  # detailed read-only status and recovery guidance$ keydris skill [--brief]  # read the bundled agent skill or session briefing$ keydris telemetry [status|on|off]  # show or change anonymous install telemetry$ keydris reset --dry-run  # preview removal of local setup and certificates$ keydris reset   # reset the local setup and certificates, leaving the harness alone

Deinit preserves unrelated harness settings, but clears the stored Agent ID and detected policy scope. It leaves the generated CA files in place for a later setup. If you used --trust-store, remove that operating-system trust entry separately when it is no longer needed.

~/.keydris.toml

Release-channel and control-plane defaults installed by npm or the native installer.

~/.keydris-data/

Local identity, Agent ID, CA, session state, proxy log, and the hash-chained evidence ledger.

~/.claude/settings.json

Claude Code sandbox, CA environment, and lifecycle and command hooks written by keydris init claude-code.

A governed action resolves to exactly one of three decisions: ALLOW, REJECT, or APPROVAL REQUIRED. The labels below are supporting states and reasons that can appear alongside a decision:

Agent

an operator-managed identity for an AI workload.

Device

an enrolled installation on which an agent runs.

KIT

the short-lived runtime identity for one agent session.

Local proxy

the CLI's TLS-terminating egress proxy; it matches each governed request to a route before anything reaches the network.

Broker

the legacy authorization path in your environment, on the agent's side.

Reader

optional enforcement on your MCP servers, on the receiving side.

Policy

operator-authored rules governing an agent's actions.

Integration

an organization connection to an external system.

Resource

a selected repository, channel, MCP tool or resource, or other governable target.

Decision

what Keydris concluded about one governed action: ALLOW, REJECT, or APPROVAL REQUIRED. Exactly these three.

Reason

why a decision came out that way (for example scope mismatch, or authority verified). A reason travels under a decision; it is never the decision.

Outcome

what happened when an allowed operation was attempted, recorded separately from the decision.

Control plane

the Keydris service that makes the authority decision against current policy and revocation state.

Authority context

the decision inputs the Reader sends: the KIT, the action, the tool, the scope, and the resource.

Governed

resources you enroll + the policy you assign, for supported actions.

Stateless MCP

independent governed MCP exchanges without retained session continuity.

Stateful MCP

governed MCP exchanges that retain continuity across a related multi-step session.