Skip to content

AI assistants

Your assistant does the setup and runs the commands. You keep the secrets.

opv ships an agent skill, a version-matched guide and a machine-readable contract, so a coding assistant can read every key's value state, propose your keys, environments and targets, check readiness, and run authorized commands through opv run, which delivers credentials directly to those processes and keeps secret values out of model-visible results. You sign in, run opv apply, and enter every value in 1Password or at opv's masked prompt. A key declared with file = "<path>" (a PEM, a certificate chain) is stored exactly with opv set <KEY> --env <env> --from-file <PATH> in your own terminal; the assistant hands that command over, never reads, writes or copies the file, and pasting a multi-line value into the 1Password app turns its line breaks into spaces. The model never sees a value.

The agent skill

The skill is a short SKILL.md embedded in the opv binary, installed where your assistant looks for skills. It tells the assistant to start every session from the installed binary, to ask before anything that writes, and to hand sign-in, opv apply and secret values to you. It carries the version of the opv that installed it, so it never describes commands your opv does not have.

  • Claude Code.claude/skills/opv/SKILL.md--target claude
  • Codex and other .agents clients.agents/skills/opv/SKILL.md--target codex

Install it

Installing opv with npm or the install script registers the skill for you, in every project, for both agents. To do it yourself, or after a Homebrew or cargo install:

$ opv skill install --user

Or for one project only (its git top level, or --project <dir>), committed with the code so the whole team gets it:

$ opv skill install

To opt out, set OPV_NO_SKILL=1 or pass the install script --no-skill. CI installs never register it. --target claude or --target codex writes one agent's copy; the default is both.

Check and update

See every installed copy, its version, and whether it matches this opv:

any directory
$ opv skill status
$ opv skill install --user     # re-register by hand, for example after --no-skill

Only the installers (the install script and the npm postinstall) and opv skill install write the skill; no other opv command writes your home directory. After a Homebrew, cargo or manual upgrade the old copy stays, and opv skill status or opv doctor reports it as outdated. A copy you edited is kept; opv skill install --force replaces one. Project copies are updated with opv skill install in that project. After upgrading from 0.11 or earlier, also run opv mcp install again: the MCP tool set changed in 0.12.0.

Guide, schema, readiness

The skill points the assistant at three commands of the installed binary, so its instructions always match the opv it is driving:

your project
$ opv guide agent        # the full agent guide for this version: rules, flows, exit codes
$ opv schema             # every command, flag, effect, JSON document and error code
$ opv ready --json       # what is ready, what is not, who acts next (read-only)

opv ready and opv doctor never write 1Password, whoever runs them. Every failure has a stable error.code, and a human_required step is handed to you, not attempted.

Skill, CLI or MCP

Agent skill

Tells the assistant how to work with opv: start from the installed binary's guide, schema and readiness, ask before anything that writes, hand sign-in, opv apply and values to you.

Instructions only. It runs nothing by itself.

opv CLI

Everything opv does. Anyone can inspect and propose (opv inventory, opv needs, opv next, opv propose); a person applies (opv apply) and enters values (opv set, opv import); CI or a person delivers (opv sync, opv ready --gate).

An assistant may run authorized commands through opv run, which hands the values to the child, not the model. Person commands (login, setup, config edit, apply, set) need your own terminal and refuse CI and agent mode.

MCP server (optional)

Five tools: opv_state, opv_next and opv_explain read; opv_propose returns a contract diff and a plan id and writes nothing; opv_import_local is the one writer, into a local-tier environment only. Every tool has the same CLI command.

Metadata only: never accepts or returns a secret value, never runs a command, never applies a plan and never syncs. Built into opv: opv mcp serve; opv mcp install registers it.

