Quickstart

• A Keydris account. Create one if you do not already have one.
• A registered agent with a policy assigned in the Keydris console. Copy its Agent ID; you will use it in the commands below. See Policies if you have not created one yet.
• Node.js 20+ with npm. The npm package supports Windows, macOS, and Linux on x64 and ARM64.
• Claude Code or the OpenAI Codex CLI installed and available in your terminal.

Pick your harness and replace <agent-id> with the Agent ID from the console:

$ sudo apt-get install bubblewrap socat

$ npm install -g @keydris/cli$ keydris init claude-code <agent-id>  # configures and signs in when needed$ keydris status  # checks the setup$ keydris run -- claude  # starts a governed Claude session

keydris init opens browser sign-in when this machine does not already have a valid identity for the selected agent. You normally do not need to run keydris login first. If init reports that sign-in is incomplete, finish it with keydris login before starting the proxy.

$ command -v keydris  # no output means the shell cannot find it$ echo "$(npm config get prefix)/bin"  # npm's global bin directory$ echo "$PATH"  # must contain that directory

$ export PATH="$(npm config get prefix)/bin:$PATH"

$ rm -rf ~/.keydris-data/identity/*

On macOS or Linux, you can use the native stable-channel installer instead of npm. It verifies the downloaded binary checksum, and this path does not require Node.js:

$ curl -fsSL https://get.keydris.com/keydris-cli/install.sh | bash$ keydris version  # confirm the installation

1. npm install installed a small JavaScript launcher and the native Keydris binary for your operating system.
2. init saved the Agent ID, generated the local CA, wrote the required Claude Code settings or Codex hooks, signed this device in when needed, and read the governed origins from the agent's assigned policy. The policy itself remains managed in Keydris, not in local CLI flags.
3. proxy up started the brokered egress proxy as a background process. It prints the log path and the command used to stop it.
4. status checked the stored identity, Agent ID, policy-derived scope, harness configuration, and control-plane reachability.
5. Starting the harness began a session. Claude Code uses the lifecycle hooks written by init; Codex uses the Keydris wrapper. The session receives a short-lived KIT and renews it during long-running work.

$ keydris status  # identity, agent, harness, scope, and control plane$ keydris proxy scope list  # origins detected from the assigned policy

Check that the Agent ID is correct, the identity is valid, the control plane is UP, and your selected integration is wired. The scope should list the origins governed by the assigned policy. If init could not detect that scope, the first successful session refreshes it.

Ask the agent to run one shell command your policy permits, then one it rejects. Seeing both outcomes is the fastest way to confirm that command governance is active before relying on it.

agent → shell
$ git status

command rule matched · read-only Git operation

ALLOW
policy permits
→ the harness executes the command

agent → shell
$ git push --force origin main

same agent · more authority requested

REJECT
reason: command rule denied
→ blocked before execution · recorded

$ keydris logs  # print the local ledger and verify its hash chain

You can also open Audit in the Keydris console for the organization-level view. Decision and execution outcome are separate facts: an allowed action can still fail at the provider.

• If init cannot open a browser on a remote machine, run it first so the Agent ID is saved, then use keydris login --no-browser. Open the printed URL in a browser to finish sign-in.
• Run keydris status first when setup looks wrong; it reports expired identity, missing harness configuration, scope problems, and control-plane reachability.
• Restart the background proxy with keydris proxy down followed by keydris proxy up. Its log is stored under ~/.keydris-data/proxy.log.
• If a native tool does not trust the generated CA, rerun your init command with --trust-store. This changes the operating system trust store and may require elevated privileges.
• For every available command and cleanup instructions, see the CLI reference.