op-agent

README

op-agent

op-agent gives local development tasks fast, batched access to 1Password without putting service-account credentials in repository files or command arguments. It combines a small Go CLI, an on-demand memory cache, and a thin mise environment plugin.

How it works

• Explicit setup of a 1Password service-account credential in macOS Keychain
• One op inject call for every cold batch of references
• Exact transport of multiline values, quotes, equals signs, Unicode, and trailing newlines
• An on-demand same-user daemon whose cache exists only in memory
• Native op passthrough for commands that do not use the cache
• Translation from mise task options to resolved, redacted environment values

Each repository maps environment names to 1Password references and selects the names each protected task needs.

Requirements

• Go 1.27 or a released op-agent binary
• The 1Password CLI
• mise when using the environment plugin

Local Keychain setup is available on macOS. Linux and CI callers supply OP_SERVICE_ACCOUNT_TOKEN and resolve each batch directly.

Install from source

go install github.com/azohra/op-agent/cmd/op-agent@v0.1.0

GitHub Releases also provides macOS and Linux archives with a SHA-256 checksum manifest.

Set up a local credential

The recommended first setup reads a service-account token through the signed-in 1Password desktop integration, then stores it in Keychain for ordinary use:

op-agent setup --from-ref 'op://vault/service-account/credential'
op-agent doctor

That first op read may show an interactive 1Password prompt. Runtime reads do not use the desktop session. Setup is idempotent; use --replace when rotating an existing credential. --token-stdin and an existing OP_SERVICE_ACCOUNT_TOKEN are also supported when a desktop reference is not appropriate.

op-agent setup also installs the mise plugin when mise is available. Use --skip-mise-plugin to manage that installation separately.

Configure a repository

The checked-in file names the plugin and declares only the keys each protected task needs:

[plugins]
op-agent = "https://github.com/azohra/op-agent.git"

[tasks.deploy]
run = "./scripts/deploy"

[tasks.deploy.env._]
op-agent = { keys = ["DEPLOY_TOKEN", "ACCOUNT_ID"] }

An owner supplies the reference map in an ignored mise.local.toml:

[env]
OP_REFS = """
DEPLOY_TOKEN op://vault/local-app/deploy-token
ACCOUNT_ID op://vault/shared/account-id
"""

Production differences are an overlay, not a second complete map:

[env]
OP_REFS_PROD = """
DEPLOY_TOKEN op://vault/production-app/deploy-token
"""

[tasks.deploy-prod.env._]
op-agent = { keys = ["DEPLOY_TOKEN", "ACCOUNT_ID"], environment = "prod" }

keys selects environment variable names. environment selects the reference overlay. account selects a separately stored service-account credential.

The plugin runs when mise resolves the environment for the task carrying the directive. A protected task refuses to run when its mapping or local setup is missing.

CI

CI supplies OP_SERVICE_ACCOUNT_TOKEN through its secret store and uses the same mapping and task contract. An explicit environment credential resolves one batch directly and is never copied into a daemon.

Commands

op-agent setup
op-agent doctor
op-agent env --keys NAME,OTHER --format json
op-agent read [--no-newline] op://vault/item/field
op-agent cache status
op-agent cache clear
op-agent cache stop

env also accepts OP_AGENT_KEYS, OP_AGENT_ENVIRONMENT, and OP_AGENT_ACCOUNT.

Unknown commands, including inject, execute the native op binary with the selected service-account credential. Stdout, stderr, signals, and exit status remain native to that process.

Cache behavior

The daemon starts on the first cacheable read and exits after eight idle hours. Entries expire after eight hours by default. Cache keys include both the credential account and the complete reference. Cold requests are serialized and rechecked so concurrent callers share one resolution instead of multiplying 1Password calls.

The mise plugin reports cacheable = false, keeping values out of mise's disk cache. The memory daemon provides warm reuse.

op-agent cache status reports counts only. It never lists reference names or values. clear and stop do not start a missing daemon.

The defaults can be changed with OP_AGENT_CACHE_TTL and OP_AGENT_IDLE_TTL. OP_AGENT_SOCKET is available for isolated testing.

See Architecture for the security and data-flow contract.