Skip to content

1Password on hosts

A host that runs agents usually needs secrets, and the usual way to give it them is a 1Password service account token on its disk. mocante offers another way: op read, op inject and op run in a mocante session on the host ask your device, which reads the secret with the 1Password app you have unlocked. The host holds no token.

Each secret is approved in mocante for the command or the session that asked, and a host may only read the vaults you list for it. It is off until you turn it on, and while it is off op on your hosts runs as it always did.

  1. On your device, install the 1Password CLI and turn on Integrate with 1Password CLI in the 1Password app’s developer settings.
  2. In mocante, open Settings › 1Password and set Read secrets with to 1Password app.
  3. On the host, install the 1Password CLI too. mocante runs it for everything it does not answer itself, such as op item create or op signin.
  4. Edit the host and list the 1Password vaults its sessions may read, one per line, exactly as 1Password names them. A host with no vault listed may read none. Leave Install the 1Password shim on this host ticked to install the shim when you save.
  5. Or choose Install 1Password shim… in the command palette and pick the host, or All connected hosts.

The shim is a small op in ~/.local/bin on the host, ahead of the real one on the PATH, so scripts and tools that call op need no change. If the install warns that the real op comes first on the host’s PATH, put ~/.local/bin before it in the host’s shell profile.

When a mocante update changes the shim, the host shows as out of date like its agent hooks, and Update agent hooks and MCP on all hosts writes it again. It never installs a shim on a host that has none. Uninstall 1Password shim… removes it from a host, or from all of them.

On a Mac, turn on Touch ID for risky approvals in Settings, under Agents. Allowing a read then also asks for your fingerprint, and a failed or cancelled prompt denies the read. A request still waits only ten seconds in all, so answer the fingerprint prompt soon after you click.

Set Read secrets with to Off in Settings › 1Password. mocante then reads no secret for any host: a shim that is still installed runs the host’s own op, as if mocante were not there.

In a session on the host, use op as usual:

Terminal window
op read "op://devbox/Postgres/password"
op inject -i config.tpl -o config.yml
op run -- npm run dev

The first time a session asks for a secret, mocante shows a request in that session naming every reference it asks for, and a notification when the session is not on screen. Approve it in mocante with Allow once, which lets only the command that asked read those secrets, or Allow for this session, which lets the session read them again without asking. Each button has a shortcut while the request is on screen. The notification has no Approve button, because it may not show every secret the approval covers. The request lists every secret; a long list scrolls. One command asks once for all the secrets it needs. The terminal shows op: waiting for approval in mocante… while it waits.

  • The request also says what reads the secrets: the 1Password app and the account it reads as, or a service account token by name.
  • An approval for the session covers those references until you remove the session or quit mocante, or for the time you set under Approvals last. Another reference asks again.
  • You are asked again when the approval no longer fits: the session was closed and started again, the host’s address now reaches another machine, this device reads the host with another 1Password account or token (even when you change it back), or the host’s list of vaults changed, here or on another of your devices. Renaming a session keeps its approvals.
  • A request that nobody answers in ten seconds fails. It never falls back to a token on the host. If something above changes while the request waits, the command fails and says what changed; run it again.
  • 1Password may also ask you to unlock it or to confirm with Touch ID on your device, sometimes before mocante asks its own question.

An agent needs a secret’s reference before it can read it. In a session on the host, these commands find one, and show names and references but never a value:

Terminal window
op vault list
op item list --vault devbox
op item get Postgres --vault devbox --format json
op whoami
  • op vault list shows the vaults you listed for the host, and asks nothing.
  • op item list lists the items of each vault you name with --vault, or of every vault the host may read. --categories works; --tags goes to the real op.
  • op item get shows an item’s fields, each with its op:// reference, and no value. Read a value with op read and that reference. Without --vault, it looks in each vault the host may read. --fields and --reveal fail and show the references to read instead. --otp fails, and one-time password fields have no reference: mocante gives no one-time password, and op read of such a field fails, so read the code in the 1Password app. With --format json, the fields have no value, so a script that reads .value gets null; read values with op read.
  • op whoami and op account list show the account your device reads this host with, and ask nothing. With several accounts in the 1Password app and none picked for the host or in Settings › 1Password, they work for five minutes after a read. A host that may read no vault gets no answer.
  • --format json prints JSON, as op does. Without it, or with --format human-readable, mocante prints a simple table.
  • op item list takes at most 16 --vault flags at once.

Listing a vault and getting an item ask in mocante as a read does, with Allow once or Allow for this session. An approval to list a vault for the session also covers the items added to it later.

A key with a number in the session header shows how many secrets, vaults and items the session may read or list without asking. Hover it to see which, and click it to forget one, or all of them. Forget 1Password approvals… in the command palette does the same. After that, the next read asks again.

To make approvals end by themselves, open Settings › 1Password and choose under Approvals last: Session keeps an approval until the session ends, or pick 1 hour, 8 hours or 1 day.

In a mocante session What answers
op read, op inject, op run your device, after you approve
op item list, op item get your device, after you approve
op vault list, op whoami, op account list your device
a vault the host may not read nobody: the command fails
any other op command, or a flag mocante does not know the real op on the host
a reference with a variable, op://$ENV/… the real op on the host
a tmux started inside the session, or tmux -L the real op on the host
a command that gives op a token the real op on the host

Outside a mocante session, for example in a plain ssh login, cron or CI, the host’s own op answers, with whatever sign-in it has. The same happens when no device is connected to the host.

A command gives op a token when it sets OP_SERVICE_ACCOUNT_TOKEN, or OP_CONNECT_HOST and OP_CONNECT_TOKEN. The host already holds that token, so mocante does not ask. Use this for a tool that reads a secret as it starts, such as a gh that gets its GitHub token through fnox: Claude Code gives gh only a few seconds, which is often too short to approve a request. If you export a token in the host’s shell profile, mocante is not asked for any command in any session on that host, and op says so in the terminal.

op inject fills {{ op://… }}, and a bare reference that fills a whole KEY=op://… line, so tools that batch secrets through it, such as fnox, get values. Any other op:// outside braces, in a comment too, makes mocante hand a template file to the host’s own op. op inject with a template on stdin that mocante cannot fill fails and asks you to pass the template with -i, because the real op could no longer read stdin.

The device that connected to the host last reads the secrets, the same device that answers agent tools. When it disconnects, or goes to sleep or leaves the network for about 45 seconds, the device that connected before it answers again. That device’s 1Password must be able to read the vault.

To make the device you are using answer, choose Make this device answer for host… in the command palette and pick the host, or All connected hosts. Use it too when op in a mocante session runs the host’s own op although your device is connected: it puts back the link that the host uses to reach your device.

If the 1Password app on your device has more than one account, or you sign in to one account as more than one person, choose which one reads the secrets: open Settings › 1Password and pick it under 1Password account. Default account uses the account the app uses when none is named. An approval belongs to the account it was given for, so picking another one asks again.

A host can read with another account than the rest. Open Edit host on that host and pick it under 1Password account. Default follows the account in Settings. The picker shows when the 1Password app has more than one account.

  • The choice is stored on this device only. Your other devices read the host with their own choice.
  • The vaults you list for the host are vaults of that account.
  • 1Password asks to unlock each account on its own, so the first read for each account may ask for Touch ID.
  • If you remove the account from the 1Password app, reads for the host fail until you pick another. They never fall back to another account.

A command or tool can name an account with --account or OP_ACCOUNT, as fnox does when its 1Password provider sets account. mocante does not switch accounts for it: the command reads only when the name is the account your device reads this host with, and fails otherwise. Name the account by its sign-in address (acme.1password.com), its account ID or your user ID. op account list --format json on your device shows all three.

  • To read from another account, pick it for the host under Edit host. The host cannot choose it.
  • An account shorthand, such as acme, is not accepted. Use the sign-in address or an ID.
  • Several personal accounts can share the sign-in address my.1password.com. If the address names more than one account in the 1Password app, the command fails; name the account by its ID.
  • A host that reads with a service account token fails every command that names an account, because mocante cannot tell which account a token is for. Remove --account and OP_ACCOUNT there.
  • If the device that answers runs an older version of mocante, a command that names an account fails, after that device has asked you to approve the read. Update mocante on that device.

The 1Password app asks for Touch ID on the device that reads the secret. On a hub that you reach from your phone, nobody is there to answer it. Let the hub read with a 1Password service account instead:

  1. In 1Password, create a service account with read access to the vaults your hosts need, and copy its token.
  2. On the hub, open Settings › 1Password.
  3. Under Service account tokens, enter a name and paste the token, then click Add.
  4. Set Read secrets with to Service account.

You still approve each secret in mocante, now from your phone, and each host still reads only the vaults you list for it.

  • The token is stored encrypted with this device’s keychain, on this device only. It never syncs to your other devices.
  • The first token you add is the default. With more than one, a host’s edit dialog shows 1Password token, where you pick the token that host uses. Make default and Remove… are next to each token.
  • If the hub reads with a service account and holds no token, reads fail rather than ask for Touch ID.
  • Only the desktop app can store a token.