MCP is optional. Through it an assistant inspects value states and proposes changes; it never applies one. A proposal writes nothing and ends with a plan id: you run opv apply <plan_id> in your own terminal, and the 1Password app asks you to authorize the writes. Every document carries a typed next (kind, actor, command): the assistant runs only an assistant step and hands a person step to you verbatim. A sync never happens over MCP; CI or you run opv sync <env> --expect-plan <id>. Sign-in, secret values and permission grants always stay with you. MCP interface

Running commands

An assistant may run a command it is already authorized to run (tests, a build, a provider client, a diagnostic) through opv run <env> -- <command>. opv delivers the actual values to that child process, as environment variables or, for keys declared as files, in a private RAM-only directory removed when the child exits. The model receives only the command's results, which must carry no value. A child needing credentials is not by itself a reason to hand the command back to you.

  • Metadata first. When opv's own value-free documents answer the question (opv ready --json, opv inventory --json, opv run --preview), the assistant uses them instead of running anything.
  • Bounded diagnostics. When a check must look at a value, a bounded child run through opv returns only a fixed classification (such as json_object or not_valid_json) or an allowlisted error code.
  • No exfiltration. No environment dumps, no printed values or exceptions that contain one, no encoded or transformed values, no secret copies the child keeps, and the assistant never reads a delivered file.
  • Masking is defense in depth. op run masks values a child prints, but that does not make arbitrary output safe, and opv does not sandbox the command: other variables and your sign-in are inherited.

Your existing authorization still applies within its scope: credential delivery alone needs no extra approval, while new external effects still need yours. Sign-in, secret entry, opv apply, a guarded environment's --confirm and your project's own approval gates stay human steps. This is the CLI; the MCP tools never run a command.

Sign-in reach. The assistant's commands see only a 1Password session its own process can use. Signing in in another terminal does not reach it. Either use the 1Password desktop app integration (Settings > Developer > Integrate with 1Password CLI; on WSL also "Use 1Password CLI with WSL"), or start the assistant inside opv login --account <ID> -- <assistant>. If its commands fail with op_not_signed_in, it asks you for that step and then resumes; it never asks for a password, token or session in chat. New in 0.22.0: or give it its own read-only agent identity, which needs no session of yours.

Agent identity (read-only) New in 0.22.0

From opv 0.22.0, your assistant can run opv unattended as its own identity instead of borrowing your write-capable session. It is the same model as CI: a 1Password service account that can only read one environment's vaults, with the CI reader's grants and the same 90 days. Its token is kept in this machine's OS credential store (macOS Keychain, Windows Credential Manager, a Secret Service keyring on Linux, and on WSL the Windows Credential Manager of the Windows user), and never passes through the assistant, the chat, argv, a file or its environment.

Every identity delivers through the same path, and none of them sees a value. Only a person changes values. 1Password vault access is the only permission. Deploys belong to CI or a person.

IdentityCreated withToken livesLifetime1Password accessRunsWrites 1Password
Personopv login or the 1Password appthe app or the shellsessionwhat the person can openeverythingyes: the only identity that changes values
CI readeropv access <env> --create --github <repo>GitHub secret90 daysread, boundary vaultsinventory, plan, readynever
CI deploy identity… --target <t> --create --github <repo>GitHub secret90 daysread boundary, read and write its state vaultsync, deployvalue-free delivery evidence only
Agent identityopv access <env> --create --agentthis machine's OS store90 daysread, boundary vaults (the CI reader's grants)run, plan, ready, status, doctornever
  1. You create it, once per environment, in your own terminal. The assistant hands you this command and never runs it (it refuses an assistant):
    $ opv access <env> --create --agent
    It shows the grants, asks once, creates <project>-<env>-agent-<machine>, checks it reads exactly those vaults and stores the token. A production-tier environment also needs --confirm <env>; --name <machine> overrides the hostname.
  2. Set OPV_IDENTITY=agent where you start the assistant (its MCP server entry, or the shell it starts in). It then runs commands as usual:
    the assistant
    $ opv ready --json
    $ opv run dev -- cargo test
    opv reads the token itself and hands it only to its own op calls, never to the assistant's shell or to the child of opv run. An environment with no agent identity stops with agent_identity_not_installed; opv never falls back to your session.
  3. Check it without changing anything:
    $ opv doctor --env <env>
    The op identity row reads, for example, agent shop-dev-agent-laptop for dev (read-only by grant; token from macOS Keychain, durable; reads 2 of 2 vaults; expires 2027-02-15, in 90 days). opv ready --json (and MCP opv_state) carries an identity array, one value-free object per environment; assistant_on_person_session means the assistant is on your own session, which can write.
  4. Rotate it before 90 days. When opv doctor warns agent_expiring (14 days ahead), you run opv access <env> --rotate --agent (without <env>, every agent identity on this machine), then delete the old account in 1Password (Developer > Service accounts), as its Do: line says.

