Apus pairs with 1Password in four independent ways:

Requirements

Resolve config secrets with the plugin

Enable the bundled plugin and create its service-account token file. Export the service account's token as OP_SERVICE_ACCOUNT_TOKEN in the shell you run this in first — the block writes that value to disk and then clears it from the environment, so without it you get an empty token file:

apus plugins enable onepassword
mkdir -p ~/.apus/credentials/onepassword
chmod 700 ~/.apus/credentials/onepassword
printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \
  ~/.apus/credentials/onepassword/service-account-token
chmod 600 ~/.apus/credentials/onepassword/service-account-token
unset OP_SERVICE_ACCOUNT_TOKEN

When APUS_STATE_DIR is set, use that directory instead of ~/.apus. Then generate and apply a SecretRef plan:

apus onepassword secretref setup \
  --openai-id op://Automation/OpenAI/credential \
  --anthropic-id op://Automation/Anthropic/credential \
  --plan-out ./apus-1password-secrets-plan.json

apus onepassword secretref status
apus secrets apply --from ./apus-1password-secrets-plan.json --dry-run --allow-exec
apus secrets apply --from ./apus-1password-secrets-plan.json --allow-exec
apus secrets audit --check --allow-exec
apus secrets reload

The setup command requires at least one target. Before the plan is applied, status may report that the provider is not configured while still reporting prerequisites ready: yes; after apply, ready: yes confirms the provider, trusted op executable, and accepted non-empty token file are all ready.

The plugin accepts native op://<vault>/<item>/<field> and op://<vault>/<item>/<section>/<field> references. It resolves only registered Apus credential targets, bounds parallel op read calls, and forces desktop-app integration off. See the plugin guide for manual configuration, custom targets, and the separate audited agent tool.

The 1password skill for agents

Apus bundles a 1password skill that teaches agents to select an available auth mode, verify access, and prefer op run or op inject over writing secret values to disk.

Agents use it for workflows that intentionally exceed the plugin's narrow contracts, for example creating or rotating an item or injecting credentials into a one-off command. When a credential is already wired to an Apus SecretRef target, the owning Apus workflow should resolve it; the agent does not need to call op directly.

Official 1Password MCP server

The official MCP server is a beta desktop workflow for 1Password Environments. It requires the 1Password desktop app and explicit approval for each interaction. It can manage environment variable names and mount values into a local process through an in-memory .env file; secret values are not returned to the MCP client or model.

It does not provide headless service-account access to arbitrary vault items, and the Apus plugin does not call it. If an MCP-managed Environment launches Apus with variables already mounted, use Apus's env SecretRefs for those values. Use the plugin when the Gateway itself should resolve 1Password references on startup or reload.

Browser sign-in with 1Password for Claude

1Password for Claude lets Claude request a login while the 1Password browser extension fills the credential directly into the page over an encrypted channel. The secret never enters the model context, the transcript, or Apus. When Apus runs the claude-cli backend with Claude Code's Chrome integration enabled, agent tasks can use that flow for websites that need a real signed-in session.

What this requires, beyond the backend itself:

Before wiring this into Apus, verify the pieces in an interactive session on the gateway host: run claude --chrome, confirm the extension connects, and check that the claude-in-chrome tools include the credential tools. If they do not appear there, they will not appear through Apus either.

One-time passcodes are filled by 1Password on the same page; never relay verification codes or passwords through chat. Headless or remote gateways cannot use this flow today because the approval and the browser both live on the gateway host.

Security notes

Troubleshooting

Homebrew command symlinks

If a manual exec provider reports command must not be a symlink for /opt/homebrew/bin/op or /usr/local/bin/op, use the plugin setup flow. Manual exec providers require a non-symlink command. Resolving the Homebrew link to a versioned Caskroom path works only while that version remains installed; a later package upgrade or cleanup can remove it.

The plugin resolves op from the Gateway process's PATH for each resolver request, then checks the real executable and its parent directories before passing the service-account token. An existing CLAW_1PASSWORD_OP override can name the stable absolute Homebrew link and receives the same checks. The plugin follows a replacement link after an upgrade without storing its versioned target in apus.json. Group- or other-writable executables still fail, as do parent directories that let another user replace the checked path.

Before migrating, map every existing credential target to the exact 1Password reference its old command reads. A manual provider may put that reference in args and use an unrelated SecretRef id; copying that id into the plugin would select a different secret or fail. Choose an unused provider alias with --provider-alias <alias> if onepassword already names a manual provider: replacing that provider would also change unlisted references that use its alias. Create the plugin token file as shown above, then generate a plan with explicit mappings, for example:

apus onepassword secretref setup \
  --target 'models.providers.anthropic.apiKey=op://Automation/Anthropic/credential' \
  --target 'models.providers.openai.apiKey=op://Automation/OpenAI/credential' \
  --plan-out ./apus-1password-secrets-plan.json

Inspect the plan's provider alias and every target before using the status, dry-run, apply, audit, and reload commands above. Remove an old manual provider only after all references to it have moved; include auth-profile and channel credentials in that check.