Skip to main content
Resolve provider API keys from 1Password at process startup instead of storing them in plaintext inside ~/.mibyan/.env. You keep your keys as 1Password items and reference them by op://vault/item/field; rotating a credential becomes a single change in 1Password.

​
How it works

  1. You install the official 1Password CLI (op) and authenticate it — either with a service-account token (headless servers) or an interactive/desktop session (your laptop).
  2. You map environment-variable names to op:// references in ~/.mibyan/config.yaml.
  3. Every time mibyan (or the gateway, or a cron job) starts, after ~/.mibyan/.env has loaded, Mibyan runs op read for each reference and sets the resolved values into os.environ.
  4. By default Mibyan overrides values already in your environment, so 1Password is the source of truth — rotate a credential once and every Mibyan process picks it up on next start. Flip override_existing: false if you want .env to win instead.
Mibyan never authenticates on your behalf and never downloads op: it shells out to your already-installed, already-trusted CLI. If op is missing, your session is locked, or a reference is wrong, Mibyan prints a one-line warning and continues with whatever credentials .env already had — it never blocks startup.

​
Authentication

op supports two non-interactive-friendly modes; Mibyan works with either:
  • Service accounts (recommended for servers/CI): create a service account in 1Password, grant it read access to the relevant vault, and export its token as OP_SERVICE_ACCOUNT_TOKEN in ~/.mibyan/.env. The token is the credential — treat it like any other bearer token.
  • Desktop / interactive sessions (laptops): run op signin (or enable CLI integration in the 1Password app). Mibyan passes your OP_SESSION_* variables through to the op child process. The 1Password cache key includes those session variables, so signing into a different account never serves a value cached under the previous identity.

​
Bootstrap token

When you authenticate with a service-account token, that token is itself the bootstrap credential Mibyan needs before it can resolve any op:// reference. It must be present in os.environ of every process that resolves secrets — including cron jobs (kanban.dispatch_in_gateway: false), subprocess invocations, CLI runs, macOS launchd agents, and Docker containers — not just the interactive gateway. There are three ways to make it available, in order of precedence:
  1. In ~/.mibyan/.env (recommended). mibyan secrets onepassword setup --token <token> writes the token to ~/.mibyan/.env, exactly like Bitwarden’s BWS_ACCESS_TOKEN. Because load_mibyan_dotenv() always loads .env, the token is available everywhere with zero extra setup. This is the simplest reliable option.
  2. In ~/.mibyan/.op.env (gitignored). If you’d rather keep the service-account token out of .env — for example so .env can be checked into a private dotfiles repo while the token stays out of version control — place it in ~/.mibyan/.op.env:
    Mibyan auto-loads .op.env at startup, after .env, and never overrides a token already present in the environment. .op.env is gitignored so the token never enters a committed file.
  3. Via systemd EnvironmentFile (Linux gateway). If you run the gateway under systemd, you can inject the token directly into the service environment:
    A token injected this way takes precedence — Mibyan detects that OP_SERVICE_ACCOUNT_TOKEN is already set and skips loading .op.env entirely.
If the token is reachable only through an interactive shell (op signin, OP_SESSION_* exports in .bashrc, etc.), it will not be inherited by cron jobs or freshly spawned subprocesses, and those contexts will log a warning and fall back to whatever credentials .env already held. Use one of the three options above for any non-interactive workload.

​
Setup

​
1. Install and sign in to op

Follow the 1Password CLI getting-started guide. Verify it works:

​
2. Enable the integration

This verifies op is on PATH (or use --binary-path), records your account/token settings, checks for an active session, and flips secrets.onepassword.enabled: true. Non-interactive flags:

​
3. Map your credentials

The reference format is op://<vault>/<item>/<field>:

​
4. Preview and confirm

From now on, every mibyan invocation resolves the references at startup. You’ll see a one-line summary in stderr the first time secrets are applied in a process.

​
CLI

op and 1password are accepted as aliases for onepassword.

​
Configuration

Defaults in ~/.mibyan/config.yaml:

​
Failure modes

1Password never blocks Mibyan startup. If anything goes wrong you’ll see a one-line warning in stderr and Mibyan continues: Startup warnings now include a → remediation line telling you exactly which command fixes the failure.

​
Caching

Successful, complete pulls are cached in-process and on disk under <mibyan_home>/cache/op_cache.json (written atomically, mode 0600), so back-to-back short-lived mibyan invocations don’t re-shell op for every reference. The cache:
  • stores only resolved secret values — never the service-account token or any raw auth material (auth is fingerprinted into the cache key);
  • is invalidated when the token, account, OP_SESSION_* variables, or the set of references change;
  • is not written when a pull had any per-reference error, so a transient auth failure isn’t frozen in for the TTL;
  • is fully disabled — reads and writes — when cache_ttl_seconds: 0.

​
Security notes

  • A 1Password service-account token can read every secret the account has access to. Store it in ~/.mibyan/.env (not config.yaml), and revoke + regenerate from 1Password if it leaks.
  • Mibyan refuses to let a resolved value overwrite the token env var itself, even with override_existing: true.
  • The op child process gets a minimal allowlisted environment (auth/session vars + PATH/HOME and the op config-location vars OP_CONFIG_DIR/XDG_CONFIG_HOME), not a copy of the full os.environ, so post-dotenv provider credentials aren’t all inherited by the child. Set OP_CONFIG_DIR when ~/.config is not writable by the Mibyan user (common in containers).
  • References are validated to start with op://, and the reference is passed after a -- option terminator so a crafted value can’t be parsed as an op flag.

​
When NOT to use this

  • Single-machine personal setups where ~/.mibyan/.env is fine.
  • Air-gapped environments that can’t reach 1Password.
  • CI/CD where an existing secrets-injection mechanism is already wired up — pick one path, not two.
The good case for this is multi-machine fleets, shared dev boxes, gateway VPSes, or anywhere you want centralized rotation and revocation across multiple Mibyan installations.