What it cannot do. It never writes 1Password and never deploys. 1Password never grants a service account a Private vault, so personal values do not reach it. Each refusal is your step, and the assistant hands you its Next:; it never suggests OPV_IDENTITY=person to get past one.

  • own_session_required: a write or a sync: you run it in your own terminal, or CI's deploy job runs the sync
  • agent_identity_not_installed: no agent identity for this environment on this machine: you run the create command
  • agent_rejected: 1Password no longer accepts the token (revoked, deleted or expired): you rotate it
  • agent_store_locked: the OS store is locked or would prompt; opv never waits: you unlock it
  • agent_store_unavailable: no usable OS store; opv never falls back to a file

What it does not defend

An assistant with a shell that runs as the same OS user can reach the token: it can read the OS store, read the environment of the op run process, or make an authorized child print a value. opv's guarantee is its own outputs: no opv output carries the token or a value. What limits the damage: read-only, one environment, 90 days. Optional hardening: run the assistant as a separate OS user or in a container that cannot reach your store, and start it where no person session reaches it (no desktop-app CLI integration in its terminal, not inside opv login --). Agent identity in the setup guide

The setup path

  1. Install the tools. opv, the 1Password CLI, and your target's CLI. opv doctor names what is missing.
  2. Sign in, privately. You run opv login --account <you> in your own terminal; the password goes only to 1Password's prompt. New in 0.14: to keep a shell signed in across commands without the desktop app, you run eval "$(opv login --shell)" (fish: opv login --shell=fish | source). The assistant hands you that command and never runs it. A sign-in in your terminal reaches the assistant only through the desktop app integration or when you start it inside opv login (sign-in reach). New in 0.22.0: for unattended runs, you create a read-only agent identity once instead, so the assistant no longer needs your session.
  3. Propose, then you apply. The assistant proposes products, keys, environments and targets (opv propose, or opv_propose over MCP) and shows you the contract diff and the vaults, items and empty fields they need. You run opv apply <plan_id> in your own terminal; the assistant never runs it. Existing values are kept, and a generated configuration is changed through its generator.
  4. Enter the values. You type each one at opv's masked prompt (opv set <KEY> --env <env>), import a file with opv import, or type it in the 1Password app at the link opv gives. A key declared with file = "<path>" (a PEM, a certificate chain) is stored exactly with opv set <KEY> --env <env> --from-file <PATH> in your own terminal; the assistant hands that command over and never reads, writes or copies the file, and pasting a multi-line value into the 1Password app turns its line breaks into spaces. Never in chat, files or command arguments. For a local-tier environment only, the assistant may import a local file with opv_import_local.
  5. Check readiness. The assistant runs opv ready --json or opv next --json and reports names and value states only. It may run your tests or app through opv run and report their value-free results.
  6. Deliver. The assistant shows you opv plan <env>. CI, or you in your own terminal, runs opv sync <env> --expect-plan <id>, which refuses if anything changed, then opv ready --gate. The assistant never syncs.

Reference

Repository: github.com/matt-cochran/1password-